mpl-plot-report 0.1.0__tar.gz

mpl_plot_report-0.1.0/.gitignore

@@ -0,0 +1 @@
+*.pyc

mpl_plot_report-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

mpl_plot_report-0.1.0/AGENTS.md

@@ -0,0 +1,182 @@
+# Agent Guide for mpl-plot-report
+
+This repo is a small Python package intended to export Matplotlib plot reports
+as JSON + Markdown sidecars. The guidance here is for agentic coding tools.
+
+## Quick Start
+
+- Python version: 3.13 (see `.python-version`).
+- Dependencies are tracked in `pyproject.toml` and `uv.lock`.
+- If you use `uv`, prefer `uv sync` or `uv run ...`.
+- If you use `pip`, create a venv and install from `pyproject.toml`.
+
+## Build / Lint / Test
+
+The project is currently very small and uses `pytest` and `black`.
+
+### Install / Sync
+
+- `uv sync`
+- `python -m venv .venv && . .venv/bin/activate && pip install -e .[dev]`
+
+### Tests
+
+- Run all tests: `uv run pytest` or `python -m pytest`
+- Run a single file: `uv run pytest tests/test_module.py`
+- Run a single test: `uv run pytest tests/test_module.py::TestClass::test_name`
+- Run by keyword: `uv run pytest -k "keyword"`
+
+### Lint / Format
+
+- Format: `uv run black .` or `python -m black .`
+- Check formatting: `uv run black --check .`
+
+### Build / Packaging
+
+This repository is not yet wired with a build tool, but common options are:
+
+- `uv build` (if using uv)
+- `python -m build` (requires `build` dependency)
+
+If you need to add a build step, update this file with the exact command.
+
+## Cursor / Copilot Rules
+
+No Cursor rules found in `.cursor/rules/` or `.cursorrules`.
+No Copilot instructions found in `.github/copilot-instructions.md`.
+
+## Code Style Guidelines
+
+This repo is early-stage; prefer simple, explicit Python with a focus on
+determinism and readability. Use the following conventions unless a file
+explicitly establishes something else.
+
+### Formatting
+
+- Use Black defaults (4-space indents, line length per Black).
+- Keep imports sorted in logical groups (stdlib, third-party, local).
+- Avoid trailing whitespace and excessive blank lines.
+- Prefer short, descriptive lines over dense one-liners.
+
+### Imports
+
+- Group imports with a blank line between groups.
+- Favor module imports over wildcard imports.
+- Keep Matplotlib usage explicit: `import matplotlib.pyplot as plt`.
+- Keep NumPy usage explicit: `import numpy as np`.
+
+### Types
+
+- Add type hints for public APIs and data structures.
+- Use `typing` module constructs where helpful (e.g., `Sequence`, `Mapping`).
+- Prefer `dict[str, Any]` or `Mapping[str, Any]` for free-form context.
+- Use `dataclasses` for schema-like objects when appropriate.
+
+### Naming
+
+- Functions and variables: `snake_case`.
+- Classes and dataclasses: `PascalCase`.
+- Constants: `UPPER_SNAKE_CASE`.
+- Keep rule/diagnostic identifiers stable and deterministic.
+
+### Error Handling
+
+- Fail fast on invariant violations when appropriate.
+- Use exceptions for programmer errors; return structured warnings for data
+  issues that should not crash the exporter.
+- Report non-fatal issues in the report `warnings[]` field.
+- Prefer explicit error messages over silent fallbacks.
+
+### Determinism and Reproducibility
+
+- Stable ordering: axes by `fig.axes`, series by `ax.lines`.
+- Stable IDs: derive from axis index + series index + label.
+- Numeric rounding must be controlled by a single `float_precision` parameter.
+- Use a deterministic decimation strategy when `n > max_points`.
+
+### JSON + Markdown Outputs
+
+- Always emit `<stem>.plot.json` and `<stem>.plot.md` sidecars.
+- Keep the schema version pinned and documented.
+- Prefer predictable key ordering when serializing.
+
+### Matplotlib / Headless
+
+- Use the Agg backend for test figures and headless runs.
+- PNGs are secondary; JSON is the source of truth for agents.
+
+### Diagnostics and Invariants
+
+- Diagnostics are numeric and data-driven, not visual.
+- Invariants encode expectations, not observations.
+- Domain-specific rules must remain in consumer projects.
+- Report FAIL invariants first; WARN invariants must include rationale.
+
+### Tests and Fixtures
+
+- Tests should be deterministic and fast.
+- Prefer small synthetic fixtures for core engine tests.
+- Keep fixtures in `tests/fixtures/` (synthetic, expected, curated).
+- Avoid brittle golden-value assertions until the schema stabilizes.
+
+## Agent Workflow Requirements (from `agent.md`)
+
+Use this as the default workflow when adding or modifying behavior.
+
+1) Generate 2-3 minimal figures for smoke/regression:
+   - Happy path line plot (strictly increasing x, smooth y)
+   - Pathology with NaNs/inf and non-monotonic x
+   - Pathology with wiggles/jumps/outliers
+2) Export sidecars for each figure:
+   - PNG
+   - `.plot.json`
+   - `.plot.md`
+3) Inspect JSON before PNGs:
+   - FAIL invariants first
+   - WARN invariants next
+   - Diagnostics for rationale
+4) Propose fixes, re-run, compare reports.
+
+CI / regression intent:
+
+- Store `.plot.json` fixtures for the 2-3 minimal figures.
+- CI should assert zero FAILs on happy path.
+- CI should assert expected FAIL/WARN signatures on pathology cases.
+- Use JSON diffs for regression review.
+
+Escalation policy:
+
+- FAIL invariants: stop and propose fix.
+- WARN invariants: justify or refine rule.
+- Clean report: accept plot without image review.
+
+## Preferred Structure (from docs)
+
+The implementation plan proposes this layout (once implemented):
+
+- `mpl_plot_report/api.py`: `dump_report()` and `build_report()`
+- `mpl_plot_report/extract.py`: figure/axes/line extraction
+- `mpl_plot_report/diagnostics.py`: numeric metrics
+- `mpl_plot_report/rules.py`: `Rule`, `RuleResult`, `RuleSet`
+- `mpl_plot_report/schema.py`: dataclasses + schema version
+- `mpl_plot_report/render_md.py`: Markdown renderer
+- `mpl_plot_report/util.py`: hashing/rounding/decimation
+
+If you add these files, follow the conventions above.
+
+## README Expectations (future)
+
+Once core API and tests are stable, update `README.md` with:
+
+- Installation (uv/pip)
+- Minimal usage snippet calling `dump_report`
+- Expected output files (`.png`, `.plot.json`, `.plot.md`)
+- How to supply a consumer `ruleset`
+- How to run tests and where fixtures live
+
+## Notes for Agents
+
+- Favor clear, minimal diffs; avoid large refactors unless required.
+- Keep the engine domain-neutral; do not encode project-specific rules.
+- Prefer small, composable helpers over monolithic functions.
+- When in doubt, document the reasoning in the report output.

mpl_plot_report-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 placerte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mpl_plot_report-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+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
+```

mpl_plot_report-0.1.0/README.md

@@ -0,0 +1,111 @@
+# 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
+```

mpl_plot_report-0.1.0/agent.md

@@ -0,0 +1,95 @@
+## Agent Workflow — Plot Report Sidecars
+
+### Objective
+Enable blind-friendly, deterministic critique of plots by agents using structured plot reports instead of rendered images.
+
+---
+
+### Minimal Test Figures (agent-generated)
+The agent should generate 2–3 figures as a smoke/regression harness for the plot-report engine:
+
+1) **Happy path line plot**
+- x strictly increasing
+- smooth y
+- should produce zero FAILs and minimal WARNs
+
+2) **Pathology: NaNs / inf / ordering**
+- inject NaNs or inf in y
+- optionally shuffle a segment of x (non-monotonic)
+- should surface non-finite warnings and ordering/dx invariants
+
+3) **Pathology: wiggles / jumps / outliers**
+- piecewise y with a step/jump + high-frequency wiggle region
+- should trigger outlier metrics and wiggle/curvature diagnostics
+
+These plots must be generated headlessly (Agg) and exported to:
+- PNG
+- `.plot.json`
+- `.plot.md`
+
+---
+
+### Standard Debugging Loop
+
+1. **Run** plotting code to generate figures
+2. **Export** sidecar reports:
+   - `<stem>.plot.json`
+   - `<stem>.plot.md`
+3. **Agent inspects JSON**:
+   - invariant failures (FAIL first)
+   - warnings (NaN, decimation, ordering issues)
+   - suspicious diagnostics (wiggles, slope variance, outliers)
+4. **Agent proposes changes**:
+   - data corrections (ordering, NaN handling)
+   - plotting fixes (scale, limits, labels, units)
+   - invariant refinements (domain rules, if any)
+5. **Re-run and compare** reports
+
+---
+
+### What the Agent Should Rely On
+
+- JSON report as the primary truth
+- Invariant results as correctness signals
+- Diagnostics to explain *why* something failed
+
+PNG viewing is secondary and optional.
+
+---
+
+### What the Agent Must Avoid
+
+- Judging correctness from PNGs alone
+- Guessing intent without reading invariants
+- Adding domain rules to the generic engine
+
+---
+
+### CI / Regression Strategy
+
+- Store `.plot.json` fixtures for the 2–3 test figures above
+- CI asserts:
+  - zero FAIL invariants for the happy-path figure
+  - expected FAIL/WARN signatures for pathology figures
+- JSON diffs used for regression review
+
+---
+
+### Escalation Policy
+
+- FAIL invariants → stop and propose fix
+- WARN invariants → justify or refine rule
+- Clean report → accept plot without image review
+
+---
+
+### After Green Tests
+
+Once the package implementation is complete and tests pass:
+- Draft a practical `README.md` for the standalone repo covering:
+  - installation (uv/pip)
+  - minimal Python usage (one small snippet calling `dump_report`)
+  - expected output files (`.png`, `.plot.json`, `.plot.md`)
+  - how to supply a `ruleset` from a consumer project
+  - how to run tests and where fixtures live
+

mpl_plot_report-0.1.0/docs/handoff.md

@@ -0,0 +1,161 @@
+# Handoff — Make `.plot.md` verbose, explicit, and agent-friendly
+
+## Objective
+Upgrade `mpl_plot_report` so the generated Markdown sidecar (`<stem>.plot.md`) is **useful on its own** for both humans and agents.
+
+Current behavior is too minimal when there are no warnings/invariants; it often prints only counts and headings.
+
+Target behavior:
+- `.plot.json` remains the source of truth
+- `.plot.md` becomes a structured, readable projection of the JSON
+- Do **not** dump full point arrays; include summaries and optional small samples
+- Include a link/embed reference to the PNG so a human can open it quickly
+
+---
+
+## Required `.plot.md` content (v1)
+
+### 0) Header
+Include:
+- Title: `<stem>`
+- Timestamp / run_id (from `context`)
+- git_hash (from `context`, if present)
+- inputs + key parameters (from `context`)
+- style identity: style name + rcParams hash (from `context.style`)
+
+### 1) PNG reference
+Add a prominent section near the top:
+- If PNG is in the same folder: include markdown image reference `![](<stem>.png)`
+  - This works on GitHub-rendered markdown and many viewers.
+- Also include a plain path line for non-rendering environments.
+
+### 2) Warnings
+- Always print a `Warnings` section.
+- If empty, explicitly print `None`.
+
+### 3) Invariants / Rules
+- Always print an `Invariant Results` section.
+- Show FAIL first, then WARN, then PASS (if present).
+- For each result:
+  - rule_id
+  - severity
+  - passed
+  - message
+  - where (axis index, series id/label, index ranges)
+
+### 4) Axes details (per axis)
+For each axis, print:
+- title
+- xlabel / ylabel
+- xscale / yscale
+- xlim / ylim
+- legend entries (or `None`)
+
+### 5) Series details (per series)
+For each series (v1: `Line2D`):
+- series id
+- label
+- kind
+
+**Stats**
+- n
+- x_min/x_max, y_min/y_max
+- first point / last point
+
+**Diagnostics** (print all fields in a stable order)
+- Non-finite: count + indices/ranges if available
+- dx sanity: min/median/non-positive count
+- dy outliers: max |dy|, robust z max, outlier count
+- slope stats: mean/median/std + quantiles if present
+- wiggles: sign-change count, wiggle score
+- curvature: std, max abs, sign changes
+
+**Data sample (optional but recommended)**
+- If `include_data=True`, do not dump full arrays.
+- Print:
+  - decimation info (original_n, max_points, method)
+  - first 5 (x,y) pairs
+  - last 5 (x,y) pairs
+
+### 6) JSON echo (optional)
+If you want “expose all JSON data” without full points:
+- Add a final section `Raw JSON (minus points)`
+- Print a pretty JSON block where `series[].data.x` and `series[].data.y` are replaced with:
+  - `{"omitted": true, "n": <n>, "sample": {"head": [...], "tail": [...]}}`
+
+This makes MD self-contained while avoiding megabytes of data.
+
+---
+
+## API changes (allowed)
+Keep existing API stable. If you add knobs, make them optional:
+
+- `md_mode: Literal["summary","full"] = "full"` (default to full to satisfy this spec)
+- `md_data_sample: int = 5` (head/tail sample size)
+- `md_include_png_embed: bool = True`
+
+No breaking changes.
+
+---
+
+## Implementation notes
+
+### Where to implement
+- `mpl_plot_report/render_md.py`
+  - Add a `render_report_full(report: dict, *, stem: str | None = None, md_data_sample: int = 5, md_include_png_embed: bool = True) -> str`
+  - Keep the existing renderer as `summary` or remove if unused.
+
+### Stable ordering
+Make the Markdown diff-friendly:
+- Use deterministic ordering for:
+  - axes
+  - series
+  - diagnostic keys (define an explicit list)
+
+### Avoid point dumps
+Even if JSON contains decimated points, MD should only show head/tail samples.
+
+---
+
+## Tests to add
+
+1) `test_md_full_has_required_sections`
+- Generate the happy-path synthetic figure
+- Assert `.plot.md` includes:
+  - PNG embed line
+  - Context header fields
+  - Warnings section
+  - Invariant Results section
+  - Axes and Series sections
+
+2) `test_md_reports_nonfinite_and_ordering`
+- Generate pathology figure (NaN + non-monotonic x)
+- Assert `.plot.md` contains:
+  - non-finite count > 0
+  - dx_non_positive_count > 0 (or equivalent)
+  - warning(s)
+
+3) `test_md_does_not_dump_full_arrays`
+- Generate a long series (n >> max_points)
+- Assert `.plot.md` length stays under a reasonable bound or that it contains `head`/`tail` samples and does not contain thousands of comma-separated floats.
+
+---
+
+## Definition of done
+- `.plot.md` is substantially informative even when warnings/invariants are empty.
+- PNG is referenced at top.
+- All diagnostics visible (not hidden in JSON only).
+- Point arrays not dumped; only samples.
+- Tests pass headlessly.
+
+---
+
+## After this task
+Once the MD verbosity upgrade is complete and tests pass:
+- Draft `README.md` for the repo:
+  - installation (uv/pip)
+  - minimal usage example calling `dump_report`
+  - explain the 3 artifacts (`.png`, `.plot.json`, `.plot.md`)
+  - how to inject a `ruleset` from consumer projects
+  - how to run tests + fixtures layout
+