Skip to content

chc.spine

Stability tier: evolving.

The four layers on one story: confounded logs -> causal effect -> plan -> safety certificate.

Every layer of this library already had its own demo; none of them ran end to end. This is the whole spine on a single decision, so the pieces are forced to compose:

  1. fit -- an incentive response estimated from logs whose behaviour policy chased a confounder (chc.causal), once naively and once with the backdoor adjustment;
  2. plan -- constrained OC with a certified Gronwall error tube (chc.plan.causal_plan);
  3. certify -- the plan priced against a partially identified effect (chc.plan.certify_safety);
  4. audit -- each plan then executed on the true plant, so the numbers a caller would have trusted offline can be compared with what actually happened.

The plant is two zones of a mobile driver pool. Incentivising zone A pulls drivers out of zone B (the [+b, -b] control column is driver conservation, i.e. the interference channel), zone B drains on its own, and the barrier is a supply floor there. So the objective and the constraint pull against each other through the only lever available, which is what makes the certificate load-bearing rather than decorative.

Deliberately control-affine: chc.plan.certify_safety reads the channel B^T grad h off the Jacobian at u = 0, exact for an affine plant and only a linearisation otherwise -- the softmax-equilibrium market in chc.marketplace is not affine, so certifying a plan on it would quietly evaluate the channel at the wrong action.

uv run python scripts/spine_demo.py

SpineArm dataclass

One controller: what it believed, what it planned, and what that plan actually cost.

SpineReport dataclass

The two arms plus the ground truth neither of them was allowed to see.

two_zone_market(effect, *, decay=0.6, coupling=0.3, drain=0.25)

Driver supply in two zones under one incentive lever, xdot = A x + B u.

A is the known mechanism: zone A relaxes back to its free-flow level at rate decay, drivers exchange between the zones at coupling, and zone B loses drivers at drain on its own. B = effect * [+1, -1] is the learned part -- the incentive gain, whose sign and size are exactly what a confounded log gets wrong.

run_spine(*, n_data=20000, horizon=25, dt=0.1, target=1.0, supply_floor=-0.4, u_max=3.0, gamma=1.6, cvar_gap=1.0, seed=0, estimator=None)

Run both arms through all four layers and report them side by side.

Parameters:

Name Type Description Default
gamma, cvar_gap

the assumed sensitivity level and the gap it scales, a share of each arm's own believed channel, passed straight to chc.plan.certify_safety. They price the plan; they do not change it.

 required
supply_floor float

the barrier is h(x) = x_B - supply_floor, safe where h >= 0.

 -0.4
u_max float

the actuation budget backing gamma_star -- the box bound, not the plan's own largest action, since gamma_star asks what the best admissible action could hold.

 3.0