consilium-principis

**English** · [Русский](README.ru.md)

<div align="center">

<img src="assets/logo-consilium-principis.png" width="300" alt="Consilium Principis" />

# Consilium Principis

**A personal board of several AI advisors — for decisions where one confident answer isn't enough.**

<img src="assets/demo-refusal-en.gif" width="760" alt="Consilium refuses a fabricated quote and confirms a real one word-for-word" />

<sub>Live: a made-up "Aurelius quote" is refused; a real line is confirmed 🔵 word-for-word with its source. The verdict is computed by code on every run, not scripted.</sub>

Each advisor looks through their own lens, argues with you and with the others, and the board
converges on a single next step. But above all: Consilium doesn't pass off a plausible fabrication
as the author's words — a 🔵 quote is checked by code against the source text **word-for-word**;
with no exact line in the corpus, the advisor simply doesn't quote.

[![CI](https://github.com/ilyautov/consilium-principis/actions/workflows/ci.yml/badge.svg)](https://github.com/ilyautov/consilium-principis/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
![no extra keys · no extra cost](https://img.shields.io/badge/no%20extra%20keys%20%C2%B7%20no%20extra%20cost-success)
![MCP ready](https://img.shields.io/badge/MCP-ready-purple)

</div>

---

## What this is

**Consilium Principis is a skill and MCP server for AI agents.** You connect it to your agent, ask a
question you need to decide on, and it gathers a board around the table: Sun Tzu, Marcus Aurelius,
Machiavelli, Epictetus, and whoever else you add. Each looks at it through their own lens, leans on
their own texts, and argues — with you and with the others. At the end you get one synthesis and one
next step. And if the question is quantifiable ("which is more worthwhile, X or Y"), the board
doesn't eyeball it — it breaks the decision into numbers and runs them through a Monte Carlo.

This project doesn't ask an AI to roleplay a sage — we tried to build a tool, not a roleplay game or
an aphorism generator. Why you can trust its quotes comes next.

One honest thing about who's at the table: these aren't the thinkers themselves but their **AI
versions** — a prism of their views over the corpus of their public texts. Nobody is "speaking from
beyond the grave." An advisor holds the author's lens and leans on their words, but it stays a model
— and we say so plainly.

No extra keys or payment — Consilium runs on the agent you already have. Checking quotes needs no
internet; a full offline setup just takes local models.

## How it differs from other councils

The "several AIs deliberate" mechanic is already common. What sets Consilium apart isn't the number
of voices. It's that a claim can be **re-verified**, and where it can't, the council honestly stays silent:

| | "Roleplay a sage" (one AI) | LLM-Council-style board | **Consilium** |
|---|:---:|:---:|:---:|
| Different lenses, disagreement as a feature | ± | ✅ | ✅ |
| **Verbatim quote checked word-for-word against the original, with its source** | ✗ | ✗ | **✅** |
| **Honestly silent outside the corpus (fail-closed)** | ✗ | ✗ | **✅** |
| Quantifiable question → Monte Carlo (📐) | ✗ | ✗ | ✅ |
| No extra keys or payment | ± | ✗ | ✅ |

<sub>A "personal board of directors" is a mainstream practice (an HBR concept); the bet on grounding
and citation transparency has been validated by both the market (Delphi, $16M from Sequoia) and
academia (multi-persona debate, the ALCE benchmark). Our angle is rigor: a verifiable quote and an
honest refusal.</sub>

## How it looks

<div align="center">

<sub>The refusal + word-for-word verification is in the demo up top. More scenarios — wrong-mouth attribution, Monte Carlo, cross-lingual: **[demo gallery →](docs/demo/gallery.md)**</sub>

</div>

You ask in plain words:

> **"I'm juggling four directions at once. What should I focus on?"**

And instead of one smooth, hedge-everything answer, you get a **session** where each advisor looks from their own vantage point, and they disagree:

> **Sun Tzu** (the "Strategist" lens) 🟡 "Whoever is strong everywhere is strong nowhere. Of the four fronts, pick the one where you have the advantage, throw your weight there; hold the rest at a minimum."
>
> **Machiavelli** 🟡 "Spread thin, you're weak on every front and vulnerable on all of them. The question isn't 'what to grow' but 'what you're willing to give up'. That is the decision."
>
> **Marcus Aurelius** 🔵 "Let it be thy earnest and incessant care as a Roman and a man to perform whatsoever it is that thou art about" *(Meditations, trans. Long)*. Do the thing in front of you wholly; four things at once is scattering.
> ↳ and ask him something that isn't in his texts, and **he'll honestly stay silent instead of inventing a quote.**

Next comes the **synthesis** (where they actually agree) and **one concrete next step**. Disagreement here is a feature: you see the decision from angles you'd have missed on your own. And if the question is quantifiable ("which is more worthwhile, X or Y"), the board will offer not to argue by eye but to **calculate** (see 📐 below).

<sub>The example is illustrative, and the advisors are AI representations built from texts, not the authors themselves. 🟡 = a thought in the author's spirit (the model reasons through their lens), 🔵 = a verbatim line with a source in the corpus. All examples are public-domain figures (Sun Tzu, Aurelius, Machiavelli, Epictetus); who sits at YOUR table is your call. Your real sessions are written to `council/` locally, and never go into git (see [technical design](docs/MANUAL.md)).</sub>

## What you can ask

No need to learn commands. Say **"what can you do?"** and the board will show a menu. For example:

- **"What could go wrong with my launch?"** a premortem: where it'll break, what to shore up in advance
- **"What would Aurelius say about burnout?"** a single advisor, strictly from his texts
- **"Have Sun Tzu and Machiavelli argue about X"** pit two viewpoints against each other
- **"Which is more worthwhile, going back to a salaried job or sticking with my own thing?"** 📐 a decision map: break it into numbers and calculate (rather than argue by eye)
- **"Help me win this argument"** a position breakdown like a chess engine: your moves, counters, an honest verdict
- **"Am I contradicting myself?"** a mirror: what you say vs. what you actually choose

## Why you can trust this

This isn't "a chatbot playing sage." Every word is tagged by a **protective contour**.

The real proof isn't in the tone but in verifiability: **a verbatim quote (🔵) is checked against
the author's genuine corpus by code, word-for-word**, and carries a source. If the exact line isn't
found, the advisor honestly stays silent (fail-closed) instead of making it up. That's what
separates a decision tool from "roleplay a sage": every claim can be re-checked.

| Marker | What it means |
|:---:|---|
| 🔵 | **verbatim quote** from the author's genuine corpus, verified word-for-word, with a source |
| 🟢 | **verbatim, but from commentary/interpretation** (not in the author's own voice), with the commentator named |
| 🟡 | **in the spirit of the author**, but not their exact words, honestly marked |
| 📐 | **calculation**: your own numbers, run through Monte Carlo; not truth, not a quote, just your own model run N times |
| *abstention* | question outside the corpus → the advisor **stays silent instead of making things up** |

Plus **different lenses, not a chorus**: each advisor keeps their own angle, and their disagreement is a working part, not a bug. You see the decision from sides you'd otherwise collapse into one.

The honesty contour itself is code, not a model: it checks every quote against its source on any machine, no keys, no cost. Without semantics only search precision gets weaker — honesty never does. Candidate relevance is scored by a two-phase gate: a model judges, code applies the threshold, so topically-close-but-not-actually-answering material won't slip through as 🔵. By default the host does that scoring — an interested party, which `doctor` labels honestly; want an independent judge, connect a local (ollama) or API backend, an explicit choice. The verbatim 🔵 gate never depends on the judge: code holds it.

## Calculate, not just discuss: the 📐 decision map

The board has two modes. The first is a **session** (discuss, challenge, synthesize). The second
kicks in on a **quantifiable** decision question ("which is more worthwhile", "is it worth it", "X
or Y"): instead of an eyeballed answer, the board breaks the choice down into a **decision map**,
that is options, quantities (your own numbers, elicited as three-point "worst / typical / best"
estimates, to avoid anchoring), and formulas. Then comes **deterministic Monte Carlo** (code does
the math, zero LLM in the calculation, same seed gives the same result): P(best option), a tornado
sensitivity chart, what actually drives the outcome. A "do nothing" option is mandatory. Breaking it
down with a premortem ("a year passed, it failed, why?") and a 2×2 on the key uncertainties is also
something the board does. Everything sits under the 📐 label, **next to** 🔵/🟢/🟡 but never blended
in: this isn't wisdom, it's your own model, run numerically. And if you log the decision, later the
board will check the **forecast against what actually happened** (the outcome loop: calibrating your
model, not "right or wrong guess").

**By default, plainly human:** the board answers **in your language** and gives a clean bottom line without extra numbers. A 🔵 quote stays in the original (so it can be verified), with a translation alongside it. Need the full breakdown (probabilities, robustness of the position, source-by-source markup), just say "show me the details."

## Installation

### Via Claude Code plugin (reco