docs/decisions.md

# Decisions

## ADR-001: Use FastAPI Instead of Streamlit

Date: 2026-06-08

Decision: Agent Tina remains a FastAPI app served by Uvicorn.

Reasoning:

- The current app is already implemented with FastAPI routes and Jinja templates.
- Browser recording and file upload flows are straightforward with the existing frontend.
- Docker deployment to Hugging Face Spaces works cleanly with Uvicorn on port `7860`.

Consequence:

- Run locally with `.\run.ps1` or `python -m uvicorn app:app`.
- Do not use `streamlit run app.py`.

## ADR-002: Use Whisper `base` by Default

Date: 2026-06-08

Decision: Default `WHISPER_MODEL` is `base`.

Reasoning:

- `base` should improve transcription accuracy compared with `tiny`.
- It remains small enough for CPU-based deployment experiments.

Consequence:

- First transcription may take longer because the model must be downloaded and loaded.
- The model remains configurable through `WHISPER_MODEL`.

## ADR-003: Use Participant Name Labels Before Voice Detection

Date: 2026-06-08

Decision: Multi-device collaboration should first use participant-entered name labels, not automatic voice detection.

Reasoning:

- Each participant joining from their own device gives a reliable identity signal.
- Speaker diarization is slower, more complex, and less reliable on free/basic CPU Spaces.
- Name labels avoid requiring extra model tokens or diarization-specific infrastructure.

Consequence:

- Each upload/recording segment will be tagged with participant name, meeting id, timestamp, and recording mode.
- Automatic speaker detection can be revisited later as an optional feature.

## ADR-004: Use One Room Recorder for In-Person Meetings

Date: 2026-06-08

Decision: In single-room meetings, prefer one device marked `Room Recorder`.

Reasoning:

- Multiple microphones in the same room capture overlapping audio.
- Overlap causes duplicate transcript lines and misleading speaker labels.
- One room recorder gives a cleaner source of truth.

Consequence:

- The UI should offer recording modes:
  - `Room Recorder`
  - `Personal Mic`
- The app should warn users when multiple people record from the same physical room.

## ADR-005: Persist Meeting Outputs as Markdown

Date: 2026-06-08

Decision: Save meeting outputs as Markdown files.

Reasoning:

- Markdown is easy to review, edit, version, export, and store.
- It works well with Obsidian and Git-style workflows.

Consequence:

- Planned files per meeting:
  - `raw_transcript.md`
  - `corrected_transcript.md`
  - `minutes.md`
  - `metadata.json`

## ADR-006: Keep Documentation Updated Explicitly

Date: 2026-06-08

Decision: Any meaningful product, deployment, architecture, or workflow change must update the relevant docs in `docs/`.

Reasoning:

- Agent Tina is evolving from a simple recorder into a collaborative MoM workflow.
- Decisions can otherwise get lost in chat history.

Consequence:

- Update `docs/progress.md` after implementation milestones.
- Update `docs/decisions.md` when a durable decision is made.
- Update workflow or architecture docs when behavior changes.

## ADR-007: Use Host-Created Meeting Sessions

Date: 2026-06-08

Decision: Agent Tina should use host-created meeting sessions with a shared participant join link and a private host link.

Reasoning:

- Meeting sessions are necessary to group multiple participant recordings.
- A host key is enough for the MVP and avoids building login too early.
- Participants only need a meeting link and name label to contribute.

Consequence:

- Backend needs meeting creation, segment upload, host dashboard, and final MoM generation routes.
- Meeting data must be stored server-side.
- Later persistence should move to a Hugging Face Dataset repo.

## ADR-008: Defer Voice Enrollment and Diarization

Date: 2026-06-08

Decision: Voice enrollment, diarization, and automatic speaker identity are deferred until after the labelled meeting workflow is stable.

Reasoning:

- Speaker identification is slower, less reliable, and privacy-sensitive.
- Hugging Face CPU Spaces may not be suitable for it.
- Room Recorder plus explicit attendee context is more reliable for the MVP.

Consequence:

- Room Recorder transcripts must avoid fake attribution.
- Speaker intelligence can be explored later as an experimental feature.

## ADR-009: Use Separate Models for Correction and MoM

Date: 2026-06-09

Decision: Use `openai/gpt-4o-mini` for transcript correction and `openai/gpt-oss-20b` for MoM generation.

Reasoning:

- The reasoning-heavy MoM model consumed correction output tokens without reliably returning a full corrected transcript.
- The correction model preserved approximately 97.7% of the verified AAC sample transcript in one call.
- Correction failures and excessive content loss now fall back to the raw transcript.

Consequence:

- Configure `OPENROUTER_CORRECTION_MODEL` separately from `OPENROUTER_MODEL`.
- Transcript correction must remain faithful and must not summarize.

## ADR-010: Keep Meeting Dataset Private

Date: 2026-06-09

Decision: The Hugging Face Dataset containing meeting metadata, transcripts, Markdown, host keys, and original recordings must be private.

Reasoning:

- Meeting audio and transcripts are sensitive.
- Host keys must not be publicly accessible.

Consequence:

- Deployment explicitly enforces private Dataset visibility.
- Public meeting endpoints expose meeting metadata only, not segments or outputs.

## ADR-011: Optimize for Long Room Recordings

Date: 2026-06-09

Decision: Treat long, multi-speaker Room Recorder audio as Agent Tina's primary workload.

Reasoning:

- The verified production-like sample is a roughly 10-minute stereo AAC room recording.
- Most expected recordings will follow this pattern.
- CPU contention and long-running upload/transcription requests require explicit safeguards.

Consequence:

- In-person and Room Recorder are the UI defaults.
- Whisper transcription is serialized.
- Original audio is persisted before transcription.
- Upload size and audio metadata are validated.
- Simultaneous segment submissions merge safely.

## ADR-012: Restore Meetings Lazily from the Dataset

Date: 2026-06-09

Decision: Restore meeting metadata from the private Hugging Face Dataset on demand after Space rebuilds, and restore large recordings/Markdown files only when requested.

Reasoning:

- Space local disk is ephemeral.
- Downloading every original room recording just to load a meeting would be slow and wasteful.
- Hosts still need reliable access to older meetings and original audio.

Consequence:

- Meeting metadata restores when a meeting is opened.
- Original audio and generated Markdown restore lazily through host-only download routes.