Análisis del razonamiento de LLM

Artefacto de conferencia para estudiar cómo las instrucciones explícitas de razonamiento afectan el comportamiento de pronóstico de LLM en preguntas de pronóstico binario estilo Metaculus. El código contiene 17 variantes de prompt, un ejecutor de inferencia por lotes, tablas de resultados generadas y scripts de trazado/análisis utilizados para las figuras del artículo. La API en vivo de Foresea también admite inteligencia de mercados de predicción: pronósticos tipados, recuperación de evidencia y análisis de ventaja modelo-vs-mercado para mercados binarios y de opción múltiple.

API en vivo

Desplegada en Google Cloud Run — modelo gpt-oss-120b, variante variant0_neutral_baseline:

https://foresea.ink

(La URL se imprime en la salida del paso de despliegue de GitHub Actions después del primer push a main.)

# 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"
  }'

Cuando attach_evidence es verdadero y no se proporcionan news_articles, /predict obtiene y clasifica noticias relevantes de GDELT, Google News RSS y Stooq por defecto, las inyecta en el prompt del modelo y devuelve los evidence_articles seleccionados junto con el pronóstico. Proporcionar news_articles omite la recuperación automática y utiliza la evidencia proporcionada por el llamador.

La respuesta incluye tanto el pronóstico como la evidencia utilizada por el modelo:

{
  "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."
  }
}

Use evidence_sources cuando un cliente solo necesite la lista de fuentes y enlaces. Use evidence_articles cuando un cliente necesite los detalles a nivel de artículo que se adjuntaron al prompt del modelo. rationale y model_rationale son generados por gpt-oss-120b y explican por qué el modelo eligió su respuesta y confianza. Cuando se proporciona market_probability, market_analysis se calcula determinísticamente a partir de la probabilidad del modelo y la probabilidad implícita del mercado.

Related MCP server: SimpleFunctions

Mercados cripto de 5 minutos

El modelo cripto de micro-mercado en src/analyzing_llm_rationale/crypto_5m.py está construido para mercados UP/DOWN de 5 minutos donde el objetivo es un comercio selectivo rentable, no una acción constante. Combina:

• fijación de precios lognormal con deriva reducida (shrunken drift),

• pronóstico de retornos AR(1) con volatilidad EWMA,

• características ML logísticas fijas o adaptativas de momentum, reversión, régimen de volatilidad, posición de rango y desequilibrio de volumen.

Cada pronóstico devuelve predicted_outcome, probability_up, component_probabilities, edge modelo-vs-mercado y una strategy consciente de comisiones. La estrategia solo recomienda una operación cuando el valor esperado neto supera las comisiones y el umbral configurado de no-operación.

.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

Use fold_aggregate y evidence_quality antes de arriesgar capital. Si la selección es inestable o el PnL de validación fuera de muestra es débil, la acción rentable correcta es abstenerse. --benchmark-log agrega un registro JSONL compacto para rastrear si el umbral seleccionado y el modo del modelo siguen funcionando en las ejecuciones de referencia. Resuelva los mercados completados contra velas de 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

El resolvedor devuelve pending antes del vencimiento y resolved después, con actual_outcome, resolved_price y prediction_correct.

Registre y resuelva señales de papel a lo largo del tiempo:

.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

El registro de señales es el conjunto de datos en evolución para la mejora del modelo: cada registro almacena el pronóstico, la recomendación, el actual_outcome posterior, la corrección y pnl_per_contract para operaciones de papel reales buy_up/buy_down. Use --signal-summary para auditar si las operaciones de papel resueltas son positivas después de comisiones; trade_ready permanece en falso hasta que se cumplan el recuento de operaciones, PnL y umbrales de tasa de acierto configurados. Use --dry-run con --paper-loop para previsualizar señales sin escribir en el registro.

Notas de despliegue de producción

La producción se sirve desde el dominio personalizado:

https://foresea.ink

El nombre del servicio de Cloud Run, el ID del proyecto y la región se establecen en el momento del despliegue mediante gcloud run deploy.

Entorno de ejecución requerido:

• SCADS_AI_API_KEY: secreto de Secret Manager utilizado para llamadas de modelo alojadas.

• MODEL_DEVICE=cpu: la producción de Cloud Run ejecuta la imagen en CPU.

• CUSTOM_DOMAIN=foresea.ink: redirige las solicitudes *.run.app al dominio público.

• GOOGLE_CLIENT_ID: ID de cliente OAuth de Google utilizado por /auth/config.

• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET: credenciales de la aplicación OAuth de GitHub. La URL de devolución de llamada de la aplicación OAuth debe ser el origen del sitio (por ejemplo, https://foresea.ink/). Cuando no se establece, el botón "Continuar con GitHub" está oculto y /auth/github devuelve 503. El inicio de sesión también funciona con Google y correo electrónico/contraseña.

• SESSION_SECRET: cadena aleatoria larga utilizada para firmar JWT de sesión del navegador y derivar referencias no reversibles separadas por dominio para análisis autenticados. Rotarlo inicia una nueva cohorte de atribución; nunca expone correos electrónicos de cuentas.

El cliente OAuth debe permitir estos orígenes de JavaScript:

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

Para actualizar variables de entorno no secretas sin reemplazar el SESSION_SECRET existente, use --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>'

Verifique la configuración de autenticación desplegada y el endpoint de salud:

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

Escalado y almacenamiento en caché

El servidor está construido para escalar horizontalmente en Cloud Run:

• Autenticación admite Google One-Tap y correo electrónico/contraseña (/auth/register, /auth/login). Las contraseñas se almacenan como hashes PBKDF2-HMAC-SHA256 con sal; las cuentas viven en Cloud Datastore.

• Almacenamiento en caché y limitación de velocidad usan Redis cuando REDIS_URL está configurado, por lo que están compartidos entre instancias; de lo contrario, recurren al estado en memoria por instancia y fallan abiertos. /predict (solicitudes no personalizadas), recuperación de evidencia y capturas de URL /extract se almacenan en caché; los GET públicos envían Cache-Control.

Historial de seguimiento en vivo

GET /track-record sirve el historial público de pronósticos. El bucle de tick pesado no se ejecuta en Cloud Run: .github/workflows/track-record-tick.yml se ejecuta cada hora en GitHub Actions, actualiza data/track_record_store.json como almacén de datos de origen, escribe el agregado público en static/track_record_live.json y confirma ambos archivos de vuelta a main. En tiempo de ejecución, Cloud Run obtiene el agregado confirmado desde GitHub raw, recurriendo al archivo incluido y luego al backtest estático en static/track_record.json.

La Action descubre mercados de Polymarket/Kalshi de horizonte corto a mediano en bandas de fecha de cierre separadas (2-7, 7-14, 14-30, 30-60 días por defecto) y llama a /predict una vez por mercado/modelo recién capturado. Si /predict está protegido, establezca el secreto de GitHub PREDICT_API_KEY; no se requiere un endpoint /track-record/tick en el servidor. TRACK_RECORD_TOKEN es opcional y solo habilita el puente de mercados inscritos por agentes.

El trabajo de pronóstico programado predeterminado está deliberadamente limitado en costo: se ejecuta cada 6 horas, captura como máximo 2 mercados por plataforma y pronostica solo gpt-oss-120b más la línea base sin LLM crowd-follow. Use la entrada de despacho manual de workflow reforecast_each_tick=1 para una actualización completa única en lugar de forzar que cada ejecución programada vuelva a pronosticar todos los mercados abiertos.

El escritorio de mercados de la página de inicio usa GET /radar, que se deriva de static/track_record_live.json y su edge_board. Radar destaca las brechas actuales modelo-vs-mercado y mantiene la primera pantalla rápida reutilizando el agregado de historial confirmado en lugar de escanear plataformas en cada carga de página.

Eleve el techo de rendimiento de Cloud Run (sin costo inactivo mientras min-instances=0):

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

Para el despliegue público de menor costo, mantenga el servicio en CPU solo por solicitud, escala a cero y limite la expansión máxima. Este es el perfil utilizado por el workflow de despliegue. El impulso de CPU de inicio permanece habilitado porque reduce la latencia de arranque en frío sin mantener una instancia inactiva caliente:

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

Mida la latencia de pronóstico desplegada después de cada cambio de tiempo de ejecución:

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

Si los arranques en frío aún dominan, eleve --min-instances a 1 como una compensación explícita de latencia/costo.

La búsqueda de mercados se ejecuta en proceso en la API principal. El microservicio opcional marketd en Go es solo de compilación/prueba en GitHub Actions y no se despliega en Cloud Run por defecto.

Retención de Artifact Registry

CI envía imágenes Docker etiquetadas por commit a Artifact Registry en cada despliegue. Mantenga activa la política de limpieza del repositorio docker para que las imágenes antiguas no se acumulen:

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

La política elimina imágenes con más de 7 días, conserva las 5 versiones más recientes por paquete y siempre mantiene la etiqueta main.

Las compilaciones Docker se ejecutan en GitHub Actions, no en Cloud Build; no se requiere un disparador de Cloud Build ni un bucket de almacenamiento provisional para la ruta de despliegue normal.

Una vez que max-instances > 1, aprovisione Memorystore para Redis (facturable) y establezca REDIS_URL para que la limitación de velocidad y el almacenamiento en caché sigan siendo correctos entre instancias:

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

Uso de la API

La API pública de Cloud Run es el objetivo de integración más fácil. Acepta preguntas de pronóstico y devuelve un pronóstico tipado, el razonamiento del modelo y artículos de evidencia opcionales. Está construida para pronósticos resolubles, no para Q&A general.

Endpoints

• GET /health: comprobación de estado del servicio.

• GET /track-record: registro de seguimiento público en vivo, con respaldo al backtest estático.

• GET /track-record/digest: resumen markdown compartible del registro de seguimiento en vivo.

• GET /pr-agent: paquete de divulgación opt-in entre agentes para el descubrimiento de Foresea.

• POST /predict: endpoint público de predicción.

• GET /markets/polymarket: obtiene una cotización en vivo de Polymarket (ver más abajo).

• GET /markets/kalshi: obtiene una cotización en vivo de Kalshi (ver más abajo).

• POST /agent/analyze: análisis integral orquestado de una pregunta en vivo (ver más abajo).

• GET /agent/scan: escanea un mercado en busca de mercados mal valorados, ordenados por ventaja (ver más abajo).

• GET /radar: panel de mercado de la página principal construido a partir del tablero de ventajas del registro de seguimiento en vivo.

• POST /analytics/visit: registra una visita a la página; las solicitudes autenticadas se vinculan únicamente a una referencia de cuenta no reversible.

• POST /analytics/event: registra eventos de embudo de producto como forecast_completed, watchlist_add, share_created y digest_sent; los eventos autenticados usan la misma referencia privada.

• GET /analytics/events/summary: resume los análisis de producto por separado de las visitas a la página, incluyendo la atribución agregada autenticada frente a anónima de los últimos 30 días.

• POST /forecasts/share: crea una página pública explícita de compartición de pronósticos.

• GET /forecast/{share_id}: muestra un pronóstico compartido sin exponer el historial de chat privado.

• GET|PUT|DELETE /trading/connections/{platform}: metadatos de conexión de intercambio por usuario cifrados y su ciclo de vida.

• POST /trading/preview: normalización de órdenes en seco autenticada.

• POST /trading/orders: envío de órdenes en vivo autenticado con confirmación explícita.

• GET /trading/portfolio: conciliación autenticada de saldo, posiciones, órdenes y ejecuciones.

• POST /trading/orders/{audit_order_id}/reconcile: actualiza el estado/ejecuciones de una orden enviada.

• DELETE /trading/orders/{audit_order_id}: cancela explícitamente la cantidad restante de una orden abierta enviada.

Estado de ejecución de la aplicación web

Los chats anónimos permanecen en el localStorage del navegador. Los usuarios autenticados sincronizan las conversaciones a través de /chat/conversations, mientras que el seguimiento de la lista de seguimiento utiliza entidades FavoriteMarket expuestas a través de /favorites y /favorites/prices. El resumen de la lista de seguimiento se ejecuta desde .github/workflows/favorites-digest.yml mediante scripts/favorites_digest.py.

La compartición de pronósticos es opt-in: los clientes llaman a POST /forecasts/share para crear una página pública GET /forecast/{share_id}. No expongas el historial completo de chat privado en las vistas de pronósticos compartidos.

Agente: capa de inteligencia automatizada

POST /agent/analyze ejecuta todo el pipeline de forma autónoma: resolver el mercado (obtener un precio en vivo de Polymarket/Kalshi cuando se proporciona un identificador) → recopilar evidencia + pronóstico → valorar la ventaja → ejecutar cualquier habilidad personalizada → recomendar. Devuelve un informe estructurado.

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?"}
    ]
  }'

Las habilidades personalizadas son tus propios pasos de análisis: cada una se ejecuta como una pasada adicional del modelo sobre la pregunta, el pronóstico y la evidencia, y regresa como una sección con nombre en el informe. Proporciona una question directamente, o una platform + identificador de mercado (slug/market_id para Polymarket, ticker para Kalshi). Pasa history (turnos anteriores) para seguimientos de múltiples turnos; con historial, los seguimientos cortos como "¿por qué?" o "¿y qué hay de junio?" se responden en contexto. Los campos BYOK (openrouter_api_key, openrouter_model, provider_base_url) también se aplican aquí. El informe incluye recommendation (buy_yes/buy_no/hold/no_market_price), edge, model_probability, market_probability, thesis, evidence_sources y pipeline (los pasos ordenados que se ejecutaron).

Ejecuciones de agente privadas y duraderas

Cada llamada autenticada a POST /agent/analyze (incluido el endpoint de streaming) también crea una AgentRun privada. Conserva una instantánea de entrada limitada y sin secretos, una línea de tiempo del ciclo de vida, el informe del modelo y cualquier traspaso de operación solo de revisión. Usa GET /agent/runs para la línea de tiempo del operador más reciente y GET /agent/runs/{run_id} para un informe completo. La instantánea excluye intencionalmente claves de proveedor, credenciales del navegador, historial de conversación e instrucciones sin procesar de habilidades personalizadas. Una ejecución de agente es solo investigación: incluso cuando tiene un traspaso de operación, no puede crear, dimensionar ni enviar una orden; el usuario debe crear y confirmar explícitamente una ejecución de operación duradera en la terminal.

Agentes copiados: recetas de investigación privadas y versionadas

Los usuarios autenticados pueden copiar un modelo público de Foresea desde el tablero de agentes. La copia se guarda en la cuenta del usuario como una receta de investigación inmutable versión 1; contiene solo el modelo fuente público y la instrucción de análisis, nunca el contexto privado del agente fuente, el historial de cuentas en la sombra, la conexión de intercambio, el tamaño de la orden o el permiso de negociación. Usa POST /agent-profiles/copy con un source_agent_id en la lista blanca y luego pasa el agent_profile_id devuelto a POST /agent/analyze.

Cuando se selecciona un perfil, el servidor resuelve el modelo y la instrucción del perfil por sí mismo, ignora las anulaciones BYOK/proveedor/modelo del cliente y fuerza el pipeline de investigación fijo (sin bucle de herramientas ni herramienta de negociación). El informe resultante devuelve su ID de perfil, fuente, versión y modo research_only para reproducibilidad. Un perfil puede preparar el traspaso de operación existente solo de revisión, pero no puede crear ni enviar una orden de intercambio; un usuario autenticado debe crear una ejecución de operación duradera y confirmar explícitamente PLACE REAL ORDER en la terminal de negociación.

Escaneo de ventajas: encuentra mercados mal valorados

GET /agent/scan lista los mercados en vivo en un mercado, pronostica cada uno y devuelve aquellos cuya brecha modelo-vs-mercado supera min_edge, ordenados por |edge|.

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

Parámetros: platform (polymarket o kalshi), limit (mercados a analizar, máx. 8), min_edge (por defecto 0.1), evidence_top_k. Cada mercado ejecuta un pronóstico completo, por lo que está limitado por limit y el resultado se almacena en caché brevemente. Respuesta: {platform, scanned, opportunities: [{question, market_url, market_probability, model_probability, edge, recommendation}]}. En la aplicación web, el botón "⚡ Escanear Polymarket en busca de mercados mal valorados" del panel llama a esto.

Servidor MCP: permite que los agentes de IA llamen a Foresea como herramientas

Foresea expone un servidor MCP remoto público en:

https://foresea.ink/mcp/

Se anuncia para descubrimiento en:

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

El servidor MCP remoto es una capa de herramientas ligera sobre la API pública. Expone:

• foresea_forecast: llama a POST /predict — produce pronósticos de probabilidad calibrados con evidencia.

• foresea_analyze_market: llama a POST /agent/analyze — evalúa un mercado específico de Polymarket/Kalshi con ventaja y tesis.

• foresea_scan_markets: llama a GET /agent/scan — escanea mercados en vivo ordenados por discrepancia modelo-vs-mercado.

• foresea_batch_quotes: llama a GET /market/batch — obtiene cotizaciones de múltiples mercados en una sola ida y vuelta.

• foresea_edge_board: llama a GET /edge-board — principales oportunidades de negociación abiertas ordenadas por ventaja estadística.

• foresea_track_record: llama a GET /track-record — precisión pública, puntuación de Brier, ECE y métricas de calibración.

• foresea_exchange_status: inspecciona el estado del intercambio de Kalshi (indicador de negociación activa) y el horario de operación.

• foresea_orderbook: obtiene la profundidad del libro de órdenes de ofertas y demandas en vivo para tickers de Kalshi o tokens de Polymarket.

• foresea_market_tags: obtiene la taxonomía de categorías y etiquetas activas de Polymarket.

• foresea_price_history: obtiene puntos de precio históricos o velas OHLC.

• foresea_live_data: obtiene estadísticas deportivas en tiempo real, datos jugada por jugada y fuentes de eventos en vivo.

• foresea_polymarket_meta: obtiene listados de series de eventos, comentarios de discusión de la comunidad o metadatos deportivos.

• foresea_recent_trades: obtiene la cinta de operaciones ejecutadas recientemente / impresiones (precios, tamaños, marcas de tiempo) en Kalshi o Polymarket.

• foresea_market_leaderboard: obtiene el ranking de los traders más rentables y las clasificaciones de volumen de Polymarket.

• foresea_pr_agent: llama a GET /pr-agent — texto conciso y metadatos de instalación para agentes/catálogos que preguntan cómo describir Foresea.

• Recursos: foresea://track-record, foresea://pr-agent y foresea://openapi.json.

Integraciones personalizadas y herramientas del ecosistema

Foresea proporciona integraciones de cliente listas para ejecutar en superficies populares de desarrollo y negociación:

1. Bots de señales de Telegram y Discord

• Bot de Telegram (scripts/foresea_telegram_bot.py): bot interactivo que admite /forecast <q>, /edge, /analyze <ticker>, /track y alertas de ventaja automatizadas para suscriptores.

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

• Bot y webhooks de Discord (scripts/foresea_discord_bot.py): publica embeds enriquecidos de Discord en canales de anuncios según un horario.

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

2. Widget web integrable (<foresea-card>)

Incorpora pronósticos interactivos de mercados de predicción en vivo en cualquier blog, sitio de noticias o Substack con una sola etiqueta de script:

<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. Puente de ejecución cuantitativa con dinero real

Un ejecutor de automatización opt-in (scripts/live_trader_bridge.py) que conecta las señales de ventaja estadística de Foresea con mercados de predicción en vivo (Polymarket y Kalshi) con estrictas salvaguardas de gestión de riesgos:

# 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

Agente de relaciones públicas: distribución entre agentes

GET /pr-agent?audience=mcp devuelve un paquete de divulgación opt-in que otros agentes, catálogos de MCP y directorios de herramientas pueden citar al presentar Foresea. Incluye la frase de una línea, el comando de instalación, los enlaces de MCP/OpenAPI, los puntos de conversación y una política explícita de no spam.

Para la divulgación en frío operada por el operador hacia endpoints de agentes explícitos, prepara una lista de objetivos y usa el ejecutor local. Por defecto hace una prueba en seco y solo envía con --send:

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

Forma del archivo de objetivos:

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

La API pública devuelve el paquete de divulgación; no expone un relé de envío de mensajes no autenticado. La acción de GitHub programada .github/workflows/pr-agent-outreach.yml se ejecuta cada 5 minutos contra data/pr_outreach_targets.json, envía con --send y registra los objetivos contactados en data/pr_outreach_state.json para que las ejecuciones programadas repetidas no vuelvan a contactar al mismo agente. Para un proceso local literalmente siempre en ejecución, ejecuta:

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

Los valores de encabezado pueden hacer referencia a secretos de GitHub Actions a través de variables de entorno, por ejemplo "Authorization": "$PR_AGENT_TARGET_AUTH".

Objetivos automatizados sembrados:

• AgentNDX (https://agentndx.ai/api/submit) — formulario público de revisión MCP/A2A/x402.

• MCP.Directory (https://mcp.directory/api/submit-server) — ruta pública de envío JSON.

• mcpub (https://mcpub.dev/mcp) — herramienta pública submit JSON-RPC de MCP.

El trabajo de listado adicional que no es adecuado para el remitente HTTP programado se encuentra en data/pr_manual_targets.json. Objetivo manual/GitHub actual: problema de mcp.so https://github.com/daodao97/chatmcp/issues/213.

Añade Foresea a tu agente (10 segundos)

Es un servidor remoto, anónimo, Streamable-HTTP — sin clave, sin instalación. Apunta cualquier cliente MCP a la 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/"
    }
  }
}

Para OpenClaw, añade también esto a la guía del espacio de trabajo del agente objetivo:

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, ...

Una demostración ejecutable de extremo a extremo (escaneo → pronóstico → ventaja) está en examples/foresea_agent_demo.py.

Usa https://foresea.ink/mcp/ directamente en clientes MCP que admitan servidores remotos Streamable HTTP. Para clientes que aún requieran un comando stdio local, ejecuta el envoltorio localmente.

El repositorio requiere Python 3.10+ porque el SDK oficial de MCP para Python lo exige. Para crear un entorno MCP de Python 3.11 local al repositorio con uv:

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

Esa instalación ligera evita arrastrar la pila completa de dependencias de inferencia (notablemente Torch/CUDA) cuando todo lo que necesitas es el envoltorio MCP. En un entorno de desarrollo completo, pip install -e ".[mcp]" también es válido.

Ejemplo de configuración de cliente MCP:

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

Para un endpoint MCP HTTP local:

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

Conecta los clientes MCP a http://127.0.0.1:8787/mcp. Si un despliegue privado requiere autenticación, establece FORESEA_API_KEY o pasa --api-key; el envoltorio lo reenvía como X-API-Key.

Verificación rápida:

.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

Obtener precios de mercado en vivo

Extrae la probabilidad implícita del mercado actual directamente de un mercado y luego introdúcela en /predict como market_probability para calcular una ventaja.

# 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"

Ambos devuelven una cotización normalizada:

{
  "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 es null para mercados sin precio/ilíquidos. Las cotizaciones se almacenan en caché brevemente (MARKET_CACHE_TTL, por defecto 30s).

Ejecución de operaciones: Polymarket y Kalshi

Foresea puede enviar órdenes de predicción de mercado con guardarraíles, pero la ejecución en vivo está deshabilitada por defecto. Mantén esto separado de /agent/analyze: el agente puede recomendar buy_yes/buy_no, pero el envío de órdenes requiere un usuario con sesión iniciada, una conexión de intercambio cifrada, FORESEA_ENABLE_BYO_TRADING=true, execute=true y la frase de confirmación exacta PLACE REAL ORDER.

El navegador envía las credenciales de conexión únicamente a PUT /trading/connections/{platform}. Foresea las valida, genera una clave única de cifrado de datos para esa conexión de usuario/plataforma concreta y cifra la carga útil de credenciales localmente. Cloud KMS envuelve la clave de datos utilizando el contexto autenticado de usuario/plataforma; Datastore recibe únicamente el texto cifrado, la clave de datos envuelta y los metadatos de la clave KMS. La clave raíz de KMS nunca entra en el proceso del servicio. Foresea nunca devuelve credenciales al navegador y rechaza venue_credentials en línea en las solicitudes de vista previa y de órdenes.

Crea una CryptoKey simétrica ENCRYPT_DECRYPT de KMS dedicada y otorga únicamente a la cuenta de servicio de Cloud Run roles/cloudkms.cryptoKeyEncrypterDecrypter en esa clave. Configura su nombre de recurso totalmente cualificado, no un valor secreto:

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"

La rotación de claves de Cloud KMS es transparente para las claves de datos envueltas existentes. El servicio utiliza la versión principal de la clave para una conexión nueva y KMS selecciona la versión anterior necesaria al descifrar una existente.

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

Instala los SDK opcionales en producción con:

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

La imagen Docker instala trading, por lo que Cloud Run solo necesita secretos/variables de entorno.

Migración de la clave compartida Fernet retirada

Si ya existen registros de conexión de versión 1, despliega la configuración de KMS y mantén disponible el valor anterior de FORESEA_CREDENTIALS_ENCRYPTION_KEY de Secret Manager solo durante la migración. Los registros existentes migran de forma diferida en su primer uso autenticado, o migra el conjunto completo desde un entorno con Application Default Credentials y acceso a Datastore:

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

El comando solo informa recuentos y nunca muestra credenciales. Una vez que no queden registros de versión 1, elimina FORESEA_CREDENTIALS_ENCRYPTION_KEY de Cloud Run y de Secret Manager.

Comprueba los metadatos de conexión de cuenta cifrados (no se devuelven secretos):

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

Conecta una cuenta a través de TLS (la carga útil se cifra antes de persistirse):

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>"}}'

Vista previa de una orden de Kalshi sin ejecución:

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
  }'

Envía una orden en vivo solo después de revisar la vista previa:

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"
  }'

Para Polymarket, pasa el token_id de CLOB para el resultado exacto, o pasa slug/market_id junto con outcome y Foresea resolverá el id de token a partir del registro público del mercado. Las órdenes limitadas usan quantity como acciones. Las órdenes de compra de mercado usan max_cost como gasto en USD cuando se proporciona y permanecen bloqueadas a menos que FORESEA_ALLOW_MARKET_ORDERS=true.

Después del envío, usa el ID de auditoría devuelto por /trading/orders para conciliar el estado actual de la plataforma en lugar de asumir que un envío se ejecutó. El terminal de operaciones también expone este flujo, incluida una confirmación explícita de CANCEL OPEN ORDER antes de cancelar una orden remanente en el libro.

Ejecuciones de operaciones duraderas y conciliación programada

Los nuevos envíos del terminal utilizan un registro duradero /trading/runs: Foresea guarda un plan de órdenes validado, requiere una segunda confirmación exacta para ejecutar ese plan guardado y lo reclama atómicamente antes de contactar con una plataforma. Esto evita órdenes duplicadas desde pestañas concurrentes o instancias de Cloud Run. El estado de la ejecución sigue a la orden de auditoría vinculada cuando se concilia una ejecución, cancelación o rechazo.

Salvaguardas de dinero real

Cada envío en vivo pasa ahora una segunda verificación previa del lado del servidor inmediatamente antes de la llamada a la plataforma. Falla de forma segura cuando Foresea no puede obtener una cotización de mercado reciente y una instantánea actual de la cartera, o cuando se superaría cualquiera de estos límites:

• Límites estrictos de Foresea: nocional por orden, presupuesto de riesgo en el peor caso del día, exposición por mercado, órdenes pendientes, desviación de cotización, antigüedad de cotización y un período de reutilización de órdenes duplicadas.

• Controles de usuario en GET/PUT /trading/guardrails: los usuarios pueden establecer límites más estrictos o pausar todas las órdenes en vivo nuevas, pero no pueden aumentar los límites de la plataforma.

• FORESEA_TRADING_KILL_SWITCH=true: bloquea cada nuevo envío en vivo sin tocar la conciliación ni las cancelaciones.

• Se comprueba una cotización de mercado sin caché contra el precio límite. Los límites de compra no pueden superar el collarín configurado y los de venta no pueden estar por debajo. Una instantánea en vivo de saldo/posición debe respaldar la orden y el límite de exposición.

El presupuesto del día se define deliberadamente como nocional en el peor caso recientemente arriesgado, no como una cifra engañosa de P&L sintético. Las posiciones ejecutadas se miden desde la instantánea de cartera de la plataforma antes de una nueva orden; el P&L diario realizado exacto sigue siendo una cuestión contable/de informes separada. Los pases de salvaguarda, bloqueos, cambios de política y transiciones conciliadas de ejecución/rechazo/cancelación se añaden a GET /trading/guardrails/events sin credenciales ni cargas útiles de órdenes. Configura los ajustes SMTP_* y ALERT_* existentes para recibir correos del operador ante eventos de envío desconocido, rechazo, ejecución y parada de emergencia de la plataforma.

Los techos de producción son variables de entorno; se aplican valores conservadores por defecto cuando se omiten:

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

El terminal requiere un slug o market_id de Polymarket para la ejecución real, de modo que Foresea pueda obtener de forma independiente una cotización de mercado reciente; un ID de token CLOB sin procesar no es suficiente para esta verificación de seguridad.

Para habilitar el conciliador programado de solo lectura, genera un token de servicio de alta entropía y almacena el mismo valor como TRADING_RECONCILIATION_TOKEN de Cloud Run y como secreto de GitHub Actions con ese nombre. Es un token de operador, no una credencial de usuario ni una clave de cifrado. El flujo de trabajo Trading reconciliation llama entonces al endpoint oculto cada 15 minutos, limitado por TRADING_RECONCILIATION_MAX_ORDERS (por defecto 25, máximo absoluto 100). El trabajo solo consulta el estado actual de los IDs de órdenes de plataforma ya enviados; no puede colocar, modificar ni cancelar una orden.

Verificación de preparación para el lanzamiento del operador

Después de desplegar la revisión de trading, usa el mismo token de conciliación de alcance limitado para leer su informe de configuración no confidencial:

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

El informe confirma el recurso KMS configurado, el cliente de almacenamiento duradero, la presencia del token de conciliación, los límites estrictos válidos, las puertas de ejecución en vivo y si la clave de cifrado compartida retirada sigue presente. No expone nombres de claves, tokens, credenciales ni datos de cuenta. Tampoco puede demostrar el IAM de Cloud KMS, que el secreto de GitHub Actions coincida, ni que una cuenta de intercambio pueda operar; verifica esos aspectos por separado durante la prueba de humo con invitación.

Implementa el índice TradingOrder en index.yaml antes de habilitar el programador:

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

Campos de solicitud

Obligatorios:

• question: pregunta de predicción, como "Will X happen by date Y?", "Who will win X?", "What will X be?" o "When will X happen?".

Opcionales:

• question_type: binary, multiple_choice, numeric o date. Si se omite, el modelo intenta inferir el tipo.

• options: opciones de respuesta para preguntas de multiple_choice.

• description: contexto adicional para la pregunta.

• resolution_criteria: cómo debe resolverse o medirse la pregunta.

• categories: lista de etiquetas temáticas.

• news_articles: artículos de evidencia proporcionados por quien llama. Si se proporcionan, se omite la recuperación automática de evidencia.

• attach_evidence: el valor por defecto es true. Cuando es true y news_articles está vacío, la API obtiene evidencia actual de GDELT, Google News RSS y Stooq.

• evidence_top_k: número de artículos de evidencia a adjuntar, limitado por el servidor.

• market_platform: plataforma de mercado de predicción como Polymarket, Kalshi, Manifold o Metaculus.

• market_url: URL del mercado que se está analizando.

• market_outcome: resultado cuyo precio de mercado se proporciona. El valor predeterminado es Yes para mercados binarios.

• market_probability: probabilidad actual implícita en el mercado para market_outcome. Usa 0.42 o 42; la API normaliza los porcentajes.

• variant: variante de prompt. El valor predeterminado es variant0_neutral_baseline.

• created_time, publish_time, resolve_time, days_open: metadatos de predicción opcionales.

• openrouter_api_key + openrouter_model: ejecuta la predicción en tu propio modelo en lugar del predeterminado del servidor (consulta "Bring your own model" a continuación).

• provider_base_url: endpoint opcional compatible con OpenAI /chat/completions para usar con tu clave/modelo en lugar de OpenRouter. Debe ser HTTPS público.

Bring your own model

Por defecto, /predict se ejecuta en el modelo alojado del servidor. Para usar el tuyo propio:

• Mediante OpenRouter — pasa openrouter_api_key y openrouter_model (p. ej., openai/gpt-4o, anthropic/claude-sonnet-4-5). La solicitud se redirige a través de OpenRouter.

• Mediante cualquier endpoint compatible con OpenAI — pasa también provider_base_url (p. ej., https://api.openai.com/v1 o https://api.openai.com/v1/chat/completions) con el openrouter_model correspondiente (aquí solo el ID del modelo del proveedor, p. ej., gpt-4o) y tu clave. Foresea normaliza internamente las URL base /v1 a /v1/chat/completions.

Por seguridad, provider_base_url debe ser HTTPS público; se rechazan los hosts de bucle local, privados, de enlace local y de metadatos de nube. En la aplicación web, el panel "Use your own model" de la barra lateral expone el proveedor, el endpoint, la clave y el modelo.

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 autoalojado

SCADS AI ya expone los modelos predeterminados de Foresea a través de un endpoint alojado compatible con OpenAI. Usa vLLM solo cuando necesites control directo sobre el punto de control, la cuantización, el rendimiento o el hardware de servicio.

Inicia un servidor local vLLM compatible con 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

Luego apunta Foresea al modelo configurado 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

Para producción, ejecuta Foresea y vLLM como servicios separados. El endpoint público bring-your-own de Foresea sigue requiriendo HTTPS público para provider_base_url; las URL de vLLM privadas o de bucle local están pensadas para configuración de servidor de confianza.

Solicitud binaria

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
  }'

Solicitud de opción múltiple

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
  }'

Solicitud numérica

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."
  }'

Solicitud con evidencia proporcionada por quien llama

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."
      }
    ]
  }'

Ejemplo de cliente 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"])

Campos de respuesta

• question_type: tipo detectado o solicitado: binary, multiple_choice, numeric o date.

• predicted_answer: "Yes", "No", la opción principal de opción múltiple o la estimación numérica/de fecha mediana.

• confidence: confianza del modelo como un número del 0 al 1 para pronósticos binarios y de opción múltiple; null para pronósticos numéricos/de fecha.

• options: probabilidades por opción para pronósticos de opción múltiple.

• range_forecast: p10, p50, p90 y unit opcional para pronósticos numéricos/de fecha.

• rationale: explicación generada por el modelo.

• model_rationale: alias de la explicación generada por el modelo, pensado para clientes de API.

• evidence_sources: lista de fuentes compacta con título del artículo, URL, fecha de publicación y puntuación de relevancia.

• evidence_articles: registros de evidencia completos adjuntos al prompt.

• evidence_error: mensaje de error de recuperación, o null cuando la recuperación de evidencia se realiza correctamente.

• market_analysis: comparación opcional con un precio de mercado proporcionado: market_probability, model_probability, edge, stance y un resumen breve. edge es model_probability - market_probability.

Contenido del repositorio

• src/analyzing_llm_rationale/: lógica empaquetada de inferencia, proveedor, validación y CLI.

• configs/: definiciones de modelos y variantes de razonamiento.

• prompts/: prompt del sistema más las variantes de prompt configuradas de razonamiento, control, ablación y sin evidencia.

• scripts/: scripts de evaluación, recuperación, SHAP, perturbación, trazado, datos de mercado y utilidades.

• slurm/: lanzadores HPC para los barridos de variante/temperatura.

• results/: salidas del modelo y metadatos de ejecución.

• analysis/: tablas de métricas agregadas y salidas de análisis de razonamiento.

• paper/: figuras del artículo, fuentes de Draw.io, PDF y estudios de caso cualitativos.

• tests/: pruebas unitarias para el paquete y el análisis de métricas.

Consulta ARTIFACT_MANIFEST.md para la lista de verificación de envío y las notas a nivel de archivo.

Instalación

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

Use .[dev] para linting y pruebas unitarias. Añade .[analysis] al regenerar gráficos, tablas de métricas o análisis SHAP. Añade .[trading] para el desarrollo local de previsualización/ejecución de órdenes de exchange.

Variantes de Prompt

Las variantes configuradas viven en configs/variants.yaml y se asignan directamente a los archivos de prompt bajo prompts/.

• variant0 es la línea base neutral.

• variant1 a variant8 cubren los prompts de atributos de razonamiento originales.

• variant9 a variant14 añaden scratchpad, controles de longitud equivalente, estructurales y controles combinados temporales/de credibilidad.

• variant15_neutral_no_rationale y variant16_no_evidence_neutral soportan ablaciones para los efectos de razonamiento y evidencia.

Al añadir una variante, actualiza configs/variants.yaml, añade el archivo de prompt y ejecuta una prueba de humo acotada:

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

Validación Rápida

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

PYTHONPATH=src es útil cuando el repositorio aún no se ha instalado o una instalación local de usuario más antigua oculta el árbol de trabajo.

Ejecuta la suite completa con Python 3.10+ y los extras relevantes instalados. Las pruebas del servidor, RAG, seguimiento y trading importan dependencias opcionales de serve, pipeline, analysis y trading.

Punto de Entrada Principal

Ejecuta el pipeline de la variante 3 con la CLI empaquetada:

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

Para un proveedor remoto compatible con OpenAI:

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

Si no quieres instalar el paquete en el entorno, invócalo directamente:

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

Opciones útiles:

• --variant variant6_step_by_step_reasoning: elige el contrato de prompt/salida.

• --model qwen2.5-7b-instruct: elige una definición de modelo configurada.

• --temperature 0.7: controla la temperatura de generación y el directorio de salida.

• --max-records 10: procesa solo un número acotado de registros.

• --reprocess-nulls: vuelve a ejecutar filas existentes con predicted_answer = null.

• --drop-article-text: elimina el texto bruto del artículo de los prompts antes de la inferencia.

• --device auto: selecciona cuda cuando esté disponible; de lo contrario, cpu.

• verify-results --variant ...: verifica integridad, duplicados, filas malformadas e IDs faltantes.

• validate-dataset: valida el esquema del dataset antes de una ejecución.

Autoinvestigación de Foresea

Foresea tiene un harness de autoinvestigación estilo Karpathy para experimentos de prompts: edita un prompt candidato, ejecuta un slice de benchmark fijo, puntúa una métrica y añade un registro de experimento auditable. La superficie de investigación es autoresearch/candidate_prompt.txt; las instrucciones del agente viven en autoresearch/program.md. El --model gpt-oss-120b predeterminado usa el endpoint compatible con OpenAI alojado en SCADS de configs/models.yaml (SCADS_AI_API_KEY o SCADS_AI_API_KEY.txt).

Ejecuta un experimento candidato:

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

Compara contra una línea base y promueve solo si el candidato mejora:

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

Cada ejecución escribe analysis/autoresearch/runs/<run_id>/score.json y añade una fila legible por máquina a analysis/autoresearch/experiments.jsonl.

Reproducción de Salidas Principales

Valida un archivo de resultados existente:

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

Regenera métricas agregadas desde results/:

python scripts/evaluate_metrics.py

Ejecuta la suite de análisis SQL de DuckDB sobre el dataset real estilo Metaculus y las salidas de modelo guardadas:

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

Esto escribe un informe en markdown más un CSV por consulta para 10 problemas SQL de nivel medio: precisión del modelo, mejores variantes, bins de calibración, puntuación de Brier, casos de consenso/discrepancia, mejora del prompt sobre la línea base, sensibilidad a la temperatura, errores de exceso de confianza y dificultad por categoría.

Ejecuta el wrapper de recuperación de noticias impulsado por 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

El pipeline de noticias usa LangChain para un paso de planificación de consultas, resumen de artículos y clasificación de relevancia basada en embeddings antes de la inferencia. Las fuentes de evidencia son configurables con --source para la CLI y --evidence-source al servir la API.

Ejecuta o programa el DAG de Prefect para la obtención de RSS/noticias, inferencia y registro en DuckDB:

# 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 * * *"

Regenera las figuras del artículo después de que las métricas estén presentes:

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

Scripts

Comandos comunes de ejecución y verificación:

• 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

Estructura del repositorio:

• scripts/: punto de entrada modular de ejecución

• slurm/: lanzadores por lotes

Auditabilidad:

• Cada ejecución escribe run_metadata_<variant>.json junto al archivo de resultados.

• Los metadatos incluyen proveedor, endpoint de proveedor normalizado, clave de modelo, identificador de modelo resuelto, temperatura, campos de salida y hashes SHA-256 de los prompts.

• Los JSON de resultados malformados existentes ahora fallan rápidamente en lugar de ignorarse silenciosamente.

Comprobaciones de Calidad

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

Datos, Modelos y Secretos

El dataset incluido es forecasting_qa_news_metaculus_2025-02-01_to_today.metaculus_frs_format.json. El acceso a los modelos se configura en configs/models.yaml. Los modelos Qwen de pesos abiertos se ejecutan localmente a través de Hugging Face; los modelos alojados usan endpoints compatibles con OpenAI y requieren claves API a través de variables de entorno o archivos de clave locales.

Nunca confirmes archivos de clave o tokens. Las cachés locales grandes (.cache/, envs/, .venv/) se ignoran intencionalmente y se excluyen de los archivos fuente.

Cita

Si este repositorio respalda una publicación, cita el artefacto con los metadatos en CITATION.cff y cita los datasets/modelos ascendentes según sus licencias.