Custom Models

---
name: custom-models
description: "Help future Researcher sessions understand and extend Orbit
  custom-model internals."
disable-model-invocation: true
metadata:
  disco-role: operating
license: NOASSERTION
---

# custom-models

Use this sub-skill when a task is about Orbit model internals rather than the public built-in model workflow.

## Trigger words
- build a custom Orbit model
- inspect the forecasting architecture
- choose between Stan MAP/MCMC and Pyro SVI
- troubleshoot a backend or template issue
- understand how a new model template plugs into Orbit

## In scope
- `ModelTemplate`
- forecaster architecture: `Forecaster`, `MAPForecaster`, `FullBayesianForecaster`, `SVIForecaster`
- estimator classes: `BaseEstimator`, `StanEstimator*`, `PyroEstimator*`
- Pyro model classes: `orbit.pyro.lgt.Model`, `orbit.pyro.ktr.Model`
- Stan loading / compilation helpers: `orbit.utils.stan.get_compiled_stan_model`
- cmdstan-path setup: `orbit.utils.set_cmdstan_path`
- built-in template families that reveal the wiring: `ETS`, `LGT`, `DLT`, `KTRLite`, `KTR`

## Out of scope
- backtesting walkthroughs
- general utility helpers unless they explain model wiring
- ordinary built-in-user model usage unless it exposes the architecture

## Core mental model
1. `ModelTemplate` defines the contract.
2. `Forecaster` validates data, builds training / prediction metadata, and calls an estimator.
3. The estimator routes to Stan or Pyro.
4. The backend returns posterior arrays and metrics.
5. The forecaster may expose extra public model helpers after fitting.

## Model contract checklist
A custom Orbit model usually needs:
- `_model_name`
- `_data_input_mapper`
- `_supported_estimator_types`
- optional `_fitter` for custom Pyro-style fitting
- `set_dynamic_attributes()`
- `set_init_values()` when Stan-style initialization is needed
- `get_model_param_names()` / `_set_model_param_names()`
- `predict()`

## Backend selection rules
- Stan path: `StanEstimatorMAP` or `StanEstimatorMCMC` with compiled `orbit/stan/{model_name}.stan`
- Pyro path: `PyroEstimatorSVI` with either a supplied `_fitter` or `orbit.pyro.{model_name}.Model`
- `Forecaster` rejects unsupported estimator/model pairs before fitting starts

## What to inspect first
1. `references/architecture.md`
2. `references/build-your-own-model.md`
3. `references/troubleshooting.md`
4. `scripts/inspect_custom_models.py`

## Handoff rule
If the task needs source-backed detail, keep the evidence in the bundled references and update the snapshot before handing off. Do not depend on reopening the source repo.