Metadata-Version: 2.4
Name: mpl-plot-report
Version: 0.1.0
Summary: Structured plot metadata and diagnostics for Matplotlib (agent-friendly sidecars)
Author: Pierre Lacerte
License: MIT
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: matplotlib
Requires-Dist: numpy
Description-Content-Type: text/markdown

# mpl-plot-report

Export Matplotlib figures as deterministic JSON + Markdown sidecars for
LLM-friendly plot debugging. PNGs are emitted as secondary artifacts.

## Installation

Using uv:

```bash
uv sync
```

Using pip:

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e .[dev]
```

## Minimal usage

```python
import matplotlib

matplotlib.use("Agg")
import matplotlib.pyplot as plt
import numpy as np

from mpl_plot_report import dump_report

x = np.linspace(0, 10, 200)
y = np.sin(x)
fig, ax = plt.subplots()
ax.plot(x, y, label="signal")

dump_report(
    fig,
    out_dir="plots/run_001",
    stem="signal",
    context={"run_id": "run_001", "style_name": "default"},
)
```

## CLI usage

You can point the CLI at a module that exposes a callable returning a
Matplotlib Figure (default callable name: `make_figure`).

```bash
uv run mpl-plot-report --module my_module --callable make_figure --out-dir plots/run_001 --stem signal
```

Or provide a run id and let the CLI create `plots/<run_id>` automatically:

```bash
uv run mpl-plot-report --module my_module --run-id run_001 --stem signal
```

## Output files

For a stem like `signal`, the exporter writes:

- `signal.png`
- `signal.plot.json`
- `signal.plot.md`

The JSON is the source of truth for agents and CI. Markdown is a concise
human-facing summary, and PNGs are optional.

## Rulesets

Domain rules should live in consumer projects and be injected at runtime.
Define a `RuleSet` (or iterable of `Rule`) and pass it to `dump_report`:

```python
from mpl_plot_report import dump_report
from mpl_plot_report.rules import Rule, RuleSet


def always_ok(report):
    return True, "ok", None


ruleset = RuleSet([Rule("demo.always_ok", "warn", always_ok)])
dump_report(fig, out_dir="plots", stem="example", ruleset=ruleset)
```

See a minimal module example at `examples/ruleset_demo.py`.

## Tests

```bash
uv run pytest
```

Single test examples:

```bash
uv run pytest tests/test_report.py
uv run pytest tests/test_report.py::test_dump_report_creates_sidecars
```

## Fixtures

Synthetic fixtures live under `tests/fixtures/expected/`. Regenerate them with:

```bash
uv run python scripts/generate_fixtures.py
```
