tapir/docs/specs/chat-with-transcript.md

# Spec — Chat with a video's stored transcript (ADR-027)

**Repo:** tapir · **Size:** medium · **Solo session.** Implements ADR-027. Read CLAUDE.md,
DECISIONS.md (ADR-021 transcript store, ADR-022 model chain, ADR-012 isolation, ADR-027), and
`docs/ui-spec.md` first. TBD, conventional commits, `task check` green per commit, `templ
generate` after view changes.

## FIRST: append ADR-027 to DECISIONS.md
ADR-027 text is provided separately (planning thread). Insert immediately before the
`## Rejected alternatives` heading, as the first commit, so the decision precedes the build.

## What this is
A per-video chat letting the user ask questions against a video's **already-stored** transcript,
entered from the summary view. Born from observed demand: the maintainer read real summaries and
some made him want to dig deeper — this gives that "I want more" reaction somewhere to go, without
watching the video.

## HARD CONSTRAINT — stored-transcript-only (the safety property)
Chat is available **ONLY** for videos that already have a stored transcript (ADR-021). It must
**never** trigger a caption fetch, never touch the rate gate, never reach YouTube. Entry being
"from a summarized video" guarantees the transcript exists. If somehow invoked on a video with no
stored transcript → show "transcript not available for chat", NO fetch. This is what makes the
feature safe by construction; do not add an on-demand-fetch path (explicitly deferred).

## 1. Entry point
- A "Dig deeper" / "Ask about this" affordance on the **summary view** of a summarized video
  (not the list cards — the detail/summary page). Quiet, consistent with the existing card-state
  styling.
- Opens a chat panel/view scoped to that one video, with its stored transcript as context.

## 2. The chat
- Read the stored transcript for the video (via the ADR-021 `TranscriptStore`, keyed by
  `(provider, provider_video_id)`). No fetch.
- Send transcript + the user's question + minimal system framing to the chosen model via the
  **existing LiteLLM gateway** (the same client the summarizer uses — a chat is a different
  call, not a new integration).
- Stream or return the answer; render in the chat panel. HTMX/no-JS ethos — match the existing
  app (the summarize status uses HTMX polling; chat can use a simple POST-and-render or HTMX
  streaming if clean).
- **Transcript truncation:** reuse/respect `TAPIR_MAX_TRANSCRIPT_CHARS` (ADR-022) so a long
  transcript fits the model context. If truncated, the chat should be honest that it's working
  from a bounded portion (a quiet note), since answers about the tail of a long video may be
  incomplete.

## 3. Model selection (the instrumentation win)
- **Default model = the model that produced this video's summary.** (Store/lookup which chain
  model summarized it — if not already recorded, this is a small addition; if recording it is
  non-trivial, default to the chain primary and note the gap.)
- **User can switch** among the ADR-022 chain models (`phi4-mini`, `gemma4-26b`,
  `mistral-small` to start) via a simple selector in the chat panel. Switching re-runs against
  the same transcript — this is deliberate model-comparison instrumentation.
- Respect the local-first / NDA posture: if `TAPIR_CLOUD_FALLBACK_MODEL=""` (cloud disabled),
  the external model is NOT offered in the switcher — only local models. Chat must honor the same
  "content stays local" guarantee as ADR-022.

## 4. Ephemeral (v1)
- No persisted chat history. Conversation lives for the session/page. No new table, no migration.
- (Multi-turn within a session is fine — keep the running messages in the request/page state —
  but nothing is written to the DB.)

## 5. Isolation
- The transcript is shared/non-RLS (ADR-021) — fine, it's public content. But the chat is invoked
  by a user about a video **in their feed**; confirm the entry path is reachable only for the
  requesting user's own videos (the summary view is already RLS-scoped). Chat adds no new
  user-data surface (ephemeral), so there's nothing new to RLS — but the test should confirm a
  user can only open chat from their own summary view, not arbitrary video ids.

## Tests
- Chat on a video with a stored transcript → answer returned; assert NO caption-fetch / no
  YouTube call occurs (the safety property — this is the key assertion).
- Chat invoked on a video with no stored transcript → honest "not available", NO fetch.
- Model switch → re-runs against the same transcript with the selected model; cloud model absent
  from the switcher when `TAPIR_CLOUD_FALLBACK_MODEL=""`.
- Truncation honored for a long transcript; the bounded-context note shows.
- Entry is reachable only from the user's own summary view (isolation).

## Out of scope / deferred (record, don't build)
- **Persisted chat history** (per-user, RLS-scoped) — deferred until evidence anyone revisits a
  conversation.
- **Show-source / transcript-verification UI** — the natural v2 (ADR-027 records it); v1 is
  chat-only/trust-the-model. ADR-021's stored transcript makes v2 cheap when wanted.
- **On-demand fetch** for un-stored videos — would reintroduce the caption-fetch surface the
  stored-only constraint removes. Not now.
- Anything that nudges the user to return (ADR-020 — gate contamination).

## Boundaries
Stored-transcript-only (HARD). No rate-gate/fetch surface. No auth changes. No new persisted
state in v1. Reuse the existing gateway client + truncation config; don't build a new model
integration.