Copilot

Status: October 2026 (slices 26–34). Bank-workspace only (IntelligenceCopilot).

Code: locus-web/src/copilot/engine.ts, async.ts, UI src/components/copilot/IntelligenceCopilot.tsx.

Platform legal vault / Watchtower live in locus-ops — see Legal vault & Watchtower. The copilot never writes to the vault.

generateCopilotResponseAsync
  → multi-turn memory (agent.ts)
  → certified tool registry (16 deterministic tools)
  → retrieveEvidence → /api/locus/search (french FTS)
  → optional polishCopilotProse (COPILOT_LLM_PROVIDER=off by default)

Numbers never come from the model.

1. Architecture (shipped)

flowchart TB
  UI[IntelligenceCopilot]
  Async[generateCopilotResponseAsync]
  Engine[Deterministic_engine]
  RAG[retrieveEvidence_BFF]
  LLM[polishCopilotProse]
  SoR[(Postgres)]
  R2[(Cloudflare_R2)]

  UI --> Async
  Async --> Engine
  Async --> RAG
  Async --> LLM
  Engine --> SoR
  RAG --> SoR
  Upload[Deal_Room_upload] --> R2
  Upload --> OCR[extractAndPersistOcr]
  OCR --> SoR

Layer	Role	Default
Agent / Registry	Agentic Tool Router (tools/registry.ts) with 16 certified quantitative & diligence tools	Always on
Aladdin CEMAC Tools	Pricing, Nelson-Siegel sovereign spread, portfolio exposure, duration decomposition, +50 bp stress	Built-in
Multi-turn Memory	Contextual conversation history resolution (history: CopilotMessage[])	Active
Retrieval	/api/locus/search → C# SearchDocuments (french tsvector + GIN)	Always attempted; empty if API down
LLM	French prose polish for draft / investigate only	COPILOT_LLM_PROVIDER=off
Ingest	R2 Put → Document row → OCR → ExtractedPages + Citations + search index	On every upload
Citations (R4)	Cell / contradiction alerts carry SoR citation ids; UI never invents bboxes	Wired

Regulatory findings tools (check_regulatory_compliance) still evaluate against the catalog / deal payload. Vault edition IDs are overlaid when the server path uses analyzeDealWithVault (not inside the copilot sheet itself) — see Regulatory analyze.

2. Code paths (technical presentation §6)

Files: locus-web/src/copilot/{engine,agent,async,retrieval,llm,financials}.ts. Certified tool registry: locus-web/src/copilot/tools/{types,registry,financial_tools,fixed_income_tools,portfolio_tools,diligence_tools}.ts. UI: IntelligenceCopilot.tsx (mounted from WorkbenchView, with badges attesting which quantitative engines ran).

generateCopilotResponseAsync
        │
        ├─► Multi-Turn Memory (`agent.ts` :: resolveFollowUpQuery)
        │      • anaphora resolution ("Et si l'EBITDA baisse de 15% ?")
        │      • keeps intent and conversation history
        │
        ├─► generateCopilotResponse (sync router)
        │      • tenant boundary check (fail-closed)
        │      • routes to the Certified Tool Registry (16 deterministic tools):
        │          - Fixed Income : BondMath CEMAC (clean/dirty, dur, conv, DV01)
        │          - Curves       : Relative value vs Nelson-Siegel Gabon/Cameroun (bps)
        │          - Portfolio    : XAF exposure, +50/+100/+150 bp stress, attribution
        │          - Credit       : SYSCOHADA (DSCR, ICR, Net Debt/EBE), EBITDA stress, covenants
        │          - Diligence    : contradiction radar, 35-month trap, blockers, compliance
        │      • certified engine badges attached to the response
        │
        ├─► retrieveEvidence → /api/locus/search
        │      • merge OCR citations with spatial coordinates (bounding boxes)
        │      • fetchDossierBlockers (tax quitus, BEAC Art. 42)
        │
        └─► polishCopilotProse (if draft|investigate && provider ≠ off)
               • strict prompt: text rewording only, figures untouchable

Mode / Domain	Source of truth & certified engine
Bond pricing / spread	BondMath CEMAC & NelsonSiegelEngine (sovereign curves)
Portfolio / rate stress	Portfolio Engine (DV01, +50 bp parallel shift, OTA/BTA decomposition)
Credit calc / stress	financial_periods → computeSyscohadaRatios (fail-closed)
Covenants & undertakings	audit_covenants (contractual thresholds & XAF headroom)
Cross-document comparison	contradiction_alerts & audit_contradictions_radar
Risks & CPs	generateRiskRegister & explain_concession_maturity_trap
Missing documents / blockers	Data-room audit + /api/locus/blockers
Legal compliance	CEMAC regulatory corpus (OHADA AUS, R-2018/02 BEAC, COSUMAF)
Committee memo	Structured Fact / Inference / Question synthesis (+ optional LLM prose)

regulatory_corpus scope blocks the deal's financial calculations to prevent context leakage.

Every assistant answer carries 3-tier assertion tags (SOURCE, CALCULATION, INTERPRETATION) and the mandatory legal disclaimer; target response SLA is < 2.5 s (grounded response budget). Live engine verification renders badges in IntelligenceCopilot.tsx (Nelson-Siegel CEMAC, BondMath CEMAC, Portfolio Engine, SYSCOHADA Ratios, …).

3. Certified Tool Catalog

#	Tool	Domain	What it does
1	get_syscohada_ratios	Credit	Net Debt / EBE, DSCR, ICR, cash, debt service
2	simulate_credit_stress	Credit	Sensitivity under EBITDA shocks (−10%, −20%, −30%)
3	audit_covenants	Credit	Facility covenants, thresholds, headrooms
4	price_fixed_income_instrument	Fixed income	Clean/dirty pricing, duration, convexity, DV01 (+50 bp)
5	compare_bond_to_curve	Fixed income	Relative value vs Nelson-Siegel sovereign curves
6	get_portfolio_exposure	Portfolio	Market value in XAF, modified duration, DV01, concentrations
7	run_portfolio_stress	Portfolio	Parallel rate shocks (+50 / +100 / +150 bp)
8	explain_portfolio_duration	Portfolio	Duration factor decomposition (OTA vs BTA tenors)
9	list_portfolio_exceptions	Portfolio	Open limit breaches
10	audit_contradictions_radar	Diligence	Cross-document discrepancies
11	explain_concession_maturity_trap	Diligence	Concession vs debt maturity gap
12	get_risk_register	Diligence	Top transaction risks and CPs
13	audit_dataroom_completeness	Diligence	Fatal blockers and completeness score
14	check_regulatory_compliance	Diligence	OHADA / BEAC / COSUMAF checks from deal + catalog
15	compile_credit_memo	Diligence	Fact / Inference / Question memo structure
16	investigate_360	Diligence	Full synthesis of solvency, contradictions, risks, data room

Portfolio tools read the tenant book from the SoR (GET /api/locus/portfolio → mapSorBookToDomain).

4. Data flow

Input	Source
Open deal	SSR / TanStack Query → Postgres SoR (empty tenant → empty deal; no demo overlay)
Multi-turn history	history: CopilotMessage[] from client state
Ratios / stress	project.financial_periods via buildFinancialSnapshot — fail closed
Contradictions / risks / completeness	Project engines + SoR-hydrated alerts
Blockers	Postgres Blockers via /api/locus/blockers
Document evidence	OCR pages → SearchDocuments → citations (page; bbox only when usable)
Tenant	organizationId from Workbench on every call

Evidence retrieval

retrieveEvidence(q, dossierId)
  → BFF /api/locus/search
  → SearchController (OrganizationId + optional TargetProjectId)
  → hits → Citation { documentId, page, bbox, snippet }

5. Env

Variable	Role
LOCUS_API_BASE_URL	C# SoR
R2_*	Tenant document vault
COPILOT_LLM_PROVIDER	off | openai | anthropic
OPENAI_API_KEY / ANTHROPIC_API_KEY	Prose only

Optional model overrides: COPILOT_OPENAI_MODEL, COPILOT_ANTHROPIC_MODEL (see locus-web/.env.example). The streaming polish route is /api/copilot/polish-stream.

6. Implementation checklist

1. [x] Kill hardcoded financial fallbacks (copilot/financials.ts)
2. [x] Wire local deal tools + tenant/scope
3. [x] Blockers + search BFF over Postgres
4. [x] R2 upload → OCR → ExtractedPages / Citations / SearchDocuments
5. [x] Tenant-scoped retrieval into async copilot path
6. [x] Optional LLM adapter (prose only; default off)
7. [x] Certified Tools Registry (16 tools)
8. [x] Multi-turn conversation memory
9. [x] UI live execution badges
10. [x] Eval pack: tests/intelligence_copilot.test.ts, copilot_retrieval_and_llm.test.ts, copilot_agent_and_tools.test.ts
11. [x] Postgres french FTS (tsvector / GIN) on SearchDocuments
12. [x] R4: no invented citation bboxes in retrieval helpers

7. Still stronger later (non-blocking)

• Higher OCR quality on hard stamps (R2 spot-check driven)
• Streaming LLM tokens in the sheet UI
• Copilot tool that opens vault statutes via openStatuteHref when findings carry vault artifact ids

8. Bottom line

The copilot is an agentic tool orchestrator + multi-turn memory + retrieval + optional prose LLM. Numbers never come from the model. Calculations come from certified deterministic engines; uploaded deal-room documents become searchable evidence with page (and optional bbox) citations. Platform statutes are managed separately in the legal vault — see Legal vault & Watchtower.

Related: SYSCOHADA & ratios · Contradictions · Citations (R4) · tests tests/copilot_editions_and_reporting_persistence.test.ts.