OmniRoute/docs/i18n/sw/docs/frameworks/PLAYGROUND_STUDIO.md

Playground Studio (Kiswahili)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Kipengele: Playground Studio — eneo la kazi lililounganishwa la kujaribu AI kwa /dashboard/playground. Mipango: 17-playground-studio-redesign.plan.md + _orchestration/master-plan-group-C.md Hali: Imetolewa katika v3.8.6

---

Muhtasari

Playground Studio inabadilisha /dashboard/playground kutoka kihariri rahisi kinachotumia Monaco kuwa eneo kamili la kazi la majaribio. Inachukua nafasi ya page.tsx ya zamani kwa ganda la PlaygroundStudio linaloonyesha vichupo vinne na kidirisha cha usanidi kinachoshirikiwa.

┌ Playground ──────────────────────────────────────────────────────────┐
│ [💬 Gumzo] [⚖ Linganisha] [{} API] [🔧 Unda]  142↑ 38↓ · $0.002 </>│
├──────────────────────────────────────────┬───────────────────────────┤
│  {maudhui ya kichupo kinachotumika}      │ ─ Usanidi                 │
│                                          │ Endpoint  [chat ∨]        │
│                                          │ Model     [gpt-5.4 ∨]     │
│                                          │ Mfumo     [textarea]      │
│                                          │ Temp      ▕▕▔▔ 0.7        │
│                                          │ Mipangilio [▾ pakia][hifadhi] │
│                                          │ [✨ Boresha prompt]        │
└──────────────────────────────────────────┴───────────────────────────┘

---

Vichupo

Kichupo cha Gumzo

Kinaboresha ChatPlayground.tsx kuwa sehemu ya kazi ya utiririshaji wa mazungumzo yenye zamu nyingi:

• Uonyeshaji kamili wa markdown kupitia MarkdownMessage.tsx (vitalu vya msimbo, majedwali, orodha, viungo).
• Prompt ya mfumo inayotoka kwenye kidirisha cha Usanidi kinachoshirikiwa.
• Tokeni/gharama kwa kila ujumbe (tokeni za prompt + ukamilishaji).
• Tengeneza upya jibu la mwisho.
• Hutuma kwa POST /v1/chat/completions kwa utiririshaji wa SSE.

Kichupo cha Kulinganisha

Kipengele kikuu kinachotofautisha proksi: endesha prompt 1 kwenye hadi modeli 4 kwa wakati mmoja.

• Hadi safu wima 4, kila moja ikitiririsha kivyake kutoka /v1/chat/completions.
• Kitufe cha + Ongeza modeli (njia ya mkato ya Cmd+K) cha kuongeza safu wima.
• Endesha zote ▶ huanzisha mitiririko yote kwa wakati mmoja kupitia Promise.all + AbortController kwa kila safu wima.
• Kitufe cha jumla cha Ghairi zote husitisha kila mtiririko unaoendelea.
• ProviderMetrics ya kila safu wima huonyesha TTFT, TPS, tokeni na makadirio ya gharama katika muda halisi.
• Vipimo vimewekewa lebo "makadirio ya upande wa mteja" (D12) — hupimwa kuanzia kipande cha kwanza cha SSE.

Kichupo cha API

Kinahifadhi 100% ya kihariri asili cha Monaco kwa watumiaji mahiri (D14):

• Endpoint 10: ukamilishaji wa gumzo, ukamilishaji, embeddings, picha, sauti, matamshi, unukuzi, udhibiti wa maudhui, upangaji upya na utafutaji.
• Upakiaji wa faili za aina nyingi za media.
• Utiririshaji wa SSE wenye matokeo ya muda halisi.
• Kimefungwa kama ApiTab.tsx (hupakiwa inapohitajika, ssr: false).

Kichupo cha Kuunda

UI ya tools/function calling na matokeo yenye muundo:

• ToolsBuilder.tsx — ongeza/hariri/ondoa tools[] kwa kutumia kihariri cha schema ya JSON kwa kila zana. Huthibitisha parameters kupitia ToolDefinitionSchema (Zod).
• StructuredOutputEditor.tsx — washa/zima hali ya JSON + kihariri cha schema ya JSON. Huthibitisha response dhidi ya schema kupitia StructuredOutputSchema (Zod).
• Hutuma ombi kwa /v1/chat/completions likiwa na tools[] na/au response_format.

---

Paneli ya Usanidi (Inayoshirikiwa)

StudioConfigPane.tsx — huonekana kila wakati, inaweza kukunjwa.

Sehemu	Kijenzi	Maelezo
Endpoint	<select>	chaguo 10 zinazolingana na PlaygroundEndpoint
Modeli	<input>	maandishi huru, k.m. openai/gpt-4o
Kidokezo cha mfumo	<textarea>	huingizwa kwenye vichupo vyote
Vigezo	ParamSliders	temperature, max_tokens, top_p, presence/frequency penalty, seed, stop
Mipangilio awali	PresetPicker	pakia/hifadhi vijipicha vya usanidi vilivyopewa majina (huhifadhiwa katika DB)
Boresha kidokezo	ImprovePromptButton	hufungua modali ya onyo la mgao, huita /api/playground/improve-prompt

Hali huinuliwa hadi PlaygroundStudio.tsx na kupitishwa kwa vichupo vyote. Kubadilisha vichupo huhifadhi hali ya usanidi.

---

Upau wa Juu

StudioTopBar.tsx:

• Kibadilisha vichupo (role="tablist").
• TokenCostCounter — onyesho la moja kwa moja la tokeni (↑/↓) na gharama iliyokadiriwa.
• Kitufe cha kuhamisha msimbo (</>) — hufungua ExportCodeModal.

---

Modali ya Kuhamisha Msimbo

ExportCodeModal.tsx hutumia codeExport.ts kutengeneza vijisehemu vya curl / Python / TypeScript kutoka kwenye PlaygroundState ya sasa. Kishikilia nafasi cha ufunguo wa API huwa $OMNIROUTE_API_KEY kila wakati (D11).

---

Kiboresha Kidokezo

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

1. Modali huonya kuwa "itatumia mgao".
2. Baada ya kuthibitisha, hutuma { system, prompt, model, tone } kwa route.
3. Route huita /v1/chat/completions kwa ndani kwa kutumia promptImprover.META_SYSTEM_PROMPT.
4. Hurejesha { improvedSystem?, improvedPrompt?, tokensIn, tokensOut }.
5. UI husasisha kidokezo cha mfumo cha paneli ya Usanidi na kidokezo cha mtumiaji cha kichupo cha Gumzo.

---

Mipangilio Awali

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

• Huhifadhiwa katika jedwali la SQLite la playground_presets (uhamishaji 084_playground_presets.sql).
• Kila mpangilio awali huhifadhi: name, endpoint, model, system, params_json, created_at.
• CRUD: orodha ya GET, uundaji wa POST, GET /:id, PUT /:id, DELETE /:id.

---

Vipimo vya Utiririshaji

useStreamMetrics.ts + streamMetrics.ts (kitendakazi kisicho na athari):

• start() — hurekodi wakati ombi lilipoanza.
• onFirstChunk() — hurekodi TTFT.
• onChunk(n) — hukusanya idadi ya tokeni za ukamilishaji.
• finish(usage?) — hukokotoa vipimo vya mwisho: ttftMs, totalMs, tps, tokensIn, tokensOut, costUsd.
• Bei kutoka kwenye jedwali tuli katika src/lib/playground/types.ts (limewekewa lebo "imekadiriwa" — D13).

---

Route za Backend

Mbinu	Njia	Kishughulikiaji
POST	/api/playground/improve-prompt	Huthibitisha ImprovePromptRequestSchema kwa Zod; huita /v1/chat/completions kwa meta-prompt
GET	/api/playground/presets	Hurejesha { presets: PlaygroundPresetListItem[] }
POST	/api/playground/presets	Huunda mpangilio awali; huthibitisha PlaygroundPresetCreateSchema
GET	/api/playground/presets/:id	Hurejesha mpangilio mmoja awali au 404
PUT	/api/playground/presets/:id	Usasishaji wa sehemu
DELETE	/api/playground/presets/:id	204

Uthibitishaji: wa hiari (REQUIRE_API_KEY). Hitilafu kupitia buildErrorBody() (Kanuni Kali #12).

---

Faili Muhimu

Njia	Madhumuni
src/app/(dashboard)/dashboard/playground/PlaygroundStudio.tsx	Kijenzi cha gamba, kipangaji wa vichupo
src/app/(dashboard)/dashboard/playground/components/StudioTopBar.tsx	Vichupo + kihesabu + kitufe cha kuhamisha
src/app/(dashboard)/dashboard/playground/components/StudioConfigPane.tsx	Paneli ya usanidi inayoshirikiwa
src/app/(dashboard)/dashboard/playground/components/tabs/ChatTab.tsx	Eneo la kazi la gumzo
src/app/(dashboard)/dashboard/playground/components/tabs/CompareTab.tsx	Ulinganishaji wa modeli nyingi
src/app/(dashboard)/dashboard/playground/components/tabs/ApiTab.tsx	Kihariri cha Monaco (kimehifadhiwa)
src/app/(dashboard)/dashboard/playground/components/tabs/BuildTab.tsx	Zana + matokeo yaliyopangwa
src/app/(dashboard)/dashboard/playground/components/ExportCodeModal.tsx	Dirisha ibukizi la kuhamisha msimbo
src/app/(dashboard)/dashboard/playground/components/CompareColumn.tsx	Safu moja ya ulinganishaji
src/app/(dashboard)/dashboard/playground/components/ProviderMetrics.tsx	Onyesho la TTFT/TPS
src/app/(dashboard)/dashboard/playground/hooks/useStreamMetrics.ts	Hooki ya vipimo ya upande wa mteja
src/app/(dashboard)/dashboard/playground/hooks/usePresets.ts	Hooki ya CRUD ya mipangilio iliyotayarishwa
src/app/(dashboard)/dashboard/playground/hooks/useImprovePrompt.ts	Hooki ya kuboresha kidokezo
src/lib/playground/codeExport.ts	Kizalishaji cha curl/Python/TS (kinashirikiwa na Zana za Utafutaji)
src/lib/playground/promptImprover.ts	Kiundaji cha kidokezo-meta
src/lib/playground/streamMetrics.ts	Ukokotoaji halisi wa vipimo
src/lib/db/playgroundPresets.ts	Moduli ya DB (CRUD)
src/app/api/playground/improve-prompt/route.ts	Njia ya REST ya kuboresha kidokezo
src/app/api/playground/presets/route.ts	Orodha ya mipangilio iliyotayarishwa + kuunda
src/app/api/playground/presets/[id]/route.ts	Kupata/kusasisha/kufuta mipangilio iliyotayarishwa
src/lib/db/migrations/084_playground_presets.sql	Uhamishaji wa DB

---

Utatuzi wa Matatizo

Dalili	Sababu	Suluhisho
Kihariri cha Monaco hakionekani kwenye kichupo cha API	SSR ilipakia Monaco	Thibitisha kuwa ApiTab inatumia dynamic(..., { ssr: false })
Mitiririko ya ulinganishaji inaanza kwa mfuatano	Matumizi yasiyo sahihi ya Promise.all	Uanzishaji wote wa mitiririko lazima utumwe katika mwito mmoja wa Promise.all
Vipimo vinaonyesha TTFT ya null	Kishughulikiaji cha sehemu ya kwanza hakijaunganishwa	Hakikisha useStreamMetrics.onFirstChunk() inaitwa ndani ya kitanzi cha kisomaji cha SSE
Mipangilio iliyowekwa awali haihifadhiwi	Uhamishaji wa DB haujaendeshwa	Endesha npm run db:migrate au anzisha upya seva (uhamishaji huendeshwa kiotomatiki wakati wa kuanza)
Uboreshaji wa kidokezo unarudisha 502	Modeli haijawekwa katika Config	Mtumiaji lazima aweke jina la modeli katika kidirisha cha Config kabla ya kuboresha
Msimbo wa kuhamisha unaonyesha MISSING_API_KEY	Kishikilia nafasi hakijaingizwa	codeExport.ts hutumia daima API_KEY_PLACEHOLDER = "$OMNIROUTE_API_KEY"

---

Marejeleo

• Mpango mkuu: _tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md
• Mpango wa kipengele: _tasks/features-v3.8.6/refactorpages/17-playground-studio-redesign.plan.md
• Uhamishaji wa msimbo: src/lib/playground/codeExport.ts
• Kiboreshaji cha kidokezo: src/lib/playground/promptImprover.ts
• Search Tools Studio: docs/frameworks/SEARCH_TOOLS_STUDIO.md