LLM adapters and MCP
Reference for the LLM adapters and the local MCP server, covering the shared layer and the four framework adapters: signatures, input and output mapping, errors, replay, tracing and the framework version each adapter was written against. For setup and a first run, see the guides: LLM adapters, Local MCP server and Record and replay.
Bringing an LLM agent
An adapter runs an agent built in another framework inside a tradefloor market. The framework reads a JSON observation and answers with a decision. tradefloor checks the decision, sends the orders to the book and scores the result. An adapter is an ordinary agent with an act method, so it runs under tf.evaluate, tf.rank and World. Two frameworks run on one seed meet an identical market. LLM adapters sets up each framework and runs it with no API key. Record and replay records a run and replays it without the model.
| Framework | Module | Install extra |
|---|---|---|
| Plain Python function | tradefloor.integrations.callable | none |
| OpenAI Agents SDK | tradefloor.integrations.openai_agents | openai-agents |
| PydanticAI | tradefloor.integrations.pydantic_ai | pydantic-ai |
| LangGraph | tradefloor.integrations.langgraph | langgraph |
| FinRobot | tradefloor.integrations.finrobot | finrobot, Python 3.11 only |
An adapter asks its framework every every decision steps, 6 by default. At the default 6 steps a day, that's one decision a simulated day. One decision can take several calls to the model provider through tool calls, framework turns and retries (Decisions and model calls).
All the adapters take one decision format, a list of actions. An action has a symbol, a side (BUY, SELL, HOLD or CANCEL), a positive quantity, and an optional limit_price that makes it a limit order. tradefloor refuses a bad action, such as an unknown symbol or a negative quantity, on its own and records it in the scorecard's errors, and the other actions still trade. An order over the participation cap, 2% of the name's average daily volume by default, is cut to the cap. The observation payload never carries fair value, the attribution of a move or the macro path the run hasn't reached. On a model that pays dividends or runs an earnings calendar, as pt-v21 does, each asset in it also has dividend and next_earnings_in_sessions (the observation payload).
A seed replays the market exactly, and a Transcript replays the model. Each entry is keyed by the payload the model was shown, so a changed roster, seed or cadence stops a replay with ReplayMiss, and a replay under different instructions is refused before the market opens. To publish a result from an external agent, record both sides: adapter.provenance() for the framework, model and settings, and a RunManifest for the market.
tf.fingerprint.fingerprint(agent) runs an agent on a fixed battery of seven 120-day markets, one per shipped scenario, and hashes what it ordered. You can compare the hashes to check whether two versions of an agent behave the same. tf.battery() returns that battery and BATTERY_VERSION names it. To show a score wasn't tuned to its seeds, publish tf.commit(seeds, salt) before the run, then publish the seeds and the salt, which tf.reveal checks. tf.sealed_battery(seeds, salt) builds the battery on them.
The MCP server
tradefloor-mcp gives a model the simulator as tools it calls over the Model Context Protocol, on your machine over stdio. Local MCP server installs it, registers it with a client and makes a first call.
Most tools build a market for one call, study it from outside and discard it. The session tools keep a simulated market open between calls, and session_step places orders in it. Call a market tool twice with the same arguments and you get the same result. A session does too, if you make the same calls from the same open. To score a model as an agent over many steps, run it through an adapter. For markets saved between runs, the hosted app has MCP tools of its own.
| Tool | What it does |
|---|---|
describe_simulator | what the simulator is, what it is measured to reproduce and what it cannot do, with every shipped preset and population |
check_envelope | whether a question is inside the validated scope, before anything runs |
validate_strategy | checks a strategy spec and returns its fingerprint |
build_universe | builds a roster: generated, concentrated in some sectors, or written by hand |
build_scenario | composes a scenario and shows what it resolves to |
list_scenarios | the shipped scenarios, the constructors and the targets |
evaluate_strategies | runs strategies and the five baselines on one market |
rank_strategies | runs them across seeds, with a paired sign test between each pair |
run_stress_scenario | what a scenario does to each strategy, against the same market without it. With fork_day, both markets run together to that day and the scenario starts on it, so every earlier day is shared. A constructor or a macro path is then refused. |
explain_price_move | a price move split into the eleven factors that sum to it |
explain | the random draws behind one day for one company |
start_job, check_job | slow work in the background, up to 252 days |
open_session | opens a market the server keeps between calls, with up to eight agents, each driven by orders or by a strategy spec |
session_step | advances a session by steps or days, with orders for one agent at the first step, and returns the fills, portfolios and prices |
session_state | reads a session without changing it, or lists the open sessions |
session_fork | copies a session at its present state into a new session |
session_rewind | returns a session to a checkpoint and drops the checkpoints after it |
list_contracts | the contracts a session's market lists: each future's symbol, expiry, multiplier and what it settles on, the price index's level, and each option expiry's strike grid, at-the-money volatility and 25-delta skew |
quote_contracts | quotes for a session's listed contracts: the bid and ask, the fair value and its carry, and the margin a contract asks, and for an option its volatility and Greeks |
option_chain | one expiry's option chain in a session, by strike: the dealer's bid and ask, the volatility, the Greeks and open interest, for the index or a listed company |
close_session | closes a session and returns its final portfolios and every order sent |
Each tool has a title and annotations that say what it changes. Most only read, are deterministic and reach nothing outside the server. start_job, open_session and session_fork add a job or a session to the server's memory. session_step advances a session, and session_rewind and close_session drop checkpoints or a session.
Strategies are JSON StrategySpec objects, and the server won't take code. Results carry a caveats list and a provenance block with tradefloor_version, the preset, seed and roster, and a model summarizing a result sees its limits too. Results from 0.9.1 and earlier also carried the version as pretium_version. A direct call runs at most 60 days and a background job 252, the horizon the model is validated over.
Every tool that runs a market, and open_session, takes preset, any shipped preset's name. Without it the tool runs pt-v22. A result on another preset says it's outside the certified envelope. evaluate_strategies, run_stress_scenario, open_session and start_job take population, either "standard" or "crowded", to run in populated mode. rank_strategies refuses a population because its paired sign test needs all the strategies on one market. Limits lists the caps, sessions included.
The shared layer
tradefloor.integrations.common holds the parts every adapter needs that belong to no single framework: the observation allowlist, the decision schema and the model built from it, two-stage validation, transcripts and replay, and the base class an adapter completes.
| Name | What it is |
|---|---|
| serialize_observation | The observation allowlist, meaning the fields a framework is shown. The framework gets this payload, never the Observation itself. By default the Observation's .engine is the read-only market view, with none of the hidden state. Under trusted_agents=True it's the live engine, and through it an agent can reach fair value, the eleven-way attribution of every move, each company's mispricing and the macro path the run hasn't reached yet. The payload is the same allowlist either way. |
| decision_schema | The one definition of a valid decision. decision_model builds the Pydantic model from it. |
| parse_decision | The first validation stage, which checks the answer against the schema. An unknown top-level key or a missing actions list refuses the whole decision with DecisionError. A bad action, such as one with an unknown field, a negative quantity or a limit order with no price, is refused on its own. It goes into the returned Decision's refused list with its reason, and the other actions stand. |
| orders_from | The second validation stage. It checks each symbol against the listed universe and each size against the participation cap (the largest fraction of average daily volume one order may take). Then it turns the actions into orders: a share count for a market order, a tf.Limit for an action with a limit_price, and a tf.Cancel for CANCEL. An order over the cap is clipped, and the clip is recorded. An unlisted symbol goes into the refused list if one is passed, and raises MarketRefusalError if not. |
| Transcript | Record and replay. Each exchange is keyed by a digest, a hash of the exact input sent to the framework. meta names the market the recording was made in. |
| run_sync | The only supported bridge from sync to async code. It runs a coroutine on another thread, and context variables the caller set don't carry into that thread. |
| FrameworkAdapter | The base class an adapter completes. ReplayMixin adds the record-and-replay path. All adapters take the constructor arguments info, every, fundamentals, max_participation and arm. |
The module exports seven constants, OBSERVABLE_MACRO, SIDES, ORDER_TYPES, HISTORY_STEPS, MAX_PARTICIPATION, DECISION_SCHEMA_VERSION ("2" since 0.8.5) and OBSERVATION_SCHEMA_VERSION ("2" since 0.10.0). Both were frozen for the 0.8.x line, when the payload was version 1. Version 2 adds two keys to each asset on a model with dividends or the earnings calendar, such as pt-v21, and on any other model the payload is version 1's. The observation payload lists the payload, and Bringing an LLM agent lists the decision. The module also has three classes, Action, Decision and AdapterInfo, and three functions, require, digest and replay_response. It also exports the preset check the built-in adapters run, for use in an adapter you write yourself: preset_of(obs), stamp_preset(recorder, obs), refuse_a_changed_preset(transcript, preset), stamp_artefact(meta) and the constant PRESET_VECTOR_KEY.
Error behavior
Every error below is a subclass of tradefloor.ValidationError. A bad answer from the agent raises DecisionError, and a failure in the framework raises FrameworkError. They're separate so a weak agent isn't mistaken for an unreliable network.
| Name | Meaning |
|---|---|
| IntegrationError | The root of this error family. |
| MissingDependencyError | Also an ImportError. require() raises it. |
| FrameworkError | The framework call itself failed, for example with a timeout, a transport failure or a budget stop. |
| DecisionError | The agent's output could not be read as a decision. The error names the step and the day. |
| MarketRefusalError | A DecisionError. The decision is well formed, but this market can't take it. The adapters pass a refused list, and one bad action is then refused on its own while the rest of the decision trades. |
| ReplayMiss | A DecisionError. The recording has no answer for this input, or it was made in a different market. World re-raises it under on_refusal="skip", so a replay that can't answer stops the run and doesn't count against the agent. |
No adapter turns a failure into an empty decision. An empty decision scores as trades=0 with an empty error column. An agent that chose not to trade scores that way too, and a failure scored as empty couldn't be told apart from it.
Replay and recording
A Transcript keys each exchange by a digest of the exact input sent to the framework. If you change the roster, the seed or the cadence, no recorded answer matches the key, and the run stops with ReplayMiss and names the step. A step-number key would hand a changed experiment the old experiment's answers, with nothing in the output to show it.
Instructions are checked separately, because most adapters don't send them in the keyed input. LangGraphAdapter renders its instructions into that input, and a change there stops the run as above. The OpenAI Agents, PydanticAI and FinRobot adapters write a digest of their instructions to meta["instructions_digest"], and a replay under different instructions raises ValidationError when the adapter is built. CallableAgentAdapter can't see the prompt inside your function, so it checks only when its AdapterInfo carries an instructions_digest.
adapter.record holds one entry per decision, live or replayed: the digest, the exact input, the raw response, the validated decision, the orders, any participation clips and any refused actions with their reasons. A limit order is held as {"quantity", "limit_price"}.
Recorded preset
Every price in an observation comes from the preset, the named set of model coefficients the engine runs. A recording replays only against the preset it was made in, and it names that preset. On the first recorded exchange, every adapter writes the running engine's fingerprint to meta["model_preset"] and the full parameter vector to meta["model_preset_vector"]. The fingerprint is a preset name such as pt-v19 or custom-XXXXXXXX. Transcript.save writes recorded_utc. For a transcript that never ran against an engine, it also writes the shipped default as model_preset. finrobot.Transcript.save writes both fields too.
replay_response(transcript, key, *, step, day, preset=None) compares the recorded preset with preset before it looks up the digest, and every adapter passes the running engine's preset. A different name raises ReplayMiss, naming both. To fix it, replay on the recorded preset with World(..., model=...) or evaluate(..., model=...), or record the run again. A preset cut again between builds can carry different values under the same name. That raises ReplayMiss too, and the error lists the model variables that moved.
A recording made before 0.8.0 has no model_preset, and a replay of it warns and goes on. From 0.8.5 a recording's meta also carries observation_schema_version and decision_schema_version. A replay of a recording made under a payload version this release doesn't accept stops before the first lookup and names both versions. A version-1 recording still replays on a model without dividends or the earnings calendar. A recording made before 0.8.5 carries neither field, and its first lookup misses because the payload it was keyed on has changed. Replay it on the release that made it.
Generic callable
CallableAgentAdapter wraps a plain Python function for evaluate to run, and callable_agent(fn, **kwargs) is the convenience constructor. An async function runs through common.run_sync. The function gets the serialized payload, never the Observation.
CallableAgentAdapter(fn=None, *, name, info, every=6, mode="live", transcript, recorder, prior, postprocess, ...). fn may be left out in replay mode, which never calls it.
postprocess(raw, payload) runs on whatever fn returned, live and on replay, and its return is the decision. The transcript records fn's return, the raw model response, and every replay runs the parsing, risk checks and sizing you write in postprocess. Code inside fn after the model call is recorded as its output and never runs on replay. Without postprocess, fn's return is the decision.
The replay key is the payload alone. Pass info=AdapterInfo(framework="callable", instructions_digest=digest(PROMPT)) when you record and when you replay. The digest is written to the transcript's meta, and a replay built with a different digest raises ValidationError before the market opens. With no AdapterInfo, a replay under an edited prompt runs to the end on the recorded answers. Replay checks has a worked example.
OpenAI Agents SDK adapter
OpenAIAgentsAdapter(agent, *, mode="replay", transcript, recorder, model, brief, max_turns=6, tracing=False, run_id, ...). The convenience constructor openai_agent(agent, **kwargs) defaults to mode="live". The module also exports payload_of(call), BRIEF, DISTRIBUTION and EXTRA. The adapter adds two methods to the base, ask(obs, payload) and input_items(payload). state() adds max_turns and brief_digest, because both change what a decision can be.
Compatibility
The adapter binds the decision schema as the output type on a copy made with Agent.clone(...). Your agent is left unchanged, and the copy keeps its instructions, tools, model settings, hooks, handoffs and guardrails. An agent that already declares its own output_type is refused, and the message says how to opt in. A run that ends on a different agent through a handoff is refused by name, because that agent has its own output type.
Runtime behavior
The adapter calls Runner.run through the shared async bridge. On 0.22.0, Runner.run_sync can't run inside an existing event loop, such as a notebook's. max_turns caps one decision at six model calls. The SDK's default of ten suits interactive use, but a loop that runs at every cadence step of every experiment arm needs a lower cap. The adapter imports the SDK only inside the method that calls it, so a replayed run needs neither the package nor the time its import takes.
Retry and validation behavior
On 0.22.0, the SDK raises ModelBehaviorError on a malformed answer and doesn't call the model again. Binding the decision model makes an invalid decision less likely, because it puts the side enum, the non-negative quantity and additionalProperties: false into the schema the provider sees. The binding adds no repair loop, so write your error handling for this adapter as if there were no retries.
Error behavior
The adapter treats seven SDK exceptions as the agent's own outcome and turns each into a DecisionError: ModelBehaviorError, ModelRefusalError, MaxTurnsExceeded and all four guardrail tripwires. By default the SDK removes model text from its messages, and its message alone can't tell you which decision point failed. A tripped guardrail is not converted to a hold. Every other exception stays a FrameworkError with the exception chain intact.
Tracing
SDK tracing is on by default and sends traces to OpenAI. This adapter passes tracing_disabled=True on every run it starts, unless you gave tracing=True. It sets this per run and leaves the SDK's process-wide switch alone, so tracing for other code in the process is unaffected.
Version notes
The minimum version is openai-agents>=0.22, the version the adapter was written against. A minimum at the major version would allow releases the adapter has not been tested against. The package imports as agents and supports Python 3.10 through 3.14. tradefloor needs 3.11 or later, and every Python that runs tradefloor also runs the SDK.
PydanticAI adapter
PydanticAIAdapter(agent, *, deps, mode="live", model, transcript, recorder, instructions, bind_output_type=True, request_limit=8, ...). The module also exports UsageLimitReached, render(payload), MANDATE and MANDATE_VERSION.
Compatibility
The adapter doesn't modify the agent you pass in. Its deps_type, tools, RunContext usage, instructions, toolsets and output type keep working, and deps reaches run(deps=...) unchanged. PydanticAI has one dependency slot, which every tool reads through RunContext.deps with no type check at runtime. An adapter that put its own payload there would hand your tools an object of the wrong type. This adapter puts nothing in it, so a tool can't query the observation from inside a decision. A tool that needs the day's prices reads them from a holder on your deps object.
Decision mapping
The adapter binds the shared decision model as the run's output type. The schema the model sees then has the side enum, the non-negative share count and the required actions list. The binding applies to that run only and leaves your agent's output type alone. PydanticAI doesn't allow an output type override on an agent with an @agent.output_validator. For such an agent the adapter says so and points to bind_output_type=False, which keeps your output type while tradefloor still validates what it produces.
Retry and validation behavior
PydanticAI's retry loop catches a schema violation and corrects it within the turn. The adapter files UnexpectedModelBehavior as a DecisionError, because an agent that used up its retries without a valid decision answered badly. A run that hits its request limit raises UsageLimitReached, a FrameworkError subclass, so you can catch a deliberate budget stop by name.
Runtime behavior
Pass an offline model through the adapter's model= argument instead of Agent.override. Agent.override is built on context variables, and those don't carry across the shared async bridge. A test suite can set models.ALLOW_MODEL_REQUESTS = False. A blocked request then raises a plain RuntimeError, so a test that expects a framework exception will miss it.
Observability
PydanticAI records no traces by default, and the adapter turns nothing on. In the supported version, turn tracing on with either logfire.configure() with logfire.instrument_pydantic_ai(), or Agent.instrument_all(). 2.36.0 has no instrument= constructor argument.
Version notes
The minimum version is pydantic-ai-slim>=2.36. The slim package has the pydantic_ai module without the provider SDKs that the full package adds, and no adapter imports any of those. TestModel and FunctionModel are both in slim.
LangGraph adapter
LangGraphAdapter(runnable, *, mode="live", transcript, recorder, input_builder, output_parser, instructions, config, thread_id, ...), with langgraph_agent(runnable, **kwargs) as the convenience constructor. The module also exports default_input_builder, default_output_parser, render, GraphInterruptedError, INSTRUCTIONS, DEFAULT_INPUT_KEYS and INTERRUPT_KEY.
Compatibility
The adapter accepts any object with an invoke method and doesn't check its class. Runnable is a nominal ABC with no __subclasshook__, and an isinstance check would reject a plain object with a working invoke, such as a deterministic test double. An object with only ainvoke runs through common.run_sync, and an uncompiled StateGraph is refused by name.
Input mapping
The default input carries both input shapes at once, observation for a structured graph and messages for the MessagesState shape. A key the graph's state schema does not declare is dropped before any node runs, so one default works for both. A TypedDict state gets no schema check at the graph boundary, and a mismatch shows up as an IndexError or a bare KeyError inside your node. Use input_builder when the graph expects a different state schema.
Output mapping
A graph returns its whole state, and the default parser takes the decision out of it. It reads a Decision, an interrupted state, a state carrying actions, a state carrying decision, or the MessagesState shape. It refuses anything else by name.
Interrupts
An interrupt raises GraphInterruptedError, a DecisionError subclass that names the unanswered question. An interrupt means pause now and resume later, and a market loop has nowhere to resume into, because the order book, the macro path and the variance process move on as soon as act returns. On 1.2.11, a GraphInterrupt never escapes invoke and arrives inside the state as __interrupt__. The parser checks for it before it looks for decision, because a checkpointed thread can carry a decision written on an earlier step. Run a human-in-the-loop graph separately, and give tradefloor a graph that decides.
Observability
The adapter puts the run's identity in config["metadata"] and adds a "tradefloor" tag, merged into any RunnableConfig you pass. It uses metadata because a node receives tags, metadata and recursion_limit from the invoking config, while the tracer consumes run_name. LangSmith tracing stays off unless one of its environment variables is true. Every exported run carries tradefloor_run_id. The adapter also stamps tradefloor_arm, tradefloor_day, tradefloor_step and tradefloor_decision_schema on each decision. Turning tracing on sends the rendered observation to LangSmith.
Version notes
The minimum version is langgraph>=1.2, which also brings in langchain-core as a hard dependency. LangGraph needs Python 3.10 or later, and with tradefloor it runs on 3.11 and later. create_react_agent is deprecated in LangGraph 1.x and points at a package this extra does not install. A plain StateGraph has no deprecated import, and the adapter treats both the same way.
FinRobot adapter
The FinRobot integration predates the shared layer, which was built from it. Its DecisionError inherits from common.DecisionError instead of directly from ValidationError. You can still import it, it's still a ValidationError, and you can also catch it as the shared error. The integration runs the shared layer's preset check too. A FinRobot recording names its market in meta, and a replay against a different one raises ReplayMiss.
The finrobot extra requires exactly Python 3.11, because FinRobot declares >=3.10, <3.12 and tradefloor needs >=3.11. Replaying a recorded run needs none of it.