xrtm-forecast 0.5.3

Institutional-grade modular engine for generative forecasting and agentic reasoning.

xrtm-forecast

Professional engine for generative forecasting and agentic reasoning

xrtm-forecast acts as the rigorous backbone for state-of-the-art agentic workflows, bridging the gap between rapid prototyping and mission-critical deployment.

It centralizes the "Reasoning Graph" definition so that agent behaviors are deterministic and auditable. forecast is the pivot across the ecosystem: if a provider is supported, it can be plugged into any agent topology (Orchestrator, Debate, Consensus) without changing business logic.

We pledge to uphold research-grade transparency: strict typing, zero-tolerance verification, and rigorous double-trace auditability for every decision made by an AI.

Installation

Standard Installation (Cloud + Core)

pip install xrtm-forecast

Hardware-Specific Local Inference

pip install "xrtm-forecast[transformers]"  # PyTorch + HuggingFace
pip install "xrtm-forecast[vllm]"          # High-throughput serving
pip install "xrtm-forecast[llama-cpp]"     # CPU-optimized GGUF
pip install "xrtm-forecast[xlm]"           # Local Encoder specialists

Quickstart

Get started with xrtm-forecast right away with the Analyst API. The Analyst is a high-level reasoning class that supports research, search, and probability estimation.

from xrtm.forecast import AsyncRuntime, create_forecasting_analyst

async def main():
    # 1. Instantiate the analyst (API keys injected from env)
    agent = create_forecasting_analyst(model_id="gemini")
    
    # 2. Execute reasoning loop
    result = await agent.run(
        "Will a general-purpose AI (AGI) be publicly announced before 2030?"
    )
    
    # 3. Inspect the rigorous output
    print(f"Confidence: {result.confidence}")
    print(f"Reasoning: {result.reasoning}")

if __name__ == "__main__":
    # The AsyncRuntime ensures uvloop is used (if available) 
    # and provides a consistent entrypoint for the platform.
    AsyncRuntime.run_main(main())

Roadmap

To understand our vision for "Institutional Grade" forecasting, including our focus on Time Travel (Chronos), Calibration, and Dynamic Trajectories (Sentinel), please read our Strategic Roadmap.

Key Features

• Institutional Sovereignty:
  • Merkle Reasoning: Every state transition is anchored via SHA-256 Merkle proofs.
  • .xrtm Manifests: Portable bundles containing full reasoning traces, telemetry, and hashes.
  • Source Epistemics: Automated IntegrityGuardian for domain-level trust evaluation.
• Institutional Grade Physics:
  • Chronos Protocol: Time-travel safe backtesting with instant-sleep acceleration.
  • Sentinel Protocol: Forecast trajectories to track probability evolution.
  • Calibration: Native PlattScaler, BetaScaler, and Brier Score decomposition.
  • Inverse Variance Weighting (IVW): Uncertainty-aware consensus for multi-agent aggregation.
• Advanced Reasoning:
  • Recursive Consensus: Peer-review topology that loops until confidence threshold is met.
  • Fact-Checking: Dedicated FactCheckerAgent to verify claims against external tools.
  • Orchestrator: Async graph engine with conditional edge support.
• Safety & Compliance:
  • Async Runtime: Managed event loop facade.
  • Provider Interface: Swap out OpenAI for Anthropic, Gemini, or vLLM with zero code changes.
  • Sovereign Memory: Abstracted vector storage (ChromaDB) for RAG pipelines.

Why should I use xrtm-forecast?

1. Temporal Integrity (The Time Machine):

   • Most agent frameworks leak future data during backtests. xrtm-forecast has a Temporal Sandboxing engine that rigidly enforces cut-off dates for search and memory.
   • Verify your strategies against past events with zero look-ahead bias.

2. Probabilistic Rigor:

   • Agents are treated as calibrated instruments, not just chatbots. We support native Brier Score calculation, Reliability Diagrams, and Confidence Interval estimation out of the box.

3. Double-Trace Auditability:

   • Forecasting requires accountability. We provide a dual-layer audit trail: Structural (OTel traces of execution flow) and Logical (reasoning snapshots) for every prediction.

4. Dynamic Trajectories (Sentinel Protocol):

   • Move beyond static snapshots. Our architecture supports continuous forecasting, allowing agents to ingest streaming news and output probability updates over time without expensive re-runs.

5. Hybrid "Quant-Qual" Intelligence:

   • Seamlessly mix fast statistical models (e.g., ARIMA, XGBoost) with slow, deliberative LLM Agents in the same graph.
   • Orchestrate complex "Consensus" topologies where multiple agents debate to reduce variance.

6. Institutional-Grade Compliance:

   • Built for environments where "Black Boxes" are forbidden.
   • Every component is strictly typed, and our Managed Async Runtime ensures that background tasks are traceable, high-performance (uvloop), and time-travel safe (Chronos).
   • See our Architecture Overview for a deep dive into Core ABCs and Agent topologies.

Why shouldn't I use xrtm-forecast?

• You need a generic "Chat with PDF" or "Customer Support" bot. We are hyper-focused on Forecasting and Research workflows.
• You want "magic" autoscaling or loose typing. We prioritize correctness, repeatability, and type-safety over ease of prototyping.
• You don't care about backtesting or time-travel debugging.

Example Components

xrtm-forecast comes with a comprehensive Kit of pre-built instruments. Expand the categories below to see examples.

Agents (Personas)

• Minimal Agent: The "Hello World" of reasoning.
• Forecasting Analyst: A specialized researcher for binary forecasting subjects.
• Fact Checker: An agent that verifies claims against tools.
• Adversary (Red Team): An agent trained to find flaws in arguments.

Topologies (Interaction Patterns)

• Debate: Two agents arguing for opposing sides before a judge.
• Consensus: Multiple agents varying in temperature converging on a decision.
• Orchestrator Basics: Building a custom state machine from scratch.
• Epistemic Security: Source trust scoring and automated filtering.
• Chronos Acceleration: Using virtual time to bypass real-world delays.

Capabilities (Skills)

• Discovery (Search): Automated information retrieval.
• Streaming: Real-time token streaming for UIs.
• Calibration: Adjusting confidence intervals to match reality.
• Trace Replay: Re-running a saved execution for debugging.

Development Environment

This project is configured with a production-grade Dev Container to ensure a consistent, reproducible environment across all machines (Mac, Linux, Windows/WSL).

Prerequisites

• Docker Desktop (running)
• VS Code with the Dev Containers extension

Getting Started

1. Clone the repository:

   git clone https://github.com/xrtm-org/forecast.git
   

2. Open in VS Code:

   code forecast
   

3. Reopen in Container:
   • Click the "Reopen in Container" button in the notification popup.
   • Or press Cmd+Shift+P (or Ctrl+Shift+P) and type "Dev Containers: Reopen in Container".

Features

• Zero Config: Python 3.12, uv dependency manager, and all project tools are pre-installed.
• Zsh Terminal: Enhanced shell with autosuggestions and syntax highlighting.
• Tooling: gh CLI, ruff (linting), pytest (testing), and mypy (typing) are ready to use.