Impulso: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

Impulso is a Python library for Bayesian Vector Autoregression (VAR). Early stage (v0.0.12), requires Python >=3.11.

Commands

# Install dependencies and prek hooks
make install

# Run all code quality checks (lock file, pre-commit, type checking)
make check

# Run tests with coverage
make test

# Run a single test
uv run python -m pytest tests/test_foo.py::test_foo -v

# Run only fast tests (skip MCMC sampling)
uv run python -m pytest -m "not slow" -v

# Type check only
uv run ty check

# Lint/format only
uv run ruff check . && uv run ruff format .

# Build the Sphinx/MyST-NB docs (executes + caches notebooks; full MCMC)
make docs

# Build docs in smoke mode, warnings-as-errors (fast MCMC; the PR CI gate)
make docs-ci

# Serve the built docs locally on :8000
make docs-serve

# Check external links resolve (no notebook execution)
make docs-linkcheck

# Multi-version test (Python 3.11-3.14)
uv run tox

Architecture

• Source: src/impulso/ — library code, built as a wheel via Hatchling
• Tests: tests/ — pytest with --cov, 90% coverage target (codecov.yaml)
• Docs: docs/ — Sphinx + MyST-NB with the shibuya theme (docs/conf.py). Tutorials are jupytext py:percent notebooks (docs/tutorials/*.py, read via nb_custom_formats); the API reference is autodoc/autosummary from docstrings. Link-preview (Open Graph) tags come from sphinxext-opengraph; a page opts into a custom og:image via MyST front matter in its first markdown cell.

Core Pipeline

The library follows an immutable pipeline where each stage produces the next:

VARData → VAR.fit() → FittedVAR → .set_identification_strategy() → IdentifiedVAR

• VARData (data.py): Validated, frozen Pydantic model holding endogenous/exogenous arrays + DatetimeIndex. Constructor from_df() for DataFrame input.
• VAR (spec.py): Model specification (lags, prior). Calling .fit(data, sampler) builds a PyMC model, samples, and returns FittedVAR.
• FittedVAR (fitted.py): Reduced-form posterior. Provides .forecast(steps) → ForecastResult and .set_identification_strategy(scheme) → IdentifiedVAR.
• IdentifiedVAR (identified.py): Structural VAR. Provides .impulse_response() → IRFResult, .fevd() → FEVDResult, .historical_decomposition() → HistoricalDecompositionResult.