> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Moderator Discourse Agent

> Live analysis of divergence, discussion intensity and pattern cards for the moderator dashboard.

## Overview

The moderator discourse agent surfaces the product North Star — **divergence & discussion intensity** — on the live moderator dashboard while the session is still running. Each round produces a `DiscourseAnalysis`:

* Pattern cards: one per claim, with communicative intent, per-device stances, items and speakers
* Divergences with opposing positions + unresolved flag, and convergences
* 0–100 discourse intensity, 0–100 interpersonal tension, and a `needs_intervention` alert
* One-line headline for the moderator

Results persist to `moderator_insights` and publish to the `kair:moderator_insight` Redis channel. The API's `moderator_insight_listener` relays them as a `discourse_insight` event on the `moderator:<session_id>` realtime topic (see [Realtime](https://docs.kair.is/platform/realtime.md)) that the dashboard already consumes. `GET /sessions/:id/discourse-insight` returns the latest stored analysis to seed the panel on load.

## How it works

1. Subscribes to `kair:chunk_transcribed` to maintain a rolling per-session transcript window, trimmed to `transcript_char_budget`.
2. On a configurable cadence (not per-utterance — the model needs time to reason), runs **one** LLM call over the window.
3. Folds the result into the session's running analysis and publishes the accumulated whole.

**One call, not two.** The canvas badges a card Split or Agreed by resolving a divergence `topic` onto a card `name`. Cards and divergences extracted by separate passes share no vocabulary and their names never line up, so both passes emit them together and every topic is anchored onto a card name afterwards (`anchor_discourse_to_cards`); topics that land on nothing are dropped.

**The analysis accumulates.** A round only ever sees the rolling window, but a claim raised twenty minutes ago and still unresolved is exactly what a moderator acts on. `fold_live_window` sums mention counts, unions items and speakers, upserts divergences by topic, and takes the newer window's reading of how a claim is being argued — so a card that started as `exploring` shows `blocking` once the room turns. The scalars do the opposite and take the newest round outright: `discourse_intensity`, `tension` and `needs_intervention` describe the room *now*, not the session's peak, so the intervention banner clears when the argument cools.

The card set is capped at `MAX_PATTERNS` (8, what the canvas renders). When it overflows, cards are ranked by how recently the room touched them, then by mention count, and the tail is evicted along with any divergence that pointed at it.

Names already on the board are fed back into the prompt each round, so a continuing argument keeps its card instead of splintering into near-duplicates.

**Run a single replica** — the running per-session analysis is held in memory, so multiple instances would produce competing writes. On restart a session's cards are reseeded from its latest `moderator_insights` row, so a redeploy mid-session does not blank the canvas.

## Group consensus

A single `agreement` score cannot tell "the room agreed" from "the room stopped
objecting" — a transcript shows public compliance and private acceptance identically, and
someone who was talked over simply stops appearing in it. For group sessions the raw score
is therefore discounted by things the transcript *can* evidence, and every discount states
its reason (`ConsensusReading.caveat`). A discounted number with no reason attached is less
honest than the naive one it replaced, so the dashboard never renders one without it.

**Per-speaker ledger.** `PatternCard.speaker_ledger` accumulates every speaker heard on a
claim, keyed on the transcript label. Unlike `device_stances`, which is only ever the
current window's reading and is replaced each round, ledger entries are *unioned*: a
speaker the newest window never mentioned keeps their entry. That is what stops a
dissenter from being deleted the moment they go quiet.

**Objections.** A speaker pushing back records an `OpenObjection` stamped with the round it
was raised. It leaves the board only as `Retracted` (the objector explicitly walked it
back) or `Addressed` (someone engaged with the substance). There is deliberately no state
for "went quiet" — silence decays the consensus score instead of resolving anything. Cards
carrying a standing objection are **pinned** past the recency cap in `prune_to_cap`, up to
`MAX_PATTERNS - 2` so a long-running dispute can never crowd out what the room is
discussing now.

**The discounts**, applied in order, each capable of writing the caveat:

1. Any unretracted objection caps the score at `open_objection_cap`.
2. Coverage — speakers heard on the claim over room size — scales it. Room size comes from
   `sessions.actual_headcount`, falling back to `planned_headcount`, then to the count of
   transcript labels (which under-counts a room sharing one microphone).
3. Dominance — how far talk time skews to one voice, measured against an even split over
   the whole session — scales it by `dominance_weight`.
4. `endorsement_kind: procedural` caps it at `procedural_cap`. "Let's move on" is agreement
   to stop discussing something, which is the opposite signal to agreement with it.
   `endorsement_kind: unclear` also caps it — this fires when only one speaker announces
   the agreement ("so we agree…", "so there is an agreement on…") without another speaker
   explicitly confirming those terms. Silence after an announcement is never confirmation.

**Talk share** (`DiscourseAnalysis.speaker_shares`) counts turns and words per label,
accumulated as chunks arrive rather than off the rolling window — the window is trimmed to
a char budget, so counting it would measure the last few minutes and call it the meeting.
It never reports seconds: `ChunkTranscribedMessage` carries a start time but no duration.

**Session shape.** The worker reads the session row once per session for `session_type` and
headcount — the only thing it needs Postgres for; it is otherwise driven entirely off
Redis. `AssemblyGroupMeeting` is always group-shaped, `Interview` never is, and a plain
`Meeting` is judged on room size against `min_group_size`. Below the threshold the
discounting does not run at all and `reading` is `None`, so 1:1 sessions behave exactly as
they did before this existed.

## Attribution mode

`DiscourseAnalysis.attribution_mode` is either `diarised` or `unattributed`. `diarised` is the historic variant name: it means the transcript carries speaker labels, whatever supplied them (Recall, a transcriber's inline tags). Whisper segments carry no labels of their own, so local-Whisper sessions are normally `unattributed`. It is decided in code from **structured** transcript lines — never by the model, and never by re-parsing rendered text.

**Detection** (`core/src/discourse/transcript.rs`): the post-session pass loads `TranscriptLine { start_ms, track, speaker, text }` (`rag/src/indexing/session_transcript.rs`), and a window is `diarised` only when at least one line has a `speaker`.

* `speaker` is set from a segment's label fields (`display_kind` / `display_letter` / `speaker_label`) and is `None` when the segment has no label. The bare `"Speaker"` that `render_display_label` falls back to is a placeholder, not a person.
* Unsegmented blobs are split on a transcriber's inline tags (`[S1]: … [S2]: …`), which are real speaker labels. Timestamp-only tags (`[42s]:`) are not speakers.
* A track name (`Kitchen mic`) is a microphone, not a person, and never makes a line attributed. With a track, a speaker label is scoped to it (`Kitchen mic · Participant A`), because labels are only unique within a track.
* The live path uses the same rule: chunks carry a `speaker_label` only when their source supplied one (there is no live diarisation). The worker builds a `TranscriptWindow` from them (`buf_as_transcript_window`), so a live round is `diarised` only when a chunk in the window has a label; otherwise it is `unattributed` and all speaker fields are stripped.

Text heuristics cannot work here: a source-supplied `Participant A` and a model-invented `Participant A` are the same string. `TranscriptWindow.speaker_labels` is the only list grounding keeps names from.

**Effect on the analysis:**

| Mode | Speaker fields | Consensus discounting |
| - | - | - |
| `diarised` | `speakers`, `device_stances`, `speaker_ledger` populated | Full discounting runs |
| `unattributed` | All speaker fields stripped by `sanitise()` after merge | Discounting skipped |

Without speaker labels there is no attribution at all: no inferred speakers and no estimated speaker count. Points are recorded as "this point was made".

## Cadence: what is live and what is not

An insight that arrives half an hour late is no use to a moderator, so the work is split by
cost rather than by feature:

| Tier | When | What |
| - | - | - |
| Deterministic | every round, no LLM | talk share, dominance, coverage, ledger accumulation, objection pinning, the discounts |
| Same existing call | every round, \~free | `endorsement_kind` — one extra field on the prompt already being sent |
| Reconciliation | `reconcile_seconds`, or a natural pause | have standing objections actually been settled |

Only reconciliation adds a model call, roughly one per session per ten minutes against the
existing one per round. It exists because the rolling window cannot answer the question: an
objection raised twenty minutes ago is not in the window, so the per-round pass has no way
to tell a resolved dissent from one that merely scrolled out of view. It is handed the
standing objections explicitly and judges the recent transcript against them, and the
prompt refuses the inference that matters most — silence is not resolution, and when in
doubt the verdict is `open`.

A natural pause is the room falling quiet for `pause_seconds` (which must sit below
`staleness_seconds`, or the session is already being skipped by then). It is the cheapest
moment to spend a call, since nothing new is arriving to analyse.

## Concern alerts

Live concern detection substring-matches each transcript chunk against the workspace's
concerns. Every hit is written as a `concern_appearance` — that is the analytic record —
but the realtime feed is throttled: a concern alerts on first mention, then goes quiet for
`ALERT_COOLDOWN` (180 s), re-firing when that expires or when its hit count crosses one of
`ESCALATE_AFTER` (3, then 10). Both are constants in the listener rather than YAML — make
them configurable when a deployment actually needs different values. The event carries `occurrence` and `escalation` so the dashboard bumps
a count on the existing row instead of stacking duplicates, and recurrence reads as *this
keeps coming up* rather than as more noise. The state is held in process, which is correct
here: `moderator_subscribers` is in-process too, so a dashboard is attached to exactly one
replica.

## Session practices

When a session has practices selected, `compose_pattern_block` from `kair_voice_core::practice` is passed into:

* **Live windows** — `build_live_discourse_prompt(..., practice_block)` in the moderator worker (`session_practice_block` loads rows from `session_practices`).
* **Post-session synthesis** — the same block plus `compose_output_schema` for `practice_outputs` in `PatternSynthesiser`.

Work items are produced only post-session (Product Feature). Live rounds receive the pattern directive only. With **no** practices, prompts stay byte-identical to the pre-practices baseline (see `practice::evaluation` and `discourse::prompts` tests).

Reference scoring for practice outputs is separate from `eval-discourse`; see [Session practices](https://docs.kair.is/platform/session-practices).

## Relationship to post-session synthesis

After the `topic_graph` job finishes, `PatternSynthesiser` (a `pattern_synthesis` job in the rag worker) re-reads the whole attributed transcript and merges onto whatever the live pass accumulated (`merge_synthesis_analysis`). Both passes run the same extraction (`kair_voice_rag::discourse_extraction`) and the same card vocabulary (`kair_voice_core::discourse::prompts`), so their cards merge rather than duplicate. A post-hoc pass never raises `needs_intervention` — intervention is a statement about a room that is still talking.

The `DiscourseAgent` exposes two methods that wrap this path:

* `synthesise(window, known_cards, session_id)` — takes a `TranscriptWindow`, builds the synthesis prompt, runs extraction, returns `(DiscourseAnalysis, raw_output, prompt)`.
* `merge_and_sanitise(live, synthesis)` — calls `merge_synthesis_analysis` then `sanitise()`. Stripping is the chokepoint: `sanitise` enforces attribution mode on the merged result, so speaker fields can never leak into an unattributed analysis regardless of what the synthesis pass returned.

These are used directly by the eval harness (`eval-discourse`) to exercise the post-session path in the same way `PatternSynthesiser` does in production.

## Evaluation harness

`eval-discourse` replays fixtures (`api/crates/moderator-agent/eval/fixtures/`) through both paths with a real model: live rolling windows folded as the worker does, then post-session synthesis merged onto the live result and sanitised. It checks each stage separately.

```bash theme={null}
cd api/crates/moderator-agent
CONFIG_FILE=../../config.local.yml EVAL_AGENT_CLIENT=ionos EVAL_N=5 \
  EVAL_EXPORT_DIR=../../../.context/eval-runs cargo run --bin eval-discourse -- eval/fixtures/*.json
```

* `CONFIG_FILE` resolves provider, model and key the way the worker does, so credentials never go in env vars. Without it, `EVAL_AGENT_CLIENT` / `EVAL_AGENT_MODEL` / `EVAL_AGENT_BASE_URL` / `EVAL_AGENT_API_KEY` apply.
* Each run exports prompts, raw outputs and persisted analyses to a timestamped subdirectory of `EVAL_EXPORT_DIR`.
* `EVAL_LIVE_STEP_CHARS` (default 1500) sets how much new transcript arrives between live rounds, so short fixtures still exercise card-name continuity.
* Fixtures declare `format` (`segments` | `inline_blob` | `unlabelled`), which decides attribution exactly as production would, and `source` (`real` | `synthetic`), reported in separate tables. Topic expectations match by keyword, never by exact card name, so a prompt that leaks a fixture's wording cannot pass for the wrong reason. The harness also fails a fixture whose text appears in a prompt template.
* The table's spreads (min/mean/max over N samples) are of the persisted synthesis result. Tension routinely spans 30+ points on the same transcript, so treat it as a coarse signal, not a threshold.

## Configuration

```yaml theme={null}
moderator_agent:
  enabled: false           # opt-in; off by default; worker idles when disabled
  agent_client: ollama     # which ai_inference provider to use
  model: "gemma4:e2b"
  cadence_seconds: 30      # how often to run analysis per active session
  staleness_seconds: 120   # skip analysis if no new transcript in this window
  transcript_char_budget: 8000
  num_ctx: 16384           # Ollama only; cloud providers size their own context
  max_tokens: 8192
  temperature: 0.2
  enable_thinking: false   # OpenAI-compatible agent_client (e.g. ionos) only
```

Connection details (base URL, API key) come from the shared `ai_inference` config; normally only `agent_client` and `model` need setting.

`enable_thinking` (default `false`, i.e. thinking off) governs any OpenAI-compatible
`agent_client` (e.g. IONOS) — `reasoning_effort` alone does not
reliably silence hidden chain-of-thought on vLLM-hosted reasoning models.

`max_tokens` matters: one round returns the full card set *plus* its divergences and convergences, and a truncated response fails JSON parsing — losing the whole round, silently.

Config resolver: `api/crates/moderator-agent/src/settings.rs`.

`trace_extractions` (default **off** in production and development, **on** in staging when omitted) controls whether full prompts and raw model output are written to `moderator_extraction_traces`. Post-session synthesis in `rag-worker` honours the same flag. `trace_retention_days` is enforced by an hourly delete sweep in `rag-worker`.

Row-level security on `moderator_extraction_traces` allows only `rag-worker` and `moderator-agent-worker` pools (`app.db_role`). The API has no policy on that table; session deletes still cascade trace rows. Set `database.url` to a direct or session-pooled connection so libpq startup `options` apply (`app.db_role` is a misconfiguration guard, not a privilege boundary).

## Implementation

Worker crate: `api/crates/moderator-agent` (`kair-voice-moderator-agent-worker`)
Extraction & reconciliation: `api/crates/rag/src/discourse_extraction.rs`
Prompts, types, folding: `api/crates/core/src/discourse/`
Consensus discounting: `api/crates/core/src/discourse/consensus.rs`
Concern alert throttling: `api/crates/api/src/util/pattern_alert_listener.rs`

The client mirrors two of these deliberately: `mergeSpeakerLedger` and `topicKeysMatch` in
`ui/src/lib/patterns/patternCard.ts` must stay in step with `merge_speaker_ledger` and
`card_keys_match` in `core`, or the browser will undo the server's fold.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.