Public API and versioning¶
From version 1.0, Market Lab follows Semantic Versioning:
MAJOR.MINOR.PATCH. This page defines what the public API is, what may change in each
kind of release and how a feature is retired.
What is public¶
| Public | Where |
|---|---|
Platform and every method without a leading underscore |
sim_platform.application.platform, imported as from sim_platform import Platform |
| The Agent SDK | sim_platform.sdk (also the separate sim_platform_agent_sdk wheel, versioned on its own) |
| Model settings and providers | ModelProfile, ProviderError, ModelProvider, RehearsalProvider, OpenAICompatibleChat |
| Execution settings | sim_platform.execution.ExecutionConfig and its fields |
| Research helpers | research.attribution, pnl_attribution, sweeps, forward, portfolio, overfitting, metrics, universe |
| Data connectors | sim_platform.market.connectors |
| Diagnostics and offline mode | sim_platform.diagnostics.configure_logging, sim_platform.network |
| Command line | market-lab command names, their arguments and their JSON output fields |
| Files | Price-bar CSV, news, fundamentals and documents formats; experiment, suite and sweep JSON configurations; report formats named by their format field |
| Saved data | Workspaces created by an earlier 1.x release open in every later 1.x release |
Everything else is internal, including modules not listed here, names with a leading underscore, the Desktop's frontend and bridge, the native library's C interface, and database tables. Internal code may change in any release.
tools/check_public_api.py records the names and signatures of the public objects in
tests/fixtures/public-api.json, and CI fails when they change without the record
being updated in the same reviewed change.
What each release may change¶
| Release | May | May not |
|---|---|---|
| Patch (1.0.x) | Fix bugs, improve documentation and performance | Change any public name, signature, output field or file format |
| Minor (1.x.0) | Add public names, optional arguments, output fields and file-format fields; deprecate | Remove or change existing public behaviour |
| Major (x.0.0) | Remove deprecated names; change behaviour, with migration notes | Remove anything that was not deprecated for at least one minor release |
A change that alters a simulated result for the same inputs (fills, fees, metrics) is a behaviour change: it is announced in the changelog, and runs recorded before it keep replaying with the rules recorded in their lineage or are refused, never silently recalculated.
Deprecation¶
- The replacement ships first, in a minor release.
- The old name keeps working and emits a
DeprecationWarningnaming its replacement and the earliest version that may remove it. - The changelog lists it under Deprecated, and the API reference marks it.
- It is removed no earlier than the next major release.
Before 1.0¶
Releases 0.x make no compatibility promise: any minor release may change the API. The changelog lists every change.
Section index · All documentation