Foresea Forecasting

Foresea：自主预测市场情报与 LLM 推理依据基准

Foresea（foresea.ink）是一个自主预测市场情报平台和实证研究框架。它整合了对 Polymarket 和 Kalshi 的实时概率预测、统计优势发现、多模型影子交易竞赛、自主的 19 工具 ReAct 执行 Agent，以及公开的 Model Context Protocol（MCP）服务。

该代码仓库还作为一项研究的成果载体，研究显式推理依据指令、证据注入和推理结构如何影响 LLM 在 Metaculus 风格问题上的预测行为和校准能力。

---

📑 目录

• 实时平台与网页视图
• 优势看板与自主影子交易工作台
• 5 分钟加密货币微型市场
• 生产部署与基础设施
• 使用 API 与端点
• Agent：自动化情报层与 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)：非托管的客户端订单预览与执行终端，使用 Cloud KMS 信封加密处理 Polymarket 和 Kalshi 凭据。
• 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 持续评估最先进的大模型与真实世界预测市场的表现，并通过三个专用视图跟踪统计优势、校准准确度和模拟投资组合表现：

1. 实时市场分歧（/edge 或 /edge/markets）

• 实时优势排名：量化 Polymarket 和 Kalshi 上模型预测与实时市场定价之间的统计差异： $$\text{Edge} = P_{\text{model}} - P_{\text{market}}$$
• 仓位规模与建议：计算分数凯利配置，并将可执行交易分类为（buy_yes、buy_no、hold）。
• 校准与结算：依据每小时提交到 static/track_record_live.json 的快照，在市场结算后计算 Brier 分数、期望校准误差（ECE）和领先时间技能。

2. 盯市评估（/edge/mtm）

• 持续投资组合估值：根据实时买卖报价评估模拟持仓，而非仅依赖最终结算。
• 未实现与已实现损益：以机构级视角展示未平仓周期内的交易走势和波动风险敞口。

3. Agentic 自主交易锦标赛（/edge/agentic）

• 多模型锦标赛：评估 8 个作为自主投资组合经理运行的不同大模型：
  • 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（无大模型的共识控制）
• 独立的 $10,000 投资组合：每个模型都以模拟的 $10,000 现金余额起步，并可自主扫描市场、评估订单簿，以及执行立即成交或取消（IOC）模拟订单。
• 权益曲线与周期健康状况：呈现累计收益（再投资 $10,000）、回撤指标、交易日志，以及每小时周期执行健康状况（跟踪服务提供商可用性、Token 预算和交易触发条件）。

5 分钟加密货币市场

src/analyzing_llm_rationale/crypto_5m.py 中的本地加密货币微观市场模型 针对 5 分钟涨跌市场构建，目标是选择性地盈利交易，而不是持续操作。它结合了：

• 收缩漂移对数正态货币性定价，
• 使用 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 K 线数据解析已结束的市场：

.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 审核已解析的模拟交易在扣除 手续费后是否盈利；只有达到配置的交易数量、PnL 和命中率阈值后，trade_ready 才会变为 true。使用 --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 Web 客户端 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 为可选项，仅用于启用由 Agent 登记的市场桥接功能。

默认的定时预测任务严格控制成本：每 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 构建在 GitHub Actions 中运行，而不是在 Cloud Build 中运行；常规部署流程不需要 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 是最简单的集成目标。它接受预测问题，并返回类型化预测、模型依据以及可选的证据文章。它专为可判定结果的预测而设计，并非通用问答服务。

端点与 Web 路由

公共网页视图

• GET /：首页工作台、实时市场雷达和交互式工作流演示。
• GET /chat、GET /chat/{id}：对话式预测工作室，提供流式推理依据和证据。
• GET /edge、GET /edge/markets：实时市场优势看板，提供统计差距排名和 Kelly 仓位规模计算。
• 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 的 Agent 间主动联络数据包，需选择加入。

预测市场与市场数据

• GET /markets/polymarket：获取 Polymarket 实时标准化报价、订单簿和流动性数据。
• GET /markets/kalshi：获取 Kalshi 实时标准化报价、行权价范围和代码元数据。

模型上下文协议（MCP）

• GET /mcp/：公开的远程模型上下文协议（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：提交实时订单，需用户明确进行两步确认。
• GET /trading/portfolio：经认证的余额、未平仓头寸、挂单和成交记录。
• POST /trading/orders/{audit_order_id}/reconcile：核对预测市场订单状态和成交情况。
• DELETE /trading/orders/{audit_order_id}：取消预测市场中的挂单。

Web 应用运行时状态

匿名聊天记录保存在浏览器的 localStorage 中。已登录用户通过 /chat/conversations 同步对话，而心愿单追踪则使用通过 /favorites 和 /favorites/prices 公开的 FavoriteMarket 实体。心愿单摘要由 .github/workflows/favorites-digest.yml 通过 scripts/favorites_digest.py 运行。

预测分享为自愿选择：客户端调用 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（先前轮次）以进行多轮追问——有了历史记录后，系统会结合上下文回答“为什么？”或“那 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 Agent 使用自主式 ReAct（推理 + 行动）循环，动态制定计划、选择工具、进行反思并恢复 JSON 错误：

• 预测与统计优势：

  • 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 运行记录

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

已复制的 Agent：私有、带版本的研究方案

已登录用户可以从 Agentic 看板复制公开的 Foresea 模型。副本会以不可变的第 1 版研究方案保存到用户账户下；其中仅包含公开源模型和分析指令，不会包含源 Agent 的私有上下文、影子账户历史记录、交易所连接、订单规模或交易权限。使用 POST /agent-profiles/copy，并传入允许列表中的 source_agent_id，然后将返回的 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}]}。在 Web 应用中，交易台的 “⚡ 扫描 Polymarket，查找定价错误的市场” 按钮会调用此接口。

MCP 服务：让 AI Agent 将 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：通过一次往返请求获取多个平台的多个市场报价。
• foresea_check_run：检查长时间运行的市场研究任务的后台执行状态。
• foresea_edge_board：按统计优势排序的热门未平仓交易机会。
• foresea_track_record：公开的准确率、Brier 分数、ECE 和校准指标。
• foresea_debate_market：开展多 Agent 对抗式辩论（看涨方 vs. 看跌方 vs. 风险评审）。
• foresea_optimize_portfolio：计算各项未平仓优势的最优 Fractional Kelly 资金分配。
• foresea_feed_latest：结合实时市场优势、Agent 交易和排行榜的实时 Alpha 信息流。
• 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>）

只需添加一个脚本标签，即可将实时交互式预测市场预测嵌入任何博客、新闻网站或 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 agent — 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 秒）

在你的编码 Agent / 扩展中搜索

打开你的编码 Agent 或 IDE（Cursor、Windsurf、Cline、Roo Code、Antigravity、Codex），在 MCP 注册表或设置中搜索 foresea，或者使用下方的单行命令立即连接：

单行 CLI 命令

# 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，还请将以下内容添加到目标 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 命令的客户端，请在本地运行封装程序。

由于官方 MCP Python SDK 有此要求，本仓库以 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

这种轻量安装方式无需拉取完整的推理依赖栈（尤其是 Torch/CUDA），适用于只需要 MCP 封装程序的情况。在完整的开发环境中，也可以使用 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，默认 30s）。

交易执行：Polymarket 和 Kalshi

Foresea 可以提交带保护措施的预测市场订单，但默认禁用实盘执行。请将此功能与 /agent/analyze 分开：Agent 可以建议 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 只需要机密/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：阻止所有新的实盘提交，不影响对账或取消操作。
• 使用无缓存市场报价检查限价。买入限价不得高于配置的价格区间上限，卖出限价不得低于该上限。实盘余额／持仓快照必须能够支持该订单及风险敞口上限。

滚动日预算有意采用新增风险的最大名义金额，而不是容易误导的模拟损益数值。新订单提交前，会根据交易场所的投资组合快照衡量已成交持仓；精确的每日已实现盈亏仍属于单独的会计／报告范畴。防护检查通过、拦截、策略变更，以及已对账的成交／拒绝／取消状态转换，都会追加到 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 不足以完成此安全检查。

要启用只读的定时对账器，请生成一个高熵服务令牌，并将相同的值分别存储为 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] 运行 lint 和单元测试。重新生成绘图、指标表或 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 自动研究

Foresea 提供了一个 Karpathy 风格的自动研究框架，用于提示词实验：编辑一个候选提示词、运行固定的基准数据切片、评估一个指标，并追加可审计的实验日志。研究入口为 autoresearch/candidate_prompt.txt；Agent 指令位于 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

这会生成一份 Markdown 报告，并为 10 个中等难度的 SQL 问题各生成一个 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 现在会立即报错，而不再被静默忽略。

质量检查

提交前务必运行单元测试、代码检查工具和知识图谱同步：

# 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 中的元数据引用该成果，并根据相应许可引用上游数据集和模型。