🔮
Forecast AI
v1.0.0

# Introduction

Forecast AI is an open-source platform that enables developers to build autonomous, multi-agent intelligence layers for prediction markets like Polymarket, Kalshi, and beyond.

Rather than querying a single monolithic LLM model—which often suffers from outdated knowledge, hallucination, and single-model bias—Forecast AI deploys specialized agents in parallel. Each agent is responsible for researching specific areas (News feeds, Social trends, Macro statistics, or On-chain metrics).

🔮

Core Philosophy: Collaborative intelligence leads to superior prediction accuracy. By framing prediction as an active debate between specialized nodes, we achieve highly calibrated forecasting scores.

# Architecture

The system is organized into three decoupled layers: **Data Sources**, **Core Intelligence**, and **Presentation Interfaces**.

System Pipeline Flow

Data Feeds (X, RSS, RPC)→Source Manager→Specialized Agents
↳Consensus Engine→Calibration & Platt Scaling→Polymarket CLOB Trade
  • Source Manager: Handles crawling, deduplication, and rate-limiting across external APIs.
  • Intelligence Agents: Parallel microservices executing LLM chains optimized with separate system prompts.
  • Consensus Engine: Aggregates individual probability scores into a single weighted probability outcome.

# Agents

Forecast AI deploys five specialized agent classes out-of-the-box. Developers can create custom agent sub-classes by extending the base `ForecastAgent` block.

News Agent

Evaluates chronological facts, verified articles, and press briefings to confirm historical events.

Social Agent

Parses Twitter/X and Reddit comments to track retail momentum and hype curves.

Macro Agent

Monitors broader economic data fields, inflation records, interest rates, and regulatory timelines.

Market Agent

Tracks orderbook depth, trading volume surges, and mid-market price drift on target platforms.

# Consensus

The **Consensus Engine** does not simply average scores. It implements a reputation-weighted Bayesian consensus system:

P_consensus = Sum( W_i * P_i ) / Sum( W_i ) where W_i = f(Historical_Brier_Score_i, Calibration_Rating_i)

If an agent has consistently generated accurate predictions on "Macro" questions in the past, its weight increases automatically. If an agent is highly inaccurate, its reputation decay decreases its active voting share.

# Memory

Memory Store & Reputations (`forecast_ai/memory/`): Uses vector stores (ChromaDB, PGVector, or local JSON caches) to log predictions, facts gathered, and the reasoning traces of each debate session.

This memory is vital for backtesting. Developers can run retrospective simulations to audit agent accuracy and adjust hyperparameters for individual markets.

# Providers

Forecast AI is model-agnostic. We support modern API endpoints with full streaming capabilities:

  • OpenAI: GPT-4o, o1, o3-mini.
  • Anthropic: Claude 3.5 Sonnet, Claude 3 Opus.
  • DeepSeek: DeepSeek-R1 (optimized for structured reason paths).
  • Ollama: Llama 3, Qwen, or custom fine-tunes run locally.

# Sources

Data source providers feed the raw inputs. Set credentials inside `.env` to enable:

  • News: Global News API, Bloomberg/Reuters RSS filters.
  • Social: Twitter/X Developer API v2 streams, Reddit search indexers.
  • On-chain: Solana mainnet RPC connection (subscribes to program account updates).

# Polymarket Integration

Our Polymarket module provides deep developer tools to interact directly with:

Gamma API Discovery

Query active market IDs, resolve requirements, categories, volume metrics, and resolve dates.

CLOB Orderbook client

Interact with limit order books, fetch current spreads, and sign buy/sell orders securely.

# API Routes

The built-in FastAPI server exposes routes for headless automation:

RouteMethodDescription
/healthzGETService health monitor.
/predictPOSTSubmit query to trigger collaborative agent run.
/marketsGETGet active prediction categories from Gamma.
/forecastsGETRetrieve historical prediction records database.

# Examples

Below is an example snippet showing how to programmatically initialize the consensus engine and execute a prediction in Python:

main.py
from forecast_ai.consensus import ConsensusEngine
from forecast_ai.agents import NewsAgent, SocialAgent

# Initialize consensus engine
engine = ConsensusEngine(
    agents=[
        NewsAgent(model="gpt-4o"),
        SocialAgent(model="claude-3-5-sonnet")
    ]
)

# Run forecasting query
result = engine.predict(
    question="Will Bitcoin reach $200,000 in 2026?"
)

print(f"Consensus Probability: {result.probability * 100}%")
print(f"Reasoning Trace: {result.rationale}")

# Roadmap

Forecast AI is growing rapidly. Track our active priorities:

✓Polymarket Gamma and CLOB wallet orderbook integrations.
✓Multi-agent consensus system & Bayesian accuracy weighting.
⏱Direct wallet execution order signatures on Polymarket contracts.
-Kalshi & Manifold prediction market bridges.