A four-valued logical system grounded in non-equilibrium thermodynamics. MPC formalises the distinction between what can be true together and what can be maintained together under finite energetic and temporal budgets.
Truth values: c (committed) · s (suspended) · k (conflict) · r (reset)
| Feature | Detail |
|---|---|
| Multi-backend model routing | Ollama (local) · Anthropic · Google — auto-detected from model name |
| Model dropdown in UI | Dynamically populated from Ollama /api/tags; cloud models listed statically |
| QuTiP partition function | Exact Z = Tr exp(−βH) for Ising Hamiltonian; falls back to classical pair approximation |
| Free energy F = −kT ln Z | Added to EnergyModel; used everywhere instead of arithmetic load sum |
| NetKet spin-glass solver | Ground-state energy & stable-subset config via exact ED (N≤16) or VMC |
| 3-D Plotly free-energy surface | Interactive F(T, E*) surface with N_max Theorem 6.1 contour overlay |
| API key persistence | Keys entered in the UI are written to .env via POST /setenv |
| Historical heatmap (v0.2) | η_i accumulation across reasoning traces (Addendum V) |
# Core (Anthropic + Google backends)
pip install -e .
# Add QuTiP for exact partition function
pip install qutip
# Add NetKet for spin-glass ground-state solver (requires JAX)
pip install "jax[cpu]" netket
# Or everything at once
pip install -e ".[full]"Requires Python ≥ 3.11.
- Install Ollama and pull any model:
ollama pull llama3 # or mistral, phi3, gemma2, qwen2, … - The MPC server queries
http://localhost:11434/api/tagsat startup — installed models appear automatically in the Model dropdown. - No API key required for local models; the key field hides automatically.
| Provider | Key env var | Models |
|---|---|---|
| Anthropic | ANTHROPIC_API_KEY |
claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-* |
GOOGLE_API_KEY |
gemini-2.5-pro-preview-, gemini-2.0-flash, gemini-1.5- |
Keys can be set in .env (auto-loaded at startup) or entered in the UI
(saved to .env on blur via POST /setenv).
export ANTHROPIC_API_KEY=sk-ant-… # or set in .env
mpc-serverStarts:
- MCP server on stdio (register in Claude desktop config or any MCP client)
- Reference browser UI on http://localhost:7771
| Tool | Description |
|---|---|
compile_text |
Full MPC analysis: hypotheses, phases, compatibility matrix, QuTiP free energy, spin-glass ground state, Theorem 6.1 bound |
read_claims |
Per-claim phase assignment (c/s/k/r) |
budget_estimate |
Theorem 6.1 bound N_max — no API call required |
{
"mcpServers": {
"mpc": {
"command": "mpc-server",
"env": { "ANTHROPIC_API_KEY": "sk-ant-…" }
}
}
}import mpc_core
# Full analysis (Anthropic, default model)
result = mpc_core.compile("Your text here…", api_key="sk-ant-…")
print(result.energy_model.free_energy) # F = -kT ln Z
print(result.ground_state.energy) # Ising ground-state energy
print(result.ground_state.stable_ids) # Most compatible hypothesis subset
print(result.analytical_summary)
# Use a local Ollama model instead
result = mpc_core.compile("…", model="llama3:8b")
# Use Google Gemini
result = mpc_core.compile("…", model="gemini-2.0-flash", api_key="AIza…")
# Per-claim phase assignment
phases = mpc_core.read_claims(
["All ravens are black.", "Some ravens are albino."],
api_key="sk-ant-…",
model="claude-sonnet-4-6",
)
# Budget theorem (no API call)
est = mpc_core.budget_estimate(N=8, d_avg=2.5, epsilon_min=1.2)
print(est.interpretation)
# Free-energy surface (no API call — uses existing epsilon matrix)
from mpc_core import free_energy_surface
surface = free_energy_surface(my_epsilon_matrix, T_range=(0.2,5), E_star_range=(2,40))
# surface["F"][T_index][E_star_index] → F value
# Historical depth across a reasoning trace
seq = mpc_core.compile_sequence(["Step 1…", "Step 2…", "Step 3…"], api_key="sk-ant-…")| Tab | Description |
|---|---|
| Analyse text | Full MPC analysis with hypothesis cards, thermodynamic strip (Z, F, S), ground-state box |
| Read claims | One claim per line → instant phase assignment |
| 3D Free Energy | Interactive Plotly surface F(T, E*) with N_max contour |
| Energy landscape | Animated 2-D canvas with budget/temperature sliders |
| Compatibility matrix | Pairwise ε_ij frustration table |
| Budget calculator | Theorem 6.1 N_max arithmetic — no API key needed |
| Historical Heatmap | η_i accumulation heatmap across a reasoning trace |
# Unit tests + arithmetic (no API key)
pytest tests/ -v
# Model routing smoke-test (all three backends)
python test_model_routing.py # arithmetic only
python test_model_routing.py --anthropic # Anthropic live call
python test_model_routing.py --google # Google live call
python test_model_routing.py --ollama llama3 # local Ollama call
python test_model_routing.py --anthropic --google --ollama llama3 # all
# Full suite with live API
ANTHROPIC_API_KEY=sk-ant-… pytest tests/ -vmpc_core/
__init__.py Public surface re-exports
compiler.py compile() · read_claims() · budget_estimate() · compile_sequence()
router.py NEW — model routing: Ollama · Anthropic · Google
thermodynamics.py NEW — QuTiP partition function · NetKet spin-glass solver · free_energy_surface()
models.py MPCResult dataclass hierarchy (now includes free_energy, GroundState)
mpc_server/
server.py MCP stdio server · localhost:7771 HTTP proxy
NEW endpoints: GET /models · POST /setenv · action free_energy_surface
static/
index.html Seven-tab UI — Plotly 3D surface · model dropdown · key persistence
tools/
mpc_proxy.py Standalone CORS proxy (only needed for filesystem HTML use)
tests/
fixtures/ instrument.txt · simple.txt · complex.txt
test_compiler.py
test_model_routing.py NEW — smoke-tests for all three routing backends
- v0.1 ✓ Phases 1–5: package structure, compiler, MCP server, reference UI
- v0.2 ✓ Multi-backend routing · QuTiP partition function · NetKet spin-glass · 3-D Plotly · Historical heatmap · API key persistence
- v0.3 Spectral Laplacian extension of Theorem 6.1, community-aware N_max bounds
- v0.4 Streaming analysis; differential η_i display per hypothesis per step
MIT