Metadata-Version: 2.4
Name: plotifi
Version: 0.1.0
Summary: Deterministic portfolio-math engine exposed over MCP
Author: Plotifi
License: Apache-2.0
Project-URL: Homepage, https://github.com/Plotifi/plotifi-engine
Project-URL: Documentation, https://github.com/Plotifi/plotifi-engine/blob/main/docs/MCP.md
Project-URL: Issues, https://github.com/Plotifi/plotifi-engine/issues
Project-URL: Changelog, https://github.com/Plotifi/plotifi-engine/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=14
Requires-Dist: scipy>=1.11
Requires-Dist: mcp<2,>=1.6
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pandas-stubs>=2.1; extra == "dev"
Provides-Extra: snapshot
Requires-Dist: yfinance==0.2.54; extra == "snapshot"
Dynamic: license-file

# 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](docs/MCP.md)** (install → first correct agent answer in <5 min).
Release steps: [docs/RELEASE.md](docs/RELEASE.md). Registry listing handoff
(Sri): [LISTING_HANDOFF.md](LISTING_HANDOFF.md).

Prior: M2.5 reconciliation — [RECONCILIATION.md](RECONCILIATION.md),
[docs/VOLATILITY_DEFECT.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):

```bash
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:**

```bash
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](docs/MCP.md)
- Mirror and strict numerical modes reconciled against the legacy
  `ionic-mirror` app — [RECONCILIATION.md](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](REPRODUCIBILITY.md))

## Honest limitations

| Claim | Reality |
| --- | --- |
| Same inputs → same outputs | Guaranteed under pinned toolchain + BLAS thread pin on CI platforms |
| Cross-hardware bit identity | **Not** guaranteed (x86 vs ARM, OpenBLAS vs MKL) |
| Live market data | **Not** reproducible; use frozen fixtures |
| Solver iteration counts | Diagnostic only — may vary with BLAS build |
| CVaR / risk parity | Scenario/sample estimators; not a substitute for fund risk systems |

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

## Tooling

| Tool | Command |
| --- | --- |
| Lint | `ruff check .` |
| Format | `ruff format .` |
| Types | `mypy src tests` |
| Tests | `pytest -v` |
| Determinism | `pytest tests/determinism/ -v` |
| Golden corpus | `pytest tests/golden/ -v` |
| Performance budget | `pytest tests/performance/ -v` |
| Scoreboard | `plotifi-scoreboard` |
| MCP server | `plotifi-mcp` / `python -m plotifi.mcp` |
| Agent eval | `pytest tests/agent_eval/ -v` |
| Reconciliation | `pytest tests/reconcile/ -v` |
| MCP docs | [docs/MCP.md](docs/MCP.md) |
| Release (PyPI tag) | [docs/RELEASE.md](docs/RELEASE.md) |
| Listing handoff (Sri) | [LISTING_HANDOFF.md](LISTING_HANDOFF.md) |
| Vol defect writeup | [docs/VOLATILITY_DEFECT.md](docs/VOLATILITY_DEFECT.md) |
| Demo handoff (Sri) | [DEMO_HANDOFF.md](DEMO_HANDOFF.md) |

## Reproducibility & performance

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

## Names

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Work issue-by-issue in milestone order.
Apache-2.0 licensed.

## License

Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
