mpl-plot-report 0.1.0__py3-none-any.whl

mpl_plot_report/__init__.py

@@ -0,0 +1,5 @@
+"""Public API for mpl_plot_report."""
+
+from mpl_plot_report.api import build_report, dump_report
+
+__all__ = ["build_report", "dump_report"]

mpl_plot_report/api.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+import matplotlib
+
+from mpl_plot_report.extract import extract_figure
+from mpl_plot_report.render_md import render_report_full
+from mpl_plot_report.rules import RuleResult, coerce_ruleset
+from mpl_plot_report.schema import SCHEMA_VERSION
+from mpl_plot_report.util import hash_rcparams, round_floats
+
+
+def build_report(
+    fig,
+    *,
+    context: Mapping[str, Any] | None = None,
+    ruleset=None,
+    include_data: bool = True,
+    max_points: int = 2000,
+    float_precision: int = 6,
+) -> dict[str, Any]:
+    context_payload = dict(context or {})
+    rcparams_hash = hash_rcparams(matplotlib.rcParams)
+    context_payload.setdefault(
+        "style",
+        {
+            "name": context_payload.get("style_name"),
+            "rcparams_hash": rcparams_hash,
+        },
+    )
+
+    axes_payload, warnings = extract_figure(
+        fig,
+        include_data=include_data,
+        max_points=max_points,
+    )
+
+    report: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "context": context_payload,
+        "figure": {
+            "dpi": float(fig.dpi),
+            "size_inches": [float(v) for v in fig.get_size_inches()],
+            "backend": matplotlib.get_backend(),
+        },
+        "axes": axes_payload,
+        "invariants": [],
+        "warnings": warnings,
+    }
+
+    rules = coerce_ruleset(ruleset)
+    if rules:
+        invariants: list[RuleResult] = rules.evaluate(report)
+        report["invariants"] = [inv.__dict__ for inv in invariants]
+
+    return round_floats(report, float_precision)
+
+
+def dump_report(
+    fig,
+    out_dir: str | Path,
+    stem: str,
+    *,
+    context: Mapping[str, Any] | None = None,
+    ruleset=None,
+    include_data: bool = True,
+    max_points: int = 2000,
+    float_precision: int = 6,
+    md_mode: str = "full",
+    md_data_sample: int = 5,
+    md_include_png_embed: bool = True,
+) -> dict[str, Any]:
+    report = build_report(
+        fig,
+        context=context,
+        ruleset=ruleset,
+        include_data=include_data,
+        max_points=max_points,
+        float_precision=float_precision,
+    )
+
+    out_path = Path(out_dir)
+    out_path.mkdir(parents=True, exist_ok=True)
+
+    png_path = out_path / f"{stem}.png"
+    json_path = out_path / f"{stem}.plot.json"
+    md_path = out_path / f"{stem}.plot.md"
+
+    fig.savefig(png_path)
+
+    json_path.write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    if md_mode == "summary":
+        md_content = render_report_full(
+            report,
+            stem=stem,
+            md_data_sample=md_data_sample,
+            md_include_png_embed=md_include_png_embed,
+        )
+    else:
+        md_content = render_report_full(
+            report,
+            stem=stem,
+            md_data_sample=md_data_sample,
+            md_include_png_embed=md_include_png_embed,
+        )
+    md_path.write_text(md_content, encoding="utf-8")
+
+    return report

mpl_plot_report/cli.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib import import_module
+from typing import Any, Callable
+
+import matplotlib
+
+from mpl_plot_report.api import dump_report
+
+
+def _load_callable(module_path: str, callable_name: str) -> Callable[..., Any]:
+    module = import_module(module_path)
+    try:
+        target = getattr(module, callable_name)
+    except AttributeError as exc:
+        raise SystemExit(
+            f"Callable '{callable_name}' not found in module '{module_path}'."
+        ) from exc
+    if not callable(target):
+        raise SystemExit(f"{module_path}.{callable_name} is not callable.")
+    return target
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Export Matplotlib plot reports.")
+    parser.add_argument(
+        "--module",
+        required=True,
+        help="Module path containing a callable that returns a Figure.",
+    )
+    parser.add_argument(
+        "--callable",
+        default="make_figure",
+        help="Callable name that returns a Matplotlib Figure.",
+    )
+    parser.add_argument("--out-dir", help="Output directory.")
+    parser.add_argument("--stem", required=True, help="Output file stem.")
+    parser.add_argument(
+        "--run-id",
+        help="Run identifier; uses plots/<run_id> when --out-dir is omitted.",
+    )
+    parser.add_argument(
+        "--context",
+        default="{}",
+        help="JSON string for context metadata.",
+    )
+    parser.add_argument(
+        "--max-points",
+        type=int,
+        default=2000,
+        help="Maximum number of points per series.",
+    )
+    parser.add_argument(
+        "--float-precision",
+        type=int,
+        default=6,
+        help="Float rounding precision for report output.",
+    )
+    parser.add_argument(
+        "--no-data",
+        action="store_true",
+        help="Exclude raw series data from JSON output.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv or sys.argv[1:])
+    matplotlib.use("Agg")
+
+    if args.out_dir is None and not args.run_id:
+        raise SystemExit("Provide --out-dir or --run-id.")
+    out_dir = args.out_dir or f"plots/{args.run_id}"
+
+    try:
+        context = json.loads(args.context)
+    except json.JSONDecodeError as exc:
+        raise SystemExit("--context must be valid JSON.") from exc
+
+    figure_factory = _load_callable(args.module, args.callable)
+    fig = figure_factory()
+
+    dump_report(
+        fig,
+        out_dir,
+        args.stem,
+        context=context,
+        include_data=not args.no_data,
+        max_points=args.max_points,
+        float_precision=args.float_precision,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mpl_plot_report/diagnostics.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def _safe_stat(values: np.ndarray, func) -> float | None:
+    if values.size == 0:
+        return None
+    return float(func(values))
+
+
+def _robust_z_stats(values: np.ndarray) -> tuple[float | None, int]:
+    if values.size == 0:
+        return None, 0
+    median = float(np.median(values))
+    mad = float(np.median(np.abs(values - median)))
+    if mad == 0.0:
+        return 0.0, 0
+    z = 0.6745 * (values - median) / mad
+    max_abs = float(np.max(np.abs(z)))
+    outliers = int(np.sum(np.abs(z) > 3.5))
+    return max_abs, outliers
+
+
+def compute_diagnostics(x: np.ndarray, y: np.ndarray) -> dict[str, Any]:
+    diagnostics: dict[str, Any] = {}
+
+    n = int(len(x))
+    finite_mask = np.isfinite(x) & np.isfinite(y)
+    diagnostics["n"] = n
+    diagnostics["non_finite_count"] = int(n - np.count_nonzero(finite_mask))
+
+    x_finite = x[np.isfinite(x)]
+    dx = np.diff(x_finite) if x_finite.size > 1 else np.array([])
+    diagnostics["dx_min"] = _safe_stat(dx, np.min)
+    diagnostics["dx_median"] = _safe_stat(dx, np.median)
+    diagnostics["dx_non_positive_count"] = int(np.sum(dx <= 0)) if dx.size else 0
+
+    y_finite = y[finite_mask]
+    x_for_slope = x[finite_mask]
+    dy = np.diff(y_finite) if y_finite.size > 1 else np.array([])
+    diagnostics["dy_max_abs"] = _safe_stat(np.abs(dy), np.max)
+    robust_z, outlier_count = _robust_z_stats(dy)
+    diagnostics["dy_robust_z_max"] = robust_z
+    diagnostics["dy_outlier_count"] = outlier_count
+
+    slope = np.array([])
+    if x_for_slope.size > 1:
+        dx_slope = np.diff(x_for_slope)
+        dy_slope = np.diff(y_finite)
+        valid = dx_slope != 0
+        if np.any(valid):
+            slope = dy_slope[valid] / dx_slope[valid]
+
+    diagnostics["slope_mean"] = _safe_stat(slope, np.mean)
+    diagnostics["slope_median"] = _safe_stat(slope, np.median)
+    diagnostics["slope_std"] = _safe_stat(slope, np.std)
+    diagnostics["slope_p10"] = _safe_stat(slope, lambda v: np.quantile(v, 0.1))
+    diagnostics["slope_p90"] = _safe_stat(slope, lambda v: np.quantile(v, 0.9))
+
+    slope_signs = np.sign(slope)
+    slope_signs = slope_signs[slope_signs != 0]
+    diagnostics["wiggle_sign_changes"] = (
+        int(np.sum(slope_signs[1:] != slope_signs[:-1])) if slope_signs.size > 1 else 0
+    )
+
+    curvature = np.diff(y_finite, n=2) if y_finite.size > 2 else np.array([])
+    diagnostics["curvature_std"] = _safe_stat(curvature, np.std)
+    diagnostics["curvature_max_abs"] = _safe_stat(np.abs(curvature), np.max)
+    curvature_signs = np.sign(curvature)
+    curvature_signs = curvature_signs[curvature_signs != 0]
+    diagnostics["curvature_sign_changes"] = (
+        int(np.sum(curvature_signs[1:] != curvature_signs[:-1]))
+        if curvature_signs.size > 1
+        else 0
+    )
+
+    return diagnostics

mpl_plot_report/extract.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from matplotlib.lines import Line2D
+
+from mpl_plot_report.diagnostics import compute_diagnostics
+from mpl_plot_report.util import decimate_series, make_stable_id
+
+
+def _safe_min(values: np.ndarray) -> float | None:
+    if values.size == 0:
+        return None
+    finite = values[np.isfinite(values)]
+    if finite.size == 0:
+        return None
+    return float(np.min(finite))
+
+
+def _safe_max(values: np.ndarray) -> float | None:
+    if values.size == 0:
+        return None
+    finite = values[np.isfinite(values)]
+    if finite.size == 0:
+        return None
+    return float(np.max(finite))
+
+
+def _series_stats(x: np.ndarray, y: np.ndarray) -> dict[str, Any]:
+    stats: dict[str, Any] = {
+        "n": int(len(x)),
+        "x_min": _safe_min(x),
+        "x_max": _safe_max(x),
+        "y_min": _safe_min(y),
+        "y_max": _safe_max(y),
+        "x_endpoints": [float(x[0]), float(x[-1])] if len(x) else None,
+        "y_endpoints": [float(y[0]), float(y[-1])] if len(y) else None,
+    }
+    return stats
+
+
+def extract_figure(
+    fig,
+    *,
+    include_data: bool,
+    max_points: int,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    axes_payload: list[dict[str, Any]] = []
+    warnings: list[dict[str, Any]] = []
+
+    for axis_index, ax in enumerate(fig.axes):
+        legend_labels = []
+        if ax.get_legend() is not None:
+            _, labels = ax.get_legend_handles_labels()
+            legend_labels = [label for label in labels if label]
+
+        axis_payload: dict[str, Any] = {
+            "index": axis_index,
+            "title": ax.get_title(),
+            "xlabel": ax.get_xlabel(),
+            "ylabel": ax.get_ylabel(),
+            "xscale": ax.get_xscale(),
+            "yscale": ax.get_yscale(),
+            "xlim": list(ax.get_xlim()),
+            "ylim": list(ax.get_ylim()),
+            "legend": legend_labels,
+            "series": [],
+        }
+
+        for series_index, line in enumerate(ax.lines):
+            if not isinstance(line, Line2D):
+                continue
+            x = np.asarray(line.get_xdata(), dtype=float)
+            y = np.asarray(line.get_ydata(), dtype=float)
+
+            if x.size != y.size:
+                min_len = min(x.size, y.size)
+                warnings.append(
+                    {
+                        "code": "length_mismatch",
+                        "message": "Line2D x/y lengths do not match; truncating.",
+                        "where": {
+                            "axis_index": axis_index,
+                            "series_index": series_index,
+                        },
+                    }
+                )
+                x = x[:min_len]
+                y = y[:min_len]
+
+            label = line.get_label() or ""
+            if not label or label.startswith("_"):
+                label = f"series_{series_index}"
+
+            series_id = make_stable_id(axis_index, series_index, label)
+            diagnostics = compute_diagnostics(x, y)
+            stats = _series_stats(x, y)
+
+            if diagnostics.get("non_finite_count", 0) > 0:
+                warnings.append(
+                    {
+                        "code": "non_finite",
+                        "message": "Series contains non-finite values.",
+                        "where": {
+                            "axis_index": axis_index,
+                            "series_index": series_index,
+                        },
+                    }
+                )
+
+            data_payload = None
+            if include_data:
+                x_use, y_use, decimation = decimate_series(x, y, max_points)
+                data_payload = {
+                    "x": x_use.tolist(),
+                    "y": y_use.tolist(),
+                    "decimation": decimation,
+                }
+
+            axis_payload["series"].append(
+                {
+                    "id": series_id,
+                    "label": label,
+                    "kind": "line2d",
+                    "data": data_payload,
+                    "stats": stats,
+                    "diagnostics": diagnostics,
+                }
+            )
+
+        axes_payload.append(axis_payload)
+
+    return axes_payload, warnings

mpl_plot_report/render_md.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+from typing import Any
+import json
+
+_DIAGNOSTIC_KEYS = [
+    "n",
+    "non_finite_count",
+    "dx_min",
+    "dx_median",
+    "dx_non_positive_count",
+    "dy_max_abs",
+    "dy_robust_z_max",
+    "dy_outlier_count",
+    "slope_mean",
+    "slope_median",
+    "slope_std",
+    "slope_p10",
+    "slope_p90",
+    "wiggle_sign_changes",
+    "curvature_std",
+    "curvature_max_abs",
+    "curvature_sign_changes",
+]
+
+
+def _format_value(value: Any) -> str:
+    if value is None:
+        return "None"
+    if isinstance(value, float):
+        return f"{value}"
+    return str(value)
+
+
+def _sample_pairs(x: list[float], y: list[float], sample: int) -> dict[str, list]:
+    if sample <= 0 or not x or not y:
+        return {"head": [], "tail": []}
+    n = min(len(x), len(y))
+    head_count = min(sample, n)
+    tail_count = min(sample, n)
+    head = list(zip(x[:head_count], y[:head_count]))
+    tail = list(zip(x[-tail_count:], y[-tail_count:]))
+    return {"head": head, "tail": tail}
+
+
+def _scrub_points(report: dict[str, Any], sample: int) -> dict[str, Any]:
+    clone = json.loads(json.dumps(report))
+    for axis in clone.get("axes", []):
+        for series in axis.get("series", []):
+            data = series.get("data")
+            if not data:
+                continue
+            x = data.get("x") or []
+            y = data.get("y") or []
+            series["data"] = {
+                "omitted": True,
+                "n": len(x),
+                "sample": _sample_pairs(x, y, sample),
+                "decimation": data.get("decimation"),
+            }
+    return clone
+
+
+def render_report_full(
+    report: dict[str, Any],
+    *,
+    stem: str | None = None,
+    md_data_sample: int = 5,
+    md_include_png_embed: bool = True,
+) -> str:
+    lines: list[str] = []
+    title = stem or "plot"
+    lines.append(f"# Plot Report: {title}")
+    lines.append("")
+
+    context = report.get("context", {})
+    style = context.get("style") or {}
+    inputs = context.get("inputs")
+    parameters = context.get("parameters")
+
+    lines.append("## Context")
+    lines.append(f"- schema_version: {report.get('schema_version')}")
+    lines.append(f"- run_id: {_format_value(context.get('run_id'))}")
+    lines.append(f"- timestamp: {_format_value(context.get('timestamp'))}")
+    lines.append(f"- git_hash: {_format_value(context.get('git_hash'))}")
+    lines.append(f"- inputs: {_format_value(inputs)}")
+    lines.append(f"- parameters: {_format_value(parameters)}")
+    lines.append(
+        "- style: name={name} rcparams_hash={hash}".format(
+            name=_format_value(style.get("name")),
+            hash=_format_value(style.get("rcparams_hash")),
+        )
+    )
+
+    lines.append("")
+    lines.append("## PNG")
+    png_name = f"{title}.png"
+    if md_include_png_embed:
+        lines.append(f"![]({png_name})")
+    lines.append(f"- png_path: {png_name}")
+
+    warnings = report.get("warnings", [])
+    lines.append("")
+    lines.append("## Warnings")
+    if warnings:
+        for warning in warnings:
+            code = warning.get("code", "warning")
+            message = warning.get("message", "")
+            where = warning.get("where")
+            where_text = f" where={where}" if where else ""
+            lines.append(f"- {code}: {message}{where_text}")
+    else:
+        lines.append("- None")
+
+    invariants = report.get("invariants", [])
+    lines.append("")
+    lines.append("## Invariant Results")
+    if invariants:
+        fails = [inv for inv in invariants if not inv.get("passed")]
+        warns = [
+            inv
+            for inv in invariants
+            if inv.get("passed") and inv.get("severity") == "warn"
+        ]
+        passes = [
+            inv
+            for inv in invariants
+            if inv.get("passed") and inv.get("severity") not in {"warn", "fail"}
+        ]
+
+        for group_name, group in (
+            ("FAIL", fails),
+            ("WARN", warns),
+            ("PASS", passes),
+        ):
+            if not group:
+                continue
+            lines.append(f"- {group_name}:")
+            for inv in group:
+                where = inv.get("where")
+                where_text = f" where={where}" if where else ""
+                lines.append(
+                    "  - {rule_id} severity={severity} passed={passed} message={message}{where}".format(
+                        rule_id=inv.get("rule_id"),
+                        severity=inv.get("severity"),
+                        passed=inv.get("passed"),
+                        message=inv.get("message"),
+                        where=where_text,
+                    )
+                )
+    else:
+        lines.append("- None")
+
+    axes = report.get("axes", [])
+    lines.append("")
+    lines.append("## Axes")
+    if not axes:
+        lines.append("- None")
+
+    for axis in axes:
+        lines.append("")
+        lines.append(f"### Axis {axis.get('index')}")
+        lines.append(f"- title: {_format_value(axis.get('title'))}")
+        lines.append(f"- xlabel: {_format_value(axis.get('xlabel'))}")
+        lines.append(f"- ylabel: {_format_value(axis.get('ylabel'))}")
+        lines.append(f"- xscale: {_format_value(axis.get('xscale'))}")
+        lines.append(f"- yscale: {_format_value(axis.get('yscale'))}")
+        lines.append(f"- xlim: {_format_value(axis.get('xlim'))}")
+        lines.append(f"- ylim: {_format_value(axis.get('ylim'))}")
+        legend = axis.get("legend") or []
+        legend_text = legend if legend else "None"
+        lines.append(f"- legend: {_format_value(legend_text)}")
+
+        series_list = axis.get("series", [])
+        if not series_list:
+            lines.append("- series: None")
+            continue
+
+        lines.append("- series:")
+        for series in series_list:
+            lines.append("")
+            lines.append(f"#### Series {series.get('id')}")
+            lines.append(f"- label: {_format_value(series.get('label'))}")
+            lines.append(f"- kind: {_format_value(series.get('kind'))}")
+
+            stats = series.get("stats", {})
+            lines.append("- stats:")
+            lines.append(f"  - n: {_format_value(stats.get('n'))}")
+            lines.append(
+                "  - x_min/x_max: {xmin} / {xmax}".format(
+                    xmin=_format_value(stats.get("x_min")),
+                    xmax=_format_value(stats.get("x_max")),
+                )
+            )
+            lines.append(
+                "  - y_min/y_max: {ymin} / {ymax}".format(
+                    ymin=_format_value(stats.get("y_min")),
+                    ymax=_format_value(stats.get("y_max")),
+                )
+            )
+            lines.append(
+                "  - first/last: {first} / {last}".format(
+                    first=_format_value(stats.get("x_endpoints")),
+                    last=_format_value(stats.get("y_endpoints")),
+                )
+            )
+
+            diagnostics = series.get("diagnostics", {})
+            lines.append("- diagnostics:")
+            for key in _DIAGNOSTIC_KEYS:
+                if key in diagnostics:
+                    lines.append(f"  - {key}: {_format_value(diagnostics.get(key))}")
+
+            data = series.get("data")
+            if data:
+                decimation = data.get("decimation", {})
+                x = data.get("x") or []
+                y = data.get("y") or []
+                samples = _sample_pairs(x, y, md_data_sample)
+                lines.append("- data_sample:")
+                lines.append(
+                    "  - decimation: original_n={n_original} max_points={max_points} method={method} decimated={decimated}".format(
+                        n_original=decimation.get("n_original"),
+                        max_points=decimation.get("max_points"),
+                        method=decimation.get("method"),
+                        decimated=decimation.get("decimated"),
+                    )
+                )
+                lines.append(f"  - head: {samples['head']}")
+                lines.append(f"  - tail: {samples['tail']}")
+
+    lines.append("")
+    lines.append("## Raw JSON (minus points)")
+    stripped = _scrub_points(report, md_data_sample)
+    lines.append("```json")
+    lines.append(json.dumps(stripped, indent=2, sort_keys=True))
+    lines.append("```")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_report(report: dict[str, Any]) -> str:
+    return render_report_full(report)

mpl_plot_report/rules.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Sequence
+
+
+@dataclass(frozen=True)
+class RuleResult:
+    rule_id: str
+    severity: str
+    passed: bool
+    message: str
+    where: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class Rule:
+    rule_id: str
+    severity: str
+    evaluator: Callable[[dict[str, Any]], tuple[bool, str, dict[str, Any] | None]]
+
+    def evaluate(self, report: dict[str, Any]) -> RuleResult:
+        passed, message, where = self.evaluator(report)
+        return RuleResult(
+            rule_id=self.rule_id,
+            severity=self.severity,
+            passed=passed,
+            message=message,
+            where=where,
+        )
+
+
+@dataclass
+class RuleSet:
+    rules: Sequence[Rule]
+
+    def evaluate(self, report: dict[str, Any]) -> list[RuleResult]:
+        return [rule.evaluate(report) for rule in self.rules]
+
+
+def coerce_ruleset(ruleset: RuleSet | Iterable[Rule] | None) -> RuleSet | None:
+    if ruleset is None:
+        return None
+    if isinstance(ruleset, RuleSet):
+        return ruleset
+    return RuleSet(list(ruleset))

mpl_plot_report/schema.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+SCHEMA_VERSION = "1.0"

mpl_plot_report/util.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Mapping
+
+import numpy as np
+
+
+def make_stable_id(axis_index: int, series_index: int, label: str) -> str:
+    safe = "".join(ch if ch.isalnum() or ch in "-_" else "_" for ch in label.strip())
+    safe = safe or "series"
+    return f"ax{axis_index}_s{series_index}_{safe}"
+
+
+def hash_rcparams(rcparams: Mapping[str, Any]) -> str:
+    payload = json.dumps(rcparams, sort_keys=True, default=repr)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def round_floats(value: Any, precision: int) -> Any:
+    if isinstance(value, float):
+        return round(value, precision)
+    if isinstance(value, list):
+        return [round_floats(item, precision) for item in value]
+    if isinstance(value, tuple):
+        return [round_floats(item, precision) for item in value]
+    if isinstance(value, dict):
+        return {key: round_floats(item, precision) for key, item in value.items()}
+    return value
+
+
+def decimate_series(
+    x: np.ndarray, y: np.ndarray, max_points: int
+) -> tuple[np.ndarray, np.ndarray, dict[str, Any]]:
+    n = len(x)
+    if max_points <= 0:
+        max_points = 1
+    if n <= max_points:
+        return (
+            x,
+            y,
+            {
+                "decimated": False,
+                "method": None,
+                "n_original": n,
+                "max_points": max_points,
+            },
+        )
+
+    target = max(max_points, 2)
+    idx = np.linspace(0, n - 1, target, dtype=int)
+    idx = np.unique(idx)
+    return (
+        x[idx],
+        y[idx],
+        {
+            "decimated": True,
+            "method": "uniform",
+            "n_original": n,
+            "max_points": max_points,
+        },
+    )

mpl_plot_report-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+mpl_plot_report/__init__.py,sha256=9WPl5-gzHUNZtQRO8OU-FYTOM5lPhgC3J23HSsR1nP4,140
+mpl_plot_report/api.py,sha256=YJRtAt6rVKGOhRJ5uMlSQe9q7Yjo-uHmsxSajFkPjoQ,3004
+mpl_plot_report/cli.py,sha256=c0sp5TeWpizd3f7EVwGUTKJDwutM5eSeLLJHxkEJGxY,2801
+mpl_plot_report/diagnostics.py,sha256=m6JuBM172oqXgpFrjajxZ3fGPEK2IyvI5acENaIlEm0,2849
+mpl_plot_report/extract.py,sha256=j42xKjDP9hWTDOc3bFgiX3MXgCYBLp0aUNCR_LAvVI4,4245
+mpl_plot_report/render_md.py,sha256=-IC8dNHoLjF99V5lZAa3ODArrrWXgNJtBTuvphpVCbg,8395
+mpl_plot_report/rules.py,sha256=0-CNmUsvfshOwqH2fCHVL8oz6ZUbSHulauqmnAH66EE,1144
+mpl_plot_report/schema.py,sha256=98Zk27gyartYRngW5GZYH4YI23xq7BLhsU165WF-0dw,59
+mpl_plot_report/util.py,sha256=7McU8VHSX4S_lTa_4tFtm88_zjalrVIK_WpvQc7o8CA,1749
+mpl_plot_report-0.1.0.dist-info/METADATA,sha256=B4DdwC6EjjBOT-1BCro-JK5rtsz0viZ9jrA_bDjHMzg,2514
+mpl_plot_report-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mpl_plot_report-0.1.0.dist-info/licenses/LICENSE,sha256=PfedwwQNUs7785-aIIOQhDpM5-l2DzAQaeMPlaM3_Ho,1065
+mpl_plot_report-0.1.0.dist-info/RECORD,,

mpl_plot_report-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mpl_plot_report-0.1.0.dist-info/licenses/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.