skforecast-ai
AGENTS.md52 starsChanged 47 days agoApache-2.0View on GitHub
skforecast-ai wraps the skforecast engine in a deterministic forecasting assistant (ForecastingAssistant) with an optional LLM layer that explains decisions but never makes them. PyPI name skforecast-ai, import name skforecast_ai. This file is the entry point for any coding agent; the detailed docstring and testing rules live in .github/instructions/ and are shared with the skforecast repository. 1. Deterministic first, LLM second. Every forecasting decision (forecaster, estimator, lags, metric, cross-validation) comes from rule-based code in recommendation/ and is reproducible without an LLM.…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- handoffSkill
- llm-context-changeSkill
- open-prSkill
- release-bumpSkill
- release-noteSkill
- sync-skforecast-assetsSkill
- verifySkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 1 is common, 1 is distinctive, and 4 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
No silent automation. When something cannot be validated, warn or raise.
- Common: line 75
No API key or network is needed for the test suite.
- Very specific: line 99
No en dashes or em dashes anywhere: code, comments, docstrings, string literals, error messages, tests or documentation.
- Very specific: line 109
Follow .github/instructions/testing.instructions.md.
- Very specific: line 113
Every test has a docstring saying what it verifies.
- Distinctive: line 118
Never call a real provider from tests.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
skforecast-ai: conventions for coding agents
skforecast-ai wraps the skforecast engine in a deterministic forecasting
assistant (ForecastingAssistant) with an optional LLM layer that explains
decisions but never makes them. PyPI name skforecast-ai, import name
skforecast_ai. This file is the entry point for any coding agent; the
detailed docstring and testing rules live in .github/instructions/ and are
shared with the skforecast repository.
Core principles
- Deterministic first, LLM second. Every forecasting decision (forecaster,
estimator, lags, metric, cross-validation) comes from rule-based code in
recommendation/and is reproducible without an LLM. The LLM explains, refines lags and window features on request, and translates a natural-language scenario intoTimeSeriesFoldparameters; its output is always validated by a Pydantic model before it touches execution. - The code you see is the code that ran.
forecast()andbacktest()execute the same script thatforecast_code()andbacktest_code()return (minus the CSV loading preamble). Rendering lives inrendering/, execution inexecution/; never let them drift apart. - No silent automation. When something cannot be validated, warn or raise.
Degrade to a deterministic result only when that result is valid on its
own (
refine_plan(),create_cv());ask()raisesLLMCallErrorbecause it has no answer without the LLM. - Privacy by default. Datasets never reach the LLM: profiles hold summary
statistics only. Results ship the values they own (predictions, metrics)
and
ask()warns about it withDataSentToLLMWarningwhensend_data_to_llm=False. - Everything crossing a module boundary is a Pydantic model (
schemas/), and every result is aDisplayMixin(renders itself) and anExplainableResult(describes itself to the LLM).
Layout
skforecast_ai/
assistant.py ForecastingAssistant: public facade, orchestration only
_utils.py input resolution and validation helpers
_display.py rich rendering shared by every result
schemas/ Pydantic models: profiles, plans, results, typed overrides
profiling/ deterministic data inspection (DataProfile)
recommendation/ rule engine: forecaster, estimator, lags, metric, CV
rendering/ script generation from a plan (one module per family)
execution/ runs rendered scripts; comparison helpers
llm/ pydantic-ai agents, prompts, context, skills, runtime
mcp/ MCP server (`skforecast-ai mcp`): tools over the assistant;
mcp/skills/ is its SKILL.md for agents, written here
skills/, resources/ synced from skforecast (do not edit by hand)
cli.py Typer CLI mirroring the Python API
tests/ mirrors the package: tests_<subpackage>/, fixtures_*.py
plugin/ Claude Code plugin of the MCP server (marketplace in
.claude-plugin/); its SKILL.md is a byte for byte copy
of skforecast_ai/mcp/skills/ and its versions follow
pyproject.toml (tests/test_plugin_distribution.py)
packages/ other PyPI packages (see packages/README.md):
skforecast-ai-mcp, the launcher that server.json (the
entry of the MCP registry) names; their versions follow
pyproject.toml (tests/test_mcp_registry_distribution.py)
tools/ maintenance scripts (see tools/README.md): ai/ for the
skforecast assets and the LLM context checks,
docs/ for the documentation buildPython environment
Interactive local session: before running any Python command (tests,
scripts, notebooks, pip install) for the first time in a session, run
conda env list and ask which environment to use. Do not assume the active
environment. Once the user confirms an environment, reuse it for the rest of
the session.
Non-interactive or cloud session (nobody to ask, no conda): install with
pip install -e ".[test,llm]" ruff and run the commands below as they are.
No API key or network is needed for the test suite; LLM calls are mocked.
Commands
pytest -n auto # full suite
pytest tests/test_assistant_ask.py -q # one file
ruff check skforecast_ai tests # lint (must be clean; CI runs it)
python tools/ai/update_golden_contexts.py # regenerate LLM context goldens
python tools/ai/check_ask_context.py --dry-run # ask() contexts, no LLM call
PYTHONPATH=. mkdocs build -q -d /tmp/site # docs build check
python tools/docs/hooks/page_meta.py # docs titles and descriptionsCode style
- PEP 8, max line length 88, enforced by ruff (
E,F). Double quotes. - Type hints on every public function and method;
X | None,list[...]. - Relative imports inside the package.
- Aligned keyword arguments in long calls, as in skforecast
(
profile = self.profile(\n data = data,\n target = target,\n)). - NumPy-style docstrings on every public class, method and function. Follow
.github/instructions/docstrings.instructions.md: single backticks, readable type names (pandas DataFrame),name : type, default value. - No en dashes or em dashes anywhere: code, comments, docstrings, string
literals, error messages, tests or documentation. Use commas, colons,
semicolons or parentheses.
tests/test_source_conventions.pyenforces it. - Comments explain why, not what. No emojis in source or messages.
- pydantic-ai is the only LLM abstraction; never import a provider SDK.
- Importing
skforecast_aimust work without the[llm]extra: keep pydantic-ai imports inside functions.
Testing
Follow .github/instructions/testing.instructions.md. In short:
- One test file per public function or method, header
# Unit test <name>. - Fixtures are module-level variables in
fixtures_<module>.py. - Every test has a docstring saying what it verifies; names follow
test_<method>_<scenario>/test_<method>_<ErrorType>_when_<condition>. - Hardcoded expected values;
pd.testingandnp.testingfor comparisons; errors and warnings withre.escape()pluspytest.raises(match=...). - LLM calls are mocked (
patch_agentintests/fixtures_assistant.py). Never call a real provider from tests. - Generated scripts are compared byte for byte in
tests/tests_rendering/and executed as real files intests/test_integration_standalone_script.py. LLM contexts have goldens intests/tests_llm/golden/; regenerate them only when the change is intentional and review the diff. - A new
ExplainableResultneeds a builder intests/fixtures_llm.py; the contract test discovers subclasses and fails otherwise. - Warnings are errors (
filterwarnings = errorinpyproject.toml). A test that expects a warning wraps the call inpytest.warns; a third-party warning that cannot be fixed here gets a targetedignoreentry inpyproject.tomlwith its reason. Never add a blanket ignore. tests/test_import_without_llm_extra.pyguards that importing the package does not load pydantic-ai, andtests/test_integration_determinism.pyguards that the same input yields the same profile, plan, script and predictions.
Working with the user
- In a local session, commit finished work without asking, on a working
branch (
feature/,fix/,docs/,chore/orperf/), never onmain, and on the release branchX.Y.xonly when the user asks for a direct change there (notes, docs, harness, synced assets); package code goes through a pull request. Ask before pushing; once a push is approved, opening the pull request needs no further confirmation. Never merge a pull request without the author's confirmation. - An autonomous remote session commits and pushes to its own branch, named
feature/<slug>,fix/<slug>,docs/<slug>,chore/<slug>orperf/<slug>, or to the release branch when asked as above. Never push tomain, never force push, and do not open a pull request unless asked. - Commits and pull requests carry only the author's identity: no
Co-Authored-Bytrailer for an AI agent, no session link trailer and no "Generated with" or "Generated by" line. The author identity comes from git config orGIT_AUTHOR_*andGIT_COMMITTER_*; do not override it. - Any user-visible change (API, CLI output, generated scripts, warnings)
gets an entry in
docs/releases/releases.mdunder the unreleased version. - A new, renamed or removed docs page updates its search engine title and
description in
tools/docs/hooks/page_meta.yml(notebooks cannot carry front matter);python tools/docs/hooks/page_meta.pychecks the coverage and the rules written at the top of the YAML. - A change to
llm/context.py,llm/prompts.pyor the rendered explanations needs a run oftools/ai/check_ask_context.pyagainst a real model before the release (it costs money, so the user launches it), and the reviewed report is saved as described intools/ai/ask_context_reports/README.md. skforecast_ai/skills/andskforecast_ai/resources/llms-base.txtare synced from the skforecast repository withtools/ai/sync_skforecast_assets.py;.github/copilot-instructions.mdis generated upstream. Do not edit any of them here. Every sync also rewrites the token estimates inllm/skills.py. When a sync adds, removes or renames a skill, the script lists the change and the files maintained by hand:llm/skills.py(ALL_SKILLSand the routing tables), the table indocs/user-guides/skills.md(tests/test_docs_skills_page.pychecks it againstALL_SKILLS) and the upstream-order test intests/tests_llm/test_select_skills.py.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

