Skip to content

Use mesqual with agents

mesqual is made for humans and agents alike. This page gives the skill that ships with mesqual, a snippet for the AGENTS.md of your project, and llms.txt, an index of these docs for language models. What agent-ready means lists what makes mesqual ready for agents, with a link to each.

What agent-ready means

  • Describe methods with JSON-ready output. as_records=True gives plain dicts on StudyManager.describe_study, describe_datasets and describe_flags. dataset.flag_info(flag).as_record() does the same for one flag. These calls load no time series data (Describe a dataset).
  • Offline synthetic data. mesqual.testing builds a study without network access and without an external platform:

    from mesqual.testing import make_dummy_study
    study = make_dummy_study()
    
  • Error messages that name the allowed values. Examples on dataset = study.scen.get_dataset('base') of the synthetic study:

    >>> dataset.fetch('Node.Results.price', solution='x')
    ValueError: Flag Node.Results.price: 'x' is not a value of 'solution'. Allowed: ['first', 'final'].
    >>> dataset.fetch('Node.Results.price', bogus=1)
    ValueError: Flag Node.Results.price: no flag spec or dataset class declares the parameters ['bogus']. Declared: ['solution'].
    

    A FlagUnavailableError names the flag, the dataset and the reason. An UnknownFlagError only says that no spec declares the flag: it does not name the fix, also when the layer in the flag name is unknown. Use describe_flags then. Section 10 of the skill, "When a call fails", lists the steps. - A versioned API with a change log. mesqual follows semantic versioning. The public API is a contract, and each API change and bug fix after 2.0.0 has an entry with its bump in the CHANGELOG. - Declared dependency floors. pyproject.toml requires Python 3.11 or later, pandas>=2.1, numpy>=1.23.2, matplotlib>=3.6 and pint>=0.24.4. Other dependencies have no floor. CI tests Python 3.11 to 3.14 with the latest dependencies. It does not test the dependency floors. - Outputs that an agent can check as text. fetch returns a pandas DataFrame or Series, KPICollection.to_dataframe() returns a frame of KPIs. Changed text values of a comparison have text markers, see the conventions. The skill says to check the numbers as text before you build figures. - An index for language models. llms.txt lists the pages of these docs, one line each. - A skill for the workflow. mesqual-study ships with the package. See Install the skill.

Install the skill

mesqual ships the skill mesqual-study in the Agent Skills format. It gives the workflow of an analysis in a study and links into these docs. Install it once per project, and again after each upgrade of mesqual, with the same options. Run the command yourself, or give it to your agent as a task:

python -m mesqual.skills install .            # to ./.agents/skills/mesqual-study/
python -m mesqual.skills install . --claude   # also to ./.claude/skills/mesqual-study/, for Claude Code

The command prints one line per skill folder, with its path and created, updated or unchanged. The shipped files overwrite files of the same name; other files in the skill folder stay. After an upgrade, paste the snippet below again too: it holds the conventions of the installed version. Commit the skill folders (.agents/skills/, and .claude/skills/ with --claude), so every clone has them.

Snippet for AGENTS.md

Paste this section into the AGENTS.md of your project:

## mesqual

This project analyzes energy market simulations with mesqual (https://docs.mesqual.io). The skill `mesqual-study` gives the workflow of an analysis. It is the file `.agents/skills/mesqual-study/SKILL.md` (or `.claude/skills/mesqual-study/SKILL.md`): read it if you do not load skills. If the file is missing, see https://docs.mesqual.io/use-with-agents/.

Never guess a flag name. Ask the study first. These calls load no time series data:

- `study.describe_study(as_records=True)`: the scenarios, the comparisons and the flags of each, as plain dicts.
- `study.scen.describe_datasets(max_depth=1, as_records=True)`: the scenarios with descriptions and attributes.
- `dataset.describe_flags(contains='price', as_records=True)`: the flags of one dataset, with availability and parameters.
- `dataset.flag_info(flag).as_record()`: description, unit, schema and parameters of one flag.
- A name with `{...}` is the template of a spec with variants: `describe_flags` gives one row per spec. Replace each placeholder with one of its values from the column `variants`: `{area_layer}.Results.price` with `area_layer` `Country` gives `Country.Results.price`. `fetch` does not accept the template. `contains=` also matches the full names, for example `contains='generation_gas'`.

The result of `fetch`:

- `fetch` returns a pandas DataFrame or Series. The flag spec declares its index and column levels: the `schema` of `dataset.flag_info(flag)`. By default, a time series has a time index and one column per object of its model flag, for example per `Node`. For a model flag, the column level is unnamed (`None: dimension`).
- `study.scen` and `study.comp` add a column level on top, with the name of each scenario or comparison. `study.scen_comp` adds the level `type` above it. `study.scen.flag_info(flag).schema` shows all levels of a collection result, the collection levels included. With `StudyManager.factory_from_scenarios`, the scenario or comparison level is named `dataset`, the values of `type` are `scenario` and `comparison`, and a comparison is named `<variation> vs <reference>`.
- A comparison gives variation minus reference for numbers by default (parameter `comparison_type`). For text values, an unchanged entry keeps its value, a changed entry becomes `<variation> (was <reference>)`, an entry that only the reference has becomes `DELETED: <reference>`, and an entry that only the variation has becomes `<variation> (new)`. `comparison_type=ComparisonTypeEnum.BOTH` puts variation and reference side by side, in a last column level `compared` that `study.comp.flag_info(flag).schema` does not show.
- A scenario that lacks an object has no column for it in a time series. With `DELTA` (default) and `BOTH`, a comparison has the entries (objects and rows) of both sides; `VARIATION` has the entries of the variation. For numbers in a `DELTA`, a missing side counts as the `fill_value`: the parameter of the comparison, by default the value of the flag spec. Without a fill value, the result is NaN there.
- The collections join the results of their datasets outer. So a scenario has NaN where it has no value, for example outside its horizon. A comparison fills such entries with its `fill_value` first, as above.
- A collection leaves out a dataset on which the flag is unavailable: that dataset has no columns. If the flag is unavailable on all datasets, `fetch` raises `FlagUnavailableError`.
- The values are in the `unit` of `dataset.flag_info(flag)`: the unit of the flag spec, or for a layer flag the unit of its base spec (`unit_source`). The result carries no unit, and `fetch` converts no units.

Where the conventions come from