Repository navigation
Releases
0.7.0 — numerical rigor, honest failures, and the pre-trade layer
git checkout main && git pull
git tag -a v0.7.0 -F - <<'EOF'
0.7.0 — numerical rigor, honest failures, and the pre-trade layer
Every number the engine reports is now the number the method computed, in a
unit the caller can name, with a loud failure where the method could not
deliver — and the pre-trade layer it lacked.
Breaking: an inaccurate solve raises instead of returning a degraded answer;
a target return is a floor rather than an equality; the Sharpe ratio and the
historical mean are arithmetic; check exits 2 on an impossible mandate;
scenarios is presets; the pandas floor is 2.2; hashes carry hash_version 2.
Added: a point-in-time universe with a genuine third state, shock-based
stress scenarios, a mandate audit that can refuse a non-compliant book, and
structural feasibility that no longer reports a solver crash as an
impossible mandate.
881 tests to 1307. CI gains type checking, a Windows cell and a pinned-pandas
cell; those three caught four defects no local run could see.
EOF
git push origin v0.7.0
v0.5.3 — Number checks
0.5.3 — the numbers that were wrong
A patch release from a full-package review. Nothing new to learn; several
things you may already be looking at now say something different, and each
one is listed here with which way it moves. The review itself, all forty
findings with file:line and reproduction evidence, is in
docs/reviews/2026-09-01-code-review.md.
Results that change
- Backtest drift no longer forces full investment. The simulation core
renormalised drifted weights by the sum of the positions, which is the
book's growth only when the book is fully invested. A half-invested book
was 100% invested from its second bar; a 60/−40 long-short became 264/−164.
Weights now drift by the book's own growth. A fully invested target replays
exactly as before; every partial, open-budget or long-short backtest moves. - Black-Litterman with no views returns the market portfolio. The
equilibrium prior uses the half-conventionπ = δΣw; the mean-variance
sub-solve it fed does not, so the effective aversion was doubled and the
no-view answer sat halfway between the market and minimum variance. Every
BL allocation moves, toward the market portfolio. Repeated solves on one
optimizer are also idempotent now; it no longer overwrites its own prior. - Max-Sharpe and max-diversification honour a leverage cap. The
ray-space reformulation carried bounds, layers and the benchmark budgets
and dropped the gross-exposure cap: a 1.2× mandate came back at 2.5× with
nothing inignored_constraints. The cap is a hard constraint now, and
fully_invested=False, which a ray cannot express, is warned about and
reported rather than silently returned as a fully invested book. - Bayes-Stein shrinkage is about 250× stronger on daily data. Jorion's
intensity counts observations, so its quadratic form has to be per
observation;shrunk_meanhanded it annualised moments. Every
expected_returns_method="shrunk_mean"vector moves toward the
minimum-variance return, which is what shrinkage is for. - A missing return no longer poisons a backtest, and comparisons score
both streams over their common window. A NaN on an asset the book never
held turned the whole NAV path NaN; a walk-forward padded to the fitted
stream's length was scored as zero returns on the padding, which flattered
theDegradationcolumn whenever the out-of-sample run was losing.
Interfaces that now agree with each other
optengine check,optimizeandbacktestbuild their inputs the same
way, socheckcan no longer call ready a mandateoptimizethen refuses,
and it accepts the currency, benchmark and active-risk flagsoptimize
does.--jsonfailures carry their reason.- The MCP
optimizer=override keeps the rest of the mandate (it was solving
max-Sharpe against a cash rate of zero);optimizeraises the documented
ToolErroron an infeasible mandate;backtestis annualised on the
config'speriods_per_year. - The ingest cache refuses a partially failed or FX-degraded panel instead
of serving it as "missing" for a day, and keys on provider options so the
fileprovider cannot serve one file's panel for another. - FX alignment fills a leading gap for at most five rows and refuses beyond
that, rather than valuing a month of prices at a rate from the future. - A config with a key the loader does not read is refused. That check is how
the shippedconfig/indices.yamlturned out never to convert its
currencies; it does now.
What did not change
Fully invested backtests, and every optimizer except black_litterman,
max_sharpe under a leverage cap and max_diversification under one,
produce the same numbers as 0.5.2. The existing 824 tests pass untouched;
44 new ones lock each fix in.
Full detail in the changelog.
v0.5.2
pip install --upgrade finport-optengine
A patch, and a documentation-only one. No optimizer, estimator or backtest
produces a different number, no signature moved, and the 837 tests are
unchanged. There is nothing here that can break you and nothing to hurry for —
but there is now somewhere to look up what a function takes and what it
refuses.
Added
A generated API reference, at
alanvaa06.github.io/Optimization_Engine/api.
Every public module, rendered from the package's own docstrings by
scripts/build_api_docs.py and republished on every push to main, so the
only file that can go stale is one that does not exist. It builds on every
pull request too, with --strict — which refuses to skip a module it cannot
import, because a missing extra quietly dropping mcp_server from the
published pages is exactly the failure a generated reference is supposed to
eliminate.
docs/ERRORS.md
— the refusal contract. This engine's argument is that it refuses rather
than fails obscurely, and until now the refusals were undocumented. All
twenty-one exception types, grouped by what they actually mean: your inputs
are wrong (fix them, retrying is pointless) / your mandate is impossible
(relax something, the exception names which) / the world got in the way
(retry, or fix the environment). Plus the full IngestError hierarchy with
what the service does about each subclass — it retries ProviderTransientError,
drops the identifier on IdentifierNotFoundError, and aborts the whole run on
ProviderCredentialsError because no other identifier is going to
authenticate either.
It also documents the CLI's exit codes, and the distinction worth honouring in
a script: 1 means the engine worked and is telling you something — check
found the mandate infeasible, ingest completed but the panel is incomplete —
while 2 means it never got that far.
And a closing section on what does not raise, which is the part that catches
people: degraded cost models, skipped identifiers, post-solve constraint
breaches, data-quality findings. All reported, none raised. try alone will
not see them.
Changed
Docstring coverage went from 74.6% to 100% across the 677 public
definitions — 166 that had none now have one. This is the part a pip install
actually receives: docstrings ship inside the wheel, so help(), IDE tooltips
and Jupyter's ? all improve. The wheel carries 392 KB of docstrings against
0.5.1's 279 KB.
Parameters are documented with their units, which is where most of the real
ambiguity lived: cost_bps per side rather than round-trip, execution_lag in
bars, alpha as a tail probability and not a confidence level (0.05 for the
95% CVaR, not 0.95), VaR levels in percent rather than as fractions, and
which figures are annualized on what basis. 86 functions documented their
arguments before; 379 do now.
Every public function that raises now declares what and when. There were
364 raise statements behind 67 Raises: sections. That gap is closed.
AGENTS.md now states that docstrings are the reference's only source, and
therefore part of the public surface rather than a courtesy.
Full detail in CHANGELOG.md.
v0.5.1 — --json keeps its promise when a command raises
pip install --upgrade finport-optengine
A patch. One bug, in the part of --json that only a failing run reaches.
Nothing an optimizer, estimator or backtest produces is different, so there
is no reason to hold off upgrading and no reason to hurry if you never parse
the CLI's output.
Fixed
--json emitted nothing at all when a command raised. The mode promised
that a failure still produces a parseable document, and delivered it only for
a command that returned a non-zero code. A raised exception — an unreadable
config being the cheapest way in, and reachable from all four commands —
propagated instead: traceback on stderr, stdout empty.
That is precisely the ambiguity the flag exists to remove. A caller parsing
stdout had to tell "the command produced no output" apart from "the command
produced output I could not parse", which is the one thing --json is
supposed to make unnecessary.
Before:
$ optengine optimize --config /no/such.yaml --json
[stdout empty, traceback on stderr, exit 1]
After:
$ optengine optimize --config /no/such.yaml --json
{
"schema_version": "1.0",
"command": "optimize",
"error": "FileNotFoundError: [Errno 2] No such file or directory: '/no/such.yaml'",
"exit_code": 1
}
The payload now carries the exception's type and message, so a caller can
tell a missing file from an unparseable one without scraping a traceback.
The traceback itself still goes to stderr, where someone debugging it looks.
Two tests cover both halves — that the document survives the exception, and
that catching it did not cost the human their diagnosis.
Changed
The README announces the agent-facing surface added in 0.5.0 instead of
leaving it to the changelog. The MCP server has its own section with the
install, how to register it with a JSON-config client and with
claude mcp add, and what each of the five tools answers; --json is
documented in the CLI section with real jq output rather than a sketch of
it. The development install gains the mcp extra it needed in order to run
the MCP tests at all.
Full detail in CHANGELOG.md.
v0.5.0 — JSON output, MCP server, and a pre-flight check that agrees with the solve
pip install --upgrade finport-optengine
A minor rather than a patch: this adds public API surface — an optional
dependency, a second console script, and a function lifted out of
run_engine — on top of a fix to a pre-flight check that was validating a
different mandate from the one it preceded.
Fixed
check validated a different mandate from the one optimize solved. On a
config with no expected_returns block it derived the vector as zeros while
run_engine derived it from the return history, so the pre-flight reported a
reachable return range of exactly zero to zero and would call a target
unreachable that the solve then reached. Both now go through
resolve_expected_returns, extracted from run_engine so the two cannot drift
apart again. Affects optengine check and the MCP check_mandate.
Added
An MCP server, optengine-mcp, behind the mcp extra (Python 3.10+):
pip install "finport-optengine[mcp]"
optengine-mcp # speaks stdio
Five tools — list_optimizers, describe_optimizer, check_mandate,
optimize, backtest — returning the same payloads as --json, from the same
module, so the two cannot disagree. Anticipated failures raise the SDK's
ToolError, which is the only class whose message reaches the client;
anything else is wrapped as "Error executing tool optimize" with the reason
discarded.
--json on optimize, backtest, check and describe. Human narration
moves to stderr, so stdout is one parseable document and an agent or pipeline
can act on a result without scraping a formatted table. Every payload carries
schema_version, and a command that fails before producing a result still
emits JSON — an object with error and exit_code — so a caller never has to
distinguish "no output" from "output I could not parse".
optimization_engine.reporting.payloads, the JSON contract as an importable
module rather than formatting buried in the CLI. Keys are chosen for the reader
instead of inherited from the attributes they came from, and a value absent
this run is null rather than a missing key, so a consumer can test a value
and never a key.
AGENTS.md and llms.txt — an API map for coding agents, including the
mistakes that cost real debugging time here: sample_dataset() returns prices
rather than returns, the solver is in result.extras, the backtest hashes are
on result.meta, and unconstrained max_sharpe puts 98.5% in cash on the
sample panel.
CI runs the MCP suite. The mcp extra is in no other job's install — it
cannot go in the 3.9-inclusive matrix — so those tests would have skipped
everywhere and looked like coverage.
Full detail in CHANGELOG.md.
v0.4.1
A correctness and packaging release, out the same day as 0.4.0 because both
defects only show up somewhere other than the developer's own machine.
covariance_method="shrink" gave different answers on different machines.
It routed through riskfolio-lib when that package happened to be installed
and fell back to scikit-learn's Ledoit-Wolf when it did not — and nothing in
CovarianceDiagnostics recorded which one had run. On the sample panel the
two estimates differ by 8.3% of the largest element of the covariance
matrix: an estimator change, not a rounding difference, decided by whether a
pip install had happened. The fallback also caught bare Exception, so any
riskfolio error would have swapped the estimator just as quietly.
shrink is now a documented alias for ledoit_wolf. Configs and saved
scenarios written against it keep loading, and now reproduce anywhere. The
extras optional dependency existed only to feed that route and is gone with
it — if you installed finport-optengine[extras], drop the suffix.
This is not a judgement about riskfolio-lib, which is good work under a
compatible licence. The problem was one method name resolving to two
different estimators.
The project page on PyPI showed nine broken images. Every figure and
repository link was a relative path, which resolves against the repo on
GitHub and against nothing on PyPI, where the description is rendered with no
base URL. All absolute now.
The README also leads with pip install and a runnable quickstart instead of
burying them 600 lines down. That example's printed output is checked against
what the code in the same block actually produces, so it cannot drift into
fiction.
No optimizer, backtest or analytics behaviour changed otherwise. If you were
not using shrink and did not install the extras extra, upgrading changes
nothing but the documentation.
Full notes in CHANGELOG.md.
v0.4.0
First release published to PyPI: pip install finport-optengine
The distribution is named finport-optengine; the import name stays
optimization_engine and the console script stays optengine.
No optimizer, estimator or backtest changed behaviour — every number this
version produces matches 0.3.0.
The core install is ~190MB smaller. matplotlib and seaborn were
never imported by anything and are gone. plotly, openpyxl, xlsxwriter
and statsmodels now sit behind the viz, excel and stats extras;
reaching a feature whose extra is missing raises with the install command
that fixes it. pip install "finport-optengine[all]" for everything.
Fixed a crash that could take your process down. scs 3.3.0 ships an
incomplete Intel oneMKL bundle, and SCS is in the default solver fallback
chain — a solve that got past CLARABEL and ECOS aborted the interpreter
with no traceback. That version is now excluded.
Also: py.typed actually ships now, so type checkers see the annotations;
optimization_engine.ingest is reachable from the top-level package.
Full notes in CHANGELOG.md.