# Overview

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

> How tradefloor fits together (engine, universe, preset, scenario, agent, run, score, fork, manifest) and where to start for the job you have.

tradefloor is a simulated stock market, with a limit order book and an economy, for testing trading strategies and AI agents. Run a market again with the same inputs and you get the same market. An agent's orders move the prices it trades at.

## Start with a task

### New to tradefloor

[Run your first market](https://docs.tradefloor.dev/quickstart.html). Install, run a five-company market for 20 days, score an agent and read the result, in five minutes.

### Building an agent

[Write an agent](https://docs.tradefloor.dev/guide-agent.html). The `act(obs)` method, the orders it can return, sizing to a target weight and what the agent can see.

### Evaluating strategies

[Compare strategies](https://docs.tradefloor.dev/guide-compare.html). Against buy-and-hold on one market, then across many seeds, and by what each one's trades cost.

### Testing counterfactuals

[Fork a market](https://docs.tradefloor.dev/guide-fork.html). Copy a running market, change one input in one copy, and measure what the change did.

### More workflows
- [Run a scenario](https://docs.tradefloor.dev/guide-scenario.html): score an agent with and without a shipped scenario on the same seeds.
- [Test an LLM agent](https://docs.tradefloor.dev/llm-adapters.html): PydanticAI, the OpenAI Agents SDK, LangGraph or a plain function, with its answers recorded.
- [Use a decision engine](https://docs.tradefloor.dev/decision-engines.html): ask an engine such as TypeSafe's Jev typed questions, act on its answers and confidence in code, and record them.
- [Record and replay](https://docs.tradefloor.dev/guide-replay.html): run a recorded LLM agent again without calling the model.
- [Reproduce or publish an experiment](https://docs.tradefloor.dev/reproducibility.html): what fixes a market, saving a run as a manifest, and what to report ([Citing tradefloor](https://docs.tradefloor.dev/cite.html)).
- [Train an RL policy](https://docs.tradefloor.dev/guide-rl.html): a Gymnasium environment whose reward includes the cost of the policy's own trading.
- [Connect through MCP](https://docs.tradefloor.dev/mcp-local.html): a local server that lets a model build markets, score strategy specs and explain price moves.

Longer walk-throughs, each with a script you can run, live on the product site under [Guides](https://tradefloor.dev/guides.html): a decision engine on markets where the regime is known, a bot against a crash, an LLM agent without look-ahead bias, skill or luck, the cost of your own orders and a risk gate in CI.

## Concepts

UniversePresetScenarioSeed

Enginethe market: order book, companies, economy

observation →← orders

Agent`act(obs)`

Runthe engine stepped through trading days

Score`evaluate`, `rank`

Checkpoint, then forktwo futures from one past

Manifest, then reproduceinputs, version and orders, saved

EngineOne market. `tf.Engine(seed=..., universe=..., model=...)` runs the order book, the companies' fair values and the economy, and returns Arrow tables of what happened. [Engine](https://docs.tradefloor.dev/core-types.html#engine)

UniverseThe companies a market trades, in order. Changing the order changes the market. `tf.Universe.random(n, seed=...)` makes made-up companies, and `Universe.from_edgar` reads real ones. [Universe](https://docs.tradefloor.dev/core-types.html#universe)

PresetA named, frozen set of model coefficients, such as pt-v22, the default. Its values don't change after it ships. [ModelParams](https://docs.tradefloor.dev/parameters.html#modelparams)

SeedThe integer behind all of the engine's random draws. `Universe.random` has a separate seed that picks the companies. [Seed](https://docs.tradefloor.dev/glossary.html#seed)

ScenarioA named set of changes to the economy or the market on given days, such as a rate shock, with the assumptions behind them stated. [Run a scenario](https://docs.tradefloor.dev/guide-scenario.html)

AgentAny object with an `act(obs)` method. Strategies, LLM agents and RL policies all trade through it. [Write an agent](https://docs.tradefloor.dev/guide-agent.html)

Observation and actionAt each decision step the agent receives an observation (prices, its portfolio, the clock) and returns an action: orders, as shares per ticker, or `None`. [What act returns](https://docs.tradefloor.dev/evaluate.html#what-act-returns)

RunAn engine stepped through trading days. With an agent in it, the run also depends on the agent's orders, because they fill against the book and move prices.

Score`tf.evaluate` runs each agent on its own copy of one market and returns a `Scorecard`. `tf.rank` repeats that over many seeds and counts which agent did better. [Compare strategies](https://docs.tradefloor.dev/guide-compare.html)

ForkA copy of a running market. Change one input in one copy and any later difference comes from that change. [Fork a market](https://docs.tradefloor.dev/guide-fork.html)

ManifestA `RunManifest` holds the version, preset, seed, universe, scenario and order log of a run, and rebuilds the market from them. [Reproducibility](https://docs.tradefloor.dev/reproducibility.html)

In code, the smallest complete run is a universe, an agent and a score:

```
import tradefloor as tf

universe = tf.Universe.random(5, seed=11)      # the companies, in order
agent = tf.baselines.BuyAndHold()              # act(obs) returns orders

# One engine per agent, on the default preset, seed 42, for 20 trading days
scores = tf.evaluate({"hold": agent}, seed=42, universe=universe, days=20)
print(scores["hold"])
```

```
Scorecard('hold', pnl=5,913, return=+0.59%, trades=5, impact=+0.13bps, sharpe=+0.59, vol=14.3%, in_market=100%, exposure=0.94x)
```

## Reference

The [recommended API](https://docs.tradefloor.dev/api.html#recommended) is the short list of classes and functions most code needs. The [complete index](https://docs.tradefloor.dev/api.html#complete-index) lists every export with its tier. The model is documented in [How prices are made](https://docs.tradefloor.dev/how-prices-are-made.html), its coefficients in [Model parameters](https://docs.tradefloor.dev/parameters.html), and what has been checked against real markets in [How it is measured](https://docs.tradefloor.dev/how-its-measured.html). [Support policy](https://docs.tradefloor.dev/support.html) says which releases get fixes and what a patch release may change.

The hosted app at app.tradefloor.dev is documented separately under [Hosted (preview)](https://docs.tradefloor.dev/hosted.html).
