ARCHITECTURE.md

# Architecture

LangGraph-native Document Intelligence platform. This document goes beyond
the README — it covers design decisions, the subgraph hierarchy, state
design, and the anti-hallucination stack.

## 1. High-level architecture

### 4 compiled LangGraph artifacts

The system is organized around four graphs sharing a common `AsyncSqliteSaver`
checkpointer:

| # | Graph | Entry point | When |
|---|-------|-------------|------|
| 1 | `pipeline_graph` | `app.run_pipeline(files)` | on upload |
| 2 | `chat_graph` | `app.ask(question)` | chat tab |
| 3 | `dd_graph` | `app.dd_report(thread_id)` | DD tab button |
| 4 | `package_insights_graph` | `app.package_insights(thread_id, pkg_type)` | demo button |

Chat tools read from the persisted pipeline state — they do not re-read
files. They access the in-memory `ChatToolContext`, which holds the
HybridStore and a documents snapshot.

### Pipeline graph topology

```
START
  → start_timer
  → dispatch_ingest          (Send API: per-doc fan-out)
  → ingest_per_doc           (PDF/DOCX/PNG/TXT loader subgraph)
  → ingest_join              (fan-in)
  → dispatch_classify        (Send API)
  → classify_per_doc         (regex/keyword classifier in dummy mode;
                              vision-aware in vLLM mode)
  → classify_join
  → dispatch_extract         (Send API)
  → extract_per_doc          (regex extractor in dummy mode +
                              flatten_universal; structured LLM in vLLM mode)
  → extract_join
  → quote_validator          (anti-hallucination layer #7)
  → dispatch_rag_index       (Send API)
  → rag_index_per_doc        (chunker + batched embed + Chroma+BM25 upsert)
  → rag_join
  → compare_node             (three-way matching, sync)
  → risk_subgraph            (basic + 14 domain × Send + plausibility +
                              LLM ensemble + duplicate)
  → finish_timer
  → report_node              (10-section JSON structure)
  → END
```

The per-doc Send fan-out yields a 5–8× speedup in a CPU-bound environment.

### Risk subgraph topology

```
risk_subgraph (input: PipelineState):
  → basic_risk_dispatch         (Send: per-doc basic risk)
  → basic_risk / noop_basic
  → domain_dispatch_node        (Send: per-doc × per-applicable-check, ~30 parallel)
  → apply_domain_check
  → [if llm provided] llm_risk_dispatch  (Send: per-doc LLM risk + 3-filter chain)
  → llm_risk_per_doc / noop_llm
  → plausibility_dispatch       (Send: per-doc plausibility)
  → plausibility / noop_plaus
  → evidence_score_node         (per-doc info)
  → duplicate_detector_node     (package-level, sync, ISA 240)
END
```

The full anti-hallucination 5+1 layer chain runs inside `llm_risk_per_doc`:
`llm_risk → filter_llm_risks → drop_business_normal → drop_repeats`.

### DD multi-agent supervisor graph

```
dd_graph:
  START
  → contract_filter_node      (keep only contract-type docs)
  → per_contract_summary_node (Python-deterministic per-contract DDContractSummary)
  → supervisor_node           (LLM router or heuristic; Command(goto=...))
        ├─ → audit_specialist     (pricing anomalies, overcharging)
        ├─ → legal_specialist     (red flags, change-of-control, non-compete)
        ├─ → compliance_specialist (GDPR, AML, data protection)
        └─ → financial_specialist (monthly obligations, expirations)
  ↺ (loops back to supervisor up to dd_supervisor_max_iterations)
  → dd_synthesizer            (one LLM call: executive_summary +
                               top_red_flags + per-contract risk_level rating)
  END
```

### Package insights graph

A simple 1-LLM-call graph: ingests the full document package and produces
cross-doc findings using a perspective-driven prompt
(`audit | dd | compliance | general`).

## 2. State design

### `PipelineState` (TypedDict)

Read-mostly fields with **reducer-driven Send fan-in**:

- `files: list[tuple[str, bytes]]` — raw upload
- `documents: Annotated[list[ProcessedDocument], merge_doc_results]` —
  per-doc field-level merge keyed by `file_name`
- `risks: Annotated[list[Risk], merge_risks]` — dedup by description
- `comparison: ComparisonReport | None`
- `report: dict`
- `package_insights: PackageInsights | None`
- `dd_report: DDPortfolioReport | None`
- `started_at`, `finished_at`, `processing_seconds`
- `progress_events: Annotated[list[str], add]` — Streamlit progress feed

### `Risk` (Pydantic)

The single risk type used everywhere:

- `description: str`
- `severity: str` (`"high" | "medium" | "low" | "info"`)
- `rationale: str`
- `kind: str` (`"validation" | "domain_rule" | "plausibility" | "llm_analysis" | "cross_check"`)
- `regulation: str | None` (e.g. `"HU VAT Act §169"`, `"ISA 240"`, `"GDPR Article 28"`)
- `affected_document: str | None`
- `source_check_id: str | None`

## 3. Anti-hallucination stack (5+1 layers)

1. **`temperature=0`** — every LLM call is deterministic-ish.
2. **`_quotes` schema field** — verbatim source citations.
3. **`_confidence` schema field** — per-field reliability (high|medium|low).
4. **`validate_plausibility()`** — Python deterministic plausibility checks
   (negative VAT, non-standard rates, future dates, etc.).
5. **3-filter LLM risk pipeline** —
   `filter_llm_risks` (formal: ≥5 words, ≥2 domain terms, ≥1 concrete fact)
   → `drop_business_normal_risks` (semantic: cross-check vs extracted_data,
   6 known false-positive patterns)
   → `drop_repeats_of_basic` (textual dedup vs basic risks, 70% threshold).
6. **Quote validator** — final cross-check that every `_quotes` entry
   actually appears in the source `full_text` (whitespace + diacritic +
   case normalized). If invalid, downgrades confidence.

## 4. Domain checks (14 deterministic rules)

| # | check_id | Regulation | HU-specific? | Applies to |
|---|----------|-----------|--------------|------------|
| 01 | `check_01_invoice_mandatory` | HU VAT Act §169 | yes | invoice |
| 02 | `check_02_tax_cdv` | HU Tax Procedure Act §22 mod-11 | yes | invoice + contract + ... |
| 03 | `check_03_contract_completeness` | Universal contract completeness | no | contract |
| 04 | `check_04_proportionality` | Universal contract proportionality (>31.7%) | no | contract |
| 05 | `check_05_rounded_amounts` | ISA 240 (Journal of Accountancy 2018) | no | invoice |
| 06 | `check_06_evidence_score` | ISA 500 | no | (separate entry, info-only) |
| 07 | `check_07_materiality` | ISA 320 | no | invoice + contract + financial_report |
| 08 | `check_08_gdpr_28` | GDPR Article 28 | no (EU) | contract |
| 09 | `check_09_dd_red_flags` | M&A DD best practice | no | contract |
| 10 | `check_10_incoterms` | Incoterms 2020 | no | contract |
| 11 | `check_11_ifrs_har` | IFRS / national GAAP comparison | no | financial_report |
| 12 | `check_12_duplicate_invoice` | ISA 240 (duplicate invoice) | no | (separate entry, package-level) |
| 13 | `check_13_aml_sanctions` | AML / Sanctions screening | no | invoice + contract + ... |
| 14 | `check_14_contract_dates` | Contract date best practice | no | contract |

The dispatch in `domain_dispatch_node` skips `check_06` and `check_12` (they
have separate entry points) and filters `is_hu_specific=True` out for non-HU
documents.

## 5. Provider system

Three providers via `configurable_alternatives`:

- **`vllm`** — `ChatOpenAI` with `base_url=VLLM_BASE_URL` pointing at the
  AMD MI300X vLLM endpoint. Production default.
- **`ollama`** — `ChatOllama` with a local Ollama daemon (Qwen 2.5 7B
  Instruct). Development fallback.
- **`dummy`** — `DummyChatModel` (deterministic stub, no network).
  CI / eval / load.

Provider selection is **runtime-switchable** without restart:

```python
graph.invoke(state, config={"configurable": {"llm_profile": "dummy"}})
```

## 6. Embedding

`BAAI/bge-m3` (2.27 GB, 1024 dim, multilingual) by default.
Sentence-transformers loads it on first call via `@lru_cache`.
Pre-downloaded at Docker build time so runtime has no network call.

## 7. Hybrid retrieval (Chroma + BM25)

`store/hybrid_store.py` runs vector search and BM25 in parallel and merges
with Reciprocal Rank Fusion (RRF). The chunker uses natural break points
(paragraph + sentence boundaries), tuned to ~15K-char chunks with 500-char
overlap.

## 8. Async-first runtime

LangGraph 0.6 is async-first. The Streamlit app runs the entire async layer
on a long-lived background event loop (`app/async_runtime.py`'s `AsyncRuntime`
singleton). This keeps the ChromaDB connection, the Anthropic / OpenAI HTTP
session, and the `AsyncSqliteSaver` SQLite pool persistent across user
interactions — they do not rebuild per request.

## 9. Multilingual support

The codebase is English-first but multilingual-tolerant:

- The classifier matches HU/EN/DE keyword patterns.
- Risk filters tolerate HU/DE business terms.
- The OCR layer keeps `eng + hun + deu` as Tesseract languages.
- Demo data may include mixed-language documents.

The output (UI, exec summary, DOCX report) is **always English**.