gallop-pds 0.2.0__tar.gz

gallop_pds-0.2.0/LICENSE

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

gallop_pds-0.2.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: gallop-pds
+Version: 0.2.0
+Summary: Product data science checks: power from priors, SRM, CUPED, always-valid inference, empirical Bayes shrinkage, out-of-time model validation, and the prior store they read.
+Author: 0trm
+License: MIT
+Project-URL: Homepage, https://0trm.github.io/gallop/
+Project-URL: Repository, https://github.com/0trm/gallop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+<p align="right">
+  <img src="site/assets/mark.svg" width="300" alt="Three riders carried on one galloping horse">
+</p>
+
+# gallop
+
+**Routes a product question to the method it deserves, then runs that method with checks in place.**
+
+A product data science system, packaged as agent skills. Most questions leave at
+intake without an analysis. The ones that stay get the method that matches how
+treatment was assigned, and the checks that decide whether the result is a
+result. What they teach is written back, so the next question starts smaller.
+
+## The map
+
+A question enters at the left and leaves as a decision. Measurement is a
+foundation rather than a phase, because what ships changes the data. Theory is a
+ceiling rather than a report, because what you learn has to outlive the test that
+produced it.
+
+Three method buckets, a floor underneath them, a memory above them, and a layer
+of judgment on top. Each bucket has its own question, its own output, and its own
+failure mode:
+
+| Bucket | Asks | Hands back | Fails by |
+|---|---|---|---|
+| Description | What happened? | A hypothesis | Being mistaken for causation |
+| Causation | Did this change cause that? | An effect size | An invalid comparison group |
+| Prediction | What will happen? Who gets what? | A forecast, a ranking, an allocation | Breaking the moment you intervene |
+
+Experimentation and causal inference share all three, so they are one bucket
+separated only by who did the randomising: you, or the world.
+
+**[Read the full map](https://0trm.github.io/gallop/map/)** ·
+**[Read the intake algorithm](https://0trm.github.io/gallop/intake/)**
+
+## Install
+
+```bash
+# Claude Code
+/plugin marketplace add 0trm/gallop
+/plugin install gallop@gallop
+
+# any other agent, or none: a skill is a directory of markdown
+cp -r gallop/skills/reading-experiments .claude/skills/
+
+# the package; the import name is gallop
+pip install gallop-pds
+```
+
+## The five-minute path
+
+One command, one synthetic dataset, every check once:
+
+```bash
+python -m gallop.examples.quickstart
+```
+
+Fifteen seconds of runtime: an MDE, an SRM verdict, an exposure ratio, a
+CUPED-adjusted effect with an always-valid interval, and the same effect shrunk
+toward a seeded prior store. The full loop, from a question arriving to the
+prior store changing on disk, is `python examples/end-to-end/run_loop.py`.
+
+## The skills
+
+<!-- skills-table:begin (generated by site/build.py; do not edit) -->
+| Skill | What it decides | Reach for it when |
+|---|---|---|
+| [`routing-questions`](skills/routing-questions/SKILL.md) | Whether this becomes work at all, and which skill it becomes | a product, analytics, or experimentation request first arrives, when someone asks for a deep dive or a dashboard, or before opening a query editor on any question about impact, lift, or whether something worked |
+| [`defining-metrics`](skills/defining-metrics/SKILL.md) | A metric turned into a computation, a source of truth, and a statement of how it will be gamed | defining a north-star or guardrail metric, when two dashboards disagree on the same number, when arbitrating between conflicting metric definitions, or when a readout depends on a metric nobody has validated |
+| [`designing-experiments`](skills/designing-experiments/SKILL.md) | The four choices that cannot be repaired after launch, with the MDE from the prior store | planning, powering, or pre-registering an experiment, when deciding whether a question is testable at the available traffic, or when a feature is about to ship without a flag |
+| [`reading-experiments`](skills/reading-experiments/SKILL.md) | Whether the result is a result: SRM, exposure, the sequential bound, CUPED, shrinkage | analysing or reviewing A/B test results, when a test looks like a winner, when someone reports a lift, or when deciding whether to ship on an experiment readout |
+| [`choosing-causal-designs`](skills/choosing-causal-designs/SKILL.md) | The method that matches how assignment happened, and the exit that says there is no comparison group | measuring the impact of something already rolled out, a launch, a migration, a pricing change, or a campaign that reached everyone at once |
+| [`automating-decisions`](skills/automating-decisions/SKILL.md) | Whether a repeated decision belongs to a model, validated out of time, and the holdout that measures its impact | someone asks for a churn, propensity, LTV, scoring, forecasting, uplift, recommendation or allocation model, when a model's offline accuracy is offered as evidence that something worked, or when deciding who gets an offer, a discount or an intervention |
+| [`writing-readouts`](skills/writing-readouts/SKILL.md) | The decision rule first, the result last; the belief filed where the next question starts | a test finishes, when documenting a shipped or killed decision, when writing up a null result or a rollback, or when a question needs an entry someone can find in a year |
+<!-- skills-table:end -->
+
+## What this is not
+
+Not an experimentation platform. It does not assign traffic, hold flags, or
+replace your warehouse. It assumes those exist and writes the part that decides
+whether the number they produced is true.
+
+## More
+
+The site renders the skills and the two arguments:
+[the map](https://0trm.github.io/gallop/map/) ·
+[the intake](https://0trm.github.io/gallop/intake/) ·
+[the theory layer](https://0trm.github.io/gallop/theory/) ·
+[install](https://0trm.github.io/gallop/install/)
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

gallop_pds-0.2.0/README.md

@@ -0,0 +1,94 @@
+<p align="right">
+  <img src="site/assets/mark.svg" width="300" alt="Three riders carried on one galloping horse">
+</p>
+
+# gallop
+
+**Routes a product question to the method it deserves, then runs that method with checks in place.**
+
+A product data science system, packaged as agent skills. Most questions leave at
+intake without an analysis. The ones that stay get the method that matches how
+treatment was assigned, and the checks that decide whether the result is a
+result. What they teach is written back, so the next question starts smaller.
+
+## The map
+
+A question enters at the left and leaves as a decision. Measurement is a
+foundation rather than a phase, because what ships changes the data. Theory is a
+ceiling rather than a report, because what you learn has to outlive the test that
+produced it.
+
+Three method buckets, a floor underneath them, a memory above them, and a layer
+of judgment on top. Each bucket has its own question, its own output, and its own
+failure mode:
+
+| Bucket | Asks | Hands back | Fails by |
+|---|---|---|---|
+| Description | What happened? | A hypothesis | Being mistaken for causation |
+| Causation | Did this change cause that? | An effect size | An invalid comparison group |
+| Prediction | What will happen? Who gets what? | A forecast, a ranking, an allocation | Breaking the moment you intervene |
+
+Experimentation and causal inference share all three, so they are one bucket
+separated only by who did the randomising: you, or the world.
+
+**[Read the full map](https://0trm.github.io/gallop/map/)** ·
+**[Read the intake algorithm](https://0trm.github.io/gallop/intake/)**
+
+## Install
+
+```bash
+# Claude Code
+/plugin marketplace add 0trm/gallop
+/plugin install gallop@gallop
+
+# any other agent, or none: a skill is a directory of markdown
+cp -r gallop/skills/reading-experiments .claude/skills/
+
+# the package; the import name is gallop
+pip install gallop-pds
+```
+
+## The five-minute path
+
+One command, one synthetic dataset, every check once:
+
+```bash
+python -m gallop.examples.quickstart
+```
+
+Fifteen seconds of runtime: an MDE, an SRM verdict, an exposure ratio, a
+CUPED-adjusted effect with an always-valid interval, and the same effect shrunk
+toward a seeded prior store. The full loop, from a question arriving to the
+prior store changing on disk, is `python examples/end-to-end/run_loop.py`.
+
+## The skills
+
+<!-- skills-table:begin (generated by site/build.py; do not edit) -->
+| Skill | What it decides | Reach for it when |
+|---|---|---|
+| [`routing-questions`](skills/routing-questions/SKILL.md) | Whether this becomes work at all, and which skill it becomes | a product, analytics, or experimentation request first arrives, when someone asks for a deep dive or a dashboard, or before opening a query editor on any question about impact, lift, or whether something worked |
+| [`defining-metrics`](skills/defining-metrics/SKILL.md) | A metric turned into a computation, a source of truth, and a statement of how it will be gamed | defining a north-star or guardrail metric, when two dashboards disagree on the same number, when arbitrating between conflicting metric definitions, or when a readout depends on a metric nobody has validated |
+| [`designing-experiments`](skills/designing-experiments/SKILL.md) | The four choices that cannot be repaired after launch, with the MDE from the prior store | planning, powering, or pre-registering an experiment, when deciding whether a question is testable at the available traffic, or when a feature is about to ship without a flag |
+| [`reading-experiments`](skills/reading-experiments/SKILL.md) | Whether the result is a result: SRM, exposure, the sequential bound, CUPED, shrinkage | analysing or reviewing A/B test results, when a test looks like a winner, when someone reports a lift, or when deciding whether to ship on an experiment readout |
+| [`choosing-causal-designs`](skills/choosing-causal-designs/SKILL.md) | The method that matches how assignment happened, and the exit that says there is no comparison group | measuring the impact of something already rolled out, a launch, a migration, a pricing change, or a campaign that reached everyone at once |
+| [`automating-decisions`](skills/automating-decisions/SKILL.md) | Whether a repeated decision belongs to a model, validated out of time, and the holdout that measures its impact | someone asks for a churn, propensity, LTV, scoring, forecasting, uplift, recommendation or allocation model, when a model's offline accuracy is offered as evidence that something worked, or when deciding who gets an offer, a discount or an intervention |
+| [`writing-readouts`](skills/writing-readouts/SKILL.md) | The decision rule first, the result last; the belief filed where the next question starts | a test finishes, when documenting a shipped or killed decision, when writing up a null result or a rollback, or when a question needs an entry someone can find in a year |
+<!-- skills-table:end -->
+
+## What this is not
+
+Not an experimentation platform. It does not assign traffic, hold flags, or
+replace your warehouse. It assumes those exist and writes the part that decides
+whether the number they produced is true.
+
+## More
+
+The site renders the skills and the two arguments:
+[the map](https://0trm.github.io/gallop/map/) ·
+[the intake](https://0trm.github.io/gallop/intake/) ·
+[the theory layer](https://0trm.github.io/gallop/theory/) ·
+[install](https://0trm.github.io/gallop/install/)
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

gallop_pds-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gallop-pds"
+version = "0.2.0"
+description = "Product data science checks: power from priors, SRM, CUPED, always-valid inference, empirical Bayes shrinkage, out-of-time model validation, and the prior store they read."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "0trm" }]
+dependencies = ["numpy>=1.26", "pandas>=2.0", "scipy>=1.11"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+[project.urls]
+Homepage = "https://0trm.github.io/gallop/"
+Repository = "https://github.com/0trm/gallop"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gallop = ["templates/*.json"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gallop_pds-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gallop_pds-0.2.0/src/gallop/__init__.py

@@ -0,0 +1,17 @@
+"""Product data science checks, thin by design.
+
+Seven modules, each backing one skill:
+
+  power       MDE, sample size and duration, two-proportion and continuous
+  trust       sample ratio mismatch and exposure-versus-eligibility
+  variance    CUPED against a pre-period covariate
+  sequential  always-valid confidence sequences and group-sequential bounds
+  shrink      empirical Bayes shrinkage toward the prior store
+  priors      the prior store and the metric registry on disk
+  validate    out-of-time validation, lift over the base rate, calibration, Qini, MASE
+
+Every function takes and returns arrays or DataFrames, never a database
+connection. Each module runs as a script: python -m gallop.<module> --help
+"""
+
+__version__ = "0.2.0"

gallop_pds-0.2.0/src/gallop/examples/quickstart.py

@@ -0,0 +1,89 @@
+"""The five-minute path: every check once, against synthetic data.
+
+One simulated experiment on a 12% activation rate with a real +0.35pp effect,
+plus a seeded prior store. No configuration, no credentials, no warehouse.
+
+Run:  python -m gallop.examples.quickstart
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+from gallop import power, priors, sequential, shrink, trust, variance
+
+RULE = "=" * 74
+
+
+def main():
+    rng = np.random.default_rng(7)
+
+    # -- the experiment: user-level activation with a pre-period covariate
+    n = 40_000
+    true_effect = 0.0035
+    x = rng.beta(2, 14, 2 * n)                      # pre-period activation propensity
+    arm = np.array(["control"] * n + ["treatment"] * n)
+    p_unit = np.clip(x + (arm == "treatment") * true_effect, 0, 1)
+    y = rng.binomial(1, p_unit).astype(float)
+
+    print(RULE)
+    print("gallop quickstart: one experiment through every check")
+    print(RULE)
+
+    print("\n1 · Size it before running it (gallop.power)")
+    m = power.mde(n, baseline_rate=0.125)
+    print(f"   at n={n:,} per arm on a 12.5% rate, the MDE is {m * 100:.2f}pp;")
+    print(f"   detecting {true_effect * 100:.2f}pp instead would need "
+          f"{power.sample_size(true_effect, baseline_rate=0.125):,.0f} per arm")
+
+    print("\n2 · The trust gate (gallop.trust)")
+    assigned = {"control": n, "treatment": n - int(rng.integers(0, 120))}
+    exposed = {k: int(v * 0.97) for k, v in assigned.items()}
+    s = trust.srm(assigned)
+    print(f"   SRM: chi2 {s['chi2']:.2f}  p {s['p']:.3f}  -> {s['verdict']}")
+    e = trust.exposure_check(assigned, exposed)
+    print(f"   exposure: pooled rate {e['pooled_rate']:.2%}  -> {e['verdict']}")
+
+    print("\n3 · The effect, with CUPED (gallop.variance)")
+    r = variance.cuped(y, x, arm, control="control")
+    print(f"   raw    {r['effect_raw'] * 100:+.3f}pp  se {r['se_raw'] * 100:.3f}pp")
+    print(f"   cuped  {r['effect_adjusted'] * 100:+.3f}pp  se {r['se_adjusted'] * 100:.3f}pp"
+          f"   variance reduction {r['variance_reduction']:.0%}")
+
+    print("\n4 · An interval that survives peeking (gallop.sequential)")
+    sd_adj = r["se_adjusted"] * np.sqrt(n / 2)
+    av = sequential.always_valid_ci(0.0, r["effect_adjusted"], sd_adj, n, tau2=1e-4)
+    lo, hi = av["ci"]
+    print(f"   always-valid 95% CI [{lo * 100:+.3f}pp, {hi * 100:+.3f}pp]"
+          f"   boundary |z| {av['bound_z']:.2f} (vs 1.96 fixed)")
+    print(f"   significant under continuous monitoring: {av['significant']}")
+
+    print("\n5 · Shrunk toward what this metric has done before (gallop.shrink + priors)")
+    with tempfile.TemporaryDirectory() as td:
+        store_path = Path(td) / "priors.jsonl"
+        past = [0.0009, -0.0004, 0.0021, 0.0013, -0.0011, 0.0028, 0.0006, 0.0016]
+        for i, eff in enumerate(past):
+            priors.append(store_path, {
+                "id": f"2026-{i + 1:02d}-activation-test", "metric": "activation_rate",
+                "date": f"2026-{i + 1:02d}-15", "design": "experiment", "effect": eff,
+                "unit": "pp", "se": 0.0011, "n_per_arm": 35_000, "decision": "ship" if eff > 0.001 else "no-ship",
+            })
+        store = priors.read(store_path)
+        sh = shrink.from_store(r["effect_adjusted"], r["se_adjusted"], store,
+                               "activation_rate", "pp")
+    print(f"   prior from {sh['n_priors']} readouts: mu {sh['mu'] * 100:+.3f}pp"
+          f"   tau {np.sqrt(sh['tau2']) * 100:.3f}pp")
+    print(f"   observed {sh['effect'] * 100:+.3f}pp -> shrunk {sh['effect_shrunk'] * 100:+.3f}pp"
+          f"   (weight on data {sh['weight_on_data']:.2f})")
+
+    print(f"\n{RULE}")
+    print(f"true simulated effect: {true_effect * 100:+.3f}pp. The shrunk estimate is the")
+    print("one to write back to the store; the raw one is the winner's curse waiting.")
+    print(RULE)
+
+
+if __name__ == "__main__":
+    main()

gallop_pds-0.2.0/src/gallop/power.py

@@ -0,0 +1,118 @@
+"""Power, MDE, sample size and duration for a two-arm test.
+
+One family of closed forms for a two-sample difference in means. A proportion
+metric is the same formula with sd = sqrt(p(1-p)), so every function takes
+either `sd` (continuous) or `baseline_rate` (proportion), never both.
+
+With the defaults (alpha 0.05 two-sided, power 0.80) the MDE reduces to the
+planning rule of thumb 2.8 * sqrt(2 p (1-p) / n).
+
+The closed form assumes the analysis unit is the randomisation unit, and it
+lies for ratio metrics, heavy tails and capped metrics. Sizing from it when
+those assumptions fail is a design question, not an arithmetic one; see the
+designing-experiments skill.
+
+Run:  python -m gallop.power mde --n 5000 --baseline-rate 0.10
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import numpy as np
+from scipy import stats
+
+# %% ------------------------------------------------------------- closed forms
+
+
+def _sd(sd: float | None, baseline_rate: float | None) -> float:
+    if (sd is None) == (baseline_rate is None):
+        raise ValueError("give exactly one of sd (continuous) or baseline_rate (proportion)")
+    if baseline_rate is not None:
+        if not 0 < baseline_rate < 1:
+            raise ValueError("baseline_rate must be strictly between 0 and 1")
+        return float(np.sqrt(baseline_rate * (1 - baseline_rate)))
+    return float(sd)
+
+
+def mde(n_per_arm, *, sd=None, baseline_rate=None, power=0.80, alpha=0.05):
+    """Smallest absolute effect detectable at the stated power. Same unit as the metric."""
+    s = _sd(sd, baseline_rate)
+    z_alpha = stats.norm.ppf(1 - alpha / 2)
+    z_beta = stats.norm.ppf(power)
+    return float((z_alpha + z_beta) * s * np.sqrt(2.0 / n_per_arm))
+
+
+def sample_size(effect, *, sd=None, baseline_rate=None, power=0.80, alpha=0.05):
+    """Units per arm needed to detect an absolute `effect`. Inverse of mde()."""
+    s = _sd(sd, baseline_rate)
+    z_alpha = stats.norm.ppf(1 - alpha / 2)
+    z_beta = stats.norm.ppf(power)
+    return float(2 * ((z_alpha + z_beta) * s / abs(effect)) ** 2)
+
+
+def power_at(n_per_arm, effect, *, sd=None, baseline_rate=None, alpha=0.05):
+    """Power of a two-sided test at the given n and absolute effect."""
+    s = _sd(sd, baseline_rate)
+    se = s * np.sqrt(2.0 / n_per_arm)
+    z_alpha = stats.norm.ppf(1 - alpha / 2)
+    z = abs(effect) / se
+    return float(stats.norm.sf(z_alpha - z) + stats.norm.cdf(-z_alpha - z))
+
+
+def duration(effect, units_per_day, *, sd=None, baseline_rate=None, power=0.80,
+             alpha=0.05, arms=2, eligible_share=1.0):
+    """Days to reach the required sample, given daily eligible traffic.
+
+    `units_per_day` is total new units entering the experiment surface per day;
+    `eligible_share` is the fraction that actually enters assignment.
+    """
+    n = sample_size(effect, sd=sd, baseline_rate=baseline_rate, power=power, alpha=alpha)
+    daily = units_per_day * eligible_share
+    if daily <= 0:
+        raise ValueError("units_per_day * eligible_share must be positive")
+    return float(arms * n / daily)
+
+
+# %% --------------------------------------------------------------------- cli
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="gallop.power", description=__doc__.splitlines()[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp, effect=False, n=False):
+        if effect:
+            sp.add_argument("--effect", type=float, required=True, help="absolute effect")
+        if n:
+            sp.add_argument("--n", type=float, required=True, help="units per arm")
+        sp.add_argument("--sd", type=float)
+        sp.add_argument("--baseline-rate", type=float)
+        sp.add_argument("--power", type=float, default=0.80)
+        sp.add_argument("--alpha", type=float, default=0.05)
+
+    common(sub.add_parser("mde", help="smallest detectable absolute effect"), n=True)
+    common(sub.add_parser("n", help="units per arm for an effect"), effect=True)
+    sp = sub.add_parser("duration", help="days to reach the required sample")
+    common(sp, effect=True)
+    sp.add_argument("--units-per-day", type=float, required=True)
+    sp.add_argument("--eligible-share", type=float, default=1.0)
+    sp.add_argument("--arms", type=int, default=2)
+    common(sub.add_parser("power", help="power at a given n and effect"), effect=True, n=True)
+
+    a = p.parse_args(argv)
+    kw = {"sd": a.sd, "baseline_rate": a.baseline_rate, "alpha": a.alpha}
+    if a.cmd == "mde":
+        print(f"mde (absolute): {mde(a.n, power=a.power, **kw):.6f}")
+    elif a.cmd == "n":
+        print(f"n per arm: {sample_size(a.effect, power=a.power, **kw):,.0f}")
+    elif a.cmd == "duration":
+        d = duration(a.effect, a.units_per_day, power=a.power, arms=a.arms,
+                     eligible_share=a.eligible_share, **kw)
+        print(f"days: {d:,.1f}")
+    elif a.cmd == "power":
+        print(f"power: {power_at(a.n, a.effect, **kw):.4f}")
+
+
+if __name__ == "__main__":
+    main()

gallop_pds-0.2.0/src/gallop/priors.py

@@ -0,0 +1,160 @@
+"""The prior store and the metric registry on disk.
+
+Both are append-friendly JSONL, one JSON object per line, validated on write
+against the schemas in gallop/templates/. JSONL because the store must be
+reviewable in a pull request; a store nobody can diff goes stale, which is the
+failure mode the theory layer exists to prevent.
+
+The store is a log, windowed on read. A correction is a new record carrying
+`supersedes`, never an edit. `expires_on` names the event that would
+invalidate the entry rather than a date somebody has to remember.
+
+Validation is done here in about thirty lines (required keys, types, enums,
+no unknown keys) rather than by the jsonschema package, so the runtime
+dependencies stay at numpy, pandas, scipy. The schema files remain the
+published contract for anything else that writes to the store.
+
+Run:  python -m gallop.priors read --store priors.jsonl --metric activation_rate
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from importlib import resources
+from pathlib import Path
+
+import pandas as pd
+
+# %% -------------------------------------------------------------- validation
+
+_TYPES = {"string": str, "number": (int, float), "integer": int, "object": dict}
+
+
+def _schema(name):
+    with resources.files("gallop.templates").joinpath(name).open() as f:
+        return json.load(f)
+
+
+def validate(record, schema_name="prior-store.schema.json"):
+    """Check a dict against one of the packaged schemas. Raises ValueError."""
+    sch = _schema(schema_name)
+    props = sch["properties"]
+    errors = []
+    for key in sch["required"]:
+        if key not in record:
+            errors.append(f"missing required field {key!r}")
+    for key, value in record.items():
+        if key not in props:
+            errors.append(f"unknown field {key!r}")
+            continue
+        spec = props[key]
+        expected = _TYPES[spec["type"]]
+        if not isinstance(value, expected) or isinstance(value, bool):
+            errors.append(f"{key!r} must be {spec['type']}, got {type(value).__name__}")
+            continue
+        if "enum" in spec and value not in spec["enum"]:
+            errors.append(f"{key!r} must be one of {spec['enum']}, got {value!r}")
+        if "pattern" in spec and not re.fullmatch(spec["pattern"], value):
+            errors.append(f"{key!r} must match {spec['pattern']}, got {value!r}")
+    if errors:
+        raise ValueError(f"invalid {sch['title']}: " + "; ".join(errors))
+    return record
+
+
+# %% ------------------------------------------------------------- prior store
+
+
+def append(path, record):
+    """Validate a record and append it to the store. Returns the record."""
+    validate(record, "prior-store.schema.json")
+    p = Path(path)
+    existing = {r["id"] for _, r in _iter_records(p)} if p.exists() else set()
+    if record["id"] in existing:
+        raise ValueError(f"id {record['id']!r} already in {path}; corrections use supersedes")
+    with p.open("a") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    return record
+
+
+def _iter_records(p):
+    with Path(p).open() as f:
+        for i, line in enumerate(f, 1):
+            if line.strip():
+                yield i, json.loads(line)
+
+
+def read(path, metric=None, window=100):
+    """The store as a DataFrame: superseded records dropped, windowed on read.
+
+    `window` keeps the most recent records per metric, by date then file
+    order. Every record is validated; a malformed line fails loudly with its
+    line number rather than flowing into a shrinkage estimate.
+    """
+    rows = []
+    for i, rec in _iter_records(path):
+        try:
+            validate(rec, "prior-store.schema.json")
+        except ValueError as e:
+            raise ValueError(f"{path}:{i}: {e}") from None
+        rows.append(rec)
+    df = pd.DataFrame(rows)
+    if df.empty:
+        return df
+    superseded = set(df["supersedes"].dropna()) if "supersedes" in df.columns else set()
+    df = df[~df["id"].isin(superseded)]
+    if metric is not None:
+        df = df[df["metric"] == metric]
+    df = df.assign(_order=range(len(df))).sort_values(["metric", "date", "_order"])
+    df = df.groupby("metric", group_keys=False).tail(window).drop(columns="_order")
+    return df.reset_index(drop=True)
+
+
+# %% ---------------------------------------------------------------- registry
+
+
+def read_registry(path, status=None):
+    """The metric registry as a DataFrame, optionally filtered by status."""
+    rows = []
+    for i, rec in _iter_records(path):
+        try:
+            validate(rec, "metric-registry.schema.json")
+        except ValueError as e:
+            raise ValueError(f"{path}:{i}: {e}") from None
+        rows.append(rec)
+    df = pd.DataFrame(rows)
+    if status is not None and not df.empty:
+        df = df[df["status"] == status].reset_index(drop=True)
+    return df
+
+
+# %% --------------------------------------------------------------------- cli
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="gallop.priors", description=__doc__.splitlines()[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sp = sub.add_parser("append", help="validate and append one record")
+    sp.add_argument("--store", required=True)
+    sp.add_argument("--json", required=True, help="the record as a JSON object")
+    sp = sub.add_parser("read", help="print the windowed store")
+    sp.add_argument("--store", required=True)
+    sp.add_argument("--metric")
+    sp.add_argument("--window", type=int, default=100)
+    sp = sub.add_parser("registry", help="print the metric registry")
+    sp.add_argument("--registry", required=True)
+    sp.add_argument("--status")
+
+    a = p.parse_args(argv)
+    if a.cmd == "append":
+        rec = append(a.store, json.loads(a.json))
+        print(f"appended {rec['id']} to {a.store}")
+    elif a.cmd == "read":
+        print(read(a.store, metric=a.metric, window=a.window).to_string(index=False))
+    else:
+        print(read_registry(a.registry, status=a.status).to_string(index=False))
+
+
+if __name__ == "__main__":
+    main()