Skip to main content

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) 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: 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 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.

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.
  • 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

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.