OmniRoute/docs/frameworks/PLAYGROUND_STUDIO.md

title	version	lastUpdated
Playground Studio	3.8.40	2026-06-28

Playground Studio

Feature: Playground Studio — unified AI testing workspace for /dashboard/playground. Plans: 17-playground-studio-redesign.plan.md + _orchestration/master-plan-group-C.md Status: Released in v3.8.6

---

Overview

Playground Studio transforms /dashboard/playground from a simple Monaco-based editor into a full-featured testing workspace. It replaces the legacy page.tsx with a PlaygroundStudio shell that renders four tabs and a shared config pane.

┌ Playground ──────────────────────────────────────────────────────────┐
│ [💬 Chat] [⚖ Compare] [{} API] [🔧 Build]     142↑ 38↓ · $0.002 </>│
├──────────────────────────────────────────┬───────────────────────────┤
│  {active tab content}                    │ ─ Config                  │
│                                          │ Endpoint  [chat ∨]        │
│                                          │ Model     [gpt-5.4 ∨]     │
│                                          │ System    [textarea]      │
│                                          │ Temp      ▕▕▔▔ 0.7        │
│                                          │ Presets [▾ load][save]    │
│                                          │ [✨ Improve prompt]        │
└──────────────────────────────────────────┴───────────────────────────┘

---

Tabs

Chat Tab

Evolves ChatPlayground.tsx into a multi-turn streaming workbench:

• Full markdown rendering via MarkdownMessage.tsx (code blocks, tables, lists, links).
• System prompt sourced from the shared Config pane.
• Token/cost per message (prompt + completion tokens).
• Regenerate last response.
• Sends to POST /v1/chat/completions with SSE streaming.

Compare Tab

The key differentiator for a proxy: run 1 prompt across up to 4 models in parallel.

• Up to 4 columns, each independently streaming from /v1/chat/completions.
• + Add model button (Cmd+K shortcut) to add columns.
• Run all ▶ triggers all streams simultaneously via Promise.all + per-column AbortController.
• Global Cancel all aborts every in-flight stream.
• Per-column ProviderMetrics shows TTFT, TPS, tokens, and estimated cost in real time.
• Metrics labelled "client-side estimate" (D12) — measured from first SSE chunk.

API Tab

Preserves 100% of the original Monaco editor for power users (D14):

• 10 endpoints: chat completions, completions, embeddings, images, audio, speech, transcriptions, moderations, rerank, search.
• Multimodal file upload.
• SSE streaming with real-time output.
• Wrapped as ApiTab.tsx (lazy-loaded, ssr: false).

Build Tab

Tools/function calling and structured output UI:

• ToolsBuilder.tsx — add/edit/remove tools[] with JSON schema editor per tool. Validates parameters via ToolDefinitionSchema (Zod).
• StructuredOutputEditor.tsx — toggle JSON mode + JSON schema editor. Validates response against schema via StructuredOutputSchema (Zod).
• Sends request to /v1/chat/completions with tools[] and/or response_format.

---

Config Pane (Shared)

StudioConfigPane.tsx — always visible, collapsible.

Field	Component	Notes
Endpoint	<select>	10 options matching PlaygroundEndpoint
Model	<input>	free text, e.g. openai/gpt-4o
System prompt	<textarea>	fed into all tabs
Parameters	ParamSliders	temperature, max_tokens, top_p, presence/frequency penalty, seed, stop
Presets	PresetPicker	load/save named config snapshots (persisted in DB)
Improve prompt	ImprovePromptButton	opens quota-warning modal, calls /api/playground/improve-prompt

State is lifted to PlaygroundStudio.tsx and passed down to all tabs. Switching tabs preserves config state.

---

Top Bar

StudioTopBar.tsx:

• Tab switcher (role="tablist").
• TokenCostCounter — live token (↑/↓) and estimated cost display.
• Export code button (</>) — opens ExportCodeModal.

---

Export Code Modal

ExportCodeModal.tsx uses codeExport.ts to generate curl / Python / TypeScript snippets from the current PlaygroundState. API key placeholder is always $OMNIROUTE_API_KEY (D11).

---

Prompt Improver

ImprovePromptButton.tsx → useImprovePrompt.ts → POST /api/playground/improve-prompt:

1. Modal warns "will consume quota".
2. On confirm, sends { system, prompt, model, tone } to the route.
3. Route calls /v1/chat/completions internally with promptImprover.META_SYSTEM_PROMPT.
4. Returns { improvedSystem?, improvedPrompt?, tokensIn, tokensOut }.
5. UI patches the Config pane system prompt and the Chat tab user prompt.

---

Presets

PresetPicker.tsx → usePresets.ts → /api/playground/presets/*:

• Stored in playground_presets SQLite table (migration 084_playground_presets.sql).
• Each preset stores: name, endpoint, model, system, params_json, created_at.
• CRUD: GET list, POST create, GET /:id, PUT /:id, DELETE /:id.

---

Stream Metrics

useStreamMetrics.ts + streamMetrics.ts (pure function):

• start() — records request start time.
• onFirstChunk() — records TTFT.
• onChunk(n) — accumulates completion token count.
• finish(usage?) — computes final metrics: ttftMs, totalMs, tps, tokensIn, tokensOut, costUsd.
• Pricing from static table in src/lib/playground/types.ts (labelled "estimated" — D13).

---

Backend Routes

Method	Path	Handler
POST	/api/playground/improve-prompt	Zod-validates ImprovePromptRequestSchema; calls /v1/chat/completions with meta-prompt
GET	/api/playground/presets	Returns { presets: PlaygroundPresetListItem[] }
POST	/api/playground/presets	Creates preset; validates PlaygroundPresetCreateSchema
GET	/api/playground/presets/:id	Returns one preset or 404
PUT	/api/playground/presets/:id	Partial update
DELETE	/api/playground/presets/:id	204

Auth: optional (REQUIRE_API_KEY). Errors via buildErrorBody() (Hard Rule #12).

---

Key Files

Path	Purpose
src/app/(dashboard)/dashboard/playground/PlaygroundStudio.tsx	Shell component, tab orchestrator
src/app/(dashboard)/dashboard/playground/components/StudioTopBar.tsx	Tabs + counter + export button
src/app/(dashboard)/dashboard/playground/components/StudioConfigPane.tsx	Shared config panel
src/app/(dashboard)/dashboard/playground/components/tabs/ChatTab.tsx	Chat workbench
src/app/(dashboard)/dashboard/playground/components/tabs/CompareTab.tsx	Multi-model compare
src/app/(dashboard)/dashboard/playground/components/tabs/ApiTab.tsx	Monaco editor (preserved)
src/app/(dashboard)/dashboard/playground/components/tabs/BuildTab.tsx	Tools + structured output
src/app/(dashboard)/dashboard/playground/components/ExportCodeModal.tsx	Code export modal
src/app/(dashboard)/dashboard/playground/components/CompareColumn.tsx	Single compare column
src/app/(dashboard)/dashboard/playground/components/ProviderMetrics.tsx	TTFT/TPS display
src/app/(dashboard)/dashboard/playground/hooks/useStreamMetrics.ts	Client-side metric hook
src/app/(dashboard)/dashboard/playground/hooks/usePresets.ts	Presets CRUD hook
src/app/(dashboard)/dashboard/playground/hooks/useImprovePrompt.ts	Improve-prompt hook
src/lib/playground/codeExport.ts	curl/Python/TS generator (shared with Search Tools)
src/lib/playground/promptImprover.ts	Meta-prompt builder
src/lib/playground/streamMetrics.ts	Pure metrics computation
src/lib/db/playgroundPresets.ts	DB module (CRUD)
src/app/api/playground/improve-prompt/route.ts	Improve-prompt REST route
src/app/api/playground/presets/route.ts	Presets list + create
src/app/api/playground/presets/[id]/route.ts	Presets get/update/delete
src/lib/db/migrations/084_playground_presets.sql	DB migration

---

Troubleshooting

Symptom	Cause	Fix
Monaco editor not rendering in API tab	SSR loaded Monaco	Verify ApiTab uses dynamic(..., { ssr: false })
Compare streams fire sequentially	Wrong Promise.all usage	All stream starts must be dispatched in one Promise.all call
Metrics show null TTFT	First chunk handler not wired	Check useStreamMetrics.onFirstChunk() is called in the SSE reader loop
Preset not persisting	DB migration not run	Run npm run db:migrate or restart the server (migration auto-runs on startup)
Improve prompt returns 502	Model not set in Config	User must enter a model name in the Config pane before improving
Export code shows MISSING_API_KEY	Placeholder not inserted	codeExport.ts always uses API_KEY_PLACEHOLDER = "$OMNIROUTE_API_KEY"

---

References

• Master plan: _tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md
• Feature plan: _tasks/features-v3.8.6/refactorpages/17-playground-studio-redesign.plan.md
• Code export: src/lib/playground/codeExport.ts
• Prompt improver: src/lib/playground/promptImprover.ts
• Search Tools Studio: docs/frameworks/SEARCH_TOOLS_STUDIO.md