meeting-lab/README.md

# Meeting Lab

The direct protocol uses saved Meeting Context `meeting.language`: `de` requests
German output and `en` requests English output, for plain and diarized transcripts
and protocol-only regeneration. Meeting Assistant supplies the same selection to
Whisper. Missing context/language retains German output for older runs. Effective
output language is recorded as `output_language` in protocol runtime metadata.
Transcript text, authored context, names and speaker mappings are not translated.

Experimentierumgebung zur Entwicklung eines lokalen Diskussionsanalyzers für Meetingtranskripte.

## Ziel

Das Meeting Lab dient dazu, Verfahren zur Analyse realer Meetingtranskripte zu entwickeln und zu evaluieren.

Im Mittelpunkt steht nicht die Softwarearchitektur, sondern die Frage:

> **Wie lässt sich aus einem realen Meeting möglichst zuverlässig strukturiertes Wissen extrahieren?**

Meeting Lab ist die experimentelle R&D-Umgebung fuer den zukuenftigen
*Meeting Assistant*. Es dient gleichzeitig als Forschungsplattform,
Architektur-Spielwiese, Regressionsframework, Benchmark-Umgebung und
Prototypimplementierung. Neue Ideen werden hier untersucht und gegen reale
Meeting-Beispiele validiert, bevor sie fuer das Produkt in Betracht kommen.

Der beabsichtigte Reifeprozess ist:

```text
Research idea
    ->
Meeting Lab experiment
    ->
Regression tests
    ->
Stable architecture
    ->
Meeting Assistant implementation
```

Nur ausreichend ausgereifte und verifizierte Komponenten sollen in den
Meeting Assistant uebernommen werden. Meeting Lab darf bewusst experimentelle
Ansaetze und Entwicklungszweige enthalten, die verworfen werden oder nie den
Assistant erreichen.

## Meeting Assistant und langfristige Produktentwicklung

Der Meeting Assistant ist als Produktionsanwendung vorgesehen. Seine erste
oeffentliche Beta soll auf einem stabilen Meeting-Lab-MVP basieren und eine
polierte User Experience, Installer, Konfiguration und eine produktionsreife
Pipeline bieten. Eine GUI ist optional; experimentelle Funktionen sollen
standardmaessig nicht aktiviert sein.

Meeting Lab entwickelt sich unabhaengig weiter und bleibt der langfristige
Innovationszweig. Der erwartete Transferpfad lautet:

```text
Meeting Lab Alpha
    ->
Meeting Lab Beta
    ->
Meeting Assistant Beta
    ->
Meeting Assistant Release
```

Meeting-Assistant-Releases uebernehmen damit gezielt bewaehrte Meeting-Lab-
Komponenten, waehrend der Assistant den stabilen Produktzweig bildet.

---

## Grundidee

Klassische Meeting-Zusammenfassungen versuchen, das gesamte Transkript in einem einzigen Schritt zu verstehen und zusammenzufassen.

Das funktioniert bei realen Diskussionen nur eingeschränkt, da Themen häufig

- begonnen,
- unterbrochen,
- später wieder aufgenommen,
- ergänzt oder
- relativiert

werden.

Deshalb verfolgt das Meeting Lab einen mehrstufigen Analyseansatz.

```text
Meeting
    ↓
Normalisierung
    ↓
Diskussionsblöcke
    ↓
Themensegmentierung
    ↓
Extraktion
    ↓
Deterministic Canonicalizer
    ↓
Semantic Consolidator
    ↓
Canonical Meeting Knowledge
    ↓
Arbeitsprotokoll / Verteilerprotokoll / Knowledge Objects
```

Jeder Verarbeitungsschritt löst genau eine klar definierte Aufgabe.

---

## Entwicklungsprinzipien

- Kleine, klar abgegrenzte Verarbeitungsschritte
- Ein Modul = eine Aufgabe
- Deterministische Vorverarbeitung
- Nachvollziehbare Ergebnisse
- Reproduzierbare Experimente
- Lokale Ausführung ohne Cloud-Abhängigkeit

---

## Repository-Struktur

```text
meeting-lab/
├── src/            # Quellcode
├── prompts/        # LLM-Prompts
├── experiments/    # Reproduzierbare Experimente
├── samples/        # Beispieltranskripte
├── tests/          # Tests
├── docs/           # Dokumentation
└── pyproject.toml
```

---

## Aktuelle Pipeline

```text
Whisper
    ↓
normalize_transcript.py
    ↓
chunk_transcript.py
    ↓
(segment_topics.py)
    ↓
Extraktoren
    ↓
Deterministic Canonicalizer
    ↓
Semantic Consolidator
    ↓
Canonical Meeting Knowledge
    ↓
Output-Ansichten
```

Der aktuelle Architekturmeilenstein trennt deterministische Kanonisierung der
Chunk-Extraktionen von semantischer Konsolidierung. Die Kanonisierung validiert
und normalisiert Extraktionsobjekte ohne LLM. Semantic Consolidator V0 nutzt
das lokale LLM nur fuer konservative facts-only Duplikaterkennung, erhaelt
Evidenz und erzeugt noch keine Canonical Meeting Knowledge.

Meeting Context V1 ist als manuell gepflegtes YAML-Geruest dokumentiert und
fuer die Chunk-Extraktion implementiert. Die Extraktion kann den Kontext
optional validieren, als autoritative Metadaten in den Prompt aufnehmen und
minimale Kontext-Provenienz im Extraction JSON speichern. Konsolidierung,
Canonical Meeting Knowledge und Rendering sind noch nicht daran angeschlossen.

Als akzeptierte, aber noch nicht implementierte Architektur soll Meeting
Context V2 kuenftig nicht mehr primaer manuell geschrieben werden. Nach Whisper
soll ein Entity-Detection- und User-Confirmation-Schritt unbekannte Namen und
Begriffe sichtbar machen. Bestaetigte Entitaeten werden in einer persistenten
Entity Registry als cross-meeting Wissensquelle mit stabilen internen IDs,
Anzeigenamen und Aliasen gepflegt. Aus Registry, Nutzerbestaetigungen und
Meeting-Metadaten erzeugt ein Meeting Context Builder dann das
meeting-spezifische `meeting_context.yaml`. Diese YAML-Datei bleibt der
authoritative meeting-spezifische Point of Truth und ein reproduzierbares
Input-Artefakt fuer den jeweiligen Pipeline-Lauf.

Der gemeinsame Extraktionsprompt besteht aktuell aus `common.md`,
`decisions.md` und `todos.md`. Die Todo-Regeln verlangen explizite Zuweisung,
Freiwilligenmeldung oder Annahme, bevor eine verantwortliche Person gesetzt
wird. Meeting Context kann Identitaet, Rolle, Abteilung und Anwesenheit
validieren, begruendet aber niemals Verantwortung. Entscheidungen und Todos
werden nicht aus derselben Proposition doppelt extrahiert; beides wird nur
ausgegeben, wenn eine gruppenweite Entscheidung und eine davon getrennte
Folgeaufgabe vorliegen.

Das Meeting Lab behandelt "das Protokoll" nicht mehr als ein einzelnes
Endprodukt. Das konsolidierte Meeting-Wissen ist die **Canonical Meeting
Knowledge**, also die kanonische semantische Repräsentation eines Meetings und
die Single Source of Truth für alle nachgelagerten Ausgaben.

Aus dieser Canonical Meeting Knowledge entstehen drei unabhängige
Output-Ansichten:

- Working Protocol (`working_protocol.md`, Arbeitsprotokoll): relativ vollständig, mit Kontext,
  Begründungen, Entscheidungen, Aufgaben und offenen Fragen.
- Distribution Protocol (`distribution_protocol.md`, Verteilerprotokoll): deutlich kürzer,
  ergebnisorientiert und für Kolleginnen, Management oder Stakeholder geeignet.
- Knowledge Objects, dargestellt zum Beispiel als Knowledge-base Entry
  (`knowledge_entry.md`) oder später strukturiert gespeichert, zum Beispiel als
  `knowledge_entry.json` (Wissensdatenbankeintrag).

Diese Ausgaben sind parallele Renderings desselben semantischen Modells. Das
Arbeitsprotokoll ist nicht die Quelle des Verteilerprotokolls, und das
Verteilerprotokoll ist nicht die Quelle der Knowledge Objects.

Gerenderte Protokolle sollen normalerweise in der dominanten Sprache des
Quelltranskripts beziehungsweise der konsolidierten Meeting Knowledge erstellt
werden, sofern keine explizite Ausgabesprache angefordert wurde.

---

## Projektstatus

Aktuell liegt der Schwerpunkt auf der Entwicklung eines modularen
Diskussionsanalyzers. Implementiert sind Vorverarbeitung, technisches Chunking,
lokale Chunk-Extraktion, Meeting Context V1 fuer die Extraktionsstufe,
Canonicalizer V1 als deterministische Vorbereitung der Extraktionsergebnisse
und Semantic Consolidator V0 fuer facts-only Duplikaterkennung. Canonical
Meeting Knowledge, breitere semantische Synthese, Meeting-Context-Integration
in spaetere Stufen und finale Output-View-Renderer sind geplante naechste
Schritte.

Canonicalizer V1 kann aus dem Repository heraus so ausgeführt werden:

```text
PYTHONPATH=src .venv/bin/python -m meeting_lab.consolidation.canonicalize \
  samples/whisper/meeting_speech_cleaned_chunks \
  -o /tmp/canonicalized_extractions.json
```

Semantic Consolidator V0 kann auf dem Canonicalizer-Output ausgefuehrt werden:

```text
PYTHONPATH=src .venv/bin/python -m meeting_lab.consolidation.consolidate_facts \
  samples/benchmarks/canonicalizer_v1/canonicalized_extractions.json \
  -o samples/benchmarks/semantic_consolidator_v0 \
  --model qwen3.5:9B \
  --endpoint http://127.0.0.1:11434/api/generate \
  --no-think
```

Die eigentliche Ausgabeerzeugung ist bewusst der letzte Verarbeitungsschritt.

Ein kompletter repository-nativer Referenzlauf fuer das Progeo-Benchmark kann
auf dem Linux AI-PC ohne Codex mit einem Befehl gestartet werden:

```text
python scripts/run_meeting.py \
  --input samples/real_live/progeo_meeting/progeo_whispercpp_vulkan_turbo_trimmed_converted.json \
  --context samples/real_live/progeo_meeting/meeting_context.yaml \
  --model qwen3.5:9b \
  --benchmark-label progeo_ai_pc
```

Die Linux-Einrichtung ist:

```text
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
ollama pull qwen3.5:9b
ollama list
ollama ps
```

`ollama ps` muss fuer den Referenzlauf leer sein. Details zu Voraussetzungen,
Artefakten, Windows-Beispiel und Vergleich mit dem AI-PC stehen in
`docs/run-meeting.md`.

---

## Lizenz

Noch nicht festgelegt.