formative
Python library for quantitative reasoning.
Requirements
- Python 3.10+
Installation
pip install formative-ds
Docs
Comprehensive documentation is available at docs.getformative.dev.
Usage
Causal estimation
Every analysis follows the same four steps: assume, estimate, refute, decide.
from formative.causal import DAG, OLSObservational
# 1. Encode your causal assumptions as a DAG
dag = DAG()
dag.assume("ability").causes("education", "income")
dag.assume("education").causes("income")
# 2. Estimate the causal effect
result = OLSObservational(dag, treatment="education", outcome="income").fit(df)
print(result.summary())
# 3. Refute: stress-test the result's assumptions
print(result.refute(df).summary())
# 4. Decide: is the treatment worth acting on?
print(result.decide(cost=8, benefit=15))
Confounders declared in the DAG are controlled for automatically. If a confounder is absent from the dataframe, an IdentificationError is raised before any estimation runs. Some estimators go further at step 4 — per-group decisions, or learning a treatment rule with learn_policy().
Decision rules
from formative.game import maximin, maximax, hurwicz, laplace, minimax
outcomes = {
"stocks": {"recession": -20, "stagnation": 5, "growth": 30},
"bonds": {"recession": 5, "stagnation": 5, "growth": 7},
"cash": {"recession": 2, "stagnation": 2, "growth": 2},
}
maximin(outcomes).solve() # safest choice (best worst case)
maximax(outcomes).solve() # most optimistic (best best case)
hurwicz(outcomes, alpha=0.5).solve() # blend of optimism and pessimism
laplace(outcomes).solve() # highest average payoff
minimax(outcomes).solve() # lowest worst-case regret
See online documentation at docs.getformative.dev for more examples and details.
Local development
Requires uv.
git clone https://github.com/maxpagels/formative
cd formative
uv sync --dev
This creates a .venv, installs all dependencies, and installs the package in editable mode.
Releasing a new version
make release BUMP=patch # 0.1.0 → 0.1.1 (bug fixes)
make release BUMP=minor # 0.1.0 → 0.2.0 (new features)
make release BUMP=major # 0.1.0 → 1.0.0 (breaking changes)
One command does everything: bumps the version in pyproject.toml and uv.lock
(commit + tag), builds the docs, snapshots them into site/<major.minor>/ (the versioned
docs site Vercel serves statically), and pushes with tags — which triggers the publish to
PyPI. It refuses to run if the working tree is dirty or uv.lock is out of date.
Running tests
uv run pytest
Importing without installing
To use formative from a script outside this repo without installing it, either prepend the path at runtime:
import sys
sys.path.insert(0, "/path/to/formative")
from formative.causal import DAG, OLSObservational
Or set PYTHONPATH before running:
PYTHONPATH=/path/to/formative python your_script.py
1 maintainer
Metadata
1 maintainer
Release files for formative-ds 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| formative_ds-2.3.0.tar.gz | 15.6 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| formative_ds-2.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 15.7 MB
Release files / formative_ds-2.3.0.tar.gz
| Download URL | formative_ds-2.3.0.tar.gz |
|---|---|
| Size | 15.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
27e52021685beaf29d78221160f8ed95028fc9eff42874f3cb6bc2ccad5ca7b9
|
|
BLAKE2b-256 checksum How to use checksums |
6a45c63a193e6342d188a84e3b0ce69f08e7cd330a72714a8eb4e1c7dc2bc1dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / formative_ds-2.3.0-py3-none-any.whl
| Download URL | formative_ds-2.3.0-py3-none-any.whl |
|---|---|
| Size | 69.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ad378e0fbb816a03aeb15b55afe3d7dad0ff7c199edc8ad929a43d37abb5a1c2
|
|
BLAKE2b-256 checksum How to use checksums |
62a4eb0210a1c239571682d4d075bab5c4e63f5095dd4de6d20146c1c5eae82e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for formative-ds 2.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for formative_ds-2.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
