Public API
==========

The curated public surface — modules pytyche commits to as stable.
The full module tree (including internal helpers and extender hooks)
lives under :doc:`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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.bcf.dispatch

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.

.. autosummary::
   :toctree: _autosummary

   pytyche.bcf.hurdle

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.bcf.config

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.

.. autosummary::
   :toctree: _autosummary

   pytyche.analysis.analyze
   pytyche.analysis.fit_policy_tree
   pytyche.analysis.thompson_allocation
   pytyche.analysis.apply_calibration
   pytyche.analysis.recommendation_summary
   pytyche.analysis.evaluate_against_truth
   pytyche.analysis.PolicyTreeResult
   pytyche.analysis.TruthComparison

Visualization
-------------

pytyche.viz
~~~~~~~~~~~

Static matplotlib primitives over the result objects. Each accepts an
optional ``ax`` for subplot composition; matplotlib loads lazily on
first use.

.. autosummary::
   :toctree: _autosummary

   pytyche.viz.plot_cells
   pytyche.viz.plot_policy_tree
   pytyche.viz.plot_segment_intervals
   pytyche.viz.plot_calibration
   pytyche.viz.experiment_evolution_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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.experiment.schedule

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.experiment.cells

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*: :func:`pytyche.experiment.simulate.simulated_experiment_generator`
  wraps a shipped DGP template and returns planted ground truth, so
  every round carries a ``TruthComparison``.
- *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
  reserved ``cell`` column, 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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.experiment.sequential

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.experiment.experiment

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

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.experiment.recommendation

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.experiment.simulate

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.calibrate.sbc
   pytyche.calibrate.layered
   pytyche.calibrate.scorecard
   pytyche.calibrate.artifact

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

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.generators.api
   pytyche.generators.core
   pytyche.generators.scenarios

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.contracts

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.diagnostics.run_monitor

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.setup

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.bcf.continuous

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.

.. autosummary::
   :toctree: _autosummary
   :recursive:

   pytyche.bcf.binary