Nixtla Plugin Showcase

Claude Code plugins and AI skills for time-series forecasting with Nixtla's statsforecast and TimeGPT.

Version: 1.7.0 | Status: Experimental | Plugins: 3 | Skills: 8

TL;DR (30 Seconds)

Health Check (Run First)

# 1. Python version OK?
python3 --version  # Need 3.10+

# 2. Clone and install
git clone https://github.com/intent-solutions-io/plugins-nixtla.git
cd plugins-nixtla
pip install -e . && pip install -r requirements-dev.txt

# 3. Tests pass?
pytest -v --tb=short

# 4. Baseline lab smoke test (90 sec, offline, no API key needed)
cd 005-plugins/nixtla-baseline-lab
./scripts/setup_nixtla_env.sh --venv
source .venv-nixtla-baseline/bin/activate
python tests/run_baseline_m4_smoke.py

All pass? You're ready. Something failed? See Troubleshooting.

Directory Map

nixtla/
├── 000-docs/                    # ALL documentation (Doc-Filing v3.0)
│   ├── 001a-planned-skills/     #   Generated skill specs (prediction markets)
│   ├── 004a-dev-planning-templates/  #   Development templates
│   └── archive/                 #   Historical docs
│
├── 003-skills/                  # Claude Skills (AI behavior mods)
│   └── .claude/skills/          #   8 production skills
│
├── 005-plugins/                 # WORKING PLUGINS (start here)
│   ├── nixtla-baseline-lab/     #   Main showcase - M4 benchmarks
│   ├── nixtla-bigquery-forecaster/   BigQuery integration
│   └── nixtla-search-to-slack/  #   Slack notifications
│
├── packages/                    # Installable packages
│   └── nixtla-claude-skills-installer/  # CLI: nixtla-skills
│
├── scripts/                     # Repo-level automation
├── tests/                       # Integration tests
├── .github/workflows/           # CI/CD pipelines (7 workflows)
│
├── CLAUDE.md                    # AI assistant instructions
├── README.md                    # You are here
├── CHANGELOG.md                 # Release history
└── VERSION                      # Current version: 1.7.0

Entry Points by Role

Environment Variables

Quick Setup:

# Minimal (baseline lab - no API key needed)
# statsforecast runs fully offline

# Full setup (TimeGPT features)
export NIXTLA_TIMEGPT_API_KEY='your-key-here'

# GCP features
export PROJECT_ID='your-gcp-project'
export LOCATION='us-central1'

Quick Commands

Install & Setup

# Clone
git clone https://github.com/intent-solutions-io/plugins-nixtla.git
cd plugins-nixtla

# Install (editable + dev deps)
pip install -e .
pip install -r requirements-dev.txt

Run Tests

pytest -v                          # All tests
pytest 005-plugins/ -v             # Plugin tests only
pytest --cov=005-plugins -v        # With coverage
python tests/run_baseline_m4_smoke.py  # Baseline lab smoke test

Lint & Format

black --check .                    # Check formatting
black .                            # Fix formatting
isort --check-only .               # Check imports
isort .                            # Fix imports
flake8 .                           # Lint check

Skills Installer

pip install -e packages/nixtla-claude-skills-installer
cd /path/to/your/project
nixtla-skills init                 # Install all skills
nixtla-skills update               # Update to latest
nixtla-skills --version            # Check version

CI/CD Reference

Location: .github/workflows/

Required to Merge: ci.yml must pass

Plugins

Quick Start (Baseline Lab)

cd 005-plugins/nixtla-baseline-lab
./scripts/setup_nixtla_env.sh --venv
source .venv-nixtla-baseline/bin/activate
pip install -r scripts/requirements.txt

# In Claude Code:
/nixtla-baseline-m4 demo_preset=m4_daily_small

Runs in ~90 seconds, fully offline, zero API costs.

Documentation

Doc-Filing System: NNN-CC-ABCD-description.md

• PP = Planning, AT = Architecture, AA = Audits, OD = Overview, DR = Reference

Troubleshooting

Still stuck? Open an issue or email [email protected]

Contributing

1. Fork the repo
2. Create feature branch: git checkout -b feature/my-feature
3. Make changes, add tests
4. Run pytest and black . locally
5. Open PR against main

See CONTRIBUTING.md for details.

Contact

Jeremy Longshore | [email protected]

Questions? Open an issue or email.

Prototypes & Research

ERCOT Grid Forecasting

Location: 002-workspaces/energy-grid-prototype/

48-hour electricity load forecasting for the Texas (ERCOT) grid with interactive map visualization.

Results: SeasonalNaive wins at 4.28% MAPE on 48h holdout.

cd 002-workspaces/energy-grid-prototype
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python ercot_grid_forecast.py

Research: See 121-AA-REPT-energy-grid-forecasting-opportunity-research.md

License

MIT