Gnomon is a forecasting toolkit for AI agents, with model comparison and memory of past results.
Agents can discover available models, run forecasts, compare them on historical outcomes, and retrieve relevant past results to inform future model choices. People and agents share Python, CLI and MCP interfaces with structured evidence behind the results.
Use your own forecasting software. Add a remote service or a persistent ledger when you need one.
Python 3.11–3.13. No required third-party dependencies.
python -m pip install 'gnomon-forecast==1.4.0'
gnomon infer --provider last_value --request '{"history":[10,12,11],"horizon":2}'From a checkout, use python -m pip install .; this also works before the
versioned package is published. These docs describe the checkout, which may contain
changes newer than an installed release. Use gnomon environment and
gnomon capabilities to check the installed build and supported operations.
The forecast command runs an offline baseline.
To use your own local model, install Gnomon in the same Python environment as
the model and its dependencies, then run that environment's gnomon or
python -m gnomon. An isolated Gnomon environment cannot import PyTorch or
another model library installed elsewhere.
Agent reading index · Copyable MCP configurations
Use the main agent workflow for connected tools, or Python forecasting for scripts. The workflow is: inspect → recall relevant evidence → forecast or compare → explain → review observed outcomes. Skip steps the task does not need. A one-off calculation needs neither a ledger nor a model comparison.
Run gnomon mcp serve in your agent host. The agent gets 6 tools by default:
gnomon_inspect: check data and freeze a reusable snapshot.gnomon_describe: calculate an observed statistic.gnomon_capabilities: find available models and their limits.gnomon_forecast: run the selected model.gnomon_evaluate: compare models on past data with an explicit budget.gnomon_read: retrieve saved results without running the model again.
A ledger adds gnomon_ledger, gnomon_route and gnomon_memory;
optional time calculations add gnomon_temporal. Discover the tools actually
available in the session instead of assuming every feature is enabled.
Forecasting and evidence operations return an agent_summary (or an
agent_summary_read call): the task scope, result, supporting evidence,
limitations and available follow-ups. Large details
remain retrievable without rerunning models. The host supplies observed outcomes
and decides when to review them; follow-ups do not run automatically.
Start the server with the MCP quickstart. Response semantics and schema discovery explain how to read results and recover from errors. Python, CLI and MCP share the session's execution contract; low-level Python engine/ledger objects retain native results.
| Task | Start here |
|---|---|
| Install or verify the Python environment | Installation |
| Complete a first forecast and outcome review | First run |
| Use connected tools as an agent | Use Gnomon |
| Forecast and save results in Python | Python skill · API |
| Compare models on past observations | Local evidence workflow |
| Configure a router that learns from outcomes | Adaptive routing |
| Review measured gains from episodic memory | Benchmark results and confidence intervals |
| Review recorded outcomes or recall lessons | Ledger skill · Memory |
| Research forecast-led trading | Trading skill |
| Find an exact argument or resolve an error | CLI/schema reference · Troubleshooting |
All guides group the detailed contracts and worked examples by task.
Register your model as a callable:
from gnomon import ForecastRequest, ForecastResult, InferenceEngine
def my_forecaster(request):
# Replace this baseline with your preferred model.
return ForecastResult((request.history[-1],) * request.horizon)
engine = InferenceEngine()
engine.register("my-model", my_forecaster)
execution = engine.forecast("my-model", ForecastRequest((10, 12, 11), 2))
print(execution.result.point) # (11.0, 11.0)StatsForecast, NeuralForecast, Darts or your own code: wrap the call and return a
ForecastResult. Use register_factory for a fresh model on each evaluation fold.
Gnomon checks inputs and outputs; you choose and install the model software.
See provider integration.
For a scoreable ledger record, give the forecast a nonempty series_id and
explicit future_timestamps. Every ledger timestamp needs an explicit timezone
such as +00:00; each actual must use the forecast's exact series_id, unit and
one of its future timestamps. The first-run guide
shows the complete CLI loop.
Local models need no account. To connect optional Ephemeris models, run
gnomon connect ephemeris; enter credentials in the hidden terminal prompt.
For Hermes, gnomon connect ephemeris --install-hermes-skill installs native
secure setup. See connection setup.
Ephemeris is one connector for remote time-series inference. Set its deployment URL and credentials in operator configuration; they are never agent tool arguments. Local models work without it. See connector setup. Agents can follow the portable Ephemeris setup skill for installation, credentials, MCP configuration and API documentation links. For trading research and execution workflows across brokers, exchanges and competitions, use Trade with Gnomon, including StatsForecast and Ephemeris integration examples.
The optional SQLite ledger saves forecasts, revised actuals, scores and decisions. Later corrections do not overwrite earlier predictions. You can ask what was known at a particular time, find forecasts that need scoring, and compare models on matched past results. Reading stored evidence does not rerun models. Gnomon does not automatically retrain them.
Two kinds of memory serve different purposes: router episodic memory uses similar completed forecasts to select a model; agent evidence recall returns recorded decisions and lessons for an agent to inspect. Recalling a lesson does not itself choose a model or validate its written explanation.
Optional date and time tools handle timezones, calendar shifts, intervals and event order. They calculate supplied facts; they do not claim to improve an LLM's reasoning.
Gnomon brings model discovery, forecasting, evaluation and outcome review into a shared agent workflow. Several projects cover related parts of that workflow:
| Project | Focus and overlap |
|---|---|
| sktime-mcp | Exposes sktime's estimator registry and execution through MCP so agents can discover, compose and run time-series workflows. |
| AutoGluon-TimeSeries | Automates training, selection and ensembling across forecasting models. |
| Darts | Provides a common Python interface for forecasting models, backtesting, covariates and ensembles. |
| Nixtla / TimeGPT | Provides a pretrained forecasting model and API tooling for forecasting and anomaly detection. |
| FASE | Research on forecasting agents that combine episodic memory with online ranking-policy learning from delayed outcomes. |
Forecasting libraries can supply models through Gnomon's provider interface. Gnomon adds recorded outcomes and evidence retrieval around those calls; model software is installed separately. Its optional FASE-inspired memory settings implement parts of the research approach, not the paper's full agent or learned ranking policy. Matched replay results were mixed, so these settings remain opt-in. Gnomon does not claim superior forecasting accuracy over the projects above.
The provider-neutral execution API is stable. Live-service verification and a real-agent comparison remain pending. A forecast is not permission to act; model quantiles are not proof of calibrated uncertainty. See validation and limits.
A gnomon is the part of a sundial that casts the shadow.
Shared agents: self-hosted remote MCP and optional Ditto memory, with project-scoped credentials, durable evidence and restart-tested handoffs.