# ilyautov/consilium-principis architecture

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

- Interactive diagram: https://gitdiagram.com/ilyautov/consilium-principis
- Repository: https://github.com/ilyautov/consilium-principis

## Overview

Consilium Principis is an MCP server and agent skill for decision support: a user asks a question through an agent, which uses the server’s tools and the agent’s own reasoning to gather perspectives and produce a synthesis and next step. The documented product also includes exact-quote verification and abstention, quantitative decision maps, premortems, argument analysis, mirrors, and a federation mode. Internally, corpus construction feeds retrieval and quote-fidelity checks. Source excerpts are partial; unsampled feature modules are included only where the README or source index establishes their role, and uncertain connections are omitted.

Main entry points: [`scripts/mcp_server.py`](https://github.com/ilyautov/consilium-principis/blob/master/scripts/mcp_server.py) (MCP tools), [`scripts/corpusbuild/pipeline.py`](https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/pipeline.py) (Corpus publishing), [`scripts/engine/retrieval.py`](https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/retrieval.py) (Passage retrieval), [`scripts/federation/coordinator.py`](https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/coordinator.py) (Federation coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Agent interaction"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
  node_advisor["Advisor lenses<br/>[build_advisor.py]"]
  node_session["Session records<br/>[session_render.py]"]
end

subgraph group_knowledge["Advisor knowledge"]
  node_source["Source texts"]
  node_ingest["Source extraction<br/>[ingest.py]"]
  node_clean["Text tagging<br/>[clean.py]"]
  node_chunk["Corpus chunking<br/>[chunk.py]"]
  node_pipeline["Corpus publishing<br/>[pipeline.py]"]
  node_corpus[("Advisor corpus<br/>[paths.py]")]
  node_retrieval["Passage retrieval<br/>[retrieval.py]"]
  node_engine["Retrieval engines<br/>[__init__.py]"]
  node_fidelity["Quote verification<br/>[fidelity.py]"]
end

subgraph group_decisions["Decision tools"]
  node_decisionmap["Decision maps<br/>[decision_map.py]"]
  node_premortem["Premortems<br/>[premortem.py]"]
  node_argument["Argument analysis<br/>[principis.py]"]
  node_mirror["Decision mirror<br/>[mirror.py]"]
end

subgraph group_federation["Federated board"]
  node_coordinator["Federation coordinator<br/>[coordinator.py]"]
  node_queue[("Role-task queue<br/>[queue.py]")]
  node_executor["Task executor<br/>[executor.py]"]
  node_judge["Candidate judge<br/>[judge.py]"]
end

node_user(("Decision-maker"))
node_agent(("Host agent"))

node_user -->|"asks question"| node_agent
node_agent -->|"calls tools"| node_mcp
node_mcp -->|"retrieves passages"| node_retrieval
node_mcp -->|"checks quotes"| node_fidelity
node_mcp -->|"offers calculation"| node_decisionmap
node_mcp -->|"starts federation"| node_coordinator
node_agent -->|"uses lenses"| node_advisor
node_source -->|"extracts text"| node_ingest
node_pipeline -->|"calls extraction"| node_ingest
node_pipeline -->|"tags records"| node_clean
node_pipeline -->|"chunks records"| node_chunk
node_pipeline -->|"publishes corpus"| node_corpus
node_retrieval -->|"reads passages"| node_corpus
node_retrieval -->|"resolves backend"| node_engine
node_fidelity -->|"checks exact text"| node_corpus
node_coordinator -->|"enqueues tasks"| node_queue
node_coordinator -->|"scores candidates"| node_judge
node_executor -.->|"claims tasks"| node_queue
node_agent -->|"records session"| node_session
node_agent -->|"requests premortem"| node_premortem
node_agent -->|"requests analysis"| node_argument
node_agent -->|"requests mirror"| node_mirror

click node_mcp "https://github.com/ilyautov/consilium-principis/blob/master/scripts/mcp_server.py"
click node_advisor "https://github.com/ilyautov/consilium-principis/blob/master/scripts/build_advisor.py"
click node_session "https://github.com/ilyautov/consilium-principis/blob/master/scripts/session_render.py"
click node_ingest "https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/ingest.py"
click node_clean "https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/clean.py"
click node_chunk "https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/chunk.py"
click node_pipeline "https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/pipeline.py"
click node_corpus "https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/paths.py"
click node_retrieval "https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/retrieval.py"
click node_engine "https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/__init__.py"
click node_fidelity "https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/fidelity.py"
click node_decisionmap "https://github.com/ilyautov/consilium-principis/blob/master/scripts/decision_map.py"
click node_premortem "https://github.com/ilyautov/consilium-principis/blob/master/scripts/premortem.py"
click node_argument "https://github.com/ilyautov/consilium-principis/blob/master/scripts/principis.py"
click node_mirror "https://github.com/ilyautov/consilium-principis/blob/master/scripts/mirror.py"
click node_coordinator "https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/coordinator.py"
click node_queue "https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/queue.py"
click node_executor "https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/executor.py"
click node_judge "https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/judge.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_mcp,node_advisor,node_session toneBlue
class node_source,node_ingest,node_clean,node_chunk,node_pipeline,node_corpus,node_retrieval,node_engine,node_fidelity toneAmber
class node_decisionmap,node_premortem,node_argument,node_mirror toneMint
class node_coordinator,node_queue,node_executor,node_judge toneRose
class node_user,node_agent toneIndigo
```

## Components

### Agent interaction

- [MCP tools](https://github.com/ilyautov/consilium-principis/blob/master/scripts/mcp_server.py): `scripts/mcp_server.py`
- [Advisor lenses](https://github.com/ilyautov/consilium-principis/blob/master/scripts/build_advisor.py): `scripts/build_advisor.py`
- [Session records](https://github.com/ilyautov/consilium-principis/blob/master/scripts/session_render.py): `scripts/session_render.py`

### Advisor knowledge

- **Source texts**
- [Source extraction](https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/ingest.py): `scripts/corpusbuild/ingest.py`
- [Text tagging](https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/clean.py): `scripts/corpusbuild/clean.py`
- [Corpus chunking](https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/chunk.py): `scripts/corpusbuild/chunk.py`
- [Corpus publishing](https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/pipeline.py): `scripts/corpusbuild/pipeline.py`
- [Advisor corpus](https://github.com/ilyautov/consilium-principis/blob/master/scripts/corpusbuild/paths.py): `scripts/corpusbuild/paths.py`
- [Passage retrieval](https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/retrieval.py): `scripts/engine/retrieval.py`
- [Retrieval engines](https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/__init__.py): `scripts/engine/__init__.py`
- [Quote verification](https://github.com/ilyautov/consilium-principis/blob/master/scripts/engine/fidelity.py): `scripts/engine/fidelity.py`

### Decision tools

- [Decision maps](https://github.com/ilyautov/consilium-principis/blob/master/scripts/decision_map.py): `scripts/decision_map.py`
- [Premortems](https://github.com/ilyautov/consilium-principis/blob/master/scripts/premortem.py): `scripts/premortem.py`
- [Argument analysis](https://github.com/ilyautov/consilium-principis/blob/master/scripts/principis.py): `scripts/principis.py`
- [Decision mirror](https://github.com/ilyautov/consilium-principis/blob/master/scripts/mirror.py): `scripts/mirror.py`

### Federated board

- [Federation coordinator](https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/coordinator.py): `scripts/federation/coordinator.py`
- [Role-task queue](https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/queue.py): `scripts/federation/queue.py`
- [Task executor](https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/executor.py): `scripts/federation/executor.py`
- [Candidate judge](https://github.com/ilyautov/consilium-principis/blob/master/scripts/federation/judge.py): `scripts/federation/judge.py`

### Other components

- **Decision-maker**
- **Host agent**

## Connections

- Decision-maker → Host agent: asks question (evidence: `README.md`)
- Host agent → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → Passage retrieval: retrieves passages (evidence: `scripts/mcp_server.py`)
- MCP tools → Quote verification: checks quotes (evidence: `scripts/mcp_server.py`)
- MCP tools → Decision maps: offers calculation (evidence: `scripts/mcp_server.py`)
- MCP tools → Federation coordinator: starts federation (evidence: `scripts/mcp_server.py`)
- Host agent → Advisor lenses: uses lenses (evidence: `README.md`)
- Source texts → Source extraction: extracts text
- Corpus publishing → Source extraction: calls extraction (evidence: `scripts/corpusbuild/pipeline.py`)
- Corpus publishing → Text tagging: tags records (evidence: `scripts/corpusbuild/pipeline.py`)
- Corpus publishing → Corpus chunking: chunks records (evidence: `scripts/corpusbuild/pipeline.py`)
- Corpus publishing → Advisor corpus: publishes corpus (evidence: `scripts/corpusbuild/pipeline.py`)
- Passage retrieval → Advisor corpus: reads passages (evidence: `scripts/engine/retrieval.py`)
- Passage retrieval → Retrieval engines: resolves backend (evidence: `scripts/engine/retrieval.py`)
- Quote verification → Advisor corpus: checks exact text (evidence: `scripts/engine/fidelity.py`)
- Federation coordinator → Role-task queue: enqueues tasks (evidence: `scripts/federation/coordinator.py`)
- Federation coordinator → Candidate judge: scores candidates (evidence: `scripts/federation/coordinator.py`)
- Task executor → Role-task queue: claims tasks
- Host agent → Session records: records session (evidence: `README.md`)
- Host agent → Premortems: requests premortem (evidence: `README.md`)
- Host agent → Argument analysis: requests analysis (evidence: `README.md`)
- Host agent → Decision mirror: requests mirror (evidence: `README.md`)
