分析LLM推理

会议工件，用于研究显式推理指令如何影响LLM在Metaculus风格二元预测问题上的预测行为。代码库包含17种提示变体、一个批量推理运行器、生成的结果表格，以及用于论文图表的绘图/分析脚本。实时Foresea API还支持预测市场情报：类型化预测、证据检索，以及二元和多选市场的模型与市场边缘分析。

实时API

部署在Google Cloud Run上——模型gpt-oss-120b，变体variant0_neutral_baseline：

https://foresea.ink

（该URL在首次推送到main后打印在GitHub Actions部署步骤的输出中。）

# 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根据模型概率和市场隐含概率确定性计算。

Related MCP server: SimpleFunctions

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，之后返回resolved，并带有actual_outcome、resolved_price和prediction_correct。

随时间记录和解析纸面信号：

.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审计已解析的纸面交易在费用后是否为正；trade_ready在达到配置的交易数量、PnL和命中率阈值之前保持为false。使用--dry-run配合--paper-loop预览信号而不写入日志。

生产部署说明

生产环境从自定义域名提供服务：

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 Web客户端ID。

• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET：GitHub OAuth应用凭据。OAuth应用的回调URL必须是站点源（例如https://foresea.ink/）。未设置时，“使用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。

实时跟踪记录

GET /track-record提供公共预测跟踪记录。繁重的tick循环不在Cloud Run上运行：.github/workflows/track-record-tick.yml每小时在GitHub Actions上运行，更新data/track_record_store.json作为事实来源实体存储，将公共聚合写入static/track_record_live.json，并将两个文件提交回main。运行时，Cloud Run从原始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-31b-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构建在GitHub Actions中运行，而非Cloud Build；正常部署路径不需要Cloud Build触发器或暂存桶。

一旦max-instances > 1，为Redis（计费）配置Memorystore并设置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

公共Cloud Run API是最简单的集成目标。它接受预测问题并返回类型化预测、模型推理和可选证据文章。它专为可解析预测构建，而非通用问答。

端点

• GET /health：服务健康检查。

• GET /track-record：公开的实时跟踪记录，回退到静态回测。

• GET /track-record/digest：可分享的实时跟踪记录 Markdown 摘要。

• GET /pr-agent：面向 Foresea 发现的可选代理间外联信息包。

• POST /predict：公开预测端点。

• GET /markets/polymarket：获取实时 Polymarket 报价（见下文）。

• GET /markets/kalshi：获取实时 Kalshi 报价（见下文）。

• POST /agent/analyze：对实时问题执行编排式端到端分析（见下文）。

• GET /agent/scan：扫描交易场所中定价错误的市场，按边际优势排序（见下文）。

• GET /radar：基于实时跟踪记录边际优势面板构建的首页市场工作台。

• POST /analytics/visit：记录页面访问；已登录请求仅关联到不可逆的账户引用。

• POST /analytics/event：记录产品漏斗事件，如 forecast_completed、watchlist_add、share_created 和 digest_sent；已登录事件使用相同的私有引用。

• GET /analytics/events/summary：独立于页面访问汇总产品分析，包括最近 30 天的聚合已认证与匿名归因。

• POST /forecasts/share：创建显式的公开预测分享页面。

• GET /forecast/{share_id}：渲染共享预测而不暴露私有聊天历史。

• GET|PUT|DELETE /trading/connections/{platform}：加密的按用户交易所连接元数据及生命周期管理。

• POST /trading/preview：已认证的试运行订单规范化。

• POST /trading/orders：已认证的实时订单提交，需显式确认。

• 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} 页面。不要在共享预测视图中暴露完整的私有聊天历史。

Agent：自动化智能层

POST /agent/analyze 自主运行整个流水线：解析市场（给定标识符时获取实时 Polymarket/Kalshi 价格）→ 收集证据 + 预测 → 定价边际优势 → 运行任何自定义技能 → 给出建议。它返回一份结构化报告。

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（先前轮次）以支持多轮追问——有历史时，像"为什么？"或"那六月呢？"这样的简短追问会在上下文中得到回答。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（已运行的按序步骤）。

持久的私有 Agent 运行

每次已登录的 POST /agent/analyze 调用（包括流式端点）也会创建一次私有 AgentRun。它保留有界、无秘密的输入快照、生命周期时间线、模型报告以及任何仅审查的交易交接。使用 GET /agent/runs 获取最新的操作员时间线，使用 GET /agent/runs/{run_id} 获取一份完整报告。快照有意排除提供商密钥、浏览器凭据、对话历史和原始自定义技能指令。Agent 运行仅用于研究：即使它有交易交接，也不能创建、设定规模或提交订单；用户仍必须在终端中创建并显式确认持久的 Trade 运行。

复制的 Agent：私有、版本化的研究配方

已登录用户可以从 Agentic 面板复制公开的 Foresea 模型。副本以不可变的版本 1 研究配方形式保存在用户账户下；它仅包含公开的源模型和分析指令——绝不包含源 Agent 的私有上下文、影子账户历史、交易所连接、订单规模或交易权限。使用 POST /agent-profiles/copy 并传入白名单中的 source_agent_id，然后将返回的 agent_profile_id 传递给 POST /agent/analyze。

当选择配置文件时，服务器自行解析配置文件的模型和指令，忽略客户端的 BYOK/提供商/模型覆盖，并强制使用固定的研究流水线（无工具循环或交易工具）。生成的报告返回其配置文件 ID、来源、版本和 research_only 模式以保证可复现性。配置文件可以准备现有的仅审查交易交接，但不能创建或提交交易所订单；已登录用户仍必须在交易终端中创建持久的 Trade 运行并显式确认 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}]}。在 Web 应用中，工作台的**"⚡ 扫描 Polymarket 寻找定价错误的市场"**按钮调用此端点。

MCP 服务器：让 AI Agent 将 Foresea 作为工具调用

Foresea 在以下地址公开远程 MCP 服务器：

https://foresea.ink/mcp/

它在以下地址被广告用于发现：

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

远程 MCP 服务器是公共 API 之上的轻量工具层。它暴露：

• foresea_forecast：调用 POST /predict——生成带证据的校准概率预测。

• foresea_analyze_market：调用 POST /agent/analyze——评估特定的 Polymarket/Kalshi 市场，包含边际优势与论点。

• foresea_scan_markets：调用 GET /agent/scan——扫描按模型与市场分歧排序的实时市场。

• foresea_batch_quotes：调用 GET /market/batch——一次往返获取多市场报价。

• foresea_edge_board：调用 GET /edge-board——按统计边际优势排序的顶级开放交易机会。

• foresea_track_record：调用 GET /track-record——公开的准确率、Brier 分数、ECE 和校准指标。

• 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：获取 Kalshi 或 Polymarket 上最近的已执行交易记录/成交（价格、规模、时间戳）。

• foresea_market_leaderboard：从 Polymarket 获取顶级盈利交易者排行榜和成交量排名。

• foresea_pr_agent：调用 GET /pr-agent——为询问如何描述 Foresea 的 Agent/目录提供简洁文案和安装元数据。

• 资源：foresea://track-record、foresea://pr-agent 和 foresea://openapi.json。

自定义集成与生态系统工具

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>）

通过单个脚本标签将实时交互式预测市场预测嵌入任何博客、新闻网站或 Substack：

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

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

<!-- Embed by Shared Forecast ID -->
<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 Agent——Agent 间分发

GET /pr-agent?audience=mcp 返回一个可选加入的外联信息包，其他 Agent、MCP 目录和工具目录在介绍 Foresea 时可以引用。它包含一句话简介、安装命令、MCP/OpenAPI 链接、谈话要点和明确的反垃圾邮件政策。

对于操作员向显式 Agent 端点进行的冷外联，请准备目标列表并使用本地运行器。它默认试运行，仅在带 --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 中，以便重复的计划运行不会重新联系同一 Agent。对于字面意义上始终运行的本地进程，运行：

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 添加到你的 Agent（10 秒）

它是一个远程、匿名的 Streamable-HTTP 服务器——无需密钥，无需安装。将任何 MCP 客户端指向该 URL：

# Claude Code
claude mcp add --transport http foresea https://foresea.ink/mcp/

// Cursor / Cline / Claude Desktop (mcp.json)
{ "mcpServers": { "foresea": { "url": "https://foresea.ink/mcp/" } } }

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

对于 OpenClaw，还需将以下内容添加到目标 Agent 的工作区指南中：

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 命令的客户端，请在本地运行包装器。

该仓库以 Python 3.10+ 为目标，因为官方 MCP Python SDK 要求如此。要使用 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，并仅授予 Cloud Run 服务账号 roles/cloudkms.cryptoKeyEncrypterDecrypter 对该密钥的权限。配置其完全限定的资源名称，而不是秘密值：

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 只需要 secrets/env vars。

迁移已退役的共享 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 的记录，从 Cloud Run 和 Secret Manager 中移除 FORESEA_CREDENTIALS_ENCRYPTION_KEY。

检查加密的账户连接元数据（不返回任何秘密）：

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

通过 TLS 连接一个账户（负载在持久化之前已加密）：

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 将从公共市场记录中解析 token id。限价订单使用 quantity 作为份额。市价买单在提供 max_cost 时使用 USD 支出，并且除非 FORESEA_ALLOW_MARKET_ORDERS=true，否则保持阻止。

提交后，使用 /trading/orders 返回的审计 ID 来核对当前场所状态，而不是假设提交已成交。交易终端也暴露此流程，包括在取消剩余挂单之前显式的 CANCEL OPEN ORDER 确认。

持久化交易运行和计划对账

新的终端提交使用持久的 /trading/runs 记录：Foresea 保存经过验证的订单计划，要求第二次精确确认才能执行该保存的计划，并在联系场所之前原子地声明它。这可以防止来自并发标签页或 Cloud Run 实例的重复订单。当成交、取消或拒绝被对账时，运行状态跟随关联的审计订单。

真实资金护栏

每次实时提交现在在场所调用之前立即通过第二次服务器端预检。当 Foresea 无法获取新鲜的市场报价和当前投资组合快照，或以下任何限制将被超过时，它失败关闭：

• Foresea 硬上限：每笔订单名义价值、当日最坏情况风险预算、每市场敞口、未完成订单、报价偏差、报价年龄和重复订单冷却时间。

• 用户在 GET/PUT /trading/guardrails 处的控制：用户可以设置更严格的限制或暂停所有新的实时订单，但不能增加平台上限。

• FORESEA_TRADING_KILL_SWITCH=true：阻止每个新的实时提交，而不影响对账或取消。

• 无缓存的市场报价与限价进行检查。买入限价不能高于配置的领口，卖出限价不能低于它。实时余额/持仓快照必须支持订单和敞口上限。

当日预算故意是最坏情况的新风险名义价值，而不是误导性的合成 P&L 数字。已成交头寸在订单前从场所投资组合快照中测量；确切的已实现每日 P&L 仍然是单独的会计/报告问题。护栏通过、阻止、策略更改和对账的成交/拒绝/取消转换被追加到 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 token ID 不足以进行此安全检查。

要启用只读的计划对账器，生成一个高熵服务令牌，并将相同的值存储为 Cloud Run 的 TRADING_RECONCILIATION_TOKEN 和该名称的 GitHub Actions 秘密。这是操作员令牌，不是用户凭据，也不是加密密钥。然后，Trading reconciliation 工作流每 15 分钟调用隐藏端点，受 TRADING_RECONCILIATION_MAX_ORDERS（默认 25，硬最大值 100）限制。该作业仅获取已提交的场所订单 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：预测问题，例如 "Will X happen by date Y?"、"Who will win X?"、"What will X be?" 或 "When will X happen?"。

可选：

• 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：可选的 OpenAI 兼容 /chat/completions 端点，与您的密钥/模型一起使用，而不是 OpenRouter。必须是公共 HTTPS。

自带模型

默认情况下，/predict 在服务器托管的模型上运行。要使用您自己的：

• 通过 OpenRouter — 传递 openrouter_api_key 和 openrouter_model（例如 openai/gpt-4o、anthropic/claude-sonnet-4-5）。请求通过 OpenRouter 代理。

• 通过任何 OpenAI 兼容端点 — 还传递 provider_base_url（例如 https://api.openai.com/v1 或 https://api.openai.com/v1/chat/completions）以及匹配的 openrouter_model（这里只是提供商的模型 ID，例如 gpt-4o）和您的密钥。Foresea 在内部将 /v1 基础 URL 规范化为 /v1/chat/completions。

为了安全，provider_base_url 必须是公共 HTTPS；拒绝环回、私有、链路本地和云元数据主机。在 Web 应用中，侧边栏的 “使用您自己的模型” 面板暴露提供商、端点、密钥和模型。

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 已经通过 OpenAI 兼容的托管端点暴露 Foresea 的默认模型。仅当您需要直接控制检查点、量化、吞吐量或服务硬件时，才使用 vLLM。

启动本地 vLLM OpenAI 兼容服务器：

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 运行变体 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 自动研究

Foresea 有一个 Karpathy 风格的自动研究工具，用于提示实验：编辑一个候选提示，运行固定的基准切片，评分一个指标，并追加可审计的实验日志。研究界面是 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）。

运行一个候选实验：

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

这会为 10 个中等难度 SQL 问题写入一份 Markdown 报告以及每个查询一个 CSV：模型准确率、最佳变体、校准分箱、Brier 分数、共识/分歧案例、提示相对基线的提升、温度敏感性、过度自信错误和类别难度。

运行由 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 现在会快速失败，而不是被静默忽略。

质量检查

python -m unittest discover -s tests
ruff check src tests scripts/*.py

数据、模型和机密

包含的数据集是 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 中的元数据引用该工件，并根据其许可证引用上游数据集/模型。