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 aDiscourseAnalysis:
- 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_interventionalert - One-line headline for the moderator
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) that the dashboard already consumes. GET /sessions/:id/discourse-insight returns the latest stored analysis to seed the panel on load.
How it works
- Subscribes to
kair:chunk_transcribedto maintain a rolling per-session transcript window, trimmed totranscript_char_budget. - On a configurable cadence (not per-utterance — the model needs time to reason), runs one LLM call over the window.
- Folds the result into the session’s running analysis and publishes the accumulated whole.
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 singleagreement 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:
- Any unretracted objection caps the score at
open_objection_cap. - Coverage — speakers heard on the claim over room size — scales it. Room size comes from
sessions.actual_headcount, falling back toplanned_headcount, then to the count of transcript labels (which under-counts a room sharing one microphone). - Dominance — how far talk time skews to one voice, measured against an even split over
the whole session — scales it by
dominance_weight. endorsement_kind: proceduralcaps it atprocedural_cap. “Let’s move on” is agreement to stop discussing something, which is the opposite signal to agreement with it.endorsement_kind: unclearalso 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.
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.
speakeris set from a segment’s label fields (display_kind/display_letter/speaker_label) and isNonewhen the segment has no label. The bare"Speaker"thatrender_display_labelfalls 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_labelonly when their source supplied one (there is no live diarisation). The worker builds aTranscriptWindowfrom them (buf_as_transcript_window), so a live round isdiarisedonly when a chunk in the window has a label; otherwise it isunattributedand all speaker fields are stripped.
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:
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:
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 aconcern_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_blockloads rows fromsession_practices). - Post-session synthesis — the same block plus
compose_output_schemaforpractice_outputsinPatternSynthesiser.
practice::evaluation and discourse::prompts tests).
Reference scoring for practice outputs is separate from eval-discourse; see Session practices.
Relationship to post-session synthesis
After thetopic_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 aTranscriptWindow, builds the synthesis prompt, runs extraction, returns(DiscourseAnalysis, raw_output, prompt).merge_and_sanitise(live, synthesis)— callsmerge_synthesis_analysisthensanitise(). Stripping is the chokepoint:sanitiseenforces attribution mode on the merged result, so speaker fields can never leak into an unattributed analysis regardless of what the synthesis pass returned.
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.
CONFIG_FILEresolves 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_KEYapply.- 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, andsource(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
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.