# LLM adapters

Source: https://docs.tradefloor.dev/llm-adapters.html

> Run an LLM agent in a tradefloor market on your machine with the OpenAI Agents SDK, PydanticAI, LangGraph, FinRobot or a function: setup, a first run, fixes.

An adapter runs an agent built in an LLM framework inside a simulated market on your machine. tradefloor sends the framework a JSON observation and the framework answers with a decision. tradefloor then checks the decision, places its orders in the simulation and scores the run. An adapter is an ordinary agent with an `act` method, so it runs under `tf.evaluate`, `tf.rank` and `World`.

Three ways to connect a model
- LLM adapters (this page) run the model inside a simulated market in your own Python process, and its decisions become orders there.
- The [local MCP server](https://docs.tradefloor.dev/mcp-local.html) gives an MCP client, such as Claude Code or a [CrewAI agent](https://docs.tradefloor.dev/crewai.html), simulation and evaluation tools, and sessions where the model sends orders step by step to a simulated market the server keeps in memory.
- The [hosted app](https://docs.tradefloor.dev/hosted.html), in beta, lets a model or a bot place orders in saved markets on app.tradefloor.dev over MCP, an HTTP API or an Alpaca-shaped API.

## Setup

Each framework is an optional extra. tradefloor needs Python 3.11 or later.

| Framework | Install | Module | Minimum version |
| --- | --- | --- | --- |
| A plain Python function | pip install tradefloor | tradefloor.integrations.callable | none |
| OpenAI Agents SDK | pip install "tradefloor[openai-agents]" | tradefloor.integrations.openai_agents | openai-agents 0.22 |
| PydanticAI | pip install "tradefloor[pydantic-ai]" | tradefloor.integrations.pydantic_ai | pydantic-ai-slim 2.36 |
| LangGraph | pip install "tradefloor[langgraph]" | tradefloor.integrations.langgraph | langgraph 1.2 |
| FinRobot | pip install "tradefloor[finrobot]" | tradefloor.integrations.finrobot | Python 3.11 exactly |

You don't need any of the extras to replay a recorded run.

## A first run with no API key

The callable adapter wraps any function that takes the observation payload and returns a decision. Start with a function that answers without a model. It's the fastest way to check the loop before you set up a key or an extra.

```
import json

import tradefloor as tf
from tradefloor.integrations.callable import callable_agent

def ask_model(payload):
    # stands in for a model call: the payload is what a model is shown
    first = payload["assets"][0]
    order = {"symbol": first["symbol"], "side": "BUY", "quantity": 100}
    return json.dumps({"actions": [order], "rationale": "add 100 a day"})

adapter = callable_agent(ask_model)
market = tf.Universe.random(12, seed=4242)
card = tf.evaluate({"model": adapter}, seed=4242, universe=market, days=5)["model"]
print(card)
print(len(adapter.record), "decisions")
```

```
Scorecard('model', pnl=812, return=+0.08%, trades=5, impact=+0.19bps, sharpe=n/a (short run), vol=0.3%, in_market=100%, exposure=0.02x)
5 decisions
```

Replace the body of `ask_model` with a call to your model, and parse its text into a decision with `postprocess=`, as in [Recording and replay](https://docs.tradefloor.dev/guide-replay.html#recording-and-replay). `adapter.record` has one entry per decision with the payload, the exact input, the raw response, the validated decision and the orders.

## Framework pages

Each framework has a page with the install line, a first run and the versions it was tested with. None of the first runs needs an API key. The OpenAI Agents SDK and PydanticAI pages use a test model the framework ships, and the LangGraph page uses a plain rule where the model would go:
- [OpenAI Agents SDK](https://docs.tradefloor.dev/openai-agents.html)
- [PydanticAI](https://docs.tradefloor.dev/pydantic-ai.html)
- [LangGraph](https://docs.tradefloor.dev/langgraph.html)
- [FinRobot](https://docs.tradefloor.dev/finrobot.html), which needs Python 3.11

## Decisions and model calls

An adapter asks its framework for a decision every `every` [decision steps](https://docs.tradefloor.dev/glossary.html#decision-step), 6 by default. `obs.step` counts steps across the whole run, so with the default 6 steps a day that's one decision a simulated day, at each day's first step. With `steps_per_day=3` the default asks every second day. On the steps between decisions the adapter records the prices it saw and returns no orders.

One decision can cost several calls to the model provider. A 20-day run is 20 decisions and can be many more provider calls:
- A framework turn is one model call, and an agent that calls tools takes several turns per decision. The OpenAI Agents adapter caps a decision at `max_turns=6`, and the PydanticAI adapter at `request_limit=8` requests.
- PydanticAI retries a schema violation inside its own loop, and each retry is another request. The OpenAI Agents SDK 0.22 makes no client-side retry on a malformed answer.
- A LangGraph graph makes whatever calls its nodes make.

## The observation payload

The framework only ever sees the serialized payload. tradefloor builds it field by field from an allowlist, and the observation object never reaches the framework:

| Key | What it holds |
| --- | --- |
| step, day, steps_per_day | The clock. step counts the whole run. |
| macro | The published figures: the VIX, the policy rate, the corporate bond yield, inflation and the business-cycle phase as announced, late. |
| assets | Per name: the symbol, price, one-day and five-day returns and volatility from the prices the adapter has seen, the best bid and ask, average daily volume, max_order_shares (the participation cap), the position held, and any fundamentals you pass with fundamentals=. On a model that pays dividends, also dividend, and on one that runs an earnings calendar, also next_earnings_in_sessions. |
| portfolio | Cash, net worth, leverage, max_leverage, buying_power and the waiting limit orders. |

`dividend` is the cash per share the name went ex for at that day's open, and 0.0 on a day it paid nothing. `next_earnings_in_sessions` is the number of sessions to the name's next earnings report. pt-v21 has both, and no earlier preset has either:

```
import json

import tradefloor as tf
from tradefloor.integrations.callable import callable_agent
from tradefloor.integrations.common import OBSERVATION_SCHEMA_VERSION

def ask_model(payload):
    return json.dumps({"actions": []})

market = tf.Universe.random(12, seed=4242)
for preset in ("pt-v21", "pt-v20"):
    adapter = callable_agent(ask_model)
    tf.evaluate({"model": adapter}, seed=4242, universe=market, days=5, model=preset)
    first = adapter.record[-1]["payload"]["assets"][0]
    extra = {k: first[k] for k in ("dividend", "next_earnings_in_sessions") if k in first}
    print(preset, extra)
print("payload version:", OBSERVATION_SCHEMA_VERSION)
```

```
pt-v21 {'dividend': 0.0, 'next_earnings_in_sessions': 28}
pt-v20 {}
payload version: 3
```

From tradefloor 0.11.0 the payload is version 3. On a model that lists contracts, as pt-v22 does, it adds `index`, `futures`, `margin` and `options`, and on every other model it is version 2's to the byte. Version 2, from 0.10.0, added these two keys to version 1, used on 0.8.5 to 0.9.x. On a preset without dividends or an earnings calendar the payload matches version 1, and a recording made under version 1 still replays there. It doesn't replay on pt-v21 or pt-v22, where the payloads have the new keys. A recording names its payload version in `meta["observation_schema_version"]`.

At any access level, the payload has no fair value, no factor attribution and no macro path the run hasn't reached. The adapter's `act` gets the read-only market view by default, or the live engine under `trusted_agents=True` (see [What the agent sees](https://docs.tradefloor.dev/guide-agent.html#the-agent-s-view)). The framework still gets only the payload.

The decision is a list of actions. Each has a `symbol`, a `side` (`BUY`, `SELL`, `HOLD` or `CANCEL`), a positive `quantity` in shares, and an optional `limit_price` that makes it a limit order. A bad action is refused on its own and listed in the scorecard's `errors`. An order over `max_order_shares`, 2% of the name's average daily volume by default, is cut to the cap, and an order below one share is dropped. [Bringing an LLM agent](https://docs.tradefloor.dev/api-integrations.html#bringing-an-llm-agent) has the full contract.

## Reference

[LLM adapters and MCP](https://docs.tradefloor.dev/api-integrations.html) has every adapter's signature, the shared layer, error types, replay rules and the framework version each adapter was written against. When a run fails or makes no trades, [Troubleshooting](https://docs.tradefloor.dev/troubleshooting.html#model-provider-failures) lists the messages and fixes.

## Next steps
- Read [Testing an LLM trading agent without look-ahead bias](https://tradefloor.dev/test-llm-trading-agent.html), a guide that seals the seeds before the run and records every model answer.
- Watch [Can Claude out-trade a bot?](https://tradefloor.dev/video-claude-trades.html), a 2:07 video recorded on the hosted app.
- Use a [decision engine](https://docs.tradefloor.dev/decision-engines.html) such as Jev instead, when you'd rather keep the decision in code and ask the model narrow questions.
