fix: reorder collection page sections and add layout to docs page
- Move use cases section above scenarios section on collection detail pages - Add AppHeader and AppFooter to /docs/developers/guide page for consistent layout
This commit is contained in:
Ajax Davis
parent
92e4f5c467
commit
5fafc90e3e
2 changed files with 574 additions and 552 deletions
|
|
@ -393,6 +393,16 @@ export function CollectionDetailClient({
|
|||
</div>
|
||||
)}
|
||||
|
||||
{/* Use Cases Section */}
|
||||
{collection.tools.length > 0 && (
|
||||
<UseCasesSection
|
||||
collectionId={collection.id}
|
||||
useCases={collection.useCases}
|
||||
generatedAt={collection.useCasesGeneratedAt}
|
||||
onUseCasesGenerated={handleUseCasesGenerated}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Scenarios Section */}
|
||||
{collection.tools.length > 0 && (
|
||||
<ScenariosSection
|
||||
|
|
@ -402,16 +412,6 @@ export function CollectionDetailClient({
|
|||
slug={collection.slug}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Use Cases Section - at the bottom */}
|
||||
{collection.tools.length > 0 && (
|
||||
<UseCasesSection
|
||||
collectionId={collection.id}
|
||||
useCases={collection.useCases}
|
||||
generatedAt={collection.useCasesGeneratedAt}
|
||||
onUseCasesGenerated={handleUseCasesGenerated}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -3,6 +3,9 @@ import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock';
|
|||
import type { Metadata } from 'next';
|
||||
import Link from 'next/link';
|
||||
|
||||
import { AppFooter } from '~/components/AppFooter';
|
||||
import { AppHeader } from '~/components/AppHeader';
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'Developers Guide | TPMJS Docs',
|
||||
description:
|
||||
|
|
@ -11,14 +14,18 @@ export const metadata: Metadata = {
|
|||
|
||||
export default function DevelopersGuidePage(): React.ReactElement {
|
||||
return (
|
||||
<div className="space-y-8">
|
||||
<div className="min-h-screen bg-background flex flex-col">
|
||||
<AppHeader />
|
||||
|
||||
<main className="flex-1">
|
||||
<div className="max-w-4xl mx-auto px-4 py-12 space-y-8">
|
||||
{/* Introduction */}
|
||||
<div>
|
||||
<h1 className="text-3xl font-bold mb-4">Developers Guide: Scenarios</h1>
|
||||
<p className="text-foreground-secondary text-lg">
|
||||
Scenarios are TPMJS's AI-powered testing and evaluation system for tool collections.
|
||||
They provide automated testing, quality tracking, and regression prevention for your
|
||||
tools.
|
||||
Scenarios are TPMJS's AI-powered testing and evaluation system for tool
|
||||
collections. They provide automated testing, quality tracking, and regression
|
||||
prevention for your tools.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
|
@ -32,9 +39,9 @@ export default function DevelopersGuidePage(): React.ReactElement {
|
|||
</CardHeader>
|
||||
<CardContent className="space-y-4">
|
||||
<p className="text-foreground-secondary">
|
||||
A Scenario is a test case that simulates how a real user would interact with your tool
|
||||
collection. Unlike traditional unit tests that verify individual functions, scenarios
|
||||
exercise your tools end-to-end with realistic prompts and assertions.
|
||||
A Scenario is a test case that simulates how a real user would interact with your
|
||||
tool collection. Unlike traditional unit tests that verify individual functions,
|
||||
scenarios exercise your tools end-to-end with realistic prompts and assertions.
|
||||
</p>
|
||||
|
||||
<div className="bg-background-secondary p-4 rounded-lg space-y-3">
|
||||
|
|
@ -45,16 +52,16 @@ export default function DevelopersGuidePage(): React.ReactElement {
|
|||
collection's tools
|
||||
</li>
|
||||
<li>
|
||||
<strong>Realistic Prompt:</strong> The agent executes your scenario's prompt
|
||||
against the tools
|
||||
<strong>Realistic Prompt:</strong> The agent executes your scenario's
|
||||
prompt against the tools
|
||||
</li>
|
||||
<li>
|
||||
<strong>LLM Evaluation:</strong> An LLM analyzes whether the task was completed
|
||||
successfully
|
||||
</li>
|
||||
<li>
|
||||
<strong>Result Recording:</strong> All results are stored for quality tracking and
|
||||
historical analysis
|
||||
<strong>Result Recording:</strong> All results are stored for quality tracking
|
||||
and historical analysis
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
|
@ -84,8 +91,8 @@ export default function DevelopersGuidePage(): React.ReactElement {
|
|||
<div className="bg-background-secondary p-4 rounded-lg">
|
||||
<h4 className="font-semibold mb-2">🎯 AI-Powered Validation</h4>
|
||||
<p className="text-foreground-secondary text-sm">
|
||||
Use LLM evaluation to verify your tools actually solve real problems, not just pass
|
||||
code tests.
|
||||
Use LLM evaluation to verify your tools actually solve real problems, not just
|
||||
pass code tests.
|
||||
</p>
|
||||
</div>
|
||||
<div className="bg-background-secondary p-4 rounded-lg">
|
||||
|
|
@ -107,24 +114,24 @@ export default function DevelopersGuidePage(): React.ReactElement {
|
|||
<h4 className="font-semibold mb-3">When to Use Scenarios</h4>
|
||||
<ul className="space-y-2 text-foreground-secondary">
|
||||
<li>
|
||||
<strong>Multi-Tool Integration:</strong> Testing how multiple tools work together in
|
||||
complex workflows
|
||||
<strong>Multi-Tool Integration:</strong> Testing how multiple tools work
|
||||
together in complex workflows
|
||||
</li>
|
||||
<li>
|
||||
<strong>API-First Tools:</strong> Validating tools that make HTTP requests or parse
|
||||
unstructured data
|
||||
<strong>API-First Tools:</strong> Validating tools that make HTTP requests or
|
||||
parse unstructured data
|
||||
</li>
|
||||
<li>
|
||||
<strong>Quality-Critical Collections:</strong> When tool reliability impacts user
|
||||
experience
|
||||
<strong>Quality-Critical Collections:</strong> When tool reliability impacts
|
||||
user experience
|
||||
</li>
|
||||
<li>
|
||||
<strong>Regression Prevention:</strong> Before deploying changes that might break
|
||||
existing functionality
|
||||
<strong>Regression Prevention:</strong> Before deploying changes that might
|
||||
break existing functionality
|
||||
</li>
|
||||
<li>
|
||||
<strong>Documentation-Driven Testing:</strong> Ensuring tools work as described in
|
||||
their public documentation
|
||||
<strong>Documentation-Driven Testing:</strong> Ensuring tools work as described
|
||||
in their public documentation
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
|
@ -167,9 +174,9 @@ export default function DevelopersGuidePage(): React.ReactElement {
|
|||
<div>
|
||||
<h4 className="font-semibold mb-3">2. Agent Execution</h4>
|
||||
<p className="text-foreground-secondary mb-2">
|
||||
When a scenario runs, an ephemeral AI agent is created with your tool collection. The
|
||||
agent executes the scenario prompt using only the tools in that collection—no external
|
||||
access, no additional context.
|
||||
When a scenario runs, an ephemeral AI agent is created with your tool collection.
|
||||
The agent executes the scenario prompt using only the tools in that collection—no
|
||||
external access, no additional context.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`Scenario: "Extract user emails"
|
||||
|
|
@ -187,9 +194,9 @@ Collection: ["json-parser", "data-validator"]
|
|||
<div>
|
||||
<h4 className="font-semibold mb-3">3. LLM Evaluation</h4>
|
||||
<p className="text-foreground-secondary mb-2">
|
||||
After execution, a powerful LLM evaluates the results. This isn't just checking
|
||||
for errors—it uses natural language understanding to verify the task was completed
|
||||
correctly.
|
||||
After execution, a powerful LLM evaluates the results. This isn't just
|
||||
checking for errors—it uses natural language understanding to verify the task was
|
||||
completed correctly.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`EVALUATION PROMPT:
|
||||
|
|
@ -227,7 +234,9 @@ Execution Time: 2.3s`}
|
|||
</ul>
|
||||
</div>
|
||||
<div className="bg-red-500/10 p-4 rounded-lg">
|
||||
<h5 className="font-semibold text-red-600 dark:text-red-400 mb-2">⚠️ On Failure</h5>
|
||||
<h5 className="font-semibold text-red-600 dark:text-red-400 mb-2">
|
||||
⚠️ On Failure
|
||||
</h5>
|
||||
<ul className="space-y-1 text-foreground-secondary text-sm">
|
||||
<li>-20% base penalty</li>
|
||||
<li>-5% penalty per consecutive fail</li>
|
||||
|
|
@ -236,9 +245,9 @@ Execution Time: 2.3s`}
|
|||
</div>
|
||||
</div>
|
||||
<p className="text-foreground-secondary text-sm mt-4">
|
||||
<strong>Example:</strong> A scenario that passes 5 times consecutively earns 25% bonus
|
||||
(50% + 5×5) for a total score of ~75%. High-quality scenarios (75%+) are featured on
|
||||
the TPMJS homepage showcase.
|
||||
<strong>Example:</strong> A scenario that passes 5 times consecutively earns 25%
|
||||
bonus (50% + 5×5) for a total score of ~75%. High-quality scenarios (75%+) are
|
||||
featured on the TPMJS homepage showcase.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
|
@ -250,8 +259,8 @@ Execution Time: 2.3s`}
|
|||
</p>
|
||||
<ul className="space-y-2 text-foreground-secondary ml-4">
|
||||
<li>
|
||||
<strong>Full Transparency:</strong> See exactly what the agent asked and how each
|
||||
tool responded
|
||||
<strong>Full Transparency:</strong> See exactly what the agent asked and how
|
||||
each tool responded
|
||||
</li>
|
||||
<li>
|
||||
<strong>Debugging:</strong> Inspect tool inputs, outputs, and errors in detail
|
||||
|
|
@ -281,8 +290,8 @@ Execution Time: 2.3s`}
|
|||
<div className="border-l-4 border-border pl-4">
|
||||
<h4 className="font-semibold mb-2">🚀 CI/CD Integration</h4>
|
||||
<p className="text-foreground-secondary text-sm mb-3">
|
||||
Automate scenario testing in your deployment pipeline to catch regressions before they
|
||||
reach production.
|
||||
Automate scenario testing in your deployment pipeline to catch regressions before
|
||||
they reach production.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`name: Run Scenarios in CI
|
||||
|
|
@ -313,16 +322,16 @@ jobs:
|
|||
showCopy={true}
|
||||
/>
|
||||
<p className="text-foreground-secondary text-sm mt-2">
|
||||
<strong>Benefits:</strong> Block deploys on failures, generate test reports, and track
|
||||
quality metrics over time.
|
||||
<strong>Benefits:</strong> Block deploys on failures, generate test reports, and
|
||||
track quality metrics over time.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div className="border-l-4 border-border pl-4">
|
||||
<h4 className="font-semibold mb-2">🔍 Local Development Testing</h4>
|
||||
<p className="text-foreground-secondary text-sm mb-3">
|
||||
Test scenarios locally during development to verify tool behavior without consuming
|
||||
quota.
|
||||
Test scenarios locally during development to verify tool behavior without
|
||||
consuming quota.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`# Generate scenarios for your tool collection
|
||||
|
|
@ -351,8 +360,8 @@ tpm scenario info clu123abc456 --json > analysis.json`}
|
|||
<div className="border-l-4 border-border pl-4">
|
||||
<h4 className="font-semibold mb-2">📊 Quality Monitoring Dashboard</h4>
|
||||
<p className="text-foreground-secondary text-sm mb-3">
|
||||
Use scenario results to build dashboards showing tool reliability, success rates, and
|
||||
performance trends.
|
||||
Use scenario results to build dashboards showing tool reliability, success rates,
|
||||
and performance trends.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`# Export scenario results as JSON
|
||||
|
|
@ -380,8 +389,8 @@ curl -X POST https://your-monitoring.com/webhook \\
|
|||
<div className="border-l-4 border-border pl-4">
|
||||
<h4 className="font-semibold mb-2">🎓 Tool Library Development</h4>
|
||||
<p className="text-foreground-secondary text-sm mb-3">
|
||||
Ensure your tools work correctly with scenarios before publishing them. High-quality
|
||||
scenarios increase tool visibility on the TPMJS homepage.
|
||||
Ensure your tools work correctly with scenarios before publishing them.
|
||||
High-quality scenarios increase tool visibility on the TPMJS homepage.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`# Create comprehensive scenario suite
|
||||
|
|
@ -413,7 +422,9 @@ Quality metrics attract more users and increase adoption.`}
|
|||
<thead>
|
||||
<tr className="border-b border-border">
|
||||
<th className="text-left py-3 px-4 font-semibold text-foreground">Feature</th>
|
||||
<th className="text-left py-3 px-4 font-semibold text-foreground">Unit Tests</th>
|
||||
<th className="text-left py-3 px-4 font-semibold text-foreground">
|
||||
Unit Tests
|
||||
</th>
|
||||
<th className="text-left py-3 px-4 font-semibold text-foreground">
|
||||
Integration Tests
|
||||
</th>
|
||||
|
|
@ -464,14 +475,18 @@ Quality metrics attract more users and increase adoption.`}
|
|||
<td className="py-3 px-4 text-foreground-secondary">
|
||||
Brittle with implementation changes
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-secondary">Better with refactoring</td>
|
||||
<td className="py-3 px-4 text-foreground-secondary">
|
||||
Better with refactoring
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground">Self-healing with AI prompts</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="py-3 px-4 text-foreground-secondary">
|
||||
<strong>Debugging</strong>
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-secondary">Stack traces, breakpoints</td>
|
||||
<td className="py-3 px-4 text-foreground-secondary">
|
||||
Stack traces, breakpoints
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-secondary">
|
||||
Network logs, service logs
|
||||
</td>
|
||||
|
|
@ -525,8 +540,8 @@ Quality metrics attract more users and increase adoption.`}
|
|||
<div>
|
||||
<h4 className="font-semibold mb-2">🚀 CI/CD Integration</h4>
|
||||
<p className="text-foreground-secondary text-sm mb-3">
|
||||
Automate scenario testing in your deployment pipeline to catch regressions before they
|
||||
reach production.
|
||||
Automate scenario testing in your deployment pipeline to catch regressions before
|
||||
they reach production.
|
||||
</p>
|
||||
<CodeBlock
|
||||
code={`# Simple CI/CD example
|
||||
|
|
@ -538,8 +553,8 @@ echo "All scenarios ran"`}
|
|||
showCopy={true}
|
||||
/>
|
||||
<p className="text-foreground-secondary text-sm mt-2">
|
||||
<strong>Benefits:</strong> Block deploys on failures, generate test reports, and track
|
||||
quality metrics over time.
|
||||
<strong>Benefits:</strong> Block deploys on failures, generate test reports, and
|
||||
track quality metrics over time.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
|
@ -554,8 +569,8 @@ echo "All scenarios ran"`}
|
|||
<div>
|
||||
<h4 className="font-semibold mb-2">🔌 Scenario Marketplace</h4>
|
||||
<p className="text-foreground-secondary text-sm">
|
||||
Share high-quality scenarios across organizations, enabling collaborative testing and
|
||||
faster scenario coverage for popular tools.
|
||||
Share high-quality scenarios across organizations, enabling collaborative testing
|
||||
and faster scenario coverage for popular tools.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
|
@ -563,8 +578,8 @@ echo "All scenarios ran"`}
|
|||
<h4 className="font-semibold mb-3">Vision</h4>
|
||||
<p className="text-foreground-secondary text-sm">
|
||||
Scenarios will become the de facto standard for tool quality assurance on TPMJS.
|
||||
Before users install a tool, they'll see its scenario history, quality scores,
|
||||
and real-world performance metrics.
|
||||
Before users install a tool, they'll see its scenario history, quality
|
||||
scores, and real-world performance metrics.
|
||||
</p>
|
||||
</div>
|
||||
</CardContent>
|
||||
|
|
@ -648,7 +663,10 @@ tpm scenario info clu123abc456
|
|||
<CardContent className="space-y-4">
|
||||
<ul className="space-y-3">
|
||||
<li>
|
||||
<Link href="/docs/api/scenarios" className="text-primary hover:underline font-medium">
|
||||
<Link
|
||||
href="/docs/api/scenarios"
|
||||
className="text-primary hover:underline font-medium"
|
||||
>
|
||||
Scenarios API Reference →
|
||||
</Link>
|
||||
<p className="text-foreground-secondary text-sm">
|
||||
|
|
@ -686,5 +704,9 @@ tpm scenario info clu123abc456
|
|||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<AppFooter />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue