Host Service: DeepSeek + TTS → atomic Programme

[zeevenn]

This was generated by AI during triage.

Parent

#39 — PRD: AI Radio — Host-driven Channel experience with chat timeline

Goal

Implement the V1 Host generation pipeline. Programme Manager supplies a CandidateSet and bounded Session Context; the Host makes one structured model-planning call, validates the plan in deterministic application code, synthesises retained Interludes, materialises playable local URIs, and atomically returns a complete Programme.

The Host is the domain abstraction. “Agent” describes its implementation style; V1 has no tool loop and does not expose Player controls.

V1 provider decisions

• Use AI SDK Core with the direct DeepSeek provider.
• Model: deepseek-v4-flash with Thinking disabled.
• Use schema-validated structured output; do not parse free-form JSON with a regular expression.
• V1 has one model provider. DeepSeek and TTS use user-owned BYOK credentials stored outside the app bundle.
• Inject TTSProvider and audio-cache boundaries. TTS returns audio bytes plus media type; the cache materialises a native file URI or Web Blob URL.
• The final TTS provider and Channel voice IDs remain gated by the Mandarin blind-listening spike.

Contracts

• ProgrammeHost.generateProgramme(request) -> Promise<Programme> receives Generation ID, generation reason, Channel, CandidateSet, bounded Session Context, optional Intervention, and AbortSignal.
• HostPlanner returns a structured HostPlan containing Track IDs and Interlude scripts.
• Versioned application-owned Host Policy defines duration, ordering, cadence, and validation rules; Channel or user text cannot override it.
• TTSProvider accepts an Interlude script, Host Voice ID, and AbortSignal, and returns bytes plus media type.
• InterludeAudioCache materialises and removes generated audio artifacts.

Programme rules

• Target 30–45 minutes instead of a fixed Track count; a small CandidateSet may produce a shorter Programme.
• Select only CandidateSet Tracks and never repeat a Track within one Programme.
• Programme Manager deterministically withholds recently used/current Programme Tracks and reintroduces the least recent Tracks only when needed for sufficient duration.
• Channel entry and Intervention may start with at most one opening/acknowledgement Interlude. Background refill must not have an opening Interlude.
• Transition Interludes follow every 2–3 Tracks according to Host Policy, and a Programme cannot end with an Interlude.
• Track Request takes effect after the current Segment and places the requested Track first, after at most one acknowledgement Interlude.

Failure and lifecycle rules

• Invalid or empty model output receives bounded retry, then degrades to a deterministic music-only Programme.
• Each TTS failure receives bounded retry, then only that failed Interlude is omitted.
• Only the latest Generation ID may commit. AbortSignal propagates to model, TTS, and cache operations; cancellation never triggers fallback.
• Stale/cancelled generation artifacts are removed.
• Player receives only a complete Programme whose retained Interludes already have playable URIs.
• Provider diagnostics may record provider, model, and Host Policy version, but never API keys.

Acceptance criteria

• Anthropic SDK and hard-coded Claude usage are removed from Host.
• DeepSeek uses AI SDK Core, deepseek-v4-flash, Thinking disabled, and schema-validated output.
• No regular-expression JSON extraction remains.
• Domain validation rejects unknown Track IDs, duplicate Tracks, invalid Segment ordering, excessive Interlude cadence, and plans outside available duration constraints.
• Track Request, generation reason, Session Context, deterministic recency, cancellation, and stale-generation races have contract tests.
• TTS and audio-cache boundaries are injected; tests use fakes and no real credentials.
• A failed TTS Interlude is omitted without making the Programme unplayable.
• Model failure after bounded retry produces a deterministic 30–45 minute music-only fallback when enough music is available.
• BYOK credentials use secure device storage and both credentials gate Radio before provider-backed generation is enabled.
• Store tests and Store/Mobile TypeScript checks pass.

Out of scope

• Speech-to-text or microphone input
• Host control of volume, pause, or Track skipping
• Long-term memory or model-owned conversation history
• Multiple model providers or user-selectable models
• Final TTS provider selection and final voice IDs
• Flow-hosted proxy/API, server-side key custody, billing, or quotas
• Radio UI redesign and persistent chat history

References

• Radio and Store Context documents
• ADRs 0007–0018

[zeevenn]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Replace the Host prototype with the V1 Host generation pipeline agreed in the Radio Context glossary and ADRs 0007–0018.

Current behavior:
The Host prototype calls Anthropic directly, requests a fixed 5–8 Tracks, extracts a JSON array from free-form text with a regular expression, calls a URL-returning TTS interface sequentially, and has no explicit schema contract, Session Context, cancellation, or runtime degradation metadata. The mobile composition still uses a local shuffle Host instead of the provider-backed Host.

Desired behavior:
The Host remains the single domain abstraction. Programme Manager supplies a CandidateSet and bounded Session Context; one DeepSeek planning call returns a structured plan; deterministic application code validates domain rules, synthesises Interludes, materialises playable cache URIs, and atomically returns a complete Programme.

The first model provider is the direct DeepSeek API through AI SDK Core using deepseek-v4-flash with Thinking disabled. V1 supports one model provider. Both DeepSeek and the selected TTS provider use BYOK credentials, and both credentials must be configured before Radio is enabled.

Programme rules:

• Target 30–45 minutes rather than a fixed Track count; a small CandidateSet may produce a shorter Programme.
• Select only input CandidateSet Tracks, never duplicate within one Programme, and apply deterministic cross-Programme recency.
• An opening/acknowledgement Interlude is allowed for Channel entry and Intervention, but not background refill.
• Interlude cadence is bounded by Host Policy to roughly one per 2–3 Tracks.
• A Track Request takes effect after the current Segment and must be the first Track in the replacement Programme, after at most one acknowledgement Interlude.

Failure and lifecycle rules:

• Invalid/empty model output receives bounded retry, then degrades to a deterministic music-only Programme.
• Each TTS failure receives bounded retry, then only that Interlude is omitted.
• TTS produces audio bytes and media type; an audio-cache boundary materialises native cache-file URIs or Web Blob URLs.
• Only the latest Generation ID may commit. Abort signals propagate to model, TTS, and cache operations; cancelled generations never trigger fallback.
• The Player receives only complete Programmes whose retained Interludes already have playable URIs.

Key interfaces:

• ProgrammeHost — accepts an explicit generation request containing Channel inputs, CandidateSet, Session Context, generation reason, optional Intervention, and cancellation signal; resolves to a complete Programme.
• Host Policy — versioned application-owned constraints and structured-output schema; Channel/user data cannot override it.
• TTSProvider — accepts an Interlude Script, Host Voice, and cancellation signal; returns generated audio bytes plus media type rather than a remote URL.
• Audio cache boundary — materialises generated audio as a playable URI and cleans stale Generation artifacts.
• Provider diagnostics — records provider/model/Host Policy version without logging API keys.

Acceptance criteria:

• Anthropic SDK and hard-coded Claude model usage are removed from the Host implementation.
• DeepSeek uses AI SDK Core with deepseek-v4-flash, Thinking disabled, and schema-validated output.
• No regular-expression JSON extraction remains.
• Domain validation rejects unknown Track IDs, duplicate Tracks, invalid Segment ordering, excessive Interlude cadence, and plans outside the available duration constraints.
• Track Request, generation reason, and Session Context rules above have contract tests.
• TTS and audio-cache boundaries are injected; tests use fakes and contain no real credentials.
• TTS failure produces a playable Programme with only the failed Interlude removed.
• Model failure after bounded retry produces a deterministic 30–45 minute music-only fallback.
• Cancellation and stale-generation races are covered; only the latest generation can commit.
• Programme Manager passes entry/intervention/refill context and deterministic Track recency to the Host.
• Store tests and TypeScript checks pass.

Out of scope:

• Speech-to-text or microphone input
• Host control of volume, pause, or Track skipping
• Long-term user memory or model-owned conversation history
• Multiple model providers or user-selectable models
• Final TTS provider selection and voice IDs, which remain gated by the Mandarin blind-listening spike
• Flow-hosted proxy/API, server-side key custody, usage billing, or quotas
• Radio UI redesign and persistent chat history