Reconcile Meeting Assistant architecture with Meeting Lab

2026-08-23 20:19:47 +02:00
parent e028f1c82c
commit 490d557cb3
12 changed files with 462 additions and 605 deletions
@@ -0,0 +1,94 @@
+# ADR 0011: Use Meeting Lab as the MVP Processing Backend
+
+## Status
+
+Accepted
+
+Supersedes ADR 0002 and amends ADRs 0001 and 0003.
+
+## Context
+
+Meeting Lab experiments have validated a practical local pipeline for turning
+a recorded meeting into an editable protocol. Earlier Meeting Assistant plans
+selected `faster-whisper`, treated diarization as required and described a
+separate knowledge-extraction stage as part of the primary pipeline. Work on an
+old feature branch also proposed mandatory fixed five-minute audio chunks and
+chunk-oriented storage.
+
+The validated backend now has a reusable Python API, optional diarization and a
+direct full-transcript protocol path. The product boundary must keep backend
+processing in Meeting Lab and user interaction in Meeting Assistant.
+
+## Decision
+
+Meeting Lab is the reusable processing backend and experimental engine.
+Meeting Assistant is the user-facing application and calls Meeting Lab through
+its Python API rather than launching its CLI as a subprocess.
+
+The MVP processing flow is:
+
+```text
+Source audio
+    -> FFmpeg preparation (mono, 16 kHz PCM WAV)
+    -> whisper.cpp transcription (large-v3-turbo)
+    -> optional pyannote.audio Community-1 diarization
+    -> direct full-transcript protocol generation
+    -> human review and editing
+```
+
+The productive path does not require fixed five-minute audio chunks. Internal
+streaming or segmentation remains an implementation detail of Meeting Lab and
+must not define Meeting Assistant's domain or storage model.
+
+Meeting Assistant integrates with these public Meeting Lab interfaces:
+
+- `MvpMeetingConfig`
+- `MvpRunResult`
+- `run_mvp_meeting(...)`
+- stage-based progress events: `preparing`, `transcription`, `diarization`,
+  `protocol_generation`, `completed` and `failed`
+
+Progress percentages are displayed only when the backend reports real
+measurable progress.
+
+`MeetingContext` is the structured input containing meeting metadata and
+participants. It may contain explicitly confirmed `SPEAKER_XX -> participant_id`
+mappings. Such mappings are authoritative only when confirmed by the user.
+The system must not infer speaker names automatically.
+
+The preferred local engines are:
+
+- `whisper.cpp` with `large-v3-turbo` for transcription
+- `pyannote.audio` Community-1 for optional diarization
+
+GPU acceleration is optional. Vulkan transcription and PyTorch/ROCm
+diarization are validated acceleration paths on North's AMD RX 9070. CPU
+execution remains the compatibility fallback.
+
+The direct full-transcript protocol path is the practical MVP direction.
+`qwen3.8:27B` has produced strong readability and contextual synthesis, while
+`qwen3.6:35B-A3B` has sometimes behaved more conservatively. Dual-model and
+diarization-assisted hard-fact experiments have not established sufficiently
+reliable attribution gains to justify mandatory MVP complexity. Model choice
+remains backend configuration, and human review is required.
+
+Meeting Assistant owns the GUI, structured context editor, participant and
+speaker-mapping controls, progress presentation, protocol editor and export.
+Meeting Lab owns audio preparation, transcription, diarization, orchestration
+and protocol-generation logic.
+
+The product should ultimately provide a detailed contextual protocol and a
+shorter participant/distribution version. The shorter version may follow the
+first GUI milestone.
+
+## Consequences
+
+- ADR 0002's `faster-whisper` selection is no longer current.
+- Fixed-duration chunking and chunk-centric storage are not MVP requirements.
+- Diarization and GPU acceleration remain optional.
+- The Meeting Lab CLI remains useful for command-line operation but is not the
+  application integration boundary.
+- Meeting Context is created through the future GUI; users are not expected to
+  hand-write YAML.
+- Backend experiments can evolve without moving processing logic into the GUI.
+- Protocols remain AI-assisted outputs that require human review.