◈ PRESAGE · The Everything Prediction Engine

English | 简体中文

Foresee every possible future.

Ask it anything unresolved — Bitcoin's trajectory, the next World Cup winner, AI's next milestone, or your own job offer. Five analyst agents with complementary cognitive biases debate independently, ten thousand worldlines are simulated in parallel, and a superforecasting-grade calibration layer converges everything into one actionable probability — all streamed live with cinematic motion design.

The built-in UI is currently in Chinese (Simplified). The engine, API, and all documentation work regardless of language.

---

Quick Start

pip install -r requirements.txt
python run.py

Open http://127.0.0.1:8712 in your browser. No API key required — the built-in local inference core works out of the box.

Optional: Plug in a real LLM (configured in the UI, no code changes)

Click Model Settings in the navigation bar, pick a provider preset (OpenAI / DeepSeek / Kimi / Qwen / OpenRouter), paste your API key, hit Test Connection, then save — takes effect immediately, no restart needed. The configuration is stored locally in data/settings.json, and the key is always masked when read back through the API.

Environment variables are also supported (useful for server deployments; UI settings take precedence):

PRESAGE_LLM_API_KEY=sk-xxxx
PRESAGE_LLM_BASE_URL=https://api.deepseek.com/v1
PRESAGE_LLM_MODEL=deepseek-chat

With an LLM connected, the question restatement, evidence drivers, and the five agents' arguments are generated by the real model, while the numerical layer (simulation and calibration) still runs through the same local pipeline. If the LLM call fails, the engine degrades seamlessly to the local core — the service never goes down.

---

The Prediction Pipeline (Six Stages)

Stage	What happens
Ⅰ Question Parsing	Domain fingerprinting (9 domains), time-horizon extraction, proposition-type detection
Ⅱ Base-Rate Anchoring	Domain historical base rates (Beta priors) + evidence-weighted drivers → anchor probability
Ⅲ Panel Debate	Five agents rule independently: the Archivist ◭ · the Trend Hunter ◮ · the Skeptic ◬ · the Signal Analyst ◈ · the Black-Swan Watcher ◉
Ⅳ Worldline Simulation	10,000 log-odds random walks seeded from the panel's belief distribution, with domain volatility injected
Ⅴ Superforecasting Calibration	Confidence-weighted log-odds pooling + mild extremization (d = 1.18, per Satopää / Baron et al.); once ≥40 resolved outcomes exist, empirical recalibration kicks in automatically (a single-parameter logistic recalibration: grid search minimizing historical Brier score, with shrinkage)
Ⅵ Oracle Verdict	Final probability, confidence, P10–P90 interval, three-scenario projection, catalysts & risk list

Reproducibility: the same question asked on the same day uses the same random seed — results are fully reproducible (audit-friendly).

Outcome Loop (à la Metaculus Track Record)

A forecast should be tested, not just emitted:

• Mark due predictions as Hit / Miss in the archive drawer (reversible)
• The engine computes the Brier score and a five-bucket calibration curve (GET /api/stats)
• The home page shows a live calibration score (0–100, higher is better) and the number of resolved cases
• The archive drawer includes a track-record strip: per-bucket "average predicted probability vs. actual hit rate" in two colors — calibration quality at a glance
• Outcomes feed back into the engine: with ≥40 resolved samples, every new prediction learns a recalibration factor from your own track record, correcting systematic bias — the more you predict and resolve, the sharper the engine gets
• Archive replay: click any history item to fully restore its verdict page (gauge, scenarios, evidence balance) and re-export the share card

Share Cards

One-click share card export from the verdict page: a 1200×630 oracle-styled PNG rendered on Canvas (question + probability + P10–P90 interval + the five-agent spectrum), sized for every major social platform.

API Reference

Interactive docs at http://127.0.0.1:8712/api/docs (auto-generated by FastAPI).

Endpoint	Method	Description
/api/stream?question=…	GET	SSE streaming prediction (stage / thought / driver / persona / mc_* / final / done)
/api/history?limit=40	GET	Prediction archive list
/api/prediction/{id}	GET	Full verdict data for one archived prediction (replay)
/api/resolve/{id}?outcome=1|0|-1	POST	Outcome resolution: hit / miss / revoke †
/api/stats	GET	Global stats (incl. Brier score & calibration buckets)
/api/settings	GET / POST	LLM config read (key masked) / save †
/api/settings/test	POST	LLM connectivity test †
/api/health	GET	Health check

† Write endpoints require the X-Presage-Token header once an admin token is configured.

Security & Deployment Notes

• Local use (default): the server binds to 127.0.0.1; nothing to configure.
• Before exposing to LAN / the internet, you must:
  1. Set an admin token: PRESAGE_ADMIN_TOKEN=<strong random string> — protects write endpoints (model config, outcome resolution);
  2. Terminate TLS behind a reverse proxy (Nginx / Caddy) and narrow CORS to your actual domain;
  3. Note that the API key in data/settings.json is stored in plaintext — keep host disk access controlled.
• All dynamic frontend content (user input, LLM output) is rendered through a single HTML-escaping helper to prevent injection.

Docker

docker build -t presage .
docker run -p 8712:8712 -v presage-data:/app/data presage

The image ships with a health check; the /app/data volume persists the prediction archive and model settings.

Testing & Quality

pip install -r requirements-dev.txt
pytest tests -q        # 41 unit/API tests: classifier, Monte Carlo (both paths), calibration & recalibration, storage, auth, SSE heartbeat
ruff check .           # static analysis (E/W/F/I/B/UP rule set), zero warnings

• Dual-path Monte Carlo: numpy-vectorized by default (~9× faster for 10k runs), with a pure-Python fallback when numpy is unavailable; both paths are deterministic under the same seed and statistically equivalent (locked by tests).
• Production-grade SSE: comment-line heartbeats are injected whenever the event gap exceeds a threshold (keeps reverse proxies / load balancers from killing "idle" connections; tune via PRESAGE_SSE_HEARTBEAT), plus no-transform and X-Accel-Buffering: no response headers.
• SQLite WAL mode: concurrent reads during writes + busy_timeout, stronger crash recovery.
• CI: GitHub Actions runs lint + tests + Docker build on Python 3.11 / 3.12 (.github/workflows/ci.yml).
• E2E: verify_api.py (27 endpoint assertions + live SSE event integrity), verify_final.py (full prediction flow / track-record strip / archive replay / mobile), plus verify_ui.py / verify_round3.py / verify_settings.py / verify_console.py.

Tech Stack

• Backend: FastAPI + SSE streaming + SQLite archive, fully async
• Frontend: zero-build vanilla HTML/CSS/JS — Canvas starfield, SVG oracle gauge, worldline fan chart, typewriter reasoning stream, all hand-written
• Engine: domain knowledge base + multi-agent pooling + Monte Carlo simulation (numpy-vectorized) + extremized calibration

Project Layout

presage/
├── run.py                  # one-command launcher (auto port fallback)
├── requirements.txt / requirements-dev.txt
├── Dockerfile / .dockerignore
├── pyproject.toml          # ruff / pytest config
├── .github/workflows/ci.yml
├── backend/
│   ├── main.py             # FastAPI + SSE
│   ├── config.py / models.py / storage.py
│   └── engine/
│       ├── orchestrator.py # six-stage pipeline orchestration
│       ├── classifier.py   # domain / horizon / type parsing
│       ├── knowledge.py    # nine-domain knowledge base
│       ├── personas.py     # the five agents
│       ├── montecarlo.py   # worldline simulation (numpy / pure-Python)
│       ├── calibration.py  # pooling & extremization
│       └── llm.py          # optional LLM enhancement (OpenAI-compatible)
├── tests/                  # pytest unit & API tests
└── frontend/
    ├── index.html
    ├── css/style.css
    └── js/ (starfield / gauge / charts / app)

Design Lineage & License Compliance

The architecture draws on publicly documented design patterns (multi-agent debate, consensus pooling, research→reasoning→calibration pipelines, SSE reasoning panels) from the following permissively licensed open-source projects. All code in this repository is an original implementation — no source code was copied:

• Metaculus/forecasting-tools (MIT)
• Alchemist-X/predict-raven (MIT)
• defidaddydavid/polyswarm (MIT)
• codebyollie/forecast-agents (MIT)

All of the above are MIT-licensed, permitting study, modification, and commercial use.

Disclaimer: PRESAGE produces structured probabilistic assessments for decision support only. Nothing it outputs constitutes investment, legal, or medical advice.