goldenanalysis 0.1.0__tar.gz

goldenanalysis-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# Build artifacts
+target/
+dist/
+build/
+*.egg-info/
+node_modules/
+__pycache__/
+**/.hypothesis/
+.venv/
+.uv-cache/
+
+# Web UI build output (populated by scripts/build_web.py before `hatch build`).
+# .gitkeep stays so the source tree exists in checkouts and the wheel's
+# force-include glob has something to match.
+packages/python/goldenmatch/goldenmatch/web/static/*
+!packages/python/goldenmatch/goldenmatch/web/static/.gitkeep
+
+# Playwright runtime artifacts
+packages/python/goldenmatch/web/frontend/test-results/
+packages/python/goldenmatch/web/frontend/playwright-report/
+
+# YAML-edit backups (web UI's POST /api/v1/rules/save writes goldenmatch.yml.bak
+# next to the file before clobbering — local-only safety net, not source).
+*.yml.bak
+
+# Steward labels — runtime-written by the inspector's review tab. Keep them
+# out of git so a contributor's labels don't ride along on PRs. If you want
+# seed labels for a demo project, commit a curated labels.seed.jsonl and
+# rename at use time.
+labels.jsonl
+
+# Generated outputs
+*_lineage.json
+*_clusters.csv
+# Allow committed test fixtures and demo project that mimic run outputs
+!packages/python/goldenmatch/tests/web/fixtures/**
+!packages/python/goldenmatch/tests/**/fixtures/**
+!packages/python/goldenmatch/web/demo/**
+
+# IDE
+.vscode/
+.idea/
+
+# Turborepo
+.turbo/
+
+# Claude Code agent worktrees (transient isolated checkouts created by
+# background subagents). Never tracked; project-level .claude settings can
+# still be committed since only the worktrees subdir is ignored.
+.claude/worktrees/
+
+# Superpowers / manual git worktrees (isolated checkouts; never tracked)
+.worktrees/
+
+# Local profiling artifacts (per CLAUDE.md convention — cProfile dumps,
+# scale-audit JSON outputs, synthetic fixtures). Documented as gitignored
+# in CLAUDE.md; this entry makes that real.
+.profile_tmp/
+packages/python/goldenmatch/bench-dataset-v1/
+
+# Local runtime state: Learning Memory DB, review queue, identity graph,
+# cross-run autoconfig memory. The engine (and the test suite) rewrites these
+# on every run, so they are never source. `.goldenmatch/memory.db` used to be
+# tracked at the repo root and re-dirtied the working tree on each run; it was
+# `git rm --cached`'d alongside this entry.
+.goldenmatch/
+
+# Compiled native acceleration ext (built from packages/rust/extensions/native
+# via scripts/build_native.py). Platform-specific abi3 artifact, never source.
+packages/python/goldenmatch/goldenmatch/_native*.so
+# GoldenCheck's counterpart (packages/rust/extensions/goldencheck-native via
+# scripts/build_goldencheck_native.py). Same rationale.
+packages/python/goldencheck/goldencheck/_native*.so
+
+# Benchmark datasets downloaded at runtime (DBLP-ACM, etc.) — not committed.
+datasets/
+# Same, for goldenflow (built from packages/rust/extensions/native-flow).
+packages/python/goldenflow/goldenflow/_native*.so
+# Same, for goldenanalysis (built from packages/rust/extensions/analysis-native
+# via scripts/build_analysis_native.py).
+packages/python/goldenanalysis/goldenanalysis/_native*.so
+
+# codebase-memory-mcp local index/snapshot (rebuilt by the SessionStart hook)
+.codebase-memory/

goldenanalysis-0.1.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to GoldenAnalysis are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses semantic
+versioning.
+
+## [0.2.0] - unreleased
+
+Phase 2a — suite consumption. Produce an `AnalysisReport` from real suite outputs.
+
+### Added
+- `ga.analyze_match(result, *, certificate=None)` — analyze a GoldenMatch
+  `DedupeResult` (`match.rates` + `cluster.distribution`).
+- `ga.analyze_pipeline(result)` — analyze a GoldenPipe `PipeResult`, fanning out to
+  every analyzer whose consumed artifacts are present.
+- Analyzers: `match.rates` (pair count, match rate, threshold, recall estimate +
+  safe bound from a certificate, mean score, score histogram), `cluster.distribution`
+  (count, singleton ratio, size quantiles, reduction ratio, size histogram),
+  `quality.rollup` (findings totals + GoldenCheck score + GoldenFlow rows-changed /
+  rules-fired, degrading per-producer).
+- Adapters: `match` / `flow` / `pipe` (duck-typed, no eager suite imports) and
+  `check` (lazy `goldencheck` import behind the `[check]` extra; pure `from_scan`
+  seam). They populate a standardized `AnalyzerInput.artifacts` vocabulary.
+
+Phase 2b — cross-run. Trend + regression detection over a run history.
+
+- `ReportHistory(backend="jsonl"|"sqlite", path=...)` — append-only store of
+  `AnalysisReport`s keyed by `(analysis_name, dataset, run_id)`; mirrors the
+  IdentityStore constructor idiom. JSONL default, SQLite optional (durable); both
+  stdlib, no new deps.
+- `hist.trend(metric_key, dataset)` → `TrendSeries`; `hist.detect_regressions(
+  dataset, baseline=..., policy=...)` → flagged `Regression`s. `Baseline` is a
+  strategy (`rolling_median` default / `previous` / `last_known_good`); `RegressionPolicy`
+  carries per-metric percent gates and respects each `Metric.direction`.
+- Narrative generation (`narrative.build_narrative`) — names the worst flagged
+  regression + co-moving metrics; `to_markdown(regressions=...)` adds the callout +
+  Δ column (byte-identical to Phase 1 without it).
+- The `goldenanalysis trend` / `regressions` CLI are now real (no longer stubs),
+  with `--policy` and `--fail-on-regression` (CI gate).
+
+### Notes
+- `match.recall_estimate` flows automatically once `goldenmatch.dedupe_df(...,
+  certify=True)` attaches a `RecallEstimate` (goldenmatch PR); `match.recall_safe_bound`
+  needs a labelled audit and is supplied via `certificate=`. Both degrade silently
+  when absent.
+- `frame.summary` does not run under `analyze_pipeline` (a `PipeResult` exposes no
+  input frame).
+- `last_known_good` baseline is v1-aliased to `previous` until a per-run health
+  signal exists (documented follow-up).
+
+## [0.1.0] - 2026-06-08
+
+Phase 1 — Python core. The generic frame path, end to end.
+
+### Added
+- `ga.analyze(df, analyzers=[...])` — run analyzers over a polars DataFrame and
+  assemble a single `AnalysisReport`. Works with zero other suite packages
+  installed.
+- Model layer: `Metric`, `AnalysisTable`, `AnalysisReport` (`schema_version=1`
+  cross-surface contract anchor), and analyzer I/O types.
+- `frame.summary` analyzer — row/column counts, mean null ratio, exact-duplicate
+  row ratio, estimated memory, and a `per_column` table.
+- Pure-Python/Polars aggregation primitives (`null_ratio_per_column`,
+  `duplicate_row_ratio`, `histogram`, `quantile`) — the byte-identical reference
+  for the future Rust accelerator.
+- Analyzer registry over the `goldenanalysis.analyzers` entry-point group, with an
+  editable-install fallback map.
+- Exporters: `to_json` / `from_json` (lossless round-trip), `to_markdown`,
+  `to_parquet` (long-form metric frame + per-table sidecars).
+- `goldenanalysis` CLI: `report` command; `trend` / `regressions` stubbed to
+  `0.2.0`.
+- Native-loader gate (`GOLDENANALYSIS_NATIVE`) with an empty `_GATED_ON` — the
+  Phase 4 seam, under contract test from day one (pure-Python fallback).
+
+### Deferred (later phases)
+- Suite adapters + `match.rates` / `cluster.distribution` / `quality.rollup`,
+  `ReportHistory` + regression detection + narrative (Phase 2).
+- TypeScript parity port (Phase 3).
+- Rust `analysis-core` / `analysis-native` accelerator (Phase 4).
+- GoldenPipe terminal stage + goldensuite-mcp surfacing, and the
+  `publish-goldenanalysis*` workflows (Phase 5 / follow-up).
+
+[0.1.0]: https://github.com/benseverndev-oss/goldenmatch/releases/tag/goldenanalysis-v0.1.0

goldenanalysis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Severn
+
+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.

goldenanalysis-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: goldenanalysis
+Version: 0.1.0
+Summary: Read-only cross-cutting analysis, metrics, and reporting engine for the Golden Suite
+Project-URL: Homepage, https://github.com/benseverndev-oss/goldenmatch
+Project-URL: Repository, https://github.com/benseverndev-oss/goldenmatch
+Project-URL: Documentation, https://github.com/benseverndev-oss/goldenmatch/tree/main/packages/python/goldenanalysis#readme
+Project-URL: Issues, https://github.com/benseverndev-oss/goldenmatch/issues
+Project-URL: Changelog, https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenanalysis/CHANGELOG.md
+Project-URL: Author, https://bensevern.dev
+Author-email: Ben Severn <ben@bensevern.dev>
+License: MIT
+License-File: LICENSE
+Keywords: analysis,data-quality,drift-detection,entity-resolution,golden-suite,metrics,polars,regression-detection,reporting
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == 'api'
+Requires-Dist: uvicorn>=0.30; extra == 'api'
+Provides-Extra: check
+Requires-Dist: goldencheck>=1.2.0; extra == 'check'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: flow
+Requires-Dist: goldenflow>=1.1.5; extra == 'flow'
+Provides-Extra: match
+Requires-Dist: goldenmatch>=1.15.0; extra == 'match'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: native
+Requires-Dist: goldenanalysis-native>=0.1.0; extra == 'native'
+Provides-Extra: pipe
+Requires-Dist: goldenpipe>=1.2.0; extra == 'pipe'
+Provides-Extra: suite
+Requires-Dist: goldencheck>=1.2.0; extra == 'suite'
+Requires-Dist: goldenflow>=1.1.5; extra == 'suite'
+Requires-Dist: goldenmatch>=1.15.0; extra == 'suite'
+Requires-Dist: goldenpipe>=1.2.0; extra == 'suite'
+Description-Content-Type: text/markdown
+
+# GoldenAnalysis
+
+**Measure and report across the Golden Suite.** A read-only, cross-cutting
+analysis / metrics / reporting engine: it consumes any stage's typed artifacts
+(or a raw DataFrame) and emits a unified, exportable `AnalysisReport`.
+
+> GoldenAnalysis ships the generic frame path plus suite adapters (GoldenMatch /
+> GoldenCheck / GoldenFlow / GoldenPipe), cross-run trend + regression detection,
+> an edge-safe TypeScript port (optional WASM), and an optional Rust accelerator
+> for the heavy aggregation primitives — all documented below. See
+> `docs/superpowers/specs/2026-06-08-goldenanalysis-cross-cutting-analysis-engine-design.md`
+> for the design rationale.
+
+## Install
+
+```bash
+pip install goldenanalysis
+```
+
+Zero suite dependencies for the generic path — it works on any polars DataFrame
+even with no other Golden package installed.
+
+## Quickstart
+
+```python
+import polars as pl
+import goldenanalysis as ga
+
+df = pl.read_parquet("customers.parquet")
+
+report = ga.analyze(df, analyzers=["frame.summary"])
+print(report.to_markdown())
+
+report.to_json("report.json")
+report.to_parquet("report.parquet")   # long-form metric frame + table sidecars
+```
+
+CLI:
+
+```bash
+goldenanalysis report customers.parquet --analyzers frame.summary --format markdown
+goldenanalysis report report.json --format markdown      # re-render a saved report
+```
+
+`trend` and `regressions` operate over a saved run history (see **Cross-run** below).
+
+## Over the suite
+
+With the relevant extra installed (`pip install goldenanalysis[match,check,flow,pipe]`):
+
+```python
+# A GoldenMatch dedupe result -> match.rates + cluster.distribution
+report = ga.analyze_match(dedupe_result)
+
+# A whole-pipeline manifest -> every analyzer whose artifacts are present
+report = ga.analyze_pipeline(pipe_result)
+```
+
+`match.rates` emits `match.recall_estimate` when GoldenMatch ran
+`dedupe_df(..., certify=True)` (it attaches an unsupervised `RecallEstimate`), and
+`match.recall_safe_bound` when you pass an audit-calibrated certificate
+(`analyze_match(result, certificate=...)`) — the safe bound needs a labelled
+sample, so it can't be computed automatically. Both degrade silently when absent.
+
+## Cross-run — trend + regression detection
+
+Store reports over time, then trend a metric or detect regressions without ground
+truth:
+
+```python
+hist = ga.ReportHistory(backend="jsonl", path=".golden/analysis.jsonl")  # or backend="sqlite"
+hist.append(report)                                  # keyed by (dataset, run_id)
+
+hist.trend("cluster.singleton_ratio", "customers")   # -> TrendSeries
+
+policy = ga.RegressionPolicy(default_pct=10.0, per_metric={"match.recall_safe_bound": 2.0})
+regs = hist.detect_regressions("customers", baseline="rolling_median", policy=policy)
+print(report.to_markdown(regs))                      # callout + Δ-vs-baseline column
+```
+
+The `Baseline` is a strategy (`rolling_median` default — immune to one noisy night
+— plus `previous` / `last_known_good`), and `RegressionPolicy` thresholds are
+per-metric and respect each metric's `direction` (a `higher_better` metric only
+flags on a drop). CLI:
+
+```bash
+goldenanalysis trend --metric cluster.singleton_ratio --dataset customers --history .golden/analysis.jsonl
+goldenanalysis regressions --dataset customers --history .golden/analysis.jsonl \
+  --policy "match.recall_safe_bound=2" --fail-on-regression   # exit 1 on a flagged regression (CI gate)
+```
+
+## GoldenCheck vs GoldenAnalysis
+
+They are easy to confuse and are deliberately distinct:
+
+| | GoldenCheck | GoldenAnalysis |
+|---|---|---|
+| **Scope** | Profiles a *single input dataset at ingest* | *Cross-cutting* over any stage's outputs |
+| **Direction** | A **producer** of artifacts (scan findings) | A **consumer** of artifacts (incl. GoldenCheck's) |
+| **Across runs?** | No — one dataset, one scan | Yes — trend / drift / regression over a run history |
+| **Writes data?** | Suggests/applies fixes | **Never** — read-only by construction |
+
+The hard line: **GoldenAnalysis depends on other packages' types; never the
+reverse.** It sits *beside* the pipeline as a reporting step, consuming
+GoldenCheck / GoldenFlow / GoldenMatch / GoldenPipe / InferMap outputs — it does
+not replace GoldenCheck's ingest-time profiling, and GoldenCheck does not import
+GoldenAnalysis.
+
+## Native accelerator (optional, `goldenanalysis[native]`)
+
+An optional Rust accelerator for the heavy aggregation primitives, gated exactly
+like `goldenmatch[native]` / `goldencheck[native]`:
+
+```bash
+pip install goldenanalysis[native]   # pulls the separate goldenanalysis-native wheel
+```
+
+The pure-Python path stays the **default and the byte-identical reference**. The
+compiled kernel (`analysis-core` pyo3-free + `analysis-native` abi3 wheel) mirrors
+`core/aggregate.py`'s `histogram` / `quantile` value-for-value, reading input as a
+Float64 Arrow array (zero-copy). The loader gate (`core/_native_loader.py`,
+`GOLDENANALYSIS_NATIVE=auto|0|1`) uses a primitive only once it's in `_GATED_ON` —
+which holds **`histogram` and `quantile`**: both proved byte-identical
+(`tests/core/test_native_parity.py`) **and** measured **5.8–9.9x faster** than the
+pure Python loop on Linux x86_64 at 1M–10M rows, *including* the list→Arrow
+conversion the dispatch pays (`benchmarks/aggregate_benchmark.py` +
+`bench-analysis-native.yml`). A new primitive joins only after the same two gates
+clear — "it's Rust" is never enough (the goldencheck composite-key kernel was 2.5x
+*slower* until the gate caught it). With `goldenanalysis[native]` installed, the
+`auto` default uses the native path automatically; `GOLDENANALYSIS_NATIVE=0` forces
+pure. In-tree dev build: `uv run python scripts/build_analysis_native.py`.
+
+## License
+
+MIT.

goldenanalysis-0.1.0/README.md

@@ -0,0 +1,135 @@
+# GoldenAnalysis
+
+**Measure and report across the Golden Suite.** A read-only, cross-cutting
+analysis / metrics / reporting engine: it consumes any stage's typed artifacts
+(or a raw DataFrame) and emits a unified, exportable `AnalysisReport`.
+
+> GoldenAnalysis ships the generic frame path plus suite adapters (GoldenMatch /
+> GoldenCheck / GoldenFlow / GoldenPipe), cross-run trend + regression detection,
+> an edge-safe TypeScript port (optional WASM), and an optional Rust accelerator
+> for the heavy aggregation primitives — all documented below. See
+> `docs/superpowers/specs/2026-06-08-goldenanalysis-cross-cutting-analysis-engine-design.md`
+> for the design rationale.
+
+## Install
+
+```bash
+pip install goldenanalysis
+```
+
+Zero suite dependencies for the generic path — it works on any polars DataFrame
+even with no other Golden package installed.
+
+## Quickstart
+
+```python
+import polars as pl
+import goldenanalysis as ga
+
+df = pl.read_parquet("customers.parquet")
+
+report = ga.analyze(df, analyzers=["frame.summary"])
+print(report.to_markdown())
+
+report.to_json("report.json")
+report.to_parquet("report.parquet")   # long-form metric frame + table sidecars
+```
+
+CLI:
+
+```bash
+goldenanalysis report customers.parquet --analyzers frame.summary --format markdown
+goldenanalysis report report.json --format markdown      # re-render a saved report
+```
+
+`trend` and `regressions` operate over a saved run history (see **Cross-run** below).
+
+## Over the suite
+
+With the relevant extra installed (`pip install goldenanalysis[match,check,flow,pipe]`):
+
+```python
+# A GoldenMatch dedupe result -> match.rates + cluster.distribution
+report = ga.analyze_match(dedupe_result)
+
+# A whole-pipeline manifest -> every analyzer whose artifacts are present
+report = ga.analyze_pipeline(pipe_result)
+```
+
+`match.rates` emits `match.recall_estimate` when GoldenMatch ran
+`dedupe_df(..., certify=True)` (it attaches an unsupervised `RecallEstimate`), and
+`match.recall_safe_bound` when you pass an audit-calibrated certificate
+(`analyze_match(result, certificate=...)`) — the safe bound needs a labelled
+sample, so it can't be computed automatically. Both degrade silently when absent.
+
+## Cross-run — trend + regression detection
+
+Store reports over time, then trend a metric or detect regressions without ground
+truth:
+
+```python
+hist = ga.ReportHistory(backend="jsonl", path=".golden/analysis.jsonl")  # or backend="sqlite"
+hist.append(report)                                  # keyed by (dataset, run_id)
+
+hist.trend("cluster.singleton_ratio", "customers")   # -> TrendSeries
+
+policy = ga.RegressionPolicy(default_pct=10.0, per_metric={"match.recall_safe_bound": 2.0})
+regs = hist.detect_regressions("customers", baseline="rolling_median", policy=policy)
+print(report.to_markdown(regs))                      # callout + Δ-vs-baseline column
+```
+
+The `Baseline` is a strategy (`rolling_median` default — immune to one noisy night
+— plus `previous` / `last_known_good`), and `RegressionPolicy` thresholds are
+per-metric and respect each metric's `direction` (a `higher_better` metric only
+flags on a drop). CLI:
+
+```bash
+goldenanalysis trend --metric cluster.singleton_ratio --dataset customers --history .golden/analysis.jsonl
+goldenanalysis regressions --dataset customers --history .golden/analysis.jsonl \
+  --policy "match.recall_safe_bound=2" --fail-on-regression   # exit 1 on a flagged regression (CI gate)
+```
+
+## GoldenCheck vs GoldenAnalysis
+
+They are easy to confuse and are deliberately distinct:
+
+| | GoldenCheck | GoldenAnalysis |
+|---|---|---|
+| **Scope** | Profiles a *single input dataset at ingest* | *Cross-cutting* over any stage's outputs |
+| **Direction** | A **producer** of artifacts (scan findings) | A **consumer** of artifacts (incl. GoldenCheck's) |
+| **Across runs?** | No — one dataset, one scan | Yes — trend / drift / regression over a run history |
+| **Writes data?** | Suggests/applies fixes | **Never** — read-only by construction |
+
+The hard line: **GoldenAnalysis depends on other packages' types; never the
+reverse.** It sits *beside* the pipeline as a reporting step, consuming
+GoldenCheck / GoldenFlow / GoldenMatch / GoldenPipe / InferMap outputs — it does
+not replace GoldenCheck's ingest-time profiling, and GoldenCheck does not import
+GoldenAnalysis.
+
+## Native accelerator (optional, `goldenanalysis[native]`)
+
+An optional Rust accelerator for the heavy aggregation primitives, gated exactly
+like `goldenmatch[native]` / `goldencheck[native]`:
+
+```bash
+pip install goldenanalysis[native]   # pulls the separate goldenanalysis-native wheel
+```
+
+The pure-Python path stays the **default and the byte-identical reference**. The
+compiled kernel (`analysis-core` pyo3-free + `analysis-native` abi3 wheel) mirrors
+`core/aggregate.py`'s `histogram` / `quantile` value-for-value, reading input as a
+Float64 Arrow array (zero-copy). The loader gate (`core/_native_loader.py`,
+`GOLDENANALYSIS_NATIVE=auto|0|1`) uses a primitive only once it's in `_GATED_ON` —
+which holds **`histogram` and `quantile`**: both proved byte-identical
+(`tests/core/test_native_parity.py`) **and** measured **5.8–9.9x faster** than the
+pure Python loop on Linux x86_64 at 1M–10M rows, *including* the list→Arrow
+conversion the dispatch pays (`benchmarks/aggregate_benchmark.py` +
+`bench-analysis-native.yml`). A new primitive joins only after the same two gates
+clear — "it's Rust" is never enough (the goldencheck composite-key kernel was 2.5x
+*slower* until the gate caught it). With `goldenanalysis[native]` installed, the
+`auto` default uses the native path automatically; `GOLDENANALYSIS_NATIVE=0` forces
+pure. In-tree dev build: `uv run python scripts/build_analysis_native.py`.
+
+## License
+
+MIT.

goldenanalysis-0.1.0/benchmarks/aggregate_benchmark.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""A/B bench for the GoldenAnalysis native aggregation kernels.
+
+Measures the 5-run median wall of ``histogram`` / ``quantile`` over a large array,
+three ways, to decide the ``_native_loader._GATED_ON`` flip:
+
+- ``pure``         -- the pure-Python reference (``core/aggregate``), a Python list in.
+- ``native_raw``   -- the native kernel with the Arrow array ALREADY materialized.
+                      This is the *frames-out ceiling*: what the kernel is worth when
+                      a caller hands it Arrow directly (the #663 columnar world).
+- ``native+conv``  -- the REALISTIC dispatch for the current call convention: a Python
+                      list in, converted to Arrow, then the native kernel. This is what
+                      ``aggregate.histogram`` would pay today (it receives a list).
+
+GATE: flip ``_GATED_ON`` for a primitive ONLY if ``native+conv`` comfortably beats
+``pure``. Don't gate on ``native_raw`` -- the current call sites pass Python lists, so
+the conversion is real. And don't gate on "it's Rust": the pure ``histogram`` is a
+tight loop and ``quantile`` leans on C ``sorted``; the goldencheck composite-key kernel
+was 2.5x SLOWER than its baseline until the gate caught it. Build the ext first
+(``scripts/build_analysis_native.py``); otherwise this reports pure-only.
+
+    POLARS_SKIP_CPU_CHECK=1 uv run python \
+        packages/python/goldenanalysis/benchmarks/aggregate_benchmark.py --rows 1000000
+"""
+from __future__ import annotations
+
+import argparse
+import platform
+import random
+import statistics
+import sys
+import time
+from collections.abc import Callable
+
+from goldenanalysis.core import aggregate
+from goldenanalysis.core._native_loader import native_available, native_module
+
+
+def _median_wall(fn: Callable[[], object], runs: int) -> float:
+    times = []
+    for _ in range(runs):
+        t0 = time.perf_counter()
+        fn()
+        times.append(time.perf_counter() - t0)
+    return statistics.median(times)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--rows", type=int, default=1_000_000)
+    ap.add_argument("--bins", type=int, default=10)
+    ap.add_argument("--runs", type=int, default=5)
+    ap.add_argument("--seed", type=int, default=0)
+    args = ap.parse_args()
+
+    rng = random.Random(args.seed)
+    values = [rng.uniform(-1000.0, 1000.0) for _ in range(args.rows)]
+    print(f"# {platform.system()} {platform.machine()} | python {sys.version.split()[0]}")
+    print(f"rows={args.rows:,} bins={args.bins} runs={args.runs}")
+
+    nm = None
+    arr = None
+    pa = None
+    if native_available():
+        import pyarrow as pa  # noqa: F811
+
+        arr = pa.array(values, type=pa.float64())
+        nm = native_module()
+    else:
+        print("native ext NOT built -> pure-only (run scripts/build_analysis_native.py to A/B)")
+
+    def bench(name: str, pure: Callable[[], object], native_on_arr: Callable[[object], object]) -> None:
+        pure_ms = _median_wall(pure, args.runs) * 1e3
+        line = f"{name:<10} pure={pure_ms:9.2f} ms"
+        if nm is not None and pa is not None:
+            raw_ms = _median_wall(lambda: native_on_arr(arr), args.runs) * 1e3
+            conv_ms = _median_wall(
+                lambda: native_on_arr(pa.array(values, type=pa.float64())), args.runs
+            ) * 1e3
+            line += (
+                f"  native_raw={raw_ms:9.2f} ms ({pure_ms / raw_ms:5.2f}x)"
+                f"  native+conv={conv_ms:9.2f} ms ({pure_ms / conv_ms:5.2f}x)"
+            )
+        print(line)
+
+    bench("histogram", lambda: aggregate.histogram(values, args.bins), lambda a: nm.histogram(a, args.bins))
+    bench("quantile", lambda: aggregate.quantile(values, 0.95), lambda a: nm.quantile(a, 0.95))
+
+    if nm is not None:
+        print("\nGATE: flip _GATED_ON only if native+conv (Python list in -> the current")
+        print("aggregate.py call convention) comfortably beats pure. native_raw is the")
+        print("frames-out ceiling (Arrow already materialized), NOT the current dispatch.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

goldenanalysis-0.1.0/golden-suite.json

@@ -0,0 +1,69 @@
+{
+  "name": "Golden Suite",
+  "description": "Data quality toolkit -- validate, transform, deduplicate, orchestrate, and analyze",
+  "version": "2026-06-08",
+  "tools": [
+    {
+      "name": "GoldenCheck",
+      "purpose": "Data quality validation",
+      "repo": "github.com/benseverndev-oss/goldencheck",
+      "install": "pip install goldencheck",
+      "mcp": {"command": "goldencheck mcp-serve", "tools": 19},
+      "a2a": {"command": "goldencheck agent-serve --port 8100", "skills": 9},
+      "cli": "goldencheck",
+      "python": "from goldencheck import scan_file, validate_file"
+    },
+    {
+      "name": "GoldenFlow",
+      "purpose": "Data transformation",
+      "repo": "github.com/benseverndev-oss/goldenflow",
+      "install": "pip install goldenflow",
+      "mcp": {"command": "goldenflow mcp-serve", "tools": 10},
+      "a2a": {"command": "goldenflow agent-serve --port 8150", "skills": 6},
+      "cli": "goldenflow",
+      "python": "from goldenflow import transform_file, transform_df"
+    },
+    {
+      "name": "GoldenMatch",
+      "purpose": "Entity resolution and deduplication",
+      "repo": "github.com/benseverndev-oss/goldenmatch",
+      "install": "pip install goldenmatch",
+      "mcp": {"command": "goldenmatch mcp-serve", "tools": 10},
+      "a2a": {"command": "goldenmatch agent-serve --port 8200", "skills": 8},
+      "cli": "goldenmatch",
+      "python": "from goldenmatch import dedupe_df, match_df"
+    },
+    {
+      "name": "GoldenPipe",
+      "purpose": "Pipeline orchestrator for the suite",
+      "repo": "github.com/benseverndev-oss/goldenpipe",
+      "install": "pip install goldenpipe[golden-suite]",
+      "mcp": {"command": "goldenpipe mcp-serve", "tools": 4},
+      "a2a": {"command": "goldenpipe agent-serve --port 8250", "skills": 4},
+      "cli": "goldenpipe",
+      "python": "from goldenpipe import run, run_df"
+    },
+    {
+      "name": "GoldenAnalysis",
+      "purpose": "Read-only cross-cutting analysis, metrics, and reporting",
+      "repo": "github.com/benseverndev-oss/goldenmatch",
+      "install": "pip install goldenanalysis",
+      "mcp": null,
+      "a2a": null,
+      "cli": "goldenanalysis",
+      "python": "from goldenanalysis import analyze"
+    },
+    {
+      "name": "goldenmatch-extensions",
+      "purpose": "SQL extensions for Postgres and DuckDB",
+      "repo": "github.com/benseverndev-oss/goldenmatch-extensions",
+      "install": "pip install goldenmatch-duckdb",
+      "mcp": null,
+      "a2a": null,
+      "cli": null,
+      "python": null
+    }
+  ],
+  "pipeline_order": ["goldencheck", "goldenflow", "goldenmatch", "goldenanalysis"],
+  "ports": {"goldencheck": 8100, "goldenflow": 8150, "goldenmatch": 8200, "goldenpipe": 8250}
+}