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).
