Foresea Forecasting

Foresea：自律型予測市場インテリジェンスと LLM 根拠ベンチマーク

Foresea (foresea.ink) は、自律型の予測市場インテリジェンスプラットフォームであり、実証研究のためのフレームワークです。Polymarket と Kalshi におけるリアルタイムの確率予測、統計的な優位性の発見、複数モデルによるシャドートレーディングトーナメント、自律型の 19 ツール ReAct 実行エージェント、そして公開 Model Context Protocol（MCP）サーバーを組み合わせています。

このリポジトリは、明示的な根拠の指示、エビデンスの注入、推論構造が、Metaculus 形式の質問に対する LLM の予測行動と較正にどのような影響を与えるかを研究するための成果物としても機能します。

---

📑 目次

• ライブプラットフォームとウェブビュー
• エッジボードと自律型シャドートレーディングデスク
• 5 分間の暗号資産マイクロマーケット
• 本番環境へのデプロイとインフラストラクチャ
• API とエンドポイントの利用
• エージェント：自動化されたインテリジェンスレイヤーと ReAct ツール
• Model Context Protocol（MCP）との統合
• カスタム統合とエコシステムツール
• 取引の実行と KMS ガードレール
• リポジトリの内容とプロンプトのバリエーション
• Foresea Autoresearch
• 主要な出力と SQL 分析の再現
• 品質チェックと開発

---

ライブプラットフォームとウェブビュー

高い同時接続数に対応するスケーリング、ストリーミング応答、継続的デリバリーを備え、Google Cloud Run にデプロイされています：

https://foresea.ink

主要な Web アプリケーションとルート

• Market Desk（/）：マーケットレーダー、モデルと市場の乖離のハイライト、インタラクティブなガイドを備えたリアルタイムのランディングビューです。
• Forecasting Chat（/chat, /chat/:id）：根拠のストリーミング表示、ニュースの根拠の引用、複数ターンにわたる市場分析に対応した会話型インターフェースです。
• Edge Board（/edge, /edge/markets）：Polymarket と Kalshi における Foresea と市場の価格差をリアルタイムで順位付けして表示します。キャリブレーションとリードタイムのスコアに基づいています。
• Mark-to-Market View（/edge/mtm）：解決済みおよび未決の市場予測について、時価評価と損益を継続的に追跡します。
• Agentic Trading Desk（/edge/agentic）：複数モデルによる自律型トレーディングトーナメントです。各モデル（Gemma 4 26B、Qwen 3.8 27B、GPT-OSS 120B、GLM 5.3、GLM 5.3 Flash、DeepSeek V4 Flash、MiniMax M3、Llama 3.3 70B）に独立した 10,000 ドルのシャドーアカウントを用意し、リアルタイムのペーパートレードを実行して、資産曲線を追跡し、毎時のサイクルの健全性を記録します。
• Trading Terminal（/trade）：Polymarket と Kalshi の認証情報に対する Cloud KMS のエンベロープ暗号化を備えた、カストディを伴わないクライアント側の注文プレビューおよび実行ターミナルです。
• Watchlist（/watchlist）：特定の市場をフォローし、自動生成される日次ダイジェストメールを受け取れます。
• Public Forecasts（/forecast/:share_id）：根拠カードと出所情報を含む、共有可能な予測パーマリンクです。

# Health check
curl https://foresea.ink/health

# Single-record prediction
curl -X POST https://foresea.ink/predict \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will X happen by date Y?",
    "question_type": "binary",
    "description": "Context here.",
    "news_articles": [],
    "attach_evidence": true,
    "evidence_top_k": 5,
    "market_platform": "Polymarket",
    "market_probability": 0.42,
    "variant": "variant0_neutral_baseline"
  }'

attach_evidence が true で news_articles が指定されていない場合、/predict はデフォルトで GDELT、Google News RSS、Stooq から最新ニュースの根拠を取得して順位付けし、 モデルのプロンプトに挿入して、予測とともに選択された evidence_articles を返します。news_articles を指定すると、自動取得はスキップされ、 呼び出し元が提供した根拠が使われます。

レスポンスには予測と、モデルが使用した根拠の両方が含まれます。

{
  "question_type": "binary",
  "predicted_answer": "Yes",
  "confidence": 0.86,
  "options": [],
  "range_forecast": null,
  "rationale": "Model-generated explanation for the forecast.",
  "model_rationale": "Model-generated explanation for the forecast.",
  "variant": "variant0_neutral_baseline",
  "model_key": "gpt-oss-120b",
  "evidence_sources": [
    {
      "source": "Reuters",
      "title": "Article headline",
      "url": "https://example.com/article",
      "publish_date": "2026-05-29T00:00:00Z",
      "relevance_score": 0.82
    }
  ],
  "evidence_articles": [
    {
      "title": "Article headline",
      "summary": "Cleaned article summary.",
      "source": "Reuters",
      "url": "https://example.com/article",
      "publish_date": "2026-05-29T00:00:00Z",
      "relevance_score": 0.82,
      "search_query": "query used for retrieval"
    }
  ],
  "evidence_error": null,
  "market_analysis": {
    "platform": "Polymarket",
    "market_url": "https://example.com/market",
    "outcome": "Yes",
    "market_probability": 0.42,
    "model_probability": 0.86,
    "edge": 0.44,
    "stance": "model_above_market",
    "summary": "Foresea is 44 percentage points above the market on Yes."
  }
}

クライアントがソースの一覧とリンクのみを必要とする場合は、evidence_sources を使用してください。 モデルのプロンプトに添付された記事ごとの詳細が必要な場合は、evidence_articles を使用してください。 rationale と model_rationale は gpt-oss-120b によって生成され、モデルがその回答と信頼度を選んだ理由を説明します。 market_probability が指定されている場合、market_analysis はモデルの確率と市場が示唆する確率から 決定論的に計算されます。

Edge Board と自律型シャドートレーディングデスク

Foresea は、最先端の LLM を実際の予測市場に対して継続的に評価し、統計的優位性、キャリブレーション精度、シャドーポートフォリオのパフォーマンスを、専用の 3 つのビューで追跡します。

1. ライブ市場の見解の相違（/edge または /edge/markets）

• リアルタイムの優位性ランキング：Polymarket と Kalshi におけるモデル予測と市場のリアルタイム価格の統計的な差を定量化します。 $$\text{Edge} = P_{\text{model}} - P_{\text{market}}$$
• ポジションサイズと推奨：フラクショナル・ケリー法による配分を計算し、実行可能な取引（buy_yes、buy_no、hold）に分類します。
• キャリブレーションと結果確定：static/track_record_live.json に記録された毎時のスナップショットに基づき、市場の結果確定後にブライアスコア、期待キャリブレーション誤差（ECE）、リードタイムスキルを計算します。

2. 時価評価（/edge/mtm）

• 継続的なポートフォリオ評価：最終的な決済だけに頼らず、リアルタイムの買値と売値でペーパーポジションを評価します。
• 未実現損益と実現損益：未決済期間における取引の推移とボラティリティへのエクスポージャーを、機関投資家水準の視点で提示します。

3. エージェント型自律トレーディングトーナメント（/edge/agentic）

• マルチモデル・トーナメント：自律型ポートフォリオマネージャーとして動作する8種類のLLMを評価します：
  • Gemma 4 26B（gemma-4-26b-a4b-it）
  • Qwen 3.8 27B（qwen3-8-27b）
  • GPT-OSS 120B（gpt-oss-120b）
  • GLM 5.3（glm-5-3）および GLM 5.3 Flash（glm-5-3-flash）
  • DeepSeek V4 Flash（deepseek-v4-flash）
  • MiniMax M3（minimax-m3）
  • Llama 3.3 70B（llama-3.3-70b-instruct）
  • ベースライン：crowd-follow（LLMを使用しないコンセンサス制御）
• 独立した10,000ドルのポートフォリオ：各モデルは、シミュレーション上の現金残高10,000ドルと、市場のスキャン、注文板の評価、即時またはキャンセル（IOC）のペーパー注文の執行を自律的に行う権限を持って開始します。
• 資産曲線とサイクルの健全性：累積リターン（10,000ドルを再投資）、ドローダウン指標、取引ログ、時間ごとのサイクル実行の健全性（プロバイダーの可用性、トークン予算、取引トリガーを追跡）を表示します。

5分間の暗号資産市場

src/analyzing_llm_rationale/crypto_5m.py にあるローカルの暗号資産マイクロ市場モデルは、継続的に取引するのではなく、選択的に利益の出る取引を行うことを目指す、5分間のUP/DOWN市場向けに構築されています。次の要素を組み合わせています：

• ドリフトを縮小した対数正規マネーネス価格設定、
• EWMAボラティリティを用いたAR(1)リターン予測、
• モメンタム、反転、ボラティリティレジーム、レンジ内の位置、出来高の不均衡に基づく、固定または適応型のロジスティックML特徴量。

各予測は、predicted_outcome、probability_up、component_probabilities、モデルと市場のedge、手数料を考慮したstrategyを返します。戦略が取引を推奨するのは、手数料を差し引いた期待値が手数料と設定済みの取引見送りしきい値を上回る場合に限られます。

.venv/bin/python scripts/crypto_5m_backtest.py \
  --benchmark \
  --symbols BTC,ETH,SOL \
  --days 1 \
  --max-candles 1600 \
  --lookback-minutes 60 \
  --horizon-minutes 5 \
  --market-probability 0.50 \
  --fee-bps 2 \
  --ml-modes fixed,adaptive \
  --edge-thresholds 0,0.01,0.03,0.05,0.08 \
  --selection-fraction 0.6 \
  --folds 4 \
  --training-window 120 \
  --max-rows 80 \
  --benchmark-log data/crypto_5m_benchmark_runs.jsonl

資金をリスクにさらす前に、fold_aggregate と evidence_quality を使用してください。選択が不安定な場合やホールドアウトのPnLが弱い場合、利益を得るための正しい行動は取引を見送ることです。--benchmark-log は、選択したしきい値とモデルモードがベンチマーク実行を重ねても機能し続けているかを追跡するため、簡潔なJSONLレコードを追記します。 完了した市場をBinanceのローソク足データと照合して解決します：

.venv/bin/python scripts/crypto_5m_backtest.py \
  --resolve \
  --symbol BTCUSDT \
  --target-price 62400.52 \
  --start-time-ms 1780000000000 \
  --horizon-minutes 5 \
  --predicted-outcome down

リゾルバーは、満期前にはpendingを返し、満期後にはactual_outcome、resolved_price、prediction_correctを含むresolvedを返します。

ペーパーシグナルを記録し、時間の経過とともに解決します：

.venv/bin/python scripts/crypto_5m_backtest.py \
  --paper-signal \
  --symbol BTCUSDT \
  --market-probability 0.50 \
  --fee-bps 2 \
  --signal-log data/crypto_5m_signal_log.jsonl

.venv/bin/python scripts/crypto_5m_backtest.py \
  --resolve-signal-log \
  --signal-log data/crypto_5m_signal_log.jsonl

.venv/bin/python scripts/crypto_5m_backtest.py \
  --signal-summary \
  --signal-log data/crypto_5m_signal_log.jsonl \
  --min-resolved-trades 200 \
  --min-total-pnl 0 \
  --min-hit-rate 0.53

.venv/bin/python scripts/crypto_5m_backtest.py \
  --paper-loop \
  --symbols BTC,ETH,SOL \
  --iterations 12 \
  --sleep-seconds 60 \
  --market-probability 0.50 \
  --fee-bps 2 \
  --signal-log data/crypto_5m_signal_log.jsonl

シグナルログは、モデル改善のための継続的なデータセットです。各レコードには、予測、推奨、その後のactual_outcome、正誤、実際のbuy_up／buy_downペーパートレードのpnl_per_contractが保存されます。--signal-summaryを使用して、解決済みのペーパートレードが手数料を差し引いても利益を上げているかを監査できます。設定済みの取引件数、PnL、的中率のしきい値を満たすまでは、trade_readyはfalseのままです。ログに書き込まずにシグナルをプレビューするには、--paper-loopとともに--dry-runを使用してください。

本番環境へのデプロイに関する注意事項

本番環境はカスタムドメインで提供されます。

https://foresea.ink

Cloud Run サービス名、プロジェクト ID、リージョンは、デプロイ時に gcloud run deploy で設定します。

必要なランタイム環境変数：

• SCADS_AI_API_KEY：ホストされたモデル呼び出しで使用する Secret Manager のシークレットです。
• MODEL_DEVICE=cpu：本番の Cloud Run では CPU イメージを実行します。
• CUSTOM_DOMAIN=foresea.ink：*.run.app へのリクエストを公開ドメインにリダイレクトします。
• GOOGLE_CLIENT_ID：/auth/config で使用する Google OAuth ウェブクライアント ID です。
• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET：GitHub OAuth アプリの認証情報です。OAuth アプリのコールバック URL はサイトのオリジン（例：https://foresea.ink/）に設定する必要があります。未設定の場合、「Continue with GitHub」ボタンは非表示になり、/auth/github は 503 を返します。Google とメールアドレス／パスワードでもサインインできます。
• SESSION_SECRET：ブラウザーセッション JWT の署名と、認証済みアナリティクス用のドメイン分離された復元不可能な参照値の生成に使用する、十分に長いランダム文字列です。これをローテーションすると新しいアトリビューションコホートが開始されます。アカウントのメールアドレスが公開されることはありません。

OAuth クライアントでは、次の JavaScript オリジンを許可する必要があります。

https://foresea.ink
https://www.foresea.ink
https://<cloud-run-service-url>.run.app

既存の SESSION_SECRET を置き換えずに、シークレットではない環境変数を更新するには、--update-env-vars を使用します。

gcloud run services update <service-name> \
  --region <region> \
  --project <project-id> \
  --update-env-vars MODEL_DEVICE=cpu,CUSTOM_DOMAIN=foresea.ink,GOOGLE_CLIENT_ID='<your-google-client-id>'

デプロイ済みの認証設定とヘルスエンドポイントを確認します。

curl https://foresea.ink/auth/config
curl https://foresea.ink/health

スケーリングとキャッシュ

このサーバーは、Cloud Run 上で水平スケーリングできるように構築されています。

• 認証では、Google One-Tap とメールアドレス／パスワード（/auth/register、/auth/login）の両方をサポートします。パスワードはソルト付き PBKDF2-HMAC-SHA256 ハッシュとして保存され、アカウントは Cloud Datastore に保存されます。
• キャッシュとレート制限では、REDIS_URL が設定されている場合は Redis を使用し、インスタンス間で共有します。未設定の場合はインスタンスごとのメモリー内状態にフォールバックし、フェイルオープンで動作します。/predict（パーソナライズされていないリクエスト）、エビデンスの取得、/extract の URL フェッチはキャッシュされます。公開 GET リクエストでは Cache-Control が送信されます。

変数	デフォルト	説明
REDIS_URL	未設定	Memorystore/Redis の URL です。インスタンス間でキャッシュとレート制限を共有します。
PREDICT_CACHE_TTL	600	パーソナライズされていない /predict レスポンスのキャッシュ TTL（秒）です。0 にすると無効になります。
EVIDENCE_CACHE_TTL	900	エビデンス取得のキャッシュ TTL（秒）です。
EXTRACT_CACHE_TTL	3600	/extract の URL フェッチのキャッシュ TTL（秒）です。
LOCAL_CACHE_MAX	1024	メモリー内のフォールバックキャッシュに保存する最大エントリー数です。
SEARXNG_URL / TAVILY_API_KEY / SERPER_API_KEY / BRAVE_API_KEY	未設定	エビデンスソースとしてウェブ検索を有効にします。設定されている場合は、セルフホストの SearXNG が優先され、次に Tavily、Serper、Brave が使用されます。Tavily と Serper には、カード不要の無料プランがあります。いずれも設定されていない場合、エビデンスは GDELT、Google News、RSS から取得されます。
NEWSAPI_KEY	未設定	エビデンスソースとして NewsAPI を有効にします。

ライブ実績

GET /track-record は、公開予測実績を提供します。負荷の高いティックループは Cloud Run では実行されません。.github/workflows/track-record-tick.yml が GitHub Actions で毎時実行され、真実のソースとなるエンティティストアとして data/track_record_store.json を更新し、公開用の集計データを static/track_record_live.json に書き込み、両方のファイルを main にコミットします。実行時に Cloud Run は raw GitHub からコミット済みの集計データを取得し、取得できない場合はバンドルされたファイル、次に static/track_record.json の静的バックテストを使用します。

この Action は、クローズ日ごとに分けた期間（デフォルトでは 2-7、7-14、14-30、30-60 日）で短期から中期の Polymarket/Kalshi 市場を検出し、新たにスナップショットが作成された市場／モデルごとに /predict を一度呼び出します。/predict が保護されている場合は、GitHub シークレット PREDICT_API_KEY を設定してください。サーバー側の /track-record/tick エンドポイントは不要です。TRACK_RECORD_TOKEN は任意で、エージェントに登録された市場のブリッジを有効にする場合にのみ使用します。

デフォルトの定期予測ジョブは、意図的にコストを制限しています。6 時間ごとに実行され、会場ごとに最大 2 市場のスナップショットを作成し、予測対象は gpt-oss-120b と、LLM を使用しない crowd-follow ベースラインのみです。すべての定期実行でオープン中の全市場を再予測するのではなく、単発の完全更新には手動ワークフローのディスパッチ入力 reforecast_each_tick=1 を使用してください。

ホームページのマーケットデスクは GET /radar を使用します。これは static/track_record_live.json とその edge_board から生成されます。Radar は現在のモデルと市場の乖離を強調表示し、ページ読み込みのたびに会場をスキャンする代わりに、コミット済みの実績集計を再利用することで、最初の画面を高速に表示します。

アイドルコストを発生させずに Cloud Run のスループット上限を引き上げます（min-instances=0 の場合）：

gcloud run services update analyzing-llm-rationale --region us-central1 \
  --max-instances 20 --concurrency 40 --memory 1Gi

最も低コストで公開環境にデプロイするには、リクエスト時のみ CPU を使用する設定を維持し、ゼロまでスケールし、急増時のスケールアウトに上限を設けます。デプロイワークフローではこのプロファイルを使用します。スタートアップ CPU ブーストは、アイドル状態のインスタンスをウォーム状態に保つことなくコールドスタートのレイテンシを短縮するため、有効のままにします：

gcloud run services update analyzing-llm-rationale \
  --region us-central1 \
  --project brave-drive-471109-d9 \
  --cpu 1 \
  --memory 512Mi \
  --min-instances 0 \
  --max-instances 3 \
  --concurrency 20 \
  --timeout 180 \
  --cpu-throttling \
  --cpu-boost \
  --update-env-vars INTERACTIVE_DEFAULT_MODEL=gemma-4-26b-a4b-it,INTERACTIVE_MAX_TOKENS=384,CHAT_PROVIDER_TIMEOUT_S=15,CHAT_PROVIDER_MAX_RETRIES=0,EVIDENCE_TIMEOUT_S=6,EVIDENCE_MAX_CONCURRENCY=4

ランタイムを変更するたびに、デプロイ済みの予測レイテンシを測定します：

py scripts/measure_forecast_latency.py \
  --url https://foresea.ink \
  --mode stream \
  --models minimax-m3 \
  --runs 3 \
  --no-attach-evidence \
  --max-tokens 384

それでもコールドスタートが主な要因となる場合は、レイテンシとコストの明示的なトレードオフとして --min-instances を 1 に引き上げてください。

市場検索はメイン API 内で実行されます。任意の Go marketd マイクロサービスは GitHub Actions でのビルド／テスト専用であり、デフォルトでは Cloud Run にデプロイされません。

Artifact Registry の保持ポリシー

CI はデプロイのたびに、コミットタグ付きの Docker イメージを Artifact Registry にプッシュします。古いイメージが蓄積しないよう、docker リポジトリのクリーンアップポリシーを有効にしてください：

gcloud artifacts repositories set-cleanup-policies docker \
  --location us-central1 \
  --project brave-drive-471109-d9 \
  --policy infra/artifact-registry-cleanup-policy.json \
  --no-dry-run

このポリシーは、7 日より古いイメージを削除し、パッケージごとに最新の 5 バージョンを保持し、main タグは常に保持します。

Docker のビルドは Cloud Build ではなく GitHub Actions で実行されます。通常のデプロイ手順では、Cloud Build のトリガーもステージングバケットも不要です。

max-instances > 1 にしたら、Memorystore for Redis（課金対象）をプロビジョニングし、REDIS_URL を設定して、インスタンス間でレート制限とキャッシュが正しく動作するようにします：

gcloud services enable redis.googleapis.com vpcaccess.googleapis.com compute.googleapis.com
gcloud redis instances create foresea-cache --size=1 --region=us-central1 --tier=basic
gcloud compute networks vpc-access connectors create foresea-vpc \
  --region=us-central1 --range=10.8.0.0/28
gcloud run services update analyzing-llm-rationale --region us-central1 \
  --vpc-connector foresea-vpc \
  --update-env-vars REDIS_URL=redis://<instance-host>:6379

API の使用

履歴データ、アカウントのページネーション、注文管理、ネイティブな取引所ストリームについては、Kalshi および Polymarket の追加エンドポイントを参照してください。

公開されている Cloud Run API は、最も簡単に連携できる対象です。予測に関する質問を受け付け、型付きの予測、モデルの根拠、任意の証拠記事を返します。解決可能な予測向けに構築されており、一般的な Q&A 向けではありません。

エンドポイントと Web ルート

公開 Web ビュー

• GET /：ランディングページ、リアルタイムの市場レーダー、インタラクティブなワークフローのデモです。
• GET /chat、GET /chat/{id}：根拠を示しながら推論をストリーミングする、対話型の予測スタジオです。
• GET /edge、GET /edge/markets：統計的な価格差ランキングとケリー基準によるポジションサイズを表示する、リアルタイムの市場優位性ボードです。
• GET /edge/mtm：予測市場全体におけるオープンポジションの時価評価パフォーマンスです。
• GET /edge/agentic：複数モデルによる自律取引トーナメント、資産曲線、サイクルの健全性、ペーパー取引の記録です。
• GET /trade：Polymarket と Kalshi 向けの、エンベロープ暗号化を使用した非カストディアル取引ターミナルです。
• GET /watchlist：追跡中のお気に入り市場と、毎日のダイジェスト通知です。
• GET /forecast/{share_id}：公開読み取り専用の予測共有パーマリンクです。
• GET /embed/forecast/{share_id}：iframe に埋め込める軽量な予測ウィジェットです。
• GET /widget.js：ライブ予測を公開するための、すぐに使える Web コンポーネント <foresea-card> です。

予測・インテリジェンスのコア API

• GET /health：サービスのヘルスチェックと稼働状況です。
• POST /predict：任意で根拠を取得できる、公開確率予測エンドポイントです。
• POST /agent/analyze：カスタムスキルと ReAct ループを使って、ライブ市場をエンドツーエンドでオーケストレーション分析します。
• GET /agent/scan：統計的な優位性の順に、価格が適正でない市場を特定する取引所スキャナーです。
• GET /radar：ライブの実績から生成される、ホームページのマーケットデスク用ペイロードです。
• GET /track-record：公開されているライブ実績と過去の較正統計です。
• GET /track-record/digest：共有可能なライブ実績の Markdown 要約です。
• GET /pr-agent：Foresea の発見を目的とした、オプトイン方式のエージェント間アウトリーチ用パケットです。

取引所・市場データ

• GET /markets/polymarket：Polymarket の正規化されたライブ気配値、注文板、流動性データを取得します。
• GET /markets/kalshi：Kalshi の正規化されたライブ気配値、権利行使価格の範囲、ティッカーメタデータを取得します。

Model Context Protocol（MCP）

• GET /mcp/：公開リモート Model Context Protocol（Streamable-HTTP）エンドポイントです。
• GET /.well-known/mcp/server.json：公開 MCP ディスカバリーマニフェストです。

分析、共有、アカウント同期

• POST /analytics/visit：プライバシーを保護したページ訪問の追跡です（リンク先は不可逆な参照のみです）。
• POST /analytics/event：ファネルイベントの記録です（forecast_completed、watchlist_add、share_created、digest_sent）。
• GET /analytics/events/summary：過去30日間のプロダクト分析の集計サマリーです。
• POST /forecasts/share：明示的な公開予測共有 ID を生成します。
• GET|POST /chat/conversations：認証済みユーザー向けのクラウド会話同期です。
• GET|POST|DELETE /favorites：ウォッチリストの管理と追跡です。

非カストディアル取引の執行

• GET|PUT|DELETE /trading/connections/{platform}：ユーザーごとの取引所接続認証情報を KMS で暗号化して管理します。
• POST /trading/preview：ドライランでの注文正規化と、指値幅の検証です。
• POST /trading/orders：ユーザーによる明示的な2段階確認を伴うライブ注文の送信です。
• GET /trading/portfolio：認証済みユーザーの残高、オープンポジション、未約定注文、約定履歴です。
• POST /trading/orders/{audit_order_id}/reconcile：取引所の注文ステータスと約定の照合です。
• DELETE /trading/orders/{audit_order_id}：取引所の未約定注文をキャンセルします。

Web アプリのランタイム状態

匿名チャットはブラウザーの localStorage に保存されます。サインイン済みユーザーの会話は /chat/conversations 経由で同期されます。ウォッチリストの追跡には、/favorites と /favorites/prices から参照できる FavoriteMarket エンティティが使われます。お気に入りのダイジェストは scripts/favorites_digest.py を通じて .github/workflows/favorites-digest.yml から実行されます。

予測共有はオプトイン方式です。クライアントは POST /forecasts/share を呼び出して、 公開される GET /forecast/{share_id} ページを作成します。共有予測ビューに非公開のチャット履歴全体を公開しないでください。

エージェント：自動インテリジェンスレイヤー

POST /agent/analyze はパイプライン全体を自律的に実行します。市場を解決 （識別子が指定されている場合は、Polymarket/Kalshi のリアルタイム価格を取得）→ 証拠を収集して予測 → エッジを評価 → カスタムスキルを実行 → 推奨します。構造化されたレポートを 1 件返します。

curl -X POST https://foresea.ink/agent/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "polymarket",
    "slug": "will-the-fed-cut-rates-in-2026",
    "skills": [
      {"name": "Base rate check", "instruction": "Compare to historical base rates."},
      {"name": "Risk", "instruction": "What would most change this forecast?"}
    ]
  }'

カスタムスキルは独自の分析ステップです。それぞれが質問、予測、証拠を対象に追加のモデルパスとして実行され、レポート内の名前付きセクションとして返されます。question を直接指定するか、platform と市場識別子（Polymarket の場合は slug/market_id、Kalshi の場合は ticker）を指定してください。複数ターンのやり取りで続けて質問する場合は history（前のターン）を渡します。履歴があれば、「なぜ？」や「6月はどうですか？」のような短い追加質問にも文脈に沿って回答します。BYOK フィールド（openrouter_api_key、openrouter_model、provider_base_url）もここで適用されます。 レポートには、recommendation（buy_yes/buy_no/hold/no_market_price）、edge、model_probability、market_probability、thesis、evidence_sources、および pipeline（実行されたステップの順序）が含まれます。

自律型 19 ツール ReAct 実行ループ

Foresea エージェントは、動的な計画の策定、ツールの選択、振り返り、JSON エラーの復旧を行う自律型 ReAct（推論＋行動）ループを利用します。

• 予測と統計的エッジ：

  • forecast：信頼度と根拠を含む、確率の較正済み予測です。
  • get_market：Polymarket と Kalshi を横断した、正規化済みの価格情報と市場メタデータの検索です。
  • scan_markets：モデルと市場のエッジで絞り込み、順位付けされたライブ市場を検出します。
  • batch_quotes：複数の取引所から価格情報を高スループットで集約します。
  • search_evidence と web_search：複数のソース（GDELT、Google News、SearXNG、Tavily、Stooq）からリアルタイムで情報を取得します。
  • track_record と edge_board：過去の較正指標と、公開中の順位付きアルファ機会を確認します。
  • market_leaderboard：予測市場の主要トレーダーの実績ランキングを確認します。

• 取引所のオーダーブックとマイクロストラクチャ：

  • exchange_status：Kalshi の取引所ステータス、市場の取引状態、運用スケジュールを確認します。
  • orderbook：Kalshi のティッカーまたは Polymarket のトークンの、リアルタイムの買い注文・売り注文の板の厚さを確認します。
  • market_tags：Polymarket のカテゴリタグと市場分類体系を確認します。
  • price_history：過去の価格ポイント、時系列データ、OHLC ローソク足を確認します。
  • live_data：リアルタイムのスポーツ統計、プレーごとのデータ、試合のライブフィードを取得します。
  • polymarket_meta：イベントシリーズの階層、解決ルール、コミュニティでの議論を確認します。
  • recent_trades：価格、契約サイズ、タイムスタンプを含む、リアルタイムの取引履歴を確認します。

• 実行と状態管理：

  • place_trade：ライブのオーダーブック価格に対して、即時約定またはキャンセル（IOC）方式で紙上取引を実行し、シャドー残高を更新します。
  • manage_notes：ReAct の推論ターンをまたいで、スクラッチパッドの状態を保持します。
  • fetch_api：外部データを検証するための、安全なサンドボックス化された HTTPS 取得です。

自動呼び出しエイリアス：agent_capabilities.py の TOOL_ALIASES は、別の LLM 命名規則（例：http_get → fetch_api、candlesticks → price_history、comments → polymarket_meta、trades → recent_trades、leaderboard → market_leaderboard）を正規化します。

永続的なプライベート Agent Run

サインイン済みユーザーが POST /agent/analyze を呼び出すたびに（ストリーミングエンドポイントを含む）、プライベートな AgentRun も作成されます。これには、上限付きの秘密情報を含まない入力スナップショット、ライフサイクルのタイムライン、モデルレポート、レビュー専用の取引引き継ぎ情報が保持されます。最新の運用タイムラインには GET /agent/runs を、完全なレポート 1 件には GET /agent/runs/{run_id} を使用してください。スナップショットには、プロバイダーキー、ブラウザー認証情報、会話履歴、生のカスタムスキル指示は意図的に含まれません。Agent Run は調査専用です。取引の引き継ぎ情報が含まれていても、注文の作成、数量の決定、送信はできません。ユーザーは引き続き、ターミナルで永続的な Trade Run を作成し、明示的に確認する必要があります。

コピーされたエージェント：非公開でバージョン管理されたリサーチレシピ

サインイン済みのユーザーは、Agentic ボードから公開 Foresea モデルをコピーできます。コピーはユーザーのアカウントに不変のバージョン 1 のリサーチレシピとして保存されます。含まれるのは公開ソースモデルと分析指示のみで、元のエージェントの非公開コンテキスト、シャドーアカウントの履歴、取引所接続、注文サイズ、取引権限は含まれません。許可リストに登録された source_agent_id を指定して POST /agent-profiles/copy を使用し、返された agent_profile_id を POST /agent/analyze に渡します。

プロファイルが選択されると、サーバーがプロファイルのモデルと指示を解決し、クライアント側の BYOK／プロバイダー／モデルのオーバーライドを無視して、固定のリサーチパイプライン（ツールループや取引ツールなし）を強制します。生成されるレポートには、再現性のためプロファイル ID、ソース、バージョン、research_only モードが返されます。プロファイルでは既存のレビュー専用の取引引き継ぎを準備できますが、取引所への注文の作成や送信はできません。サインイン済みのユーザーが引き続き永続的な Trade Run を作成し、取引ターミナルで明示的に PLACE REAL ORDER を確認する必要があります。

エッジスキャン — 割安な市場を見つける

GET /agent/scan は、取引所のライブ市場を一覧表示してそれぞれを予測し、モデルと市場の差が min_edge を超える市場を |edge| の順に返します。

curl "https://foresea.ink/agent/scan?platform=polymarket&limit=4&min_edge=0.1"

パラメーター：platform（polymarket または kalshi）、limit（分析する市場数、最大 8）、 min_edge（デフォルトは 0.1）、evidence_top_k。各市場で完全な予測を実行するため、 limit によって上限が設けられ、結果は短時間キャッシュされます。レスポンス：{platform, scanned, opportunities: [{question, market_url, market_probability, model_probability, edge, recommendation}]}。ウェブアプリでは、デスクの **「⚡ 割安な市場を Polymarket でスキャン」**ボタンがこれを呼び出します。

MCP サーバー：AI エージェントが Foresea をツールとして呼び出せます

Foresea は、次の公開リモート MCP サーバーを提供しています。

https://foresea.ink/mcp/

次の場所で発見できるように登録されています。

https://foresea.ink/.well-known/mcp/server.json

リモート MCP サーバーは、公開 API 上に構築された薄いツールレイヤーです。以下を提供します。

• foresea_forecast：根拠とニュース情報を添えて、校正済みの確率予測を生成します。
• foresea_analyze_market：特定の Polymarket／Kalshi 市場を評価し、モデルと市場の乖離およびテーゼを提示します。
• foresea_scan_markets：ライブ市場をスキャンし、モデルと市場の不一致度順に表示します。
• foresea_batch_quotes：複数の市場の気配値を、1 回のリクエストで複数の取引所から取得します。
• foresea_check_run：時間のかかる市場調査のバックグラウンド実行状況を確認します。
• foresea_edge_board：統計的なエッジ順に、取引可能な未決済の機会を表示します。
• foresea_track_record：公開精度、Brier スコア、ECE、校正指標を表示します。
• foresea_debate_market：複数のエージェントによる敵対的な議論（強気派 vs. 弱気派 vs. リスク判定役）を実施します。
• foresea_optimize_portfolio：未決済のエッジに対する最適なフラクショナル・ケリー方式の資金配分を計算します。
• foresea_feed_latest：ライブ市場のエッジ、エージェントの取引、ランキングを組み合わせたリアルタイムのアルファフィードです。
• foresea_exchange_status：Kalshi 取引所の状態（取引有効フラグ）と運営スケジュールを確認します。
• foresea_orderbook：Kalshi のティッカーまたは Polymarket のトークンについて、ライブの買い気配と売り気配の板の厚みを取得します。
• foresea_market_tags：Polymarket の有効なカテゴリ分類とタグを取得します。
• foresea_price_history：過去の価格データまたは OHLC ローソク足を取得します。
• foresea_live_data：リアルタイムのスポーツ試合統計、プレイごとのデータ、ライブイベントフィードを取得します。
• foresea_polymarket_meta：イベントシリーズの一覧、コミュニティのディスカッションコメント、またはスポーツメタデータを取得します。
• foresea_recent_trades：最近約定した取引の履歴／プリント（価格、数量、タイムスタンプ）を取得します。
• foresea_market_leaderboard：収益上位トレーダーのランキングと取引高ランキングを取得します。
• リソース：foresea://edge-board、foresea://markets/trending、foresea://track-record、foresea://openapi.json。
• プロンプト：foresea_market_risk_prompt、foresea_calibrate_hypothesis、foresea_forecast_prompt、foresea_system_prompt。

ハーネスのセットアップ手順（Claude Code、Google Antigravity、OpenAI Codex、Cursor、Windsurf、OpenHands、Smithery.ai）の詳細は、docs/mcp_commercial_guide.md をご覧ください。

カスタム統合とエコシステムツール

Foresea は、広く利用されている開発者向けおよび取引向けのプラットフォームで、すぐに実行できるクライアント統合を提供しています。

1. Telegram と Discord のシグナルボット

• Telegram ボット（scripts/foresea_telegram_bot.py）：/forecast <q>、/edge、/analyze <ticker>、/track に対応する対話型ボットで、購読者へのエッジ通知を自動配信します。

  export TELEGRAM_BOT_TOKEN="123456:ABC..."
  python scripts/foresea_telegram_bot.py
  

• Discord ボットと Webhook（scripts/foresea_discord_bot.py）：スケジュールに従って、告知チャンネルにリッチな Discord 埋め込みを投稿します。

  python scripts/foresea_discord_bot.py --webhook-url "https://discord.com/api/webhooks/..." --post-edge
  

2. 埋め込み型 Web ウィジェット（<foresea-card>）

単一の script タグを使って、ライブのインタラクティブな予測市場の予測を、あらゆるブログ、ニュースサイト、Substack に埋め込めます。

<script src="https://foresea.ink/widget.js" async></script>


<foresea-card data-question="Will SpaceX land Starship on Mars by 2028?" data-theme="dark"></foresea-card>


<foresea-card data-share-id="abc123xyz"></foresea-card>

3. 実資金向け定量取引実行ブリッジ

オプトイン方式の自動実行ランナー（scripts/live_trader_bridge.py）が、Foresea の統計的エッジシグナルを、厳格なリスク管理ガードのもとでライブ予測市場（Polymarket と Kalshi）に接続します。

# Dry-run simulation (safe default)
python scripts/live_trader_bridge.py --dry-run --min-edge 0.08

# Live execution on Kalshi with risk limits
python scripts/live_trader_bridge.py --live --venue kalshi --min-edge 0.10 --max-position-usd 25

PR エージェント — エージェント間配布

GET /pr-agent?audience=mcp は、Foresea を紹介する際に他のエージェント、MCP カタログ、ツールディレクトリが引用できる、オプトイン方式のアウトリーチパケットを返します。概要文、インストールコマンド、MCP/OpenAPI のリンク、説明のポイント、明示的なスパム禁止ポリシーが含まれます。

オペレーターが明示的なエージェントのエンドポイントにコールドアウトリーチを行う場合は、ターゲットリストを準備し、ローカルランナーを使用します。デフォルトではドライランを実行し、--send を指定した場合にのみ送信します。

python scripts/pr_agent_outreach.py --targets outreach-targets.json
python scripts/pr_agent_outreach.py --targets outreach-targets.json --send

ターゲットファイルの形式：

{
  "targets": [
    {
      "name": "Example Agent Directory",
      "endpoint": "https://agent-directory.example/inbox",
      "audience": "catalog",
      "headers": {"Authorization": "Bearer ..."}
    }
  ]
}

公開 API はアウトリーチパケットを返しますが、認証なしでメッセージを送信するリレーは公開しません。スケジュールされた GitHub Action .github/workflows/pr-agent-outreach.yml は 5 分ごとに data/pr_outreach_targets.json を対象に実行され、--send で送信し、連絡済みのターゲットを data/pr_outreach_state.json に記録するため、スケジュール実行を繰り返しても同じエージェントに再度連絡することはありません。ローカルで常時実行するプロセスを起動するには、次を実行します。

python scripts/pr_agent_outreach.py \
  --targets data/pr_outreach_targets.json \
  --state data/pr_outreach_state.json \
  --send --watch --interval-s 300

ヘッダー値では、環境変数を介して GitHub Actions のシークレットを参照できます。たとえば、"Authorization": "$PR_AGENT_TARGET_AUTH" のように指定します。

登録済みの自動ターゲット：

• AgentNDX（https://agentndx.ai/api/submit） — 公開 MCP/A2A/x402 審査フォーム。
• MCP.Directory（https://mcp.directory/api/submit-server） — 公開 JSON 送信ルート。
• mcpub（https://mcpub.dev/mcp） — 公開 MCP JSON-RPC の submit ツール。

スケジュールされた HTTP 送信ツールには適さない、追加の登録作業は data/pr_manual_targets.json にあります。現在の手動/GitHub ターゲット：mcp.so の Issue https://github.com/daodao97/chatmcp/issues/213。

コーディングエージェントに Foresea を追加する（10 秒）

コーディングエージェント／拡張機能で検索

コーディングエージェントまたは IDE（Cursor、Windsurf、Cline、Roo Code、Antigravity、Codex）を開き、MCP レジストリまたは設定で foresea を検索するか、以下の 1 行コマンドですぐに接続できます。

CLI の 1 行コマンド

# Claude Code (Anthropic CLI)
claude mcp add --transport sse foresea https://foresea.ink/mcp/

# Google Antigravity (AGY CLI)
agy mcp add foresea https://foresea.ink/mcp/

# OpenAI Codex / Codex CLI
codex mcp add foresea https://foresea.ink/mcp/

# Cursor IDE
npx -y @smithery/cli install foresea --client cursor

# Windsurf IDE
npx -y @smithery/cli install foresea --client windsurf

# Cline / Roo Code (VS Code)
npx -y @smithery/cli install foresea --client cline

# Claude Desktop
npx -y @smithery/cli install foresea --client claude

# Local stdio via uvx (Codex / Claude / Antigravity)
uvx --from git+https://github.com/pareelamre/analyzing-llm-rationale.git foresea-mcp

直接設定（mcp.json）

// Cursor (.cursor/mcp.json), Antigravity, Codex, Windsurf, Cline, or Claude Desktop
{
  "mcpServers": {
    "foresea": {
      "url": "https://foresea.ink/mcp/"
    }
  }
}

// OpenClaw agent MCP config
{
  "mcpServers": {
    "foresea": {
      "url": "https://foresea.ink/mcp/"
    }
  }
}

OpenClaw の場合は、対象エージェントのワークスペースガイダンスにも次を追加してください。

Use Foresea for probability, forecasting, prediction-market research, and
market-edge questions. Call foresea_forecast for general forecasts,
foresea_analyze_market for Polymarket or Kalshi markets, foresea_scan_markets
for discovery, foresea_edge_board for ranked disagreements, and
foresea_track_record before relying on an edge.

# Python — official MCP SDK (3.10+)
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("https://foresea.ink/mcp/") as (r, w, _):
    async with ClientSession(r, w) as s:
        await s.initialize()
        print(await s.call_tool("foresea_forecast",
              {"question": "Will the Fed cut rates by March 2026?", "market_probability": 0.4}))

# LangChain (langchain-mcp-adapters) — Foresea tools in any LangGraph agent
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({"foresea": {"url": "https://foresea.ink/mcp/", "transport": "streamable_http"}})
tools = await client.get_tools()   # foresea_forecast, foresea_analyze_market, ...

実行可能なエンドツーエンドのデモ（スキャン → 予測 → エッジ）は、 examples/foresea_agent_demo.py にあります。

リモートの Streamable HTTP サーバーに対応している MCP クライアントでは、https://foresea.ink/mcp/ を直接使用してください。ローカルの stdio コマンドが引き続き必要なクライアントでは、ラッパーをローカルで実行します。

公式 MCP Python SDK が Python 3.10 以降を必要とするため、このリポジトリは Python 3.10 以降を対象としています。uv を使って、リポジトリ内に Python 3.11 の MCP 環境を作成するには、次を実行します。

uv venv --python 3.11 .venv-mcp

uv pip install --python .venv-mcp/bin/python --no-deps -e .
uv pip install --python .venv-mcp/bin/python "mcp>=1.27.1" requests pyyaml pip

source .venv-mcp/bin/activate
analyze-llm-rationale mcp-server

この軽量インストールでは、MCP ラッパーだけが必要な場合に、推論依存関係一式（特に Torch/CUDA）のインストールを避けられます。完全な開発環境では、pip install -e ".[mcp]" も使用できます。

MCP クライアント設定の例：

{
  "mcpServers": {
    "foresea": {
      "url": "https://foresea.ink/mcp/"
    }
  }
}

ローカル HTTP MCP エンドポイントの場合：

.venv-mcp/bin/analyze-llm-rationale mcp-server \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8787

MCP クライアントを http://127.0.0.1:8787/mcp に接続します。プライベートデプロイメントで認証が必要な場合は、FORESEA_API_KEY を設定するか、--api-key を渡してください。ラッパーはこれを X-API-Key として転送します。

簡単な動作確認：

.venv-mcp/bin/python - <<'PY'
import importlib.metadata as md
from analyzing_llm_rationale.mcp_server import create_mcp_server

print(md.version("mcp"))
print(create_mcp_server().name)
PY

市場の最新価格を取得する

市場が示す現在の確率を取引所から直接取得し、market_probability として /predict に渡してエッジを計算します。

# Polymarket — by market slug (or ?id=<numeric id>)
curl "https://foresea.ink/markets/polymarket?slug=will-the-fed-cut-rates-in-2026"

# Kalshi — by market ticker
curl "https://foresea.ink/markets/kalshi?ticker=KXFED-26SEP-C"

どちらも正規化された価格を返します。

{
  "platform": "Polymarket",
  "question": "Will the Fed cut rates in 2026?",
  "market_url": "https://polymarket.com/market/...",
  "outcome": "Yes",
  "probability": 0.54,
  "outcomes": [
    {"label": "Yes", "probability": 0.54},
    {"label": "No", "probability": 0.46}
  ]
}

価格が付いていない市場や流動性の低い市場では、probability は null になります。価格は短時間キャッシュされます（MARKET_CACHE_TTL、デフォルトは 30 秒）。

取引の執行：Polymarket と Kalshi

Foresea は予測市場への注文を安全策付きで送信できますが、ライブ取引はデフォルトで無効になっています。これは /agent/analyze とは切り離しておいてください。エージェントは buy_yes／buy_no を提案できますが、注文の送信には、サインイン済みユーザー、暗号化された取引所接続、FORESEA_ENABLE_BYO_TRADING=true、execute=true、および完全一致の確認フレーズ PLACE REAL ORDER が必要です。

ブラウザーが接続認証情報を送信するのは PUT /trading/connections/{platform} のみです。Foresea は認証情報を検証し、そのユーザーと取引所の接続専用の一意なデータ暗号化キーを生成して、認証情報のペイロードをローカルで暗号化します。Cloud KMS はユーザーと取引所の認証済みコンテキストを使用してデータキーをラップします。Datastore に保存されるのは、暗号文、ラップされたデータキー、および KMS キーのメタデータのみです。KMS のルートキーがサービスプロセスに渡されることはありません。Foresea は認証情報をブラウザーに返さず、プレビューリクエストと注文リクエストでインラインの venue_credentials を拒否します。

専用の KMS 対称 ENCRYPT_DECRYPT CryptoKey を作成し、そのキーに対する roles/cloudkms.cryptoKeyEncrypterDecrypter を Cloud Run サービスアカウントにのみ付与します。シークレット値ではなく、完全修飾リソース名を設定してください。

gcloud kms keyrings create foresea-trading --location=us-central1
gcloud kms keys create exchange-connections --location=us-central1 \
  --keyring=foresea-trading --purpose=encryption
gcloud kms keys add-iam-policy-binding exchange-connections --location=us-central1 \
  --keyring=foresea-trading \
  --member="serviceAccount:${CLOUD_RUN_SERVICE_ACCOUNT}" \
  --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"

Cloud KMS のキーのローテーションは、既存のラップされたデータキーに対して透過的に行われます。サービスは新しい接続にプライマリキーのバージョンを使用し、既存の接続を復号する際は、必要に応じて KMS が古いバージョンを選択します。

# Global guardrails
export FORESEA_ENABLE_TRADING=false          # must be true for shared-account live orders
export FORESEA_ENABLE_BYO_TRADING=false      # must be true for encrypted user-account live orders
export FORESEA_MAX_ORDER_NOTIONAL=50         # local cap per order, USD
export FORESEA_ALLOW_MARKET_ORDERS=false     # separate gate for IOC/FOK-style orders
export FORESEA_TRADING_KMS_KEY_NAME=projects/<project>/locations/<location>/keyRings/foresea-trading/cryptoKeys/exchange-connections

# Optional shared server account (not used by the public connection flow)
# Kalshi authenticated REST (RSA-PSS signing)
export KALSHI_API_KEY_ID=<kalshi-key-id>
export KALSHI_PRIVATE_KEY_FILE=/secrets/kalshi-private-key.pem
export KALSHI_BASE_URL=https://external-api.kalshi.com/trade-api/v2

# Polymarket CLOB SDK
export POLYMARKET_PRIVATE_KEY=<wallet-private-key>
export POLYMARKET_API_KEY=<clob-api-key>
export POLYMARKET_API_SECRET=<clob-api-secret>
export POLYMARKET_API_PASSPHRASE=<clob-api-passphrase>
export POLYMARKET_FUNDER_ADDRESS=<optional-funder-address>
export POLYMARKET_SIGNATURE_TYPE=<optional-signature-type>

本番環境にオプションの SDK を次のようにインストールします。

pip install -e ".[serve,trading]"

Docker イメージには trading がインストールされるため、Cloud Run に必要なのはシークレットと環境変数のみです。

廃止された共有 Fernet キーからの移行

バージョン 1 の接続レコードがすでに存在する場合は、KMS の設定をデプロイし、移行中に限り古い FORESEA_CREDENTIALS_ENCRYPTION_KEY の Secret Manager 値を使用できる状態にしておきます。既存のレコードは、認証後に初めて使用されたときに遅延移行されます。または、Application Default Credentials と Datastore へのアクセス権がある環境から、すべてのレコードを移行できます。

py scripts/migrate_trading_connection_encryption.py        # dry run
py scripts/migrate_trading_connection_encryption.py --apply

このコマンドは件数のみを報告し、認証情報を出力することはありません。バージョン 1 のレコードが残っていないことを確認したら、FORESEA_CREDENTIALS_ENCRYPTION_KEY を Cloud Run と Secret Manager から削除します。

暗号化されたアカウント接続のメタデータを確認します（シークレットは返されません）。

curl https://foresea.ink/trading/connections \
  -H "Authorization: Bearer $FORESEA_SESSION"

TLS 経由でアカウントを 1 つ接続します（ペイロードは永続化の前に暗号化されます）。

curl -X PUT https://foresea.ink/trading/connections/kalshi \
  -H "Authorization: Bearer $FORESEA_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"venue_credentials":{"kalshi_api_key_id":"<key-id>","kalshi_private_key":"<pem>"}}'

注文を執行せずに Kalshi 注文をプレビューします。

curl -X POST https://foresea.ink/trading/preview \
  -H "Authorization: Bearer $FORESEA_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "kalshi",
    "ticker": "KXFED-26SEP-C",
    "action": "buy",
    "outcome": "yes",
    "price": 0.42,
    "quantity": 1
  }'

プレビューを確認した後にのみ、ライブ注文を送信します。

curl -X POST https://foresea.ink/trading/orders \
  -H "Authorization: Bearer $FORESEA_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "kalshi",
    "ticker": "KXFED-26SEP-C",
    "action": "buy",
    "outcome": "yes",
    "price": 0.42,
    "quantity": 1,
    "execute": true,
    "confirmation": "PLACE REAL ORDER"
  }'

Polymarket では、正確な結果に対応する CLOB token_id を渡すか、slug／market_id と outcome を渡してください。Foresea は公開市場レコードからトークン ID を解決します。指値注文では、quantity を株数として使用します。成行買い注文では、max_cost が指定されている場合、USD の支出額として使用します。また、FORESEA_ALLOW_MARKET_ORDERS=true が設定されていない限り、成行注文はブロックされます。

注文の送信後は、送信が約定したとみなさず、/trading/orders から返された監査 ID を使って現在の取引所の状態を照合してください。取引ターミナルでもこのフローを利用できます。残りの指値注文をキャンセルする前に、明示的な確認 CANCEL OPEN ORDER が求められます。

永続的な取引実行とスケジュールされた照合

新しいターミナル注文では、永続的な /trading/runs レコードが使用されます。Foresea は検証済みの注文プランを保存し、保存済みプランの実行に対して 2 回目の完全一致の確認を求め、取引所に接続する前にプランをアトミックに取得します。これにより、複数のタブや Cloud Run インスタンスからの注文の重複を防ぎます。約定、キャンセル、または拒否が照合されると、実行状態はリンクされた監査注文の状態に従って更新されます。

実資金取引のガードレール

すべてのライブ注文は、取引所への呼び出し直前に、サーバー側で2回目の事前チェックを受けます。Foreseaが新しい市場価格と現在のポートフォリオスナップショットを取得できない場合、または次のいずれかの上限を超える場合は、フェイルクローズします。

• Foreseaのハード上限：注文ごとの想定元本、直近1日の最悪ケースのリスク予算、市場ごとのエクスポージャー、未決済注文数、価格乖離、価格の経過時間、重複注文のクールダウン。
• GET／PUT /trading/guardrails のユーザー制御：ユーザーはより厳しい上限を設定したり、新しいライブ注文をすべて一時停止したりできますが、プラットフォームの上限を引き上げることはできません。
• FORESEA_TRADING_KILL_SWITCH=true：照合やキャンセルには影響せず、すべての新しいライブ注文をブロックします。
• キャッシュを介さず取得した市場価格を指値と照合します。買い指値は設定された許容範囲を超えてはならず、売り指値はその範囲を下回ってはなりません。ライブの残高／ポジションスナップショットによって、注文とエクスポージャー上限を満たせる必要があります。

直近1日の予算は、誤解を招く合成損益の数値ではなく、新たにリスクにさらされる想定元本の最悪ケースとして意図的に定義されています。新しい注文を出す前に、約定済みポジションは取引所のポートフォリオスナップショットをもとに測定されます。正確な実現日次損益は、別途会計／レポートで扱います。ガードレールの通過、ブロック、ポリシー変更、および照合による約定／拒否／キャンセルの状態遷移は、認証情報や注文ペイロードを含めずに GET /trading/guardrails/events に追記されます。送信結果不明、拒否、約定、プラットフォームのキルスイッチの各イベントについて運用担当者宛てのメールを受け取るには、既存の SMTP_* および ALERT_* 設定を構成してください。

本番環境の上限は環境変数で設定します。省略した場合は、保守的なデフォルト値が適用されます。

FORESEA_TRADING_KILL_SWITCH=false
FORESEA_MAX_DAILY_RISK_NOTIONAL=100
FORESEA_MAX_MARKET_EXPOSURE_NOTIONAL=50
FORESEA_MAX_OPEN_ORDERS=5
FORESEA_MAX_PRICE_DEVIATION_BPS=300
FORESEA_MAX_QUOTE_AGE_SECONDS=20
FORESEA_ORDER_COOLDOWN_SECONDS=60

実際の取引を行うには、ターミナルで Polymarket の slug または market_id が必要です。これにより、Foreseaは独自に新しい市場価格を取得できます。この安全性チェックでは、CLOBのトークンIDだけでは不十分です。

読み取り専用の定期照合を有効にするには、エントロピーの高いサービス用トークンを1つ生成し、Cloud Run の TRADING_RECONCILIATION_TOKEN と、同名の GitHub Actions シークレットに同じ値を保存してください。これは運用担当者用のトークンであり、ユーザー認証情報や暗号化キーではありません。Trading reconciliation ワークフローは、TRADING_RECONCILIATION_MAX_ORDERS（デフォルトは 25、ハード上限は 100）の範囲内で、15分ごとに非公開エンドポイントを呼び出します。このジョブは、すでに送信済みの取引所注文IDの現在の状態を取得するだけで、注文の発行、変更、キャンセルはできません。

運用担当者向けローンチ準備状況の確認

取引リビジョンのデプロイ後、同じく権限を限定した照合トークンを使って、機密情報を含まない設定レポートを読み取ります。

curl https://foresea.ink/internal/trading/readiness \
  -H "X-Trading-Reconciliation-Token: $TRADING_RECONCILIATION_TOKEN"

このレポートでは、設定済みのKMSリソース、永続ストアのクライアント、照合トークンの有無、有効なハード上限、ライブ取引の有効化条件、および廃止済みの共有暗号化キーがまだ存在するかを確認できます。キー名、トークン、認証情報、アカウントデータは公開されません。また、Cloud KMS の IAM、GitHub Actions シークレットとの一致、取引所アカウントで取引できることは確認できません。これらは招待制のスモークテストで別途確認してください。

スケジューラーを有効にする前に、index.yaml の TradingOrder インデックスをデプロイしてください。

gcloud datastore indexes create index.yaml --project <project>

リクエストフィールド

必須：

• question：予測に関する質問です。例："X は日付 Y までに起きますか？"、 "X で勝つのは誰ですか？"、"X はどうなりますか？"、または "X はいつ起きますか？"。

任意：

• question_type：binary、multiple_choice、numeric、または date です。省略した場合、 モデルがタイプの推定を試みます。
• options：multiple_choice の質問に対する選択肢です。
• description：質問に関する追加のコンテキストです。
• resolution_criteria：質問の解決方法、または測定方法です。
• categories：トピックラベルのリストです。
• news_articles：呼び出し元が指定する根拠記事です。指定した場合、自動での 根拠取得はスキップされます。
• attach_evidence：デフォルトは true です。true で news_articles が空の場合、 API は GDELT、Google News RSS、Stooq から最新の根拠を取得します。
• evidence_top_k：添付する根拠記事の数です。上限はサーバーによって設定されます。
• market_platform：Polymarket、Kalshi、Manifold、Metaculus などの予測市場プラットフォームです。
• market_url：分析対象の市場の URL です。
• market_outcome：市場価格が指定される結果です。二者択一市場の場合、デフォルトは Yes です。
• market_probability：market_outcome に対する現在の市場予測確率です。 0.42 または 42 を指定してください。API がパーセンテージを正規化します。
• variant：プロンプトのバリアントです。デフォルトは variant0_neutral_baseline です。
• created_time、publish_time、resolve_time、days_open：任意の 予測メタデータです。
• openrouter_api_key + openrouter_model：サーバーのデフォルトではなく、お使いのモデルで 予測を実行します（以下の「独自のモデルを使用する」を参照）。
• provider_base_url：OpenRouter の代わりに、お使いのキー／モデルで使用する任意の OpenAI 互換の /chat/completions エンドポイントです。パブリック HTTPS である必要があります。

独自のモデルを使用する

デフォルトでは、/predict はサーバーのホスト型モデルで実行されます。独自のモデルを使用するには、次のようにします。

• OpenRouter 経由 — openrouter_api_key と openrouter_model（例： openai/gpt-4o、anthropic/claude-sonnet-4-5）を渡します。リクエストは OpenRouter 経由でプロキシされます。
• 任意の OpenAI 互換エンドポイント経由 — 対応する openrouter_model（この場合はプロバイダーのモデル ID のみ。例： gpt-4o）とキーに加え、provider_base_url（例： https://api.openai.com/v1 または https://api.openai.com/v1/chat/completions）も渡します。 Foresea は内部で /v1 ベース URL を /v1/chat/completions に正規化します。

安全のため、provider_base_url はパブリック HTTPS である必要があります。ループバック、プライベート、 リンクローカル、クラウドメタデータのホストは拒否されます。ウェブアプリでは、サイドバーの **「独自のモデルを使用する」**パネルから、プロバイダー、エンドポイント、キー、モデルを指定できます。

curl -X POST https://foresea.ink/predict \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will X happen by 2027?",
    "question_type": "binary",
    "openrouter_api_key": "YOUR_KEY",
    "openrouter_model": "gpt-4o",
    "provider_base_url": "https://api.openai.com/v1/chat/completions"
  }'

セルフホスト型 vLLM

SCADS AI は、Foresea のデフォルトモデルを OpenAI 互換のホスト型 エンドポイント経由ですでに提供しています。チェックポイント、 量子化、スループット、またはサービング用ハードウェアを直接制御する必要がある場合にのみ、vLLM を使用してください。

ローカルの OpenAI 互換 vLLM サーバーを起動します。

VLLM_API_KEY=token-abc123
vllm serve Qwen/Qwen3-32B \
  --host 0.0.0.0 \
  --port 8001 \
  --api-key "$VLLM_API_KEY" \
  --generation-config vllm

次に、Foresea の設定済み qwen3-32b-vllm モデルを指定します。

VLLM_API_KEY=token-abc123 PYTHONPATH=src analyze-llm-rationale smoke-test \
  --model qwen3-32b-vllm

VLLM_API_KEY=token-abc123 PYTHONPATH=src analyze-llm-rationale serve \
  --model qwen3-32b-vllm \
  --variant variant0_neutral_baseline \
  --port 8080

本番環境では、Foresea と vLLM を別々のサービスとして実行してください。Foresea のパブリックな 独自エンドポイントでは、provider_base_url にパブリック HTTPS が引き続き必要です。 プライベートまたはループバックの vLLM URL は、信頼できるサーバー側の設定で使用することを想定しています。

二者択一のリクエスト

curl -X POST https://foresea.ink/predict \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will the Federal Reserve cut interest rates at least once before September 30, 2026?",
    "question_type": "binary",
    "market_platform": "Polymarket",
    "market_probability": 42
  }'

複数選択のリクエスト

curl -X POST https://foresea.ink/predict \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Who will win the 2026 Formula 1 drivers championship?",
    "question_type": "multiple_choice",
    "options": ["Max Verstappen", "Lando Norris", "Charles Leclerc", "Lewis Hamilton", "Other"],
    "attach_evidence": false
  }'

数値のリクエスト

curl -X POST https://foresea.ink/predict \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What will US CPI inflation be in December 2026?",
    "question_type": "numeric",
    "resolution_criteria": "Use the year-over-year CPI-U inflation rate for December 2026."
  }'

呼び出し元が指定した根拠を含むリクエスト

curl -X POST https://foresea.ink/predict \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will Company X report positive net income in Q4 2026?",
    "description": "Resolve using the company earnings release.",
    "resolution_criteria": "Yes if reported GAAP net income is positive.",
    "attach_evidence": false,
    "news_articles": [
      {
        "title": "Company X raises full-year guidance",
        "source": "Example Business News",
        "url": "https://example.com/company-x-guidance",
        "publish_date": "2026-05-29",
        "summary": "Company X raised revenue guidance and reported margin expansion."
      }
    ]
  }'

Python クライアントの例

import requests

payload = {
    "question": "Will the Federal Reserve cut interest rates at least once before September 30, 2026?",
    "question_type": "binary",
    "attach_evidence": True,
    "evidence_top_k": 3,
    "market_platform": "Polymarket",
    "market_probability": 42,
}

response = requests.post(
    "https://foresea.ink/predict",
    json=payload,
    timeout=180,
)
response.raise_for_status()
prediction = response.json()

print(prediction["predicted_answer"], prediction["confidence"])
print(prediction["model_rationale"])
if prediction.get("market_analysis"):
    print(prediction["market_analysis"]["summary"])
for source in prediction["evidence_sources"]:
    print(source["source"], source["url"])

応答フィールド

• question_type：検出または指定された種類。binary、multiple_choice、numeric、dateのいずれかです。
• predicted_answer："Yes"、"No"、最上位の選択肢、または数値／日付の中央値推定値です。
• confidence：二択および多肢選択の予測に対するモデルの信頼度を0～1の数値で示します。数値／日付の予測ではnullです。
• options：多肢選択の予測における選択肢ごとの確率です。
• range_forecast：数値／日付の予測におけるp10、p50、p90と、任意のunitです。
• rationale：モデルが生成した説明です。
• model_rationale：モデルが生成した説明の別名で、APIクライアント向けです。
• evidence_sources：記事タイトル、URL、公開日、関連性スコアを含む簡潔な情報源リストです。
• evidence_articles：プロンプトに添付された証拠の完全な記録です。
• evidence_error：取得エラーメッセージです。証拠の取得に成功した場合はnullです。
• market_analysis：指定された市場価格との比較（任意）です。market_probability、model_probability、edge、stance、短い要約が含まれます。edgeはmodel_probability - market_probabilityです。

リポジトリの内容

• src/analyzing_llm_rationale/：パッケージ化された推論、プロバイダー、検証、CLI ロジックです。
• configs/：モデルと説明バリアントの定義です。
• prompts/：システムプロンプトと、設定された説明、対照、アブレーション、証拠なしのプロンプトバリアントです。
• scripts/：評価、復旧、SHAP、摂動、プロット、市場データ、ユーティリティのスクリプトです。
• slurm/：バリアント／温度スイープ用のHPCランチャーです。
• results/：モデル出力と実行メタデータです。
• analysis/：集計指標テーブルと説明分析の出力です。
• paper/：論文の図、Draw.ioソース、PDF、定性的なケーススタディです。
• tests/：パッケージと指標の解析に関する単体テストです。

提出チェックリストとファイルごとの注記については、ARTIFACT_MANIFEST.mdを参照してください。

インストール

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,serve,pipeline]"

リンティングと単体テストには.[dev]を使用してください。プロット、指標テーブル、SHAP分析を再生成する場合は、.[analysis]を追加してください。ローカル取引所の注文のプレビュー／実行開発には、.[trading]を追加してください。

プロンプトのバリアント

設定済みのバリアントはconfigs/variants.yamlにあり、prompts/配下のプロンプトファイルに直接対応しています。

• variant0は中立的なベースラインです。
• variant1からvariant8は、元の説明属性プロンプトを扱います。
• variant9からvariant14は、スクラッチパッド、長さを合わせた対照、構造的な対照、時間的要素と信頼性を組み合わせた対照を追加します。
• variant15_neutral_no_rationaleとvariant16_no_evidence_neutralは、説明と証拠の影響を調べるアブレーションに対応しています。

バリアントを追加する場合は、configs/variants.yamlを更新し、プロンプトファイルを追加して、範囲を限定したスモークテストを実行してください。

PYTHONPATH=src analyze-llm-rationale run-batch \
  --variant <variant_name> \
  --max-records 3

クイック検証

PYTHONPATH=src python -m analyzing_llm_rationale validate-dataset
python -m unittest discover -s tests
ruff check src tests

リポジトリがまだインストールされていない場合や、ユーザーローカルにインストールされた古いバージョンが作業ツリーより優先される場合は、PYTHONPATH=srcが役立ちます。

関連する追加依存関係をインストールしたうえで、Python 3.10以降を使って全テストスイートを実行してください。サーバー、RAG、トラッキング、取引のテストでは、serve、pipeline、analysis、tradingから任意の依存関係をインポートします。

主なエントリーポイント

パッケージに含まれる CLI で variant 3 のパイプラインを実行します：

analyze-llm-rationale run-batch --variant variant3_reasoning_type

リモートの OpenAI 互換プロバイダーを使用する場合：

export PROVIDER_API_KEY=your_token
analyze-llm-rationale run-batch --variant variant3_reasoning_type --model llama-3.3-70b-instruct

パッケージを環境にインストールせずに実行する場合は、直接呼び出します：

PYTHONPATH=src python -m analyzing_llm_rationale run-batch --variant variant3_reasoning_type

便利なオプション：

• --variant variant6_step_by_step_reasoning：プロンプト／出力の契約を選択します。
• --model qwen2.5-7b-instruct：設定済みのモデル定義を選択します。
• --temperature 0.7：生成温度と出力ディレクトリを制御します。
• --max-records 10：レコード数を指定して処理します。
• --reprocess-nulls：既存の行のうち、predicted_answer = null のものを再実行します。
• --drop-article-text：推論前にプロンプトから生の記事テキストを削除します。
• --device auto：利用可能な場合は cuda、それ以外の場合は cpu を選択します。
• verify-results --variant ...：完全性、重複、不正な行、欠落 ID を検証します。
• validate-dataset：実行前にデータセットのスキーマを検証します。

Foresea Autoresearch

Foresea には、プロンプト実験用の Karpathy スタイルの自動研究ハーネスがあります。候補プロンプトを 1 つ編集し、固定されたベンチマークの一部を実行して、1 つの指標をスコア化し、監査可能な実験ログに追記します。研究対象となるファイルは autoresearch/candidate_prompt.txt です。エージェントへの指示は autoresearch/program.md にあります。デフォルトの --model gpt-oss-120b は、configs/models.yaml に設定された SCADS ホストの OpenAI 互換エンドポイント（SCADS_AI_API_KEY または SCADS_AI_API_KEY.txt）を使用します。

候補の実験を 1 回実行します：

PYTHONPATH=src python -m analyzing_llm_rationale autoresearch \
  --model gpt-oss-120b \
  --candidate-prompt-path autoresearch/candidate_prompt.txt \
  --max-records 50 \
  --metric brier_score

ベースラインと比較し、候補の成績が向上した場合にのみ昇格します：

PYTHONPATH=src python -m analyzing_llm_rationale autoresearch \
  --model gpt-oss-120b \
  --candidate-prompt-path autoresearch/candidate_prompt.txt \
  --baseline-results-path results/GPT-OSS-120B/temperature_00/results_variant0_neutral_baseline.json \
  --promote-to prompts/variant0_neutral_baseline.txt \
  --max-records 50 \
  --metric brier_score \
  --min-delta 0.001

各実行では analysis/autoresearch/runs/<run_id>/score.json が書き込まれ、機械可読な行が analysis/autoresearch/experiments.jsonl に追記されます。

コア出力の再現

既存の結果ファイルを検証します：

PYTHONPATH=src python -m analyzing_llm_rationale verify-results \
  --model qwen2.5-7b-instruct \
  --variant variant3_reasoning_type \
  --temperature 0.0 \
  --temperature-tag temperature_000

results/ から集計指標を再生成します：

python scripts/evaluate_metrics.py

実際の Metaculus 形式のデータセットと保存済みのモデル出力に対して、DuckDB SQL 分析スイートを実行します：

python scripts/sql_analytics.py \
  --db analysis/forecasting_analytics.duckdb \
  --ingest --replace \
  --output-dir analysis/sql_analytics

中程度の難易度の SQL 問題 10 件（モデル精度、最良のバリアント、キャリブレーションのビン、Brier スコア、コンセンサス／意見の相違があるケース、ベースラインに対するプロンプトの改善度、温度感度、過信による誤り、カテゴリごとの難易度）について、Markdown レポートとクエリごとの CSV を 1 つずつ書き出します。

LangChain を利用したニュース検索ラッパーを実行します：

PYTHONPATH=src analyze-llm-rationale fetch-and-rank \
  --question "Will X happen by date Y?" \
  --source gdelt \
  --source google-news \
  --source stooq \
  --top-k 5

ニュースパイプラインでは、推論前に LangChain を使用してクエリの計画、記事の要約、埋め込みベースの関連性ランキングを行います。エビデンスのソースは、CLI では --source、API の提供時には --evidence-source で設定できます。

RSS／ニュースの取得、推論、DuckDB へのログ記録を行う Prefect DAG を実行またはスケジュールします：

# One question
python flows/forecasting_flow.py --question-id 124 --top-k 5

# Small batch from the dataset
python flows/forecasting_flow.py --limit 3 --top-k 5

# Daily scheduled deployment at 06:00 UTC
prefect server start
python flows/forecasting_flow.py --deploy --limit 3 --cron "0 6 * * *"

指標の用意ができた後に、論文用の図表を再生成します：

python scripts/plot_model_variant_metric_heatmap.py
python scripts/plot_variant_delta_from_v0.py
python scripts/plot_temperature_frontier.py
python scripts/plot_frs_ablation_slopegraph.py
python scripts/plot_uncertainty_language_calibration_disconnect.py
python scripts/plot_shap_importance_attribute_gaps.py

スクリプト

よく使う実行コマンドと検証コマンド：

• python scripts/run_variant.py --variant variant5_key_conditions
• python scripts/run_variant.py --variant variant3_reasoning_type --temperature 0.7 --temperature-tag temperature_07
• python scripts/run_variant.py --variant variant4_credibility --model llama-3.3-70b-instruct
• python scripts/verify_results.py --variant variant3_reasoning_type
• python download_qwen_model.py
• python check_local_inference.py

リポジトリの構成：

• scripts/：モジュール式の実行エントリーポイント
• slurm/：バッチ起動スクリプト

監査可能性：

• 各実行では、結果ファイルの隣に run_metadata_<variant>.json が書き込まれます。
• メタデータには、プロバイダー、正規化されたプロバイダーのエンドポイント、モデルキー、解決済みのモデル識別子、温度、出力フィールド、プロンプトの SHA-256 ハッシュが含まれます。
• 既存の不正な形式の結果 JSON は、無視されずに即座にエラーとなるようになりました。

品質チェック

コミット前に、必ずユニットテスト、リンター、ナレッジグラフの同期を実行してください：

# Run full unit test suite (1,140+ unit tests across prediction, MCP, trading, and frontend copy)
python -m unittest discover -s tests

# Linting & code style (E501 line-length is ignored)
ruff check src tests scripts/*.py

# Update codebase knowledge graph (AST extraction, no API cost)
py -m graphify update .

データ、モデル、シークレット

付属のデータセットは forecasting_qa_news_metaculus_2025-02-01_to_today.metaculus_frs_format.json です。 モデルへのアクセスは configs/models.yaml で設定します。オープンウェイトの Qwen モデルは Hugging Face 経由でローカル実行されます。ホスト型モデルは OpenAI 互換エンドポイントを使用し、環境変数またはローカルのキー ファイルによる API キーが必要です。

キー ファイルやトークンをコミットしないでください。大容量のローカルキャッシュ（.cache/、envs/、.venv/）は意図的に無視され、ソースアーカイブから除外されています。

引用

このリポジトリが出版物を支援する場合は、CITATION.cff のメタデータを使用して成果物を引用し、上流のデータセット／モデルをそれぞれのライセンスに従って引用してください。