Agent Design

Documentation Index

Fetch the complete documentation index at: https://docs.litigationlabs.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Shared Infrastructure

• State primitives — CourtroomSession, Scenario, CourtEvent, AgentConfig, and related Zod schemas live in lib/courtroom/types.ts.
• Turn entry point — handleTurn in lib/courtroom/orchestrator.ts accepts { session, scenario, userUtterance } and returns { events, updatedSession }.
• Gateway — callAgentThroughGateway (lib/courtroom/gateway.ts) streams completions from the Vercel AI Gateway.
• Prompt builders — lib/courtroom/prompts.ts holds helper functions for OCA, Judge, and Witness prompts.
• Scoring — computeScoreDeltaFromAnswer increments score metrics based on unlocked witness elicits.

​

Orchestrator / Director

​

Responsibilities

• Accepts the player question and appends it to the transcript as a CourtEvent.
• Computes OCA mode (objection_mode vs. examination_mode) by examining session phase, player side, and selected witness.
• Runs the objection / judge / witness pipeline sequentially while updating session metrics and score state.
• Emits system-level fallback events when downstream agents fail.

​

Turn Sequence

1. OCA Gate — Only runs when determineOCAMode returns objection_mode. Calls buildOCSystemPrompt and parses the response through ocaObjectionResponseSchema.
2. Judge Ruling (conditional) — Triggered when OCA returns response_type === "objection". Parses JSON into { ruling: sustain | overrule, reason }. Sustained objections skip the witness call.
3. Witness Answer — Runs when no objection or the objection was overruled. Records the raw answer as a CourtEvent and invokes scoring.
4. Session Persistence — Caller (/api/courtroom/turn) persists the resulting session via saveSession.

​

Error Handling

• Each agent call is wrapped in try/catch with graceful degradation.
• JSON parsing uses safeParseJSON to tolerate LLMs that wrap JSON with commentary.
• shouldCallWitness flag prevents accidentally querying the witness when a sustained objection or error occurs.

​

Opposing Counsel Agent (OCA)

​

Modes

• Objection mode (player examining their own witness): Returns response_type: "objection" | "no_objection" with objection_type, optional rule_refs, and is_intentionally_incorrect.
• Examination mode (player objecting while OCA examines): Returns response_type: "question" with question_text, is_intentionally_defective, and optional linkages.

​

Configuration Parameters

• intentionalErrorRate — % of turns that produce intentionally incorrect objections/questions.
• objectionTypes — whitelist of admissible objection enums.
• modelOverride and temperature — switch models per agent without redeploying.

​

Judge Agent

​

Output Contract

{
  "ruling": "sustain | overrule",
  "reason": "Brief explanation citing FRE rule"
}

​

Witness Agents

​

Responsibilities

• Role-play a specific witness using their affidavit, tendencies, and elicits.
• Answer questions in natural prose (no JSON) while respecting the current phase and side alignment.

​

Output & Post-processing

• Raw text answer captured verbatim in the transcript.
• Scoring uses keyword heuristics (computeScoreDeltaFromAnswer) to award points and unlock elicits.

​

Future / Auxiliary Agents

• Director or Coach overlays — Additional agents that subscribe to CourtEvents for real-time coaching.
• Evidence Clerk — Manages exhibit foundations and ties into ocaExaminationResponseSchema.uses_exhibit_id.
• Scenario-specific agents — New agent IDs can be introduced in Payload and referenced from the orchestrator without modifying UI layers.