# 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.