effect-uai

Use when the user is upgrading effect-uai across versions, sees compile errors after a version bump, or asks Claude to "update my effect-uai code to the latest". Encodes per-version rename tables and behavior changes so Claude can rewrite call sites mechanically without re-reading the changelog each time.

Use when building AI agents and AI media workflows with effect-uai (Effect-based primitives for agent loops, tools, streaming, structured output, embeddings, speech, and music generation). Covers design philosophy, core primitives, provider wiring, and recipe skills for retry, fallback, tool approval, embeddings, transcription, speech synthesis, voice loops, music generation, SSE/JSONL, and more.

Use when the user wants a long-lived chat agent that pulls user messages from a queue, debounces typing bursts into one batch, and only checks for new input between cleanly-finished turns. Mid-task tool exchanges run uninterrupted; new messages are buffered until the next clean turn boundary.

Use when the user wants the canonical effect-uai agent loop — stream a model turn, run any tools the model asks for, append outputs, continue until the model produces a final answer. The starting shape every other recipe is a variation of.

Use when the user wants cost-aware model routing with effect-uai — start on a fast cheap model and let it escalate hard questions to a stronger model via a tool call. Covers the escalate(reason, question) descriptor, prompt-level escalation policy, onTurnComplete interception, tier_active/escalated events, and the difference from provider-failure fallback.

Use when a tool needs to emit progress, partial results, or sub-agent reasoning to the user UI in real time, while still returning one clean structured value to the model. Common cases — sub-agent text streaming, file download with progress, sandboxed exec output, long-running search.

Use when the user wants a human-in-the-loop verdict before sensitive tool calls run (send_email, delete_user, transfer_funds, etc.). Approvals can arrive synchronously bundled with the next HTTP request, or asynchronously over a long-lived queue / WebSocket. Every gated call ends up with a matching function_call_output in history regardless of verdict.

Use when the user wants text-to-speech with effect-uai from finished text — read aloud, generate audio files, notification readers, podcast snippets, or chunked TTS playback. Covers SpeechSynthesizer.synthesize, SpeechSynthesizer.streamSynthesis, AudioBlob / AudioChunk results, provider voice IDs, and OpenAI / Gemini / ElevenLabs / Inworld layers.

Use when the user wants to generate music with effect-uai — prompt to audio, background music, song drafts, Lyria 3 clips, ElevenLabs Music tracks, composition plans, C2PA / SynthID watermark handling. Covers MusicGenerator.generate, GenerateResult variants, both provider Layers (Google Lyria, ElevenLabs), and when to reach for provider-typed extras.

Use when the user wants to run untrusted code (LLM-generated scripts, user-submitted snippets, agent shell commands) inside an isolated microVM. Covers picking a provider (Microsandbox locally vs Deno Deploy hosted), provisioning a sandbox with a chosen OCI image and network policy, and executing commands. Pair with `effect-uai-streaming-tool-output` to expose a sandbox to a model as a tool.

Use when the user wants to cancel an in-flight model turn cleanly — e.g. user clicks "stop", a new prompt arrives mid-generation, a deadline elapses. The upstream HTTP connection drops via Effect's structured concurrency; partial deltas already emitted stay with the consumer.

Use when the user wants three (or more) models to answer the same question, score each other's answers (no self-judging), and emit a winner — e.g. consensus voting, audit, automated quality picking. Pure Stream composition; no Queue, no Deferred, no manual forks.

Use when the user wants to retry transient model failures (rate limits, transport hiccups, timeouts) with exponential backoff, while letting non-retryable failures (content filtered, auth, invalid request, context length) propagate immediately. Inline pipeline with no helper service.

Use when the user wants to format the loop's output for a wire transport — Server-Sent Events (browser) or JSONL (CLI pipes, queue payloads). One Stream.filterMap of Turn.toSSE / Turn.toJSONL is the entire transport layer.

Use when the user wants to transcribe a finished audio file with effect-uai — voice notes, meeting recordings, podcast clips, or batch STT. Covers the generic Transcriber service, provider-swappable sync transcription, OpenAI Whisper word timestamps, and choosing OpenAI, Gemini, ElevenLabs, or Inworld layers for file transcription.

Use when the user wants low-latency text-to-speech from incremental text with effect-uai — LLM token deltas to audio, spoken chat responses, browser playback from AudioChunk streams, or ElevenLabs / Inworld stream-input TTS. Covers SpeechSynthesizer.streamSynthesisFrom, TtsIncrementalText markers, raw PCM output formats, and piping Stream<string> into audio.

Use when the user wants live speech-to-text with effect-uai — browser microphone captions, voice search, realtime STT, partial/final transcript events, or streaming audio frames over WebSocket. Covers Transcriber.streamTranscriptionFrom, SttStreaming capability markers, provider sample-rate config, and OpenAI Realtime / ElevenLabs / Inworld streaming layers.

Use when the user wants a voice assistant with effect-uai — live microphone STT to LLM to streaming TTS, follow-up utterance queueing, stop-word interruption, browser WebSocket audio, or one-fiber-per-turn voice pipelines. Covers Transcriber.streamTranscriptionFrom, LanguageModel.streamTurn, SpeechSynthesizer.streamSynthesisFrom, Stream.share, settleBurst, Fiber.interrupt, and partial history commits.

Use when the user is worried about long conversations exceeding the context window or the input-token budget — summarize earlier history into one item once a turn / token threshold is crossed, keep the last few items verbatim, then continue. The compaction step is just another streamTurn; history is just state.

Use when the user wants to fall back from a primary provider/model to a secondary on retryable failures (rate-limited, unavailable). Reuses the same history; non-retryable failures (content filtered, auth, etc.) propagate. Tier list is plain data — add as many tiers as needed.

Use when the user wants to soft-pause the agent loop between turns (no provider call held open) and resume later — e.g. cooldown after rate-limit, manual UI pause button, scheduled gating. State threads through naturally; resume picks up exactly where pause left off, no checkpointing needed.

Use when the user wants to embed text or images with effect-uai — semantic search, RAG retrieval primitive, cross-modal cosine ranking, or late-interaction (multivector) scoring. Covers the EmbeddingModel service, the Embedding tagged union (float32 / int8 / binary / sparse / multivector), provider wiring (OpenAI text-only, Gemini multimodal, Jina sparse / multivector / binary), and Vector math primitives (cosine, sparseCosine, maxSim).

Use when the user wants typed JSON objects to appear one-by-one as the model writes them — e.g. live "search results", recipe streamer, transcoded chunks. Prompt for JSONL, frame the text stream into lines, decode each line with the schema. Errors are typed per stage.

Use when the user wants the model to return a typed JSON object (not prose) and have it validated locally — e.g. extracting a structured form, classifying input into a schema, returning a recipe / contact / event. One Effect Schema crosses the wire as JSON Schema and runs locally as the decoder.

Use when the user wants the same prompt sent to multiple providers concurrently and their tagged answers streamed side-by-side — e.g. compare reasoning quality, audit verdicts, ensemble. Per-member error isolation: a failure in one provider becomes one event, not a stream termination.