Public API¶
The curated public surface — modules pytyche commits to as stable. The full module tree (including internal helpers and extender hooks) lives under Internal.
Start here¶
pytyche.fit (pytyche.bcf.dispatch)¶
Most users only need ``pt.fit``. Auto-selects the BCF entry point
from the observed data’s outcome shape and arm count, stashes the
observed data on the result, and returns a posterior whose methods
(analyze, fit_policy_tree, thompson_allocation, …) carry
the whole analysis surface.
Auto-selecting BCF entry point — |
pytyche.bcf.hurdle¶
fit_hurdle_bcf — the canonical entry point for zero-inflated
outcomes. Dispatches on pooling: "joint" (default) fits the
shared-tree joint MCMC over both channels; "independent" composes
separately fit participation and magnitude channels.
Public fit entry point for hurdle BCF. |
Result types and analysis methods¶
pytyche.bcf.config¶
The three posterior result types (HurdleBCFResult,
ContinuousBCFResult, BinaryBCFResult) and the sampling
configuration. The result types carry the L2 analysis methods —
analyze, fit_policy_tree, thompson_allocation,
apply_calibration, recommendation_summary,
evaluate_against_truth, and the capability probes.
Configuration dataclass, result types, and small utilities for the GPU BCF. |
pytyche.analysis¶
Function forms of the analysis methods (each takes the posterior as
its first argument), the polymorphic one-shot analyze, and the
analysis result types.
|
Fit-if-needed, then assemble the canonical analysis output. |
|
Discover interpretable segments from the posterior's per-visitor treatment effects, by fitting a shallow decision tree. |
|
Per-segment traffic split: each arm's weight is the posterior probability that it is the segment's best arm. |
Return a new posterior of the same type with calibration attached. |
|
Act-now SHIP / CONTINUE / STOP recommendation for one treatment. |
|
Evaluate the posterior + tree policy against ground truth. |
|
|
Policy-tree segmentation output. |
|
Sim-mode evaluation metrics. |
Visualization¶
pytyche.viz¶
Static matplotlib primitives over the result objects. Each accepts an
optional ax for subplot composition; matplotlib loads lazily on
first use.
|
Horizontal bar chart of per-cell traffic weights. |
|
Render the fitted policy tree as a policy, not a classifier. |
|
Forest plot of per-segment gate estimates with 80% intervals. |
|
Plot the attached R(p) coverage-remapping curve. |
|
Render the round-by-round experiment evolution to an animated GIF. |
Sequential experiments¶
pytyche.experiment.schedule¶
Round-size schedules — how many visitors each round of a sequential
experiment gets. GeometricSchedule (doubling batches) is the
first-class choice; FixedSchedule and ExplicitSchedule cover
flat and fully custom plans, and anything implementing the two-member
Schedule protocol works. All re-exported at the top level.
Schedule protocol + shipped variants for per-round visitor counts. |
pytyche.experiment.cells¶
Experiment cells and assignment policies. A round’s traffic is split
across Cell objects by weight; each cell routes its visitors
through a Policy — BaselinePolicy, UniformPolicy,
TreePolicy, or your own implementation of the two-member
protocol. All re-exported at the top level.
Cell (assignment cohort) + Policy protocol with shipped routing variants. |
pytyche.experiment.sequential¶
The sequential experiment loop. pt.sequential_experiment(...)
returns a stateful SequentialExperiment you iterate round by
round; each next(exp) runs one full round (generate → fit on
cumulative data → analyze → recommend the next round’s cells).
Data enters through a generator — any callable matching the
Generator alias: (round_idx, plan) -> (ObservedExperimentData,
CalibrationTruth | None). Two shapes:
Sim mode:
pytyche.experiment.simulate.simulated_experiment_generator()wraps a shipped DGP template and returns planted ground truth, so every round carries aTruthComparison.Real-data mode: your callable pulls the round’s data from the experimentation platform and returns
truth=None. It must honor the plan’s cell structure, write each visitor’s cell id into the reservedcellcolumn, and record the platform-reported assignment propensities into the reserved propensity columns — estimators ignore them today, but they make any future adaptive-assignment correction cheap.
The full per-round obligations (including truth-array ordering for
custom sim generators) live on the Generator alias docstring.
The |
pytyche.experiment.experiment¶
The per-round snapshot. Experiment composes the round’s fitted
posterior and analysis with the sequential context — cells shipped,
per-cell observed performance (CellObservation), the next-round
plan, and the sim-only truth comparison.
Per-round experiment snapshot: |
pytyche.experiment.recommendation¶
The recommendation engine’s output types: NextRoundPlan (the cell
structure proposed for the next round, carrying the round’s fitted
policy tree), GraduationCandidate (a treatment × segment pair
ready to ship), and the graduation rules — the GraduationRule
protocol and the default ExpectedLossRule.
Recommendation engine: the per-round |
pytyche.experiment.simulate¶
Sim-mode generator adapter: simulated_experiment_generator(...)
exposes a shipped DGP template as a Generator-conforming callable
for dress-rehearsal runs (K ≥ 3). Allocates visitors to the plan’s
cells by weight, draws treatments from each cell’s policy, and
records cell membership and blended propensities alongside the
planted truth.
Sim-mode generator adapter — pytyche DGP templates as a |
Calibration¶
pytyche.calibrate¶
Simulation-based calibration (SBC) plus isotonic R(p) recalibration. The SBC harness, the layered correction stack, and the scorecard machinery used to evaluate calibration quality — what makes “we’re 90% confident” actually a 90% claim.
v2 calibration evaluator. |
|
Layered calibration deployment primitive — R(p) below ceiling, scale-family above. |
|
v2 scorecard — decision summary and per-scenario aggregation. |
|
Calibration artifact — the v0.2 minimal contract. |
DGP generators (for power, SBC, and methodology)¶
pytyche.generators¶
Programmatic DGP generators — built-in scenarios + the sampling API
used to synthesize visitor-level data from a parameterized DGP. Same
machinery drives power simulations, SBC sweeps, and methodology
validation. Bring your own DGP or use TEMPLATES.
v2 data generator — typed output via CalibrationBundle. |
|
V2 generator core — single potential-outcomes pipeline. |
|
V2 stress scenario catalog for BCF development. |
Contracts and diagnostics¶
pytyche.contracts¶
Honest-uncertainty contract types — ClaimLevel, observed-vs-truth
records, and the shared dataclasses every fit and every calibration
artifact passes around. Read this module to understand what pytyche
promises (and refuses to promise) about its posterior outputs.
v2 typed contracts for the pytyche analysis pipeline. |
pytyche.diagnostics.run_monitor¶
Operational resource monitoring — RunLog, HWMonitor, and
ResourceSummary for capturing GPU / CPU / memory telemetry around
a fit. Useful for SBC sweep accounting and for surfacing the
wall-clock cost of a single fit.
Resource monitoring primitives for GPU calibration sweeps. |
pytyche.setup¶
Runtime inspection — check_setup() prints a summary and returns a
frozen SetupReport: package versions, JAX devices, CUDA
availability, bundled calibration artifacts, and a recommended install
command when something is missing. Also home of the once-per-process
no-CUDA fit warning; set PYTYCHE_SUPPRESS_GPU_WARNING=1 to
silence it.
Runtime setup inspection ( |
Lower-level building blocks¶
The single-channel fits below are exposed for power users / extenders
who want to drive the conversion and magnitude channels independently.
The canonical user path is fit_hurdle_bcf above; reach for these
only if you have a reason to.
pytyche.bcf.continuous¶
GPU-accelerated continuous-outcome BCF — the regression channel of the joint hurdle model, also usable stand-alone when the outcome is continuous.
Phase 1 — independent continuous BCF (bartz-based JIT scan). |
pytyche.bcf.binary¶
GPU-accelerated probit-link BCF — the participation channel of the joint hurdle model, also usable stand-alone when the outcome is binary.
Phase 2 — independent binary/probit BCF (Albert-Chib data augmentation). |