Metadata-Version: 2.4
Name: xrtm-forecast
Version: 0.8.0
Summary: Institutional-grade modular engine for generative forecasting and agentic reasoning.
Author-email: XRTM Team <moy@xrtm.org>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/xrtm-org/forecast
Project-URL: Issues, https://github.com/xrtm-org/forecast/issues
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: freezegun>=1.2.0
Requires-Dist: openai>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: xrtm-data>=0.2.7
Requires-Dist: xrtm-eval>=0.2.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: mkdocs>=1.5.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.4.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.23.0; extra == "dev"
Dynamic: license-file

# xrtm-forecast v0.7.0

[![PyPI](https://img.shields.io/pypi/v/xrtm-forecast?style=flat-square)](https://pypi.org/project/xrtm-forecast/)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

**The Runtime Engine for XRTM.**

`xrtm-forecast` provides the agents, providers, topologies, and orchestration to build AI forecasting systems. It's a composable framework — import the pieces you need and wire them together.

## Installation

```bash
pip install xrtm-forecast
```

## Quick Start

```python
from xrtm.forecast.kit.agents.specialists.analyst import ForecastingAnalyst
from xrtm.forecast.core.config.inference import OpenAIConfig
from xrtm.forecast.providers.inference.factory import ModelFactory

# Use any OpenAI-compatible endpoint


config = OpenAIConfig(
    model_id="your-model",
    base_url="$OPENAI_BASE_URL",
    api_key="your-api-key",
)
provider = ModelFactory.get_provider(config)
analyst = ForecastingAnalyst(model=provider, name="forecaster")

# Ask a forecasting question
from xrtm.data import ForecastQuestion
question = ForecastQuestion(
    id="fed-march-2025",
    title="Will the Fed raise rates in March 2025?",
)
forecast = await analyst.run(question)
print(f"Probability: {forecast.probability:.2f}")
```

## What's Included

### OpenAI-compatible Provider
One provider that works with any OpenAI-compatible API: any OpenAI-compatible endpoint. Set `base_url` to point anywhere.

### Agents
- **`ForecastingAnalyst`** — Full forecast agent: structured prompts, causal reasoning traces, JSON output parsing
- **`LLMAgent`** — Base agent with tool retrieval, output parsing
- **`RoutingAgent`** — FAST/SMART tiered routing for cost optimization
- **`ToolAgent`** / **`GraphAgent`** — Wrap functions or sub-graphs as agents

### Topologies
Composable multi-agent patterns in `kit/topologies/`:
- **`RecursiveConsensus`** — Parallel analysts → aggregate → supervisor → loop
- **`create_debate_graph()`** — Pro/Con/Judge debate pattern
- **`create_fanout_graph()`** — Parallel workers → aggregator

### Orchestration
- **`Orchestrator`** — DAG state machine for workflow graphs
- **`AsyncRuntime`** — Chronos-aware async runtime

### Infrastructure
- **`InferenceCache`** — SQLite cache for LLM responses (enabled by default)
- **Retry with backoff** — 2 retries on API errors
- **`LeakageGuardian`** — Temporal leakage prevention for backtests

## XRTM Ecosystem

Part of the XRTM forecasting stack:

| Package | Role | Version |
|---------|------|---------|
| `xrtm-data` | Schemas & question sources | 0.3.0 |
| `xrtm-eval` | Scoring (Brier, ECE, LogScore) | 0.3.0 |
| `xrtm-forecast` | Runtime engine (this package) | 0.7.0 |
| `xrtm-train` | Backtesting & optimization | 0.3.0 |
| `xrtm` | Product CLI | 0.9.0 |

## License

Apache 2.0
