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.