Impulso: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents working in this repository.

Project Overview

Impulso is a Python library for Bayesian Vector Autoregression (VAR). Early stage, 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 (docs/conf.py), tutorials as executable jupytext py:percent .py notebooks (read via nb_custom_formats), prose/reference pages as MyST .md. Docstrings auto-rendered via Sphinx autosummary (summary tables + per-object pages generated under docs/reference/generated/, gitignored; custom stub templates in docs/_templates/autosummary/ emit MyST) + napoleon. sphinx-codeautolink links API names in tutorial code to the reference; sphinxcontrib-bibtex powers {cite} (bib in docs/references.bib); sphinx-sitemap emits sitemap.xml; numfig + labelled $$…$$ (label) equations cross-referenced with {eq}`label`. Link-preview (Open Graph) tags come from sphinxext-opengraph; a page opts into a custom og:image via a meta directive in its first markdown cell. Notebooks execute at build via jupyter-cache; no outputs are committed. Theme: shibuya. Tutorial .py files are excluded from ruff (they are notebooks, not library code).