# burhan-mujahid/precedent architecture

> Architecture diagram of the GitHub repository burhan-mujahid/precedent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/burhan-mujahid/precedent
- Repository: https://github.com/burhan-mujahid/precedent

## Overview

Precedent turns team conversations into human-approved, versioned operating rules, then checks agent decisions against those rules before and during execution. The main path is ingest and redact messages, identify Q&A episodes, draft proposals, review them into the rulebook, and resolve agent situations into act/approval/escalation outcomes. Escalations and halts can feed later rule work; drift checks, regression evaluations, packs, exports, and MCP integration are additional capabilities. Several subsystems are documented but unsampled, so their internal links are omitted where evidence is insufficient.

Main entry points: [`precedent/kb.py`](https://github.com/burhan-mujahid/precedent/blob/main/precedent/kb.py) (Precedent API), [`precedent/loop.py`](https://github.com/burhan-mujahid/precedent/blob/main/precedent/loop.py) (Proposal learning loop), [`precedent/runtime.py`](https://github.com/burhan-mujahid/precedent/blob/main/precedent/runtime.py) (Decision resolver), [`precedent/store.py`](https://github.com/burhan-mujahid/precedent/blob/main/precedent/store.py) (Git rulebook files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Rule learning"]
  node_ingest["Chat ingestion"]
  node_episodes["Q&amp;A episodes<br/>[episodes.py]"]
  node_learning_loop["Proposal learning loop<br/>[loop.py]"]
end

subgraph group_knowledge["Rulebook and governance"]
  node_rulebook_api["Precedent API<br/>[kb.py]"]
  node_rule_store[("Git rulebook files<br/>[store.py]")]
  node_packs["Starter rule packs<br/>[packs.py]"]
  node_drift["Drift detection<br/>[drift.py]"]
  node_evaluations["Regression evaluations<br/>[evals.py]"]
  node_calibration["Provider calibration<br/>[calibrate.py]"]
  node_export["Rulebook exports<br/>[export.py]"]
end

subgraph group_decision["Agent decisions"]
  node_resolver["Decision resolver<br/>[runtime.py]"]
  node_retrieval["Rule retrieval<br/>[retrieve.py]"]
  node_execution_gate["Execution checks<br/>[guard.py]"]
end

subgraph group_interfaces["Interfaces and integrations"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_llm["Model providers<br/>[llm.py]"]
  node_mcp["MCP tools<br/>[mcp.py]"]
end

subgraph group_shared["Shared foundations"]
  node_redaction["PII redaction<br/>[redact.py]"]
  node_reasoner["Rule reasoner<br/>[reasoner.py]"]
  node_config["Rulebook configuration<br/>[config.py]"]
  node_records["Domain records<br/>[models.py]"]
end

node_team(("Team conversations"))
node_operator(("Operator"))
node_agent(("AI agent"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"invokes API"| node_rulebook_api
node_team -->|"provides exports"| node_ingest
node_ingest -->|"normalizes messages"| node_episodes
node_episodes -->|"redacts text"| node_redaction
node_rulebook_api -->|"loads and mines"| node_ingest
node_rulebook_api -->|"delegates learning"| node_learning_loop
node_learning_loop -->|"drafts candidates"| node_reasoner
node_learning_loop -->|"records proposals"| node_rule_store
node_operator -->|"reviews proposals"| node_learning_loop
node_learning_loop -->|"approves rules"| node_rule_store
node_rule_store -->|"supplies approved rules"| node_resolver
node_agent -->|"consults rulebook"| node_resolver
node_resolver -->|"ranks rules"| node_retrieval
node_resolver -->|"judges coverage"| node_reasoner
node_resolver -->|"redacts situation"| node_redaction
node_resolver -->|"logs decisions"| node_rule_store
node_agent -->|"checks each step"| node_execution_gate
node_execution_gate -->|"checks and records"| node_rule_store
node_execution_gate -->|"halts create gaps"| node_learning_loop
node_rulebook_api -->|"checks rule health"| node_drift
node_rulebook_api -->|"runs regression cases"| node_evaluations
node_rulebook_api -->|"calibrates decisions"| node_calibration
node_rulebook_api -->|"exports reports"| node_export
node_mcp -->|"exposes operations"| node_rulebook_api
node_rulebook_api -->|"configures judgement"| node_reasoner
node_reasoner -->|"requests completions"| node_llm
node_rulebook_api -->|"opens rulebook"| node_rule_store
node_rule_store -->|"loads settings"| node_config
node_learning_loop -->|"uses domain records"| node_records
node_resolver -->|"produces decisions"| node_records
node_operator -->|"answers gaps"| node_learning_loop

click node_cli "https://github.com/burhan-mujahid/precedent/blob/main/precedent/cli.py"
click node_ingest "https://github.com/burhan-mujahid/precedent/tree/main/precedent/ingest"
click node_episodes "https://github.com/burhan-mujahid/precedent/blob/main/precedent/ingest/episodes.py"
click node_redaction "https://github.com/burhan-mujahid/precedent/blob/main/precedent/ingest/redact.py"
click node_learning_loop "https://github.com/burhan-mujahid/precedent/blob/main/precedent/loop.py"
click node_reasoner "https://github.com/burhan-mujahid/precedent/blob/main/precedent/reasoner.py"
click node_llm "https://github.com/burhan-mujahid/precedent/blob/main/precedent/llm.py"
click node_rulebook_api "https://github.com/burhan-mujahid/precedent/blob/main/precedent/kb.py"
click node_rule_store "https://github.com/burhan-mujahid/precedent/blob/main/precedent/store.py"
click node_packs "https://github.com/burhan-mujahid/precedent/blob/main/precedent/packs.py"
click node_resolver "https://github.com/burhan-mujahid/precedent/blob/main/precedent/runtime.py"
click node_retrieval "https://github.com/burhan-mujahid/precedent/blob/main/precedent/retrieve.py"
click node_execution_gate "https://github.com/burhan-mujahid/precedent/blob/main/precedent/guard.py"
click node_drift "https://github.com/burhan-mujahid/precedent/blob/main/precedent/drift.py"
click node_evaluations "https://github.com/burhan-mujahid/precedent/blob/main/precedent/evals.py"
click node_calibration "https://github.com/burhan-mujahid/precedent/blob/main/precedent/calibrate.py"
click node_export "https://github.com/burhan-mujahid/precedent/blob/main/precedent/export.py"
click node_mcp "https://github.com/burhan-mujahid/precedent/blob/main/precedent/mcp.py"
click node_config "https://github.com/burhan-mujahid/precedent/blob/main/precedent/config.py"
click node_records "https://github.com/burhan-mujahid/precedent/blob/main/precedent/models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ingest,node_episodes,node_learning_loop toneBlue
class node_rulebook_api,node_rule_store,node_packs,node_drift,node_evaluations,node_calibration,node_export toneAmber
class node_resolver,node_retrieval,node_execution_gate toneMint
class node_cli,node_llm,node_mcp toneRose
class node_redaction,node_reasoner,node_config,node_records,node_team,node_operator,node_agent toneIndigo
```

## Components

### Rule learning

- [Chat ingestion](https://github.com/burhan-mujahid/precedent/tree/main/precedent/ingest): `precedent/ingest`
- [Q&A episodes](https://github.com/burhan-mujahid/precedent/blob/main/precedent/ingest/episodes.py): `precedent/ingest/episodes.py`
- [Proposal learning loop](https://github.com/burhan-mujahid/precedent/blob/main/precedent/loop.py): `precedent/loop.py`

### Rulebook and governance

- [Precedent API](https://github.com/burhan-mujahid/precedent/blob/main/precedent/kb.py): `precedent/kb.py`
- [Git rulebook files](https://github.com/burhan-mujahid/precedent/blob/main/precedent/store.py): `precedent/store.py`
- [Starter rule packs](https://github.com/burhan-mujahid/precedent/blob/main/precedent/packs.py): `precedent/packs.py`
- [Drift detection](https://github.com/burhan-mujahid/precedent/blob/main/precedent/drift.py): `precedent/drift.py`
- [Regression evaluations](https://github.com/burhan-mujahid/precedent/blob/main/precedent/evals.py): `precedent/evals.py`
- [Provider calibration](https://github.com/burhan-mujahid/precedent/blob/main/precedent/calibrate.py): `precedent/calibrate.py`
- [Rulebook exports](https://github.com/burhan-mujahid/precedent/blob/main/precedent/export.py): `precedent/export.py`

### Agent decisions

- [Decision resolver](https://github.com/burhan-mujahid/precedent/blob/main/precedent/runtime.py): `precedent/runtime.py`
- [Rule retrieval](https://github.com/burhan-mujahid/precedent/blob/main/precedent/retrieve.py): `precedent/retrieve.py`
- [Execution checks](https://github.com/burhan-mujahid/precedent/blob/main/precedent/guard.py): `precedent/guard.py`

### Interfaces and integrations

- [CLI commands](https://github.com/burhan-mujahid/precedent/blob/main/precedent/cli.py): `precedent/cli.py`
- [Model providers](https://github.com/burhan-mujahid/precedent/blob/main/precedent/llm.py): `precedent/llm.py`
- [MCP tools](https://github.com/burhan-mujahid/precedent/blob/main/precedent/mcp.py): `precedent/mcp.py`

### Shared foundations

- [PII redaction](https://github.com/burhan-mujahid/precedent/blob/main/precedent/ingest/redact.py): `precedent/ingest/redact.py`
- [Rule reasoner](https://github.com/burhan-mujahid/precedent/blob/main/precedent/reasoner.py): `precedent/reasoner.py`
- [Rulebook configuration](https://github.com/burhan-mujahid/precedent/blob/main/precedent/config.py): `precedent/config.py`
- [Domain records](https://github.com/burhan-mujahid/precedent/blob/main/precedent/models.py): `precedent/models.py`

### Other components

- **Team conversations**
- **Operator**
- **AI agent**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Precedent API: invokes API (evidence: `precedent/cli.py`)
- Team conversations → Chat ingestion: provides exports (evidence: `README.md`)
- Chat ingestion → Q&A episodes: normalizes messages (evidence: `precedent/ingest/__init__.py`)
- Q&A episodes → PII redaction: redacts text (evidence: `precedent/ingest/episodes.py`)
- Precedent API → Chat ingestion: loads and mines (evidence: `precedent/kb.py`)
- Precedent API → Proposal learning loop: delegates learning (evidence: `precedent/kb.py`)
- Proposal learning loop → Rule reasoner: drafts candidates (evidence: `precedent/loop.py`)
- Proposal learning loop → Git rulebook files: records proposals (evidence: `precedent/loop.py`)
- Operator → Proposal learning loop: reviews proposals (evidence: `README.md`)
- Proposal learning loop → Git rulebook files: approves rules (evidence: `README.md`)
- Git rulebook files → Decision resolver: supplies approved rules (evidence: `precedent/runtime.py`)
- AI agent → Decision resolver: consults rulebook (evidence: `README.md`)
- Decision resolver → Rule retrieval: ranks rules (evidence: `precedent/runtime.py`)
- Decision resolver → Rule reasoner: judges coverage (evidence: `precedent/runtime.py`)
- Decision resolver → PII redaction: redacts situation (evidence: `precedent/runtime.py`)
- Decision resolver → Git rulebook files: logs decisions (evidence: `precedent/runtime.py`)
- AI agent → Execution checks: checks each step (evidence: `README.md`)
- Execution checks → Git rulebook files: checks and records (evidence: `precedent/guard.py`)
- Execution checks → Proposal learning loop: halts create gaps (evidence: `precedent/guard.py`)
- Precedent API → Drift detection: checks rule health (evidence: `precedent/kb.py`)
- Precedent API → Regression evaluations: runs regression cases (evidence: `precedent/kb.py`)
- Precedent API → Provider calibration: calibrates decisions (evidence: `precedent/kb.py`)
- Precedent API → Rulebook exports: exports reports (evidence: `precedent/kb.py`)
- MCP tools → Precedent API: exposes operations (evidence: `precedent/mcp.py`)
- Precedent API → Rule reasoner: configures judgement (evidence: `precedent/kb.py`)
- Rule reasoner → Model providers: requests completions (evidence: `precedent/reasoner.py`)
- Precedent API → Git rulebook files: opens rulebook (evidence: `precedent/kb.py`)
- Git rulebook files → Rulebook configuration: loads settings (evidence: `precedent/store.py`)
- Proposal learning loop → Domain records: uses domain records (evidence: `precedent/loop.py`)
- Decision resolver → Domain records: produces decisions (evidence: `precedent/runtime.py`)
- Operator → Proposal learning loop: answers gaps (evidence: `README.md`)