# API index

Source: https://docs.tradefloor.dev/api.html

> The recommended tradefloor API grouped by task, then every exported symbol with its tier (recommended, advanced, deprecated or internal) and its reference.

The classes and functions most code builds against are listed first, then every export with its tier.

## Recommended API

Build against these. Each has a reference section. Within a long-term support line, none of them is removed, renamed or changed in a way that breaks a call ([support policy](https://docs.tradefloor.dev/support.html#changes-allowed-in-a-patch-release)).

### Run a market

[>ArrowStream](https://docs.tradefloor.dev/core-types.html#output-tables)

[>Engine](https://docs.tradefloor.dev/core-types.html#engine)

[>Instrument](https://docs.tradefloor.dev/core-types.html#instrument)

[>Macro](https://docs.tradefloor.dev/core-types.html#macro)

[>run_many](https://docs.tradefloor.dev/core-types.html#run-many)

[>Universe](https://docs.tradefloor.dev/core-types.html#universe)

### Agents and scoring

[>Agent](https://docs.tradefloor.dev/evaluate.html#what-act-returns)

[>baselines](https://docs.tradefloor.dev/evaluate.html#reference-agents)

[>Cancel](https://docs.tradefloor.dev/evaluate.html#what-act-returns)

[>evaluate](https://docs.tradefloor.dev/evaluate.html#evaluate)

[>Limit](https://docs.tradefloor.dev/evaluate.html#what-act-returns)

[>Observation](https://docs.tradefloor.dev/evaluate.html#what-the-agent-sees)

[>rank](https://docs.tradefloor.dev/evaluate.html#rank)

[>Ranking](https://docs.tradefloor.dev/evaluate.html#ranking)

[>reference_agents](https://docs.tradefloor.dev/evaluate.html#reference-agents)

[>Scorecard](https://docs.tradefloor.dev/evaluate.html#scorecard)

[>tca](https://docs.tradefloor.dev/evaluate.html#tca-analyse)

[>versus_buy_and_hold](https://docs.tradefloor.dev/evaluate.html#capture-ratio)

### Scenarios

[>run_scenario](https://docs.tradefloor.dev/api-scenario.html#run-scenario)

[>Scenario](https://docs.tradefloor.dev/api-scenario.html#scenario)

### Forks and reproducibility

[>branch](https://docs.tradefloor.dev/api-counterfactual.html#checkpoint)

[>Checkpoint](https://docs.tradefloor.dev/api-counterfactual.html#checkpoint)

[>compare](https://docs.tradefloor.dev/api-counterfactual.html#agree-compare)

[>replay](https://docs.tradefloor.dev/api-counterfactual.html#checkpoint)

[>RunManifest](https://docs.tradefloor.dev/evaluate.html#runmanifest)

[>World](https://docs.tradefloor.dev/api-counterfactual.html#world)

### Model and presets

[>ModelParams](https://docs.tradefloor.dev/parameters.html#modelparams)

[>preset_names](https://docs.tradefloor.dev/parameters.html#preset-record)

[>preset_record](https://docs.tradefloor.dev/parameters.html#preset-record)

### Errors

[>OrderError](https://docs.tradefloor.dev/core-types.html#exceptions)

[>ScenarioValidationError](https://docs.tradefloor.dev/api-scenario.html#intervention)

[>ValidationError](https://docs.tradefloor.dev/core-types.html#exceptions)

### Adapters, RL and MCP

[>gym](https://docs.tradefloor.dev/rl-environment.html#tradingenv)

[>integrations](https://docs.tradefloor.dev/api-integrations.html#bringing-an-llm-agent)

[>mcp](https://docs.tradefloor.dev/api-integrations.html#the-mcp-server)

[>TradingEnv](https://docs.tradefloor.dev/rl-environment.html#tradingenv)

Everything else that imports from tradefloor is in the complete index below, with its tier. Some of those symbols aren't meant to be built against.

## Integrations

tradefloor.gymTradingEnv, a Gymnasium environment. Extra: pip install "tradefloor[rl]". Reference: [Gym environment](https://docs.tradefloor.dev/rl-environment.html).

tradefloor.edgarSnapshots of SEC filings and Universe.from_edgar. Reference: [Engine and data](https://docs.tradefloor.dev/core-types.html#real-companies-from-edgar).

tradefloor.mcpThe MCP server, command tradefloor-mcp. Extra: pip install "tradefloor[mcp]". Tool reference: [LLM adapters and MCP](https://docs.tradefloor.dev/api-integrations.html#the-mcp-server).

tradefloor.integrations.finrobotRuns a FinRobot agent inside a World, with an allowlist that controls which observations the agent sees. Extra: pip install "tradefloor[finrobot]" (Python 3.11 exactly). Usage: [Forks and counterfactuals](https://docs.tradefloor.dev/api-counterfactual.html#counterfactuals). Shipped studies: examples/rate-shock/ and examples/integrations/finrobot/.

tradefloor.integrations.openai_agentsRuns an OpenAI Agents SDK agent against a World. Extra: pip install "tradefloor[openai-agents]". Reference: [LLM adapters and MCP](https://docs.tradefloor.dev/api-integrations.html).

tradefloor.integrations.pydantic_aiRuns a PydanticAI agent against a World. Extra: pip install "tradefloor[pydantic-ai]". Reference: [LLM adapters and MCP](https://docs.tradefloor.dev/api-integrations.html).

tradefloor.integrations.langgraphRuns a LangGraph graph against a World. A LangGraph checkpoint holds the graph's workflow state but no market state. The reference lists what each checkpoint holds. Extra: pip install "tradefloor[langgraph]". Reference: [LLM adapters and MCP](https://docs.tradefloor.dev/api-integrations.html).

tradefloor.integrationsAdapters that run an OpenAI Agents SDK agent, a PydanticAI agent, a LangGraph graph or any plain Python function in one evaluation loop. Extras: pip install "tradefloor[openai-agents]", "[pydantic-ai]", "[langgraph]". Usage: [LLM adapters](https://docs.tradefloor.dev/llm-adapters.html). Reference: [LLM adapters and MCP](https://docs.tradefloor.dev/api-integrations.html).

## Complete index

Every symbol in tradefloor.__all__, and the optional submodules that extras install, in alphabetical order. Symbols with no link in the reference column are documented under exports without a reference page, below.

recommended build against it, listed above
advanced supported, for research, calibration and model work
deprecated an engine internal that warns on use and names its new import path
internal-transition a model internal that will leave the top-level namespace

| Symbol | Module | Tier | Category | Reference |
| --- | --- | --- | --- | --- |
| Agent | tradefloor.harness | recommended | evaluation | reference |
| AgentRecord | tradefloor.ranking | advanced | evaluation | reference |
| agree | tradefloor.counterfactual | advanced | counterfactuals | reference |
| Agreement | tradefloor.counterfactual | advanced | counterfactuals | reference |
| ArrowStream | tradefloor._core | recommended | data | reference |
| atlas | tradefloor.atlas | advanced | model utility | in the table below |
| baselines | tradefloor.baselines | recommended | evaluation | reference |
| Battery | tradefloor.fingerprint | advanced | evaluation | reference |
| battery | tradefloor.fingerprint | advanced | evaluation | reference |
| BATTERY_VERSION | tradefloor.fingerprint | advanced | evaluation | reference |
| bonds | tradefloor | advanced | market | reference |
| boundary | tradefloor.boundary | advanced | counterfactuals | reference |
| BoundaryMap | tradefloor.boundary | advanced | counterfactuals | reference |
| branch | tradefloor.checkpoint | recommended | reproducibility | reference |
| callable | tradefloor.integrations.callable | advanced | integration | reference |
| Cancel | tradefloor.portfolio | recommended | execution | reference |
| capture_ratio | tradefloor.baselines | advanced | evaluation | reference |
| capture_withheld | tradefloor.baselines | advanced | evaluation | reference |
| Cell | tradefloor.fingerprint | advanced | evaluation | reference |
| Checkpoint | tradefloor.checkpoint | recommended | reproducibility | reference |
| commit | tradefloor.fingerprint | advanced | trust | reference |
| common | tradefloor.integrations.common | advanced | integration | reference |
| compare | tradefloor.counterfactual | recommended | counterfactuals | reference |
| Comparison | tradefloor.counterfactual | advanced | counterfactuals | reference |
| counterfactual | tradefloor.counterfactual | advanced | counterfactuals | reference |
| DayLedger | tradefloor.manifest | advanced | reproducibility | reference |
| Divergence | tradefloor.counterfactual | advanced | counterfactuals | reference |
| edgar | tradefloor.edgar | advanced | data | reference |
| Engine | tradefloor._core | recommended | market | reference |
| EngineBatch | tradefloor._core | advanced | market | reference |
| envelope | tradefloor.envelope | advanced | trust | reference |
| evaluate | tradefloor.harness | recommended | evaluation | reference |
| Execution | tradefloor.tca | advanced | execution | reference |
| Exercise | tradefloor.portfolio | advanced | execution | reference |
| explain | tradefloor.explain | advanced | trust | reference |
| Explanation | tradefloor.explain | advanced | trust | reference |
| externalities | tradefloor.externality | advanced | evaluation | in the table below |
| Externality | tradefloor.externality | advanced | evaluation | in the table below |
| externality | tradefloor.externality | advanced | evaluation | in the table below |
| facts | tradefloor.facts | advanced | trust | in the table below |
| fair_value | tradefloor._core | advanced | model utility | in the table below |
| FairValue | tradefloor._core | advanced | model | in the table below |
| Fill | tradefloor._core | advanced | market | reference |
| Fingerprint | tradefloor.fingerprint | advanced | evaluation | reference |
| fingerprint | tradefloor.fingerprint | advanced | evaluation | reference |
| FingerprintComparison | tradefloor.fingerprint | advanced | evaluation | reference |
| Firing | tradefloor.interventions | advanced | scenarios | reference |
| Flip | tradefloor.boundary | advanced | counterfactuals | reference |
| flip | tradefloor.boundary | advanced | counterfactuals | reference |
| flow_impact | tradefloor | advanced | execution | reference |
| FlowImpact | tradefloor | advanced | execution | reference |
| GameRng | tradefloor._core | advanced | utility | in the table below |
| gym | tradefloor.gym | recommended | integration | reference |
| HiddenState | tradefloor.sandbox | advanced | evaluation | reference |
| History | tradefloor.harness | advanced | evaluation | reference |
| Instrument | tradefloor._core | recommended | market | reference |
| integrations | tradefloor.integrations | recommended | integration | reference |
| Intervention | tradefloor.interventions | advanced | scenarios | reference |
| interventions | tradefloor.interventions | advanced | scenarios | reference |
| Invariance | tradefloor.counterfactual | advanced | integration | reference |
| invariance | tradefloor.counterfactual | advanced | integration | reference |
| JSONRenderer | tradefloor.render | advanced | integration | reference |
| langgraph | tradefloor.integrations.langgraph | advanced | integration | reference |
| leaderboard | tradefloor.harness | advanced | evaluation | reference |
| Limit | tradefloor.portfolio | recommended | execution | reference |
| loss | tradefloor.loss | advanced | trust | in the table below |
| Macro | tradefloor._core | recommended | market | reference |
| manifest | tradefloor.manifest | advanced | reproducibility | reference |
| map_boundaries | tradefloor.boundary | advanced | counterfactuals | reference |
| market_status | tradefloor._core | advanced | utility | in the table below |
| MarketView | tradefloor.sandbox | advanced | evaluation | reference |
| MatchResult | tradefloor._core | advanced | market | reference |
| mcp | tradefloor.mcp | recommended | integration | reference |
| model_preset | tradefloor._core | advanced | model | reference |
| ModelParams | tradefloor._core | recommended | model | reference |
| News | tradefloor._core | advanced | market | reference |
| NewsImpact | tradefloor._core | advanced | market | reference |
| Node | tradefloor.explain | advanced | trust | reference |
| noise | tradefloor.noise | advanced | reproducibility | in the table below |
| Observation | tradefloor.harness | recommended | evaluation | reference |
| openai_agents | tradefloor.integrations.openai_agents | advanced | integration | reference |
| oracle_is_ceiling | tradefloor.baselines | advanced | evaluation | reference |
| OrderBook | tradefloor._core | advanced | market | reference |
| OrderError | tradefloor._core | recommended | errors | reference |
| Population | tradefloor.population | advanced | evaluation | in the table below |
| population | tradefloor.population | advanced | evaluation | in the table below |
| Portfolio | tradefloor.portfolio | advanced | evaluation | reference |
| PortfolioView | tradefloor.sandbox | advanced | evaluation | reference |
| Position | tradefloor.portfolio | advanced | evaluation | in the table below |
| preset_names | tradefloor._core | recommended | model | reference |
| preset_record | tradefloor.records | recommended | model | reference |
| preset_records | tradefloor.records | advanced | model | reference |
| PriceLevel | tradefloor._core | advanced | market | reference |
| pydantic_ai | tradefloor.integrations.pydantic_ai | advanced | integration | reference |
| rank | tradefloor.ranking | recommended | evaluation | reference |
| Ranking | tradefloor.ranking | recommended | evaluation | reference |
| RATE_SECTOR | tradefloor | advanced | market | reference |
| rate_specs | tradefloor | advanced | market | reference |
| RATE_TICKERS | tradefloor | advanced | market | reference |
| reference_agents | tradefloor.baselines | recommended | evaluation | reference |
| render | tradefloor.render | advanced | integration | reference |
| Renderer | tradefloor.render | advanced | integration | reference |
| replay | tradefloor.replay | recommended | reproducibility | reference |
| Resample | tradefloor.counterfactual | advanced | counterfactuals | reference |
| resample | tradefloor.counterfactual | advanced | counterfactuals | reference |
| reveal | tradefloor.fingerprint | advanced | trust | reference |
| run_many | tradefloor | recommended | market | reference |
| run_scenario | tradefloor.scenario | recommended | scenarios | reference |
| RunManifest | tradefloor.manifest | recommended | reproducibility | reference |
| sandbox | tradefloor.sandbox | advanced | evaluation | reference |
| SandboxError | tradefloor.sandbox | advanced | errors | reference |
| Scenario | tradefloor.scenario | recommended | scenarios | reference |
| ScenarioValidationError | tradefloor.interventions | recommended | errors | reference |
| Scorecard | tradefloor.harness | recommended | evaluation | reference |
| sealed_battery | tradefloor.fingerprint | advanced | evaluation | reference |
| sectors | tradefloor._core | advanced | utility | in the table below |
| spec | tradefloor.spec | advanced | evaluation | reference |
| SPEC_VERSION | tradefloor.spec | advanced | evaluation | in the table below |
| StrategySpec | tradefloor.spec | advanced | evaluation | reference |
| sweep | tradefloor.sweep | advanced | evaluation | in the table below |
| SweepCost | tradefloor._core | advanced | market | reference |
| TARGETS | tradefloor.boundary | advanced | scenarios | reference |
| tca | tradefloor.tca | recommended | execution | reference |
| TextRenderer | tradefloor.render | advanced | integration | reference |
| TickResult | tradefloor._core | advanced | market | reference |
| TradingEnv | tradefloor.gym | recommended | integration | reference |
| Universe | tradefloor | recommended | market | reference |
| UNSUPPORTED_TARGETS | tradefloor.interventions | advanced | scenarios | reference |
| ValidationError | tradefloor._core | recommended | errors | reference |
| Verification | tradefloor.manifest | advanced | reproducibility | reference |
| version | tradefloor._core | advanced | utility | in the table below |
| __version__ | tradefloor | advanced | utility | in the table below |
| versus_buy_and_hold | tradefloor.baselines | recommended | evaluation | reference |
| World | tradefloor.counterfactual | recommended | counterfactuals | reference |
| yaml_subset | tradefloor.yaml_subset | internal-transition | utility | in the table below |

## Exports without a reference page

Exports with no section elsewhere, and exports not meant for new code, with their signature, import path and tier. All of them still import from tradefloor. A deprecated symbol emits a DeprecationWarning that names the module to import it from, and leaves the top level no earlier than the next minor release. An internal-transition symbol leaves on that schedule too, with no warning, because the package itself imports it.

| Signature | Import | Tier | Purpose |
| --- | --- | --- | --- |
| __version__: str = '0.11.0' | tradefloor | advanced | The installed package version, as a string. It is what a RunManifest records and what a published result cites. |
| tradefloor.atlas | tradefloor.atlas | advanced | Atlas: a map of how the model responds across its parameter space. |
| externalities(world: 'World', days: 'int' = 1) -> 'Externality' | tradefloor.externality | advanced | Fork a cohort, remove each agent in turn, and measure what changed. |
| Externality(*, labels, matrix, diagonal, diagonal_bps, cohort_pnl, trades, traded, exposure, agreement, days, fork_day, fork_step, held_at_fork, levels=None, live=False) -> 'None' | tradefloor.externality | advanced | One cohort's agents, measured against the cohorts without each of them. Members: COLUMNS, agreement, as_dict, caveats, cohort_pnl, days, diagonal, diagonal_bps, effect_on, exposure, fork_day, fork_step, held_at_fork, labels, levels, live, matrix, render, table, traded, trades. |
| tradefloor.externality | tradefloor.externality | advanced | What each agent in a cohort did to each other agent, under the same draws. |
| tradefloor.facts | tradefloor.facts | advanced | Stylised facts: what these markets look like, measured, next to real ones. |
| fair_value(*, eps=None, sector, revenue_growth=None, federal_funds_rate=0.0, corporate_bond_yield=None, qe_pe_boost=None, book_value_per_share=None, neutral_discount_rate=None, qe_assets_ratio=None, qe_pe_gain=None, qe_pe_stock_gain=None, rate_pe_sensitivity=None, fair_value_book_floor=None, model=None) | tradefloor._core | advanced | Fair value per share from fundamentals and the macro state. |
| FairValue | tradefloor._core | advanced | A fair-value result and its decomposition. Members: book_value_path, fair_value, qe_adjustment, rate_adjustment, sector_anchor_pe, target_pe. |
| GameRng(seed, sequence) | tradefloor._core | advanced | Deterministic seeded random number generator (PCG32 + Box-Muller). Members: next_bool, next_float, next_int, next_normal. |
| tradefloor.loss | tradefloor.loss | advanced | The calibration objectives: band distance, and a residual scoring rule. |
| market_status(hour, minute, day_of_week) | tradefloor._core | advanced | Which session a moment falls in. |
| tradefloor.noise | tradefloor.noise | advanced | The draw stream as an addressable, editable object. |
| Population(participants: 'Iterable[Participant]', *, name: 'str' = 'custom') -> 'None' | tradefloor.population | advanced | A declarative, fingerprinted set of background traders. Members: as_dict, crowded, fingerprint, from_dict, name, named, participants, standard. |
| tradefloor.population | tradefloor.population | advanced | Background traders that share the market with your agents. |
| Position(ticker: 'str') -> 'None' | tradefloor.portfolio | advanced | A holding in one instrument. Members: avg_cost, market_value, quantity, realised, ticker, unrealised. |
| sectors() | tradefloor._core | advanced | The twelve sector keys, in contractual declaration order. |
| SPEC_VERSION: int = 1 | tradefloor | advanced | The StrategySpec schema version. A spec written against an older number still loads. One written against a newer number does not, so a manifest that records it says whether this install can replay the run. |
| sweep(seeds: 'Iterable[int]', *, universe: 'Sequence[Instrument]', days: 'int' = 1, ticks_per_day: 'int' = 390, macro: 'Macro \| None' = None, scenario: 'Any' = None, collect: 'str' = 'bars', grain: 'str \| None' = None, minutes: 'int \| None' = None, start: 'tuple[int, int, int]' = (9, 30, 3), workers: 'int' = 1, model: 'str \| ModelParams \| None' = None) -> 'Iterator[tuple[int, Any]]' | tradefloor.sweep | advanced | Yield (seed, table) for each seed, one at a time. |
| version() | tradefloor._core | advanced | The compiled core's version, as a string. It reports the same value as __version__ and is kept for callers written before that attribute existed. |
| tradefloor.yaml_subset | tradefloor.yaml_subset | internal-transition | A reader for the boring part of YAML, and nothing else. |

Atlas surveys the model's parameter space. It reports which parameters move which outputs, what shape each effect has, and which trades are available at once. It's meant for people who calibrate the model, and these docs don't have a tutorial for it.
