tradefloor

tradefloor

tradefloorは、戦略を実行できる市場シミュレーターです。RustコアとPython APIを備えています。

シードと企業のリストを指定すると、市場を先へ進めます。価格、指値注文板、約定、そして日々変化する経済をシミュレートします。注文は注文板の厚みに対してマッチするため、取引によって価格が動きます。

実際の市場データでは、異なる取引をしていたらどうなったか、あるいは値動きの原因が何だったのかはわかりません。tradefloorでは、すべての価格を計算しているため、それがわかります。進行中の市場を分岐させ、一方の分岐で1つの要素（利上げ、流動性危機、異なるエージェントなど）を変えて、2つの分岐がどこで異なったかを測定できます。engine.truth()は、価格とモデルの適正価値の差における各値動きを12の要因に分解し、engine.explain(ticker, day)は取引価格の値動きを分析します。この2つの記録は、どの過去データセットにもありません。

ドキュメントはhttps://docs.tradefloor.devにあります。

インストール

pip install tradefloor

CPython 3.11以降向けにLinux、macOS、Windows用のホイールを用意しており、依存関係はありません。同じエンジンをRustクレートとしても利用できます（cargo add tradefloor）。 オプションの追加機能では、MCP サーバー（tradefloor[mcp]）、Arrow出力（tradefloor[arrow]）、Gymnasium環境（tradefloor[rl]）、およびエージェントフレームワークごとの追加機能を利用できます。

APIは1.0より前に変更される可能性があります。モデルの変更は新しいプリセットとして提供されるため、エージェントの注文がない市場は、後のリリースでも指定したプリセットで正確に再生できます。tradefloorは0.5.0までpretiumという名前でした。0.4.3までのバージョンは引き続きその名前でインストールでき、それらで記録した結果も引き続き再生できます。

最初の実行

import tradefloor as tf

universe = tf.Universe.random(40, seed=111)

spec = tf.StrategySpec.momentum(lookback_days=1.0, top_k=5)
scores = tf.evaluate({"mine": spec}, seed=7, universe=universe, days=10)

scores["mine"].return_pct            # what it made
scores["mine"].impact_bps            # what its own footprint cost
scores["mine"].strategy_fingerprint  # sha256, cite this
scores["mine"].errors                # each step that raised or was refused
scores["mine"].sharpe                # annualised, from the daily closes
scores["mine"].time_in_market        # share of steps holding a position

この結果は1つのランダムな市場から得られたものなので、戦略だけでなくシードの影響も受けています。tf.rankは多数のシードを実行し、対応のある符号検定で戦略を比較します。エントリーにtf.baselines.reference_agents()を加え、tf.versus_buy_and_hold(scores)を使うと、各スコアを同じ市場におけるバイ・アンド・ホールドと比較できます。

Pythonエージェントは、注文を返すact(obs)を持つ任意のオブジェクトです。注文には、成行注文の株数、tf.Limit(quantity, price)、またはtf.Cancel()を指定します。エージェントには市場と自身のポートフォリオの読み取り専用ビューが表示され、obs.historyには銘柄ごとの日足データが格納されます。日足データの終値は、その日の最後に成立した価格です。pt-v21では、終値を基にすべての銘柄が再評価され、翌取引日の開始前に夜間の値動きが加わるため、翌日はその約定価格とは異なる価格で始まります。20銘柄の構成では、中央値で終値はその約定価格から11bp離れ、始値は終値から25bp離れます。 docs/AGENTS.mdでは、ビューに含まれる情報、取引手数料、フレームワークアダプター（OpenAI Agents SDK、PydanticAI、LangGraph、FinRobot）、およびスコアリングの仕組みについて説明しています。

デモ

例はパッケージではなく、このリポジトリに含まれているため、まずクローンしてください。

git clone https://github.com/simoncoombes/tradefloor
cd tradefloor
python examples/rate-shock/counterfactual.py

制御された市場でエージェントを実行し、世界のチェックポイントを作成して分岐させ、一方の分岐で金利を200 bp引き上げたうえで、同じエージェントが次にどう行動するかを比較します。2つの分岐が同一の状態で始まったこと、エージェントの行動が変わったステップ、そして2つの分岐を並べて比較した結果を、9つのチェック項目として出力します。実行に必要なCPU時間は5秒未満で、キーもネットワークも不要です。手順については 初めての反実仮想実験を参照してください。

内容

engine.truth()	価格が動いた理由：誤価格の変動を1e-16まで合計して説明する12の要因
engine.prints()	各取引価格の決まり方：ショックと、それを吸収した注文板の厚み
反実仮想TCA	注文ありの場合と注文なしの場合で、同じシードを使って算出する取引コスト
tf.rank	複数のシードと、対応のある符号検定
RunManifest	実行を再現するために必要な情報。reproduce()で検証できます
World / compare	実行中の実験を分岐させ、1つの変数を変更し、2つの結果が分かれた箇所を測定します
シナリオ	パッケージに含まれる7つのショックと、独自のシナリオ用ファイル形式
MCP サーバー	コーディングエージェント向けの19個のツール。そのうち13個は読み取り専用です。シナリオ、同梱の任意のプリセット、同梱のバックグラウンドトレーダー集団に加え、ステップ実行、分岐、巻き戻しができる市場セッションを利用できます
その他	Gymnasium環境、Arrow出力、チェックポイント、SEC EDGARデータ、シミュレーションによる金利指数、ブラウザビルド

エージェントから操作する

pip install "tradefloor[mcp]"
claude mcp add tradefloor -- tradefloor-mcp

tradefloor-mcpはstdio経由でMCPを使用し、tradefloor mcpでも同じサーバーを起動できます。戦略、ユニバース、シナリオはデータであるため、ツールの引数からコードにアクセスすることはできません。各結果には注意事項が含まれます。セッションでは、呼び出しの間もサーバー内の市場が維持されるため、エージェントは注文を1ステップずつ出し、2つのアクションを試すために市場を分岐させ、巻き戻すことができます。 こちらのMCPページを参照してください。

シナリオ

engine = tf.Engine(seed=42, universe=universe)
engine.run_days(20)                                # a shared history first
scenario = tf.Scenario.load("liquidity_crisis")    # ships with the package

control, stress = tf.branch(engine, 2)
for day in range(80):
    scenario.apply(stress, day)
    ...                                  # run both branches

シナリオとは、市場と、その市場に関する前提への変更を記述したファイルです。各変更はエンジンが読み取るフィールドを対象とし、ファイルではショックと、それに続いて起きると想定する波及効果を分けて記述します。

tradefloor scenario show oil_price_spike

Exogenous shocks
----------------------------------------------------------
  day 50+            commodity.oil            x1.4

Assumed transmission
----------------------------------------------------------
  day 55..74 ramp    macro.inflation          +1.50pp
  day 55+            macro.corporate_yield    +0.50pp

シナリオのatは、シナリオの適用初日からの日数を数えるため、分岐では分岐した日から数えます。パッケージに含まれるファイルの多くは、50日目に最初のイベントが発生します。分岐後の初日にイベントを発生させるには、scenario.starting_at(0)を使うか、Worldでworld.apply(scenario, at=0)を実行してください。イベント間隔は変わらず、実行記録にはパッケージファイルのフィンガープリントと各イベントの発生日が保存されます。

tradefloorは、戦争、選挙、原油価格のショック、不況が市場に何をもたらすかを予測しません。前提を指定すると、その条件下でエージェントがどのように行動するかを測定します。tradefloor scenario listでパッケージに含まれる7つのシナリオを確認でき、tradefloor scenario targetsでシナリオが変更できるすべてのフィールドを一覧表示できます。

再現性

同じシードを使えば、どのプラットフォームでも同じ市場になります。tradefloor は独自の exp、log、pow、sin、cos を使用するため、システムの数学ライブラリによって結果が変わることはありません。また、各リリースでは 5 つのプラットフォームで固定シミュレーションを実行し、結果に違いがあれば停止します。

同梱のプリセットは変更されないため、エージェントの注文がない市場は、後続のどのリリースでも、指定したプリセットで完全に同じ状態に再現できます。各リリースでは、プリセットごとのダイジェストを使ってこれを確認します。エージェントの注文がある実行は、同じリリース上であれば完全に同じ状態に再現できます。リリースをまたぐ場合の保証は、より限定的です。0.8.5 では、すべてのプリセットでエージェントの約定を市場に反映する方法が変更されたため、0.8.5 より前に記録された取引ありの実行は、最初の取引までは一致し、その後は異なります。デフォルトのプリセットは pt-v21 で、それ以前のプリセットも指定できます。

eng = tf.Engine(seed=42, universe=u, model="pt-v10")

結果を読者が再実行できるようにするには、その RunManifest を公開してください。これにはバージョン、プリセット、シード、ユニバース、マクロ状態、シナリオが記録されており、reproduce() は不一致があると停止します。マニフェストは市場を検証しますが、スコアは含みません。その result ブロックには、市場の digest、days の数、draws_consumed が格納されます。tf.evaluate と tf.rank はマニフェストを書き出さないため、公開されたスコアを検証するには再実行する必要があります。 docs/REPRODUCIBILITY.md には、保存したエンジン状態を復元したときに保証される内容を含め、仕様の全容が記載されています。また、 docs/SUPPORT.md には、長期的な研究で固定すべきリリースが記載されています。

リアリズム

tradefloor は、docs/STATISTICS.md に記載されている、名前付きの 3 つの統計セットを使って、市場を実際の市場と照合します。0.10.0 からのデフォルトである pt-v21 では、1 年間のテーブルにある 19 の統計（ボラティリティ、ファットテール、株価がどの程度連動するか、下落後に VIX がどれだけ上昇するか）はすべて、実際の市場が 1 年間で示す範囲内に、設定された帯域で収まります。指数のリターンと、3％以上下落する日の割合は、長期基準と同じ方法で 360 個のシードにわたって読み取ります。指数が 3％以上下落する日の割合は 0.98％で、実際の範囲である 0.64～2.34％に収まります。2 年間パネルの 15 の統計も、すべて 2 年間の範囲内です。長期基準は 21 年間にわたる 40 項目で、暴落の深さ、恐怖が続く期間、10 年あたりの弱気相場の数、2008 年と 2020 年の再現、指数の金利、そして注文板における規模のコストを対象とします。pt-v21 は、270 の履歴で読み取った 40 項目すべてを満たします。

これらの主張は、限定的に捉えてください。

• 1 年間の件数は、30 個のシード（指数のリターンと 3％下落については 360 個）にわたってまとめた数値に対する評価です。1 つのシードでは、その年の 14 個の形状統計の一部が範囲を外れることがよくあります。シード 101～116 では、16 個中 8 個で 14 項目すべてが範囲内に収まり、あるシードでは 14 項目中 11 項目が範囲内でした。条件ごとに市場を 1 つだけ実行する場合は、各統計について、シード間のばらつきを tf.envelope.intervals() で確認してください。
• 形状統計の範囲は、実際の 1 年間のウィンドウ 35 件の中央値に、トリム標準偏差の 2.1 倍を足し引きして算出するため、範囲内に収まっても、証拠としては弱いものです。ボラティリティ・クラスタリングがその一例です。abs_return_acf5 は 0.020 で、2015～2025 年の実際のすべてのウィンドウを下回っています（最低値は 0.034）。それでも合格するのは、範囲の下限がそうしたウィンドウの値より低いためです。
• VIX の持続性は実際より高くなっています。日々の持続性は 0.956 で、実際の市場データの 0.930 に対し、これを評価する符号検定では不合格となります。
• 1 年間のテーブルは、pt-v21 が採用している係数の多くを選ぶ際に使われたため、保留データでの検証には新しいシードと、パネルを繰り返す際に使う新しい企業セットを使用しています。
• 認証済みの期間は 1 年です。2 年間は 2 年間パネルで評価し、それより長い実行は長期基準だけで評価します。
• 駆動シナリオでは、価格が実際の値動きの約半分から 5 分の 4 の大きさで、正しい方向に動きます。シナリオは反応の検出に使い、その大きさを予測値として解釈しないでください。
• ボラティリティの記憶はラグ 1 で 0.095 となり、実際の 0.107 に対して、その後は実際よりはるかに速く薄れます。ラグ 20 では実際の値の 20 分の 1 未満です。65 分のステップより短い時間幅は調整されていません。
• 1 日に分割した注文は、1 日の出来高の 10％を 36 回に分けて執行すると、日次標準偏差の中央値で 0.13 のコストとなります。これは、公表された研究で示される 0.15～0.3 の範囲の下限にあたります。
• デフォルトでは、他のトレーダーがあなたに反応しないため、流動性スパイラルも略奪的取引も発生しません。参加者ありモードでは、あなたのシグナルに反応して取引し、予測可能な注文フローを先回りするバックグラウンドトレーダーが追加されますが、予測可能なプログラムには約 2.4％高いコストがかかります。これは実際の市場で見られる水準を大きく下回ります。

tf.envelope.check(horizon_days=...) は、測定済みの上限を超える質問を拒否します。 docs/REALISM.md には、これらの主張の根拠となる数値すべてと、上限の全表が記載されています。

結果を公開する前に

• 各日の値動きの要因を当てたエージェントには、explanation_accuracyが付与されます。pt-v21では、常に同じ回答をすると0.70から0.95のスコアになるため、精度だけでなく、ベースラインを差し引いた精度であるexplanation_edgeを引用してください。
• 1回のtf.evaluateまたはtf.rank呼び出しでは、エージェントは同じPythonプロセス内で、同じシードを使って1体ずつ順番に実行されます。先に実行されたエージェントが、後のエージェントのために価格推移をクラス変数に残すことがあります。不正をするように書かれたエージェントは、sys._getframeを使ってハーネスのフレームからシードを読み取り、市場の先行シミュレーションを実行することもできます。どちらも検出されません。読み取り専用の市場ビューが防ぐのは偶発的な操作だけなので、自分で作成していないエージェントは、それぞれ別のプロセスでMCP サーバーを通じて実行してください。
• すべてのevaluateとrankの実行は0日目から始まるため、価格データを20日分必要とするルールでは、買い持ちが投資されている最初の20日間は取引できません。history_days=20を渡すと、誰も取引しない状態で市場を20日間先に進めてから実行できます。
• 複数のエージェントがいるWorldでは、同じステップで発注された注文は、実行期間全体を通じてラベルのアルファベット順に約定します。同じ市場で異なるエージェントを比較する場合は、実行ごとにラベルの順序を入れ替えてください。
• 手数料、空売りの借入手数料、逆指値注文はありません。1日6ステップの設定で、各ステップで確認する逆指値は、その水準から中央値で26.5 bp離れた価格で約定します。cash_interest=Trueを渡さない限り、未投資の現金には利息が付きません。また、現金残高がマイナスの場合は、ブローカーの証拠金金利より低い政策金利が適用されます。

docs/AGENTS.md には、これらの各項目の根拠となる測定値が記載されています。

例

番号付きの 12 個の examples/ は読む順に並んでおり、テストスイートでも実行されます。

00-a-year-in-one-market	まずはこちらから：1 社、1 年、2 つの危機、1 つのチャート
01-first-simulation	ユニバース、エンジン、オーダーブック、決定性
02-evaluating-a-strategy	仕様、ベースライン、シード間のランキング
03-why-did-the-price-move	誤価格の変動を合計する 12 の要因
04-how-realistic-is-this	リアリズムパネルとその限界
05-training-an-agent	Gymnasium 環境と、サイズに伴うコスト
06-execution-and-impact	TCA と反実仮想の実行
07-research-workflow.py	1 つのファイルで完結する研究全体の流れです。CPU で約 40 秒かかり、tradefloor[arrow] が必要です
08-claude-agent.py	ハーネスを通じて市場を取引する LLM エージェント
09-a-pandemic-shaped-market	実際の 2020-21 年のマクロ経路と、伝達されるフィールドを確認します。評価経路を担う QE チャネルを持つ pt-v12 に固定し、最後にデフォルトの pt-v21 でも同じ経路を適用します
10-forking-a-market	市場をフォークし、一方のブランチで金利を引き上げ、将来の結果を比較します
11-scenario-fork.py	フォークの一方のブランチにシナリオファイルを適用し、そのコストを確認します

rate-shock/ の研究は上記のデモであり、 integrations/ では同種の実験を各エージェントフレームワークで実行できます。オフラインで利用でき、API キーも不要です。

ドキュメント

https://docs.tradefloor.dev では、インストール方法、API、ガイド、モデルの評価方法を説明しています。このリポジトリにある以下のページでは、上記の各セクションの詳細を説明しています。

• docs/MODEL.md： 方程式で示したモデル、デフォルトのプリセットにおけるすべての係数の値と、その根拠
• docs/STATISTICS.md： 名前が付けられたリアリズム統計のセット
• docs/REALISM.md： リアリズムの結果と、測定されたすべての限界値
• docs/REPRODUCIBILITY.md： プラットフォーム、リリース、復元された状態をまたいで、何が完全に再現されるか
• docs/AGENTS.md： エージェントの作成、スコアリング、比較
• docs/SUPPORT.md： どのリリース系列が、どれくらいの期間修正を受けられるか
• docs/EMBEDDING.md： ゲームや別のホストから Rust エンジンを動かす方法と、モデル独自のフローがどれほど大きいか

コントリビューションとサポート

CONTRIBUTING.md では、プロジェクトのビルド方法とテスト方法を説明しています。主なルールは、シミュレーションの軌跡に対する変更は、どれほど小さくても破壊的変更となるため、モデルの変更は新しいプリセットとしてリリースすることです。RELEASING.md はリリースチェックリストです。

脆弱性は公開の issue ではなく、GitHub の セキュリティアドバイザリーフォーム から報告してください。 SECURITY.md には、対象範囲が記載されています。バグや質問は GitHub issues にお寄せください。

0.8.5 とそれ以降の 0.8 パッチは長期サポート系列で、バグ修正とセキュリティ修正が 24 か月間提供されます。 docs/SUPPORT.md には、サポート系列で保証される内容と、長期研究で固定すべきリリースが記載されています。

tradefloor の引用

実行したバージョンを引用し、プリセット名を明記してください。同じバージョンで複数のプリセットを実行でき、結果はプリセットによって異なります。

@software{tradefloor,
  author  = {Coombes, Simon},
  title   = {tradefloor: a deterministic market simulator with a limit order book},
  version = {0.10.2},
  year    = {2026},
  url     = {https://github.com/simoncoombes/tradefloor},
  note    = {Model preset pt-v21}
}

CITATION.cff にも同じ情報が記載されており、GitHub の「このリポジトリを引用」ボタンはこのファイルを読み取ります。

本文では、使用したモデルを明記してください。たとえば、「tradefloor 0.10.2、docs/MODEL.md に記載されたプリセット pt-v21」のように記載します。 docs/REPRODUCIBILITY.md では、読者が結果を再実行できるように公開する方法と、スコアがシードに合わせて調整されていないことを示す方法を説明しています。

ライセンス

tradefloor は、MIT または Apache-2.0 のライセンスで提供され、どちらを選ぶかは利用者に委ねられています。LICENSE-MIT と LICENSE-APACHE をご覧ください。GitHub のサイドバーに Apache-2.0 と表示されるのは、ライセンス検出機能がどちらか一方のファイルを選び、そこで処理を終了するためです。適用されるライセンスはデュアルライセンスであり、pyproject.toml、rust/Cargo.toml、およびこのセクションに記載されています。