et-agent — full system flow

1. System topology

Three independent services in one tailnet, all on the same Hetzner host. Each has its own Postgres database. They communicate over HTTP.

2. Models in use

3. Ingestion: udcalc lead → et-agent case

A claimant fills the udcalc unfair-dismissal calculator. On submit, the lead lands in udcalc.leads (a separate database). When the claimant elects to engage et-agent for representation, a handoff is created.

Step-by-step

1. Calculator submission — frontend POSTs to PostgREST /rest/v1/leads. Row created in udcalc.leads with structured fields (dates, pay, claim_types JSONB, claim_details JSONB, evidence_scores JSONB).
2. Email handoff — claimant clicks "speak to a lawyer" → frontend POSTs to /functions/v1/sa-submit-lead (Deno). The Deno function calls Attio (CRM) and then et-agent's /intake/handoff endpoint.
3. et-agent: POST /intake/handoff creates rows in:
   • udcalc_handoffs — raw payload + claim_types snapshot
   • cases — new case row, state=pre_engagement
   • claims — one row per claim_type, is_lead_claim set on the most-valuable one (heuristic: discrimination > whistleblowing > unfair dismissal)
4. Engagement letter — operator (or claimant via portal) signs an engagement letter. State → engaged. A row in engagement_letters stores the signed PDF link + version.
5. State → evidence_gathering — triggers the intake_completion ensemble.

// HTTP
udcalc.uk frontend     →  PostgREST :5435  →  udcalc DB     (leads, sa_leads)
udcalc.uk frontend     →  Deno :8787       →  udcalc DB     (sa_submit-lead)
                                            →  Attio CRM       (deals/contacts)
                                            →  et-agent :8000  (handoff)
et-agent /intake/handoff →  asyncpg         →  et_agent DB  (cases, claims, udcalc_handoffs)

4. Intake completion ensemble

Once a case is in evidence_gathering, three triggers fire intake_orchestrator.run_intake_completion(case_id):

1. Engagement signed (one-shot).
2. Claimant sends a chat message (copilotkit on_complete).
3. Claimant uploads/links a document (/evidence/{id}/link).

The orchestrator throttles to one full run per minute per case, then loads the snapshot + history and fires the intake_completion ensemble.

Ensemble: 4 prompts in sequence

Inputs / outputs / DB touches

5. Document handling

Claimants upload PDFs (dismissal letters, grievance correspondence, contracts, payslips, medical letters). Each upload runs:

1. POST /documents stores the file in object storage (R2), creates a documents row, status=uploaded.
2. Text extraction — pdfplumber over the bytes. The extracted text is stored as documents.raw_text.
3. Classification — document_classifier prompt haiku-4-5 returns {kind: dismissal_letter|grievance|appeal_outcome|contract|payslip|..., confidence}. Writes documents.kind.
4. Kind-specific extraction:
   • document_extractor for generic — pulls {parties, dates, key_facts, references}
   • grievance_outcome_extractor — structured outcome JSON (upheld, partially_upheld, rejected, with reasons + actions_offered)
   • lbc_response_extractor — employer's reply to the LBC, extracts {stance, amount_gbp, conditions, time_to_respond}
   • sar_response_extractor — confirms compliance with the SAR + any redactions challenged
   • inbound_classifier for emails → then one of inbound_acknowledgement_extractor, inbound_counter_offer_extractor, or inbound_info_request_extractor
5. Evidence linking — operator (or autonomous rule) links a document to one or more evidence_items against specific pleaded claims. The link triggers a re-run of intake_completion.

All extractor prompts return strict JSON. Anthropic's tool_use mode with a Pydantic-typed schema is the wire-level format.

6. Artefact production pipeline

This is the core loop. It runs for six artefact types — defined in src/et_agent/artefact_configs/*.yaml:

• grievance — claimant's pre-action grievance letter
• sar — Subject Access Request
• demand_letter — pre-LBC demand
• lbc — Letter Before Claim
• settlement_letter — Calderbank / settlement proposal
• et1 — Employment Tribunal claim form

The full pipeline (et1 example)

The whole pipeline is orchestrated by services/produce_artefact.py::produce_artefact().

Sampling strategies (per artefact)

7. Critics and scorer

Critics are not gatekeepers; they are peer reviewers. Each runs in parallel against the same draft + same snapshot, returning structured findings. The orchestrator then decides:

• Any critical issue → reject, re-draft with critique_block injected.
• ≥2 major issues → reject.
• 1 major → soft pass, operator review.
• Only minor issues → pass.

Critic role catalogue

Scorer

Each scorer prompt has a paired _user template that bundles the draft + a per-artefact rubric (loaded from JSON). The rubric defines dimensions (e.g. for et1: pleading_clarity, statutory_citation, factual_completeness, prospect_of_strike_out, prospects_of_success) with weights. Output is JSON: {overall_score: int, dimensions: {name: {score, evidence_quote, fix}}, overall_summary}.

8. Verification gate

Three Haiku prompts run after critics pass but before red-team. All read the draft + the case_snapshot + corpus blocks. They DO NOT have the temperature to generate; they cross-reference.

Verifier failures block the artefact and trigger one re-draft with the verifier's findings injected as a critique. Two consecutive verifier failures → operator alert.

All verifier runs persist to verification table for audit.

9. Red-team gate

Only ET1 currently runs the full red-team. Four prompts:

1. strike_out_simulator sonnet-4-5 — Plays a respondent's solicitor. Reads the draft + comparable_cases_block + foundational_law_block. Output: {vectors: [{ground, severity, predicted_outcome, supporting_authority}]}. Severities: high (likely to succeed), medium, low.
2. worst_case_award_calculator sonnet-4-5 — Calculates the defensible floor award given the pleaded facts. Considers Polkey reductions, contributory fault, mitigation. Output: {floor_gbp, ceiling_gbp, rationale, deductions: [...]}.
3. opposing_counsel_responder sonnet-4-5 — Drafts the response we expect from a competent employer solicitor. Used to find weaknesses we haven't pleaded around.
4. red_team_accuracy_judge haiku-4-5 — Evaluates whether the red-team predictions were credible (e.g. "you predicted vector X but cited authority Y which actually doesn't support it"). Filters noise.

If strike_out_simulator returns ≥1 high-severity vector, the artefact is blocked and the drafter re-runs with the vectors in the critique_block. Stored in red_team_predictions.

10. et-pipeline corpus / RAG

et-pipeline is a separate project at /srv/active/et-pipeline that owns the UK employment-law corpus. It is the only system allowed to write to the et_pipeline database.

Corpus baseline (2026-05-13)

State machine (ingestion)

Govuk ET first-instance bypasses the LLM stage (raw_text → embed) — first-instance is persuasive only, semantic search on facts is sufficient. Higher courts get the full extraction because their reasoning + cited cases feed the citation graph.

Retrieval API (consumed by et-agent)

Tiered search (binding precedent ↑)

/search/cases splits its top-k candidates 60/40 between binding precedent (SC/HL/CA/EAT/UT/HC) and first-instance (ET). The binding pool feeds from a partial HNSW index idx_judgments_embedding_facts_binding over WHERE state='embedded' AND court IN ('SC','HL','CA','EAT','UT','HC'). Without this index, the 130k ET rows dominate post-filter and only ~9 binding cases survive per query.

The API's IN clause MUST literally match the partial index predicate (no parameterised arrays — planner can't prove subset). Constants live in retrieval/api.py::_BINDING_IN_CLAUSE.

11. Voyage embeddings — chunking, shape, storage

Two embeddings per judgment

Chunking

No chunking. One row → two embeddings → one document in the result set. Voyage-4-large's 16k token window accommodates ~30-page judgments; longer ones are truncated to the first 14k chars (which captures the head facts, issues, and most of the reasoning).

For statute sections: each section_number is its own row in statute_sections. No further chunking; sections are already the natural retrieval unit.

Indexing

CREATE INDEX idx_judgments_embedding_facts ON judgments
  USING hnsw (embedding_facts vector_cosine_ops)
  WHERE state = 'embedded';

-- Partial: binding-precedent only (130x faster recall on binding subset)
CREATE INDEX idx_judgments_embedding_facts_binding ON judgments
  USING hnsw (embedding_facts vector_cosine_ops)
  WHERE state = 'embedded'
    AND court IN ('SC','HL','CA','EAT','UT','HC');

CREATE INDEX idx_statute_sections_embedding ON statute_sections
  USING hnsw (embedding vector_cosine_ops);

Retrieval flow

_HNSW_EF_SEARCH = 1000 is set SET LOCAL per query for cases where the partial index can't be used (e.g. jurisdiction_codes filter).

12. Testing scaffold (what we just built)

The system above had no objective accuracy measurement. This new scaffold gives us one.

Generation cost ledger

Total cost: $7.47 across 414 attempted, ~$0.018/case.

Next step (not built yet)

Eval / grader: read tests/runs/<prompt>/*.json + the corresponding tests/fixtures/cases/*.json::ground_truth → score each output against the labels → produce a per-prompt accuracy report (precision/recall on claim_types extracted, exact-match on dates, conflict-detection rate for fact_checker, citation grounding rate for legal_authority_checker, etc.).

13. Database tables

et_agent (25 tables)

et_pipeline (6 tables)

14. Data formats

CaseSnapshot (canonical case shape)

Defined in et_agent/domain/case_state.py. This is what every drafter / critic / scorer sees as case_file_json.

class CaseSnapshot(BaseModel):
    case_id: str
    case_reference: str
    state: str

    claimant_name: str | None
    employer_name: str | None
    employment_status: str | None       # dismissed | constructively_dismissed | ...
    employment_start_date: date | None
    employment_end_date: date | None
    weekly_pay_gross: float | None
    annual_pay_gross: float | None
    age_at_termination: int | None
    country: str | None                  # england-wales | scotland | northern-ireland

    udcalc_narrative: str | None         # claimant's own story

    formula_compensation_low: float | None
    formula_compensation_high: float | None

    claims: list[ClaimSummary]      # claim_type, is_lead, value range

class ClaimSummary(BaseModel):
    claim_type: str
    is_lead_claim: bool
    estimated_value_low: float | None
    estimated_value_high: float | None

Prompt frontmatter

---
name: et1_drafter_user
description: User message template for the ET1 drafter
role: user
expected_variables:
  - case_file_json
  - comparable_cases_block
  - relevant_statutes_block
  - current_rates_block
  - critique_block
tags:
  - et1
  - drafter
version_notes: |
  Pure data envelope — tune wording sparingly; substantive guidance
  lives in et1_drafter.md.
---

CASE FILE:
$case_file_json

COMPARABLE CASES (cite only from this list):
$comparable_cases_block

RELEVANT STATUTE SECTIONS:
$relevant_statutes_block

$current_rates_block

$critique_block

Comparable cases block (rendered)

<comparable_cases>
  <case id="findcaselaw-eat-1234" court="EAT" date="2023-04-12">
    <name>Smith v Acme Ltd UKEAT/0123/23</name>
    <facts>Claimant dismissed after raising health-and-safety
      concerns. EAT held that the protected disclosure
      principle applied even though the disclosure was made
      informally...</facts>
  </case>
  ...
</comparable_cases>

Test case fixture (what we just generated)

{
  "meta": {
    "id": "claudehaiku45_lead_0543_v1",
    "source_lead_id": "<udcalc.leads.id uuid>",
    "generator_model": "claude-haiku-4-5",
    "generator_variant": 1,
    "cost_usd": 0.0298
  },
  "case_snapshot": { ...full CaseSnapshot dict... },
  "narrative": "I worked for Roslyn Care Foundation for nearly 28 years...",
  "documents": {
    "dismissal_letter": "Roslyn Care Foundation\n14 Ashford Lane...",
    "grievance_letter": "...",
    "grievance_outcome_letter": "...",
    "appeal_letter": "...",
    "appeal_outcome_letter": "...",
    "inbound_messages": [
      {"kind": "lbc_response", "from": "employer_solicitor",
       "received_at": "2026-03-14",
       "body": "...",
       "amount_gbp": 4500}
    ]
  },
  "ground_truth": {
    "expected_claim_types": ["unfair_dismissal"],
    "expected_lead_claim": "unfair_dismissal",
    "expected_acas_compliant": false,
    "acas_failures": ["no_appeal_offered", "predetermined_outcome"],
    "expected_outcome_category": "upheld",
    "expected_value_range_gbp": {"low": 14000, "high": 32000},
    "automatic_unfair_grounds": [],
    "time_limit_status": "in_time",
    "red_team_flags": ["procedural_unfairness"],
    "conflicts": [
      {"description": "narrative says March 2024, dismissal_letter dated April",
       "where": ["narrative", "documents.dismissal_letter"],
       "truth": "dismissal_letter date is correct (April)",
       "trips_prompts": ["fact_checker", "consistency_checker"]}
    ]
  }
}

Voyage embedding wire shape

POST https://api.voyageai.com/v1/embeddings
Authorization: Bearer pa-...
Content-Type: application/json

{
  "input": ["text 1", "text 2", ...],   # batch up to 8 docs
  "model": "voyage-4-large",
  "input_type": "document"               # or "query" for retrieval
}

→ {
  "data": [
    {"embedding": [0.012, -0.034, ..., 0.022], "index": 0},   # 1024 floats
    ...
  ],
  "usage": {"total_tokens": 12384}
}

Pgvector storage

judgments.embedding_full   vector(1024)   # nullable until embed worker fills
judgments.embedding_facts  vector(1024)
statute_sections.embedding vector(1024)

Cosine similarity query (pgvector idiom used by et-pipeline)

SELECT id, case_name, court, decision_date,
       embedding_facts <=> :query_vec AS cosine_distance
FROM   judgments
WHERE  state = 'embedded'
  AND  court IN ('SC','HL','CA','EAT','UT','HC')
ORDER BY embedding_facts <=> :query_vec
LIMIT  30;

Appendix — the 65 prompts