Benchmark-backed hourly demand forecasting core.
Preprocess irregular series, benchmark models, and route operational forecast workloads through one API.
Time-series forecasting is still fragmented across incompatible runtimes, ad hoc preprocessing, and weak production evidence. tollama Core turns that into one opinionated workflow for operations teams: preprocess, forecast, benchmark, and route from benchmark-backed evidence, with a checked-in hourly-demand demo path and a thin artifact bundle.
Every TSFM ships its own install, its own API, and its own dependency tree. Building on top of them means fighting fragmentation at every layer.
Install the Core path, start the daemon, and run the hourly-demand concrete solution in under five minutes.
python -m pip install "tollama[eval,preprocess]"
# from source (dev):
python -m pip install -e ".[dev]"# terminal 1
tollama serve
# check health + diagnostics
curl http://localhost:11435/api/version
tollama doctor
tollama info --json# terminal 2
tollama quickstart
USE_CHECKED_IN_INPUT=1 MODELS=mock bash examples/core_concrete_solution_demo.sh
tollama routing show artifacts/core-solution/benchmark/result.json --jsonHuman-friendly progress is enabled automatically on interactive terminals. The upstream repo now includes a checked-in hourly benchmark input, a concrete-solution walkthrough, and an expected artifact bundle: docs/concrete-solution.md and examples/core_solution_expected_output.
The first-touch story is not platform breadth. It is one operational loop: preprocess irregular series, forecast, benchmark, and route future requests.
import numpy as np
from tollama.preprocess import PreprocessConfig, run_pipeline
x = np.arange(48, dtype=float)
y = np.sin(x * 0.15) * 10
y[[7, 19, 33]] = np.nan
result = run_pipeline(x, y, config=PreprocessConfig(lookback=12, horizon=4))
print(result.X.shape, result.y.shape)Spline-based preprocessing is the Core differentiator for irregular series with gaps, smoothing needs, and leakage-safe window generation.
from tollama import Tollama
sdk = Tollama()
forecast = sdk.forecast(
model="chronos2",
series={"target": [10, 11, 12, 13, 14], "freq": "D"},
horizon=3,
)
print(forecast.to_df())Core keeps the forecast contract stable across TSFMs and neural baselines, even when runtime dependencies differ per family.
tollama benchmark examples/core_solution_hourly_input.json \
--models chronos2,granite-ttm-r2,timesfm-2.5-200m,moirai-2.0-R-small \
--horizon 24 \
--folds 2 \
--output artifacts/core-solution/benchmarkCore benchmark output is intentionally thin: result.json, routing.json, leaderboard.csv, and the operator-facing summary.md.
tollama routing apply artifacts/core-solution/benchmark/result.json
tollama routing show artifacts/core-solution/benchmark/result.json --json
python -c "from tollama import Tollama; \
sdk = Tollama(); \
resp = sdk.auto_forecast(series={'target':[10,11,12,13,14],'freq':'D'}, horizon=3, mode='high_accuracy'); \
print(resp.selection.chosen_model)"Routing turns benchmark evidence into reusable defaults like default, fast_path, and high_accuracy, while preserving lane rationale for later Trust attachment.
The upstream registry spans TSFMs and neural baselines that share the same Core CLI, SDK, and HTTP forecast contract while family runtimes stay isolated under ~/.tollama/runtimes/.
| Model Family | Past Numeric | Past Categorical | Known-Future Numeric | Known-Future Categorical |
|---|---|---|---|---|
| Chronos-2 | ✓ | ✓ | ✓ | ✓ |
| Granite TTM | ✓ | — | ✓ | — |
| TimesFM 2.5 | ✓ | — | ✓ | — |
| Uni2TS / Moirai | ✓ | — | ✓ | — |
| Sundial | — | — | — | — |
| Toto Open Base | ✓ | — | — | — |
| Lag-Llama | — | — | — | — |
| PatchTST | — | — | — | — |
| TiDE | ✓ | — | ✓ | — |
| N-HiTS / N-BEATSx | — | — | — | — |
These integrations remain available, but they are intentionally secondary to the Core workflow. Start with preprocess, forecast, benchmark, and route first.
Register tollama-mcp as an MCP server. AI assistants discover and call 15 forecasting tools — forecast, auto-forecast, pipeline, what-if, model management, and data ingest.
First-party LangChain toolkit with 13 tools wrapping the full API surface. Compose forecast chains, embed in ReAct agents, or use with LangGraph workflows.
Framework adapters now ship directly in the package: CrewAI tools, AutoGen tool specs plus function maps, and smolagents-compatible tool wrappers.
Skill package at skills/tollama-forecast/ with health, models, forecast, pull, rm, and info wrappers. E2E validated with contract-first error handling.
Authenticated discovery plus task lifecycle support via POST /a2a and /.well-known/agent-card.json, including message/stream, tasks/get, tasks/query, and tasks/cancel.
The tollamad daemon supervises worker-per-family runtimes, keeps the public contract stable, and auto-bootstrap installs isolated venvs per backend when needed.
~/.tollama/runtimes//api/usage/api/eventsCombined analysis, recommendation, and forecast in a single call via /api/report, with optional narrative blocks.
Real-time forecast refinement and daemon event feeds over SSE via /api/forecast/progressive and /api/events.
Model-free descriptive analysis at /api/analyze and synthetic series generation at /api/generate.
Forecast directly from CSV or Parquet using data_url, /api/forecast/upload, or /api/ingest/upload.
Chain benchmarks, comparisons, and end-to-end plans through /api/compare and /api/pipeline.
Explore alternative futures with /api/what-if, /api/counterfactual, and /api/scenario-tree.
Zero-config model selection via /api/auto-forecast, with ensemble mean and median strategies available today.
Create named forecast profiles with tollama modelfile and manage pull or routing defaults with tollama config.
Optional API-key auth, docs protection, usage metering at /api/usage, Prometheus at /metrics, and full diagnostics at /api/info.
The current endpoint inventory spans system diagnostics, model lifecycle, upload plus ingest, stable v1 routes, structured analysis, scenario workflows, TSModelfiles, observability, and A2A discovery.
The upstream roadmap is now implementation-aware and explicitly tracks what is shipped versus what remains for v1 hardening.
mean and median strategies.tollama.preprocess.Runtime management, analysis, ingest, dashboards, and agent integration all ship in the same platform.