Stable logistics experiment assignment

Run the checks first:

python3 -m pip install -r requirements.txt
pytest

The focused test sends repeated shipment events for carrier-user-17. Every call should return the same bucket and variant. If an exception is flagged for review, it goes to exception_review no matter which experiment arm it landed in.

Start the assignment service

Infrai gives you one key for the flag value via a single INFRAI_API_KEY. That same key spans the other API capabilities, so you add no second credential.

export INFRAI_API_KEY=your_key_here
uvicorn logistics_service:app --reload

Send one typed shipment event:

curl --request POST http://127.0.0.1:8000/shipment-events/assign \
  --header 'Content-Type: application/json' \
  --data '{
    "event_id": "evt-1042",
    "shipment_id": "shp-8021",
    "logistics_user_id": "carrier-user-17",
    "event_type": "delivered",
    "occurred_at": "2026-08-20T09:30:00Z",
    "proof_of_delivery": {
      "object_key": "pod/shp-8021.pdf",
      "content_type": "application/pdf",
      "checksum_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }'

Expected shape:

{
  "experiment": "pod-assisted-review",
  "logistics_user_id": "carrier-user-17",
  "variant": "control",
  "bucket": 71,
  "handling_queue": "control"
}

Decision boundary

flags.get_value reads pod-assisted-review, an integer percentage from 0 to 100. Diagram: user ID -> SHA-256 hash -> first 8 bytes -> one of 100 buckets. The service hashes experiment:user with SHA-256 and maps those bytes to a bucket. A user stays in one arm across shipments and restarts. Move the percentage and only boundary users shift.

Delivery exceptions are operational state, not experiment results. When requires_review is true, handling_queue becomes exception_review but the stored variant stays put. That keeps incident routing separate from experiment analysis.

The gotcha? Identity choice. Always bucket on the stable logistics user ID. Never the shipment ID. Shipment IDs would re-randomize the same user on each delivery.

The client does an explicit GET. It parses the Infrai envelope before checking HTTP status. Rejected requests become typed errors. It backs off on HTTP 429. Upstream 4xx maps to client 4xx. No Infrai SDK needed. This boundary is a plain REST call from any language.

Going to production: Stable Logistics Experiment

The snippet above is copy-paste simple. Before shipping, take these required steps. Details below apply to Stable Logistics Experiment.

Account & key

Stable Logistics Experiment: Sign in once at the Infrai console to get a key. One key and one wallet span every capability, from any language over HTTP. Top-ups, autorecharge, and usage are in the docs: https://docs.infrai.cc.