Plotifi Engine

Plotifi — a deterministic portfolio-math engine exposed over MCP, so any AI agent can compute portfolio math instead of hallucinating it.

The same inputs give the same answer, to the decimal, forever.

That is the product claim. If two runs with the same engine_version, pinned toolchain, and identical inputs disagree, we treat it as a bug — not a “numerical tolerance” shrug.

Status

M3 — MCP server & public v0.1.0. Stdio MCP tools for optimize, frontier, CVaR, risk parity, and backtest. Copy-paste host config and worked examples: docs/MCP.md (install → first correct agent answer in <5 min). Release steps: docs/RELEASE.md. Registry listing handoff (Sri): LISTING_HANDOFF.md.

Prior: M2.5 reconciliation — RECONCILIATION.md, docs/VOLATILITY_DEFECT.md.

Why determinism matters

Agent callers will retry, fan out, and cache. If the engine drifts across threads, OSes, or Python patch levels, every downstream tool call becomes non-auditable. Plotifi pins BLAS threads, hashes canonical inputs, surfaces solver status (never silent fallbacks), and locks numerics behind golden files.

Quickstart (60 seconds)

Agent / MCP path (strangers start here):

pip install plotifi   # after PyPI publish; else pip install -e . from a clone
# Paste the config block from docs/MCP.md into Claude Desktop or Cursor

Library / contrib path:

git clone https://github.com/Plotifi/plotifi-engine.git
cd plotifi-engine
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-lock.txt
pip install -e ".[dev]"

# Bundled sample — zero external data
python -c "from plotifi import load_sample_returns, sample_covariance, mean_variance_optimize; \
r=load_sample_returns().result; mu=r.mean().to_numpy(); cov=sample_covariance(r.to_numpy()).result; \
print(mean_variance_optimize(mu, cov).result.weights)"

ruff check . && mypy src tests && pytest -v
plotifi-scoreboard
plotifi-mcp   # MCP stdio server

What this is

• Deterministic mean-variance, CVaR (Rockafellar–Uryasev), risk-parity, and backtest computations
• Canonical response envelopes (result, input_hash, engine_version, solver, iterations, warnings)
• MCP tools for agent callers — docs/MCP.md
• Mirror and strict numerical modes reconciled against the legacy ionic-mirror app — RECONCILIATION.md

What this is not

• Investment advice, rankings, or recommendations
• Custody, order execution, or portfolio storage
• Live or licensed market data (frozen fixtures only in v0)
• A UI or dashboard
• Bit-identical floats across arbitrary CPU/BLAS stacks (see REPRODUCIBILITY.md)

Honest limitations

A quant should trust us for auditable, pinned, offline portfolio math — and should not treat envelopes as investment advice or live risk signs.

Tooling

Reproducibility & performance

• REPRODUCIBILITY.md — pins, BLAS, hashing, guarantees
• PERFORMANCE.md — wall-clock ceilings (100-asset frontier, 10-year backtest); regressions fail CI
• tests/golden/TOLERANCE.md — golden tolerance + version-bump policy

Names

PyPI / GitHub / docs domain reservation status is tracked in NAMES.md (owner: Sri; issue #7).

Contributing

See CONTRIBUTING.md. Work issue-by-issue in milestone order. Apache-2.0 licensed.

License

Apache License 2.0 — see LICENSE and NOTICE.