meeting-lab/docs/meeting-context.md

Meeting Context V1

Purpose

Meeting Context V1 is a manually maintained YAML file for reliable meeting metadata. It gives later pipeline stages known names, aliases, organizational terms and vocabulary without asking an LLM to infer them from a transcript.

The context is authoritative only for metadata that is explicitly supplied in the file. It must not be used to infer responsibilities, decisions or commitments.

Scope

V1 is implemented for loading, validation and optional injection into the chunk extraction prompt. It is not yet integrated with the Canonicalizer, Semantic Consolidator, Canonical Meeting Knowledge or output renderers.

Supported metadata:

• meeting title, language, date, objective and notes
• actual participants and participant aliases
• participant role and department when known
• known non-participants mentioned during the meeting
• known departments and aliases
• abbreviations
• relevant products, projects, systems, locations and technical terms

Future Direction: V2

Accepted Architecture. Implementation deferred.

Meeting Context V2 should be generated from an interactive entity confirmation workflow after Whisper transcription:

Whisper
    ↓
Entity Detection
    ↓
User Confirmation
    ↓
Entity Registry Update
    ↓
Meeting Context Builder
    ↓
meeting_context.yaml
    ↓
Extraction Pipeline

The YAML remains the extraction interface and the authoritative meeting-specific Point of Truth for a meeting run. It should become a meeting-specific snapshot generated or assisted from the Entity Registry, user confirmations and meeting metadata.

The Entity Registry is the persistent cross-meeting knowledge source for confirmed entities, aliases and organizational metadata. It stores stable internal identifiers and never learns automatically. The Registry must not override explicit meeting-specific confirmations, and Registry changes after a meeting run must not silently change the historical Meeting Context used for that run.

Unknown names should be explicitly classified by the user as meeting participant, mentioned person, external person, transcription error or ignore. Similarity suggestions for spelling variants, Whisper variants, umlaut handling and OCR-like mistakes require explicit confirmation.

See docs/adr-meeting-context-v2-entity-registry.md.

File Locations

• Generic template: samples/templates/meeting_context.template.yaml
• Real-Life Sample context: samples/real_live/project_process_meeting/meeting_context.yaml
• Future meeting-specific contexts should live next to the meeting input data.

Field Descriptions

schema_version: Version of the Meeting Context file shape.

meeting.title: Required for future GUI entry. Human-readable meeting title.

meeting.meeting_id: Required stable meeting identifier used for extraction context provenance.

meeting.language: Required for future GUI entry. Dominant meeting language, for example de or en.

meeting.date: Optional ISO date or null.

meeting.objective: Optional objective entered by the user.

meeting.notes: Optional neutral notes about context or scope.

participants: Actual meeting attendees. Participant names are required for future GUI entry.

participant_id: Stable identifier. It should not change when display names or aliases are corrected.

display_name: Preferred display name.

aliases: Alternative spellings, short forms or Whisper variants.

role: Organizational function. Optional and nullable.

department: Organizational unit. Optional and nullable.

attendance_status: exactly present for participants or mentioned_only for people who are relevant but did not attend. For backward compatibility, a missing status defaults to present in participants and mentioned_only in mentioned_people.

mentioned_people: People discussed or referenced but not present. They are not participants and must not be treated as speakers.

organization.name: Optional organization name.

organization.departments: Known departments with stable ids, names and aliases.

organization.abbreviations: Known abbreviation expansions. Empty strings mean the expansion is not yet confirmed.

known_entities: Meeting vocabulary for projects, products, systems, locations and technical terms. These lists do not imply responsibility.

context_rules: Conservative defaults for later integrations.

Filled Example

schema_version: "1"

meeting:
  title: "Projektprozess fuer neue Initiativen"
  language: "de"
  date: "2026-08-01"
  objective: "Klaeren, wie der bestehende Projektprozess angepasst wird."
  notes: ""

participants:
  - participant_id: "martin"
    display_name: "Martin"
    aliases: ["Martin T."]
    role: null
    department: null
    attendance_status: "present"
    notes: null

mentioned_people:
  - person_id: "alex"
    display_name: "Alex"
    aliases: []
    role: null
    department: null
    attendance_status: "mentioned_only"
    notes: "Wurde erwaehnt, war aber nicht anwesend."

organization:
  name: null
  departments:
    - id: "pm"
      name: "PM"
      aliases: ["Projektmanagement"]
  abbreviations:
    PM: "Projektmanagement"
    BD: "Business Development"
    MK: ""
    GF: ""

known_entities:
  projects: []
  products: []
  systems: []
  locations: []
  technical_terms: ["Lastenheft"]

context_rules:
  participant_list_is_authoritative: true
  do_not_infer_roles: true
  do_not_infer_departments: true
  do_not_infer_responsibilities: true
  mentioned_people_are_not_participants: true

Concept Distinctions

Participant: a person who actually attended the meeting.

Mentioned person: a person discussed or referenced but not present.

Speaker: transcript-level attribution, which may be unknown or unreliable.

Responsible person: a person explicitly assigned to or accepting an action item.

Role: the person's organizational function.

Department: the organizational unit to which the person belongs.

These concepts must never be collapsed automatically. A participant may discuss a topic outside their own department. Discussing, objecting to or suggesting work does not establish responsibility.

Editing Guidance

Enter only objective context that is known independently or confirmed by the user. Do not guess uncertain names, roles, departments or abbreviation expansions. Leave unknown values as null, an empty string or an empty list.

Use aliases for spelling variants, shortened names and Whisper variants. Keep stable ids unchanged after a context file has been used in experiments.

Do not copy responsibilities from generated protocols into Meeting Context. Responsibilities belong to evidence-backed extraction and later action-item models, not to this metadata file.

Extraction Integration

The chunk extraction CLI accepts an optional Meeting Context file:

PYTHONPATH=src .venv/bin/python -m meeting_lab.extraction.extract_chunks \
  samples/chunks/chunk_01_normalized.txt \
  -o /tmp/chunk_01_extraction.json \
  --meeting-context samples/real_live/project_process_meeting/meeting_context.yaml

When supplied, the file is validated and rendered as deterministic authoritative metadata inside the extraction prompt. When omitted, prompt construction and extraction output remain unchanged.

The shared extraction prompt is assembled from:

• common.md
• decisions.md
• todos.md

Extraction JSON receives only minimal context provenance:

{
  "context": {
    "meeting_id": "2026-07-27-projektprozess",
    "source_file": "samples/real_live/project_process_meeting/meeting_context.yaml",
    "schema_version": "1"
  }
}

Full personal metadata is not copied into every extraction result.

Meeting Context loading uses PyYAML when installed. PyYAML>=6.0 is declared as a project dependency.

Prompt Behavior

Meeting Context validates identity, role, department and attendance, but never establishes responsibility.

The todo prompt records a named responsible person only when the transcript explicitly assigns the task, the person volunteers, or the person accepts or confirms the task. Addressing a person, requesting department input, discussing department-specific criteria, stating expertise, objecting, suggesting, or listing Meeting Context role metadata is not enough.

The decision prompt treats a personal commitment to concrete future work as a todo unless the group separately establishes a binding outcome, rule, approval, rejection, deferral, selection, process state or responsibility policy. The same proposition should not be duplicated under decisions and todos; extract both only when the transcript contains semantically separate propositions.

Validation Rules

The current validator checks that:

• YAML syntax is valid
• schema_version is supported
• meeting.meeting_id, meeting.title and meeting.language are present
• participant ids are unique and non-empty
• mentioned-person ids are unique and non-empty
• participant ids and mentioned-person ids do not collide
• referenced departments exist in organization.departments
• attendance_status values are valid
• speaker mappings reference present participants only; mentioned-only people cannot be diarized speakers
• participants are marked present
• mentioned people are not marked present

Invalid values are not inferred or repaired.

Gold Tests

Two focused Gold scenarios cover the main responsibility boundary:

• responsibility_attribution_negative: discussion, objection and department proximity must not create a named owner.
• position_explicit_objection: explicit objection extraction is tested separately as a position scenario.

Responsibility attribution and position extraction are intentionally tested independently so each scenario has unique ground truth.

Confidentiality

Meeting Context can contain real names, departments, project names and internal terminology. Treat it as confidential meeting data. Keep private sample contexts inside the private repository and avoid exposing them in screenshots, logs or generated reports.

Future GUI Entry

Future product UI should make these fields easy to enter before processing.

Required GUI fields:

• meeting title
• language
• participant names

Optional GUI fields:

• objective
• aliases
• role
• department
• mentioned non-participants
• abbreviations
• known entities
• notes

Future Pipeline Integration

Later stages may use Meeting Context to normalize names, recognize aliases, avoid treating absent mentioned people as speakers and avoid expanding abbreviations incorrectly. This later-stage integration is still planned.

Integration must remain conservative:

• Meeting Context may supply metadata only.
• It must not infer decisions.
• It must not infer responsibilities.
• It must not override source evidence.
• It must preserve uncertainty when transcript evidence is ambiguous.