Ad mediation engine

app/mediation/ is header bidding for kiosk screens: every unsold loop slot is auctioned across all attached demand networks, the highest normalized eCPM above the screen's floor wins, and house/ContentX content fills whatever is left. Direct-sold sponsorship campaigns are guaranteed inventory — they take their purchased slot share before any auction runs and cannot be outbid.

Real DOOH networks don't all allow the same participation (Vistar's policy: "We expect you to implement waterfall logic… We do not allow you to host a secondary auction"), so every adapter is attached in one of three participation modes.

Decision order per slot

1. Direct-sold — STORE.active_campaigns_for_machine (active, in-flight, targeting this machine) fills its weighted share of the loop rotation first. No fan-out happens for these slots.
2. Reservation (mode="reservation", Blindspot-style booked plays) — walked sequentially in tier order before the auction. A booked play is a commitment, not a bid: if the network returns one, it runs, full stop.
3. Auction (mode="auction") — every enabled auction adapter's request_bid(SlotContext) runs concurrently, each under its own hard timeout. Highest eCPM ≥ floor wins.
4. Waterfall tiers (mode="waterfall_tier", Vistar-compliant) — never price-compared against auction bids. Walked in tier order only when the auction produced no clearing winner, and only then is the network even called — so a waterfall lease is always played, never leased-and-dropped (an unplayed lease damages the network's spend-rate metric). The first fill wins at its own price, floor notwithstanding (the floor gates whether we call, never whether we honor the response).
5. House — anything unsold always gets the house creative. A kiosk never shows an empty slot.

Adapter contract

class MyNetwork:
    async def request_bid(self, ctx: SlotContext) -> Bid | None: ...

from app import mediation
mediation.default_engine().registry.attach(
    "my_network", MyNetwork(),
    enabled=True, timeout_seconds=0.25, respects_floor=True, priority=None,
    mode="auction",          # auction | waterfall_tier | reservation
    tier=None,               # walk order for waterfall/reservation modes
    auto_approve=False,      # False → creatives queue for operator approval
)

SlotContext carries screen id, machine, OpenOOH venue type + category id, geo, resolution, slot duration, impression multiplier (est. impressions per play), loop size, and the advertised floor. Registry changes (attach / detach / enable) are safe at runtime: auctions snapshot the enabled set at start, so an in-flight auction completes untouched and the next one sees the new config.

The five price bases

Bid.price_model expresses the network's native pricing; the engine normalizes everything to USD eCPM before comparing:

Real network adapters (behind flags, all off by default)

app/mediation/networks/ implements the four integrate-behind-flag networks from the DOOH dossier. Each is unit-tested against documented example payloads with injected transports — no live vendor calls anywhere in the suite.

The Vistar request payload lives in one place (app.mediation.networks.vistar.build_get_ad_payload) and is shared with the legacy single-SSP path in app/ssp.py — the two cannot drift.

Until credentials exist, KIOSKX_MEDIATION_MOCKS (default true) attaches the built-in mock set at startup — mock_px (auction, CPM), mock_adomni (auction, contract CPM, estimated), mock_vistar (waterfall tier 1, nano-dollar spots) — whose mock:// PoP callbacks settle in-process, so production exercises the full pipeline with zero external traffic.

Proof-of-play: deadlines, retries, expiry

report_play is one-shot per auction (Vistar semantics). External winners' receipts land in a PoP dispatch queue (app/mediation/pop.py):

• the network deadline is recorded at play time (deadlineAt = played_at + deadlineSeconds);
• transient dispatch failures retry with backoff (1 s → 5 s → 30 s → 2 m → 10 m), pumped opportunistically by getAd polls and saveAdRecord reports;
• a play unreported by its deadline is marked expired — distinctly, never settled — so reconciliation sees exactly what each network was never told about;
• Adomni-style supportsTimestamp PoPs get t=<epoch-ms of the play> appended automatically.

The queue is in-memory (STORE architecture) but duck-typed — anything with enqueue(receipt, played_at=) can replace it (MediationEngine(pop_queue=…)) for a DB-backed outbox later. Inspect it at GET /api/v1/mediation/pop.

Creative approval queue

Programmatic creatives are pending by default: the first time a (source, creative URL) pair is seen from an adapter without auto_approve=True, it enters the approval queue and the engine skips it (audit status creative_pending) — in every mode, at any price. getAd can never serve an unapproved programmatic creative.

Operator surface (ads:read / ads:write scopes):

• GET /api/v1/mediation/creatives?status=pending
• POST /api/v1/mediation/creatives/{id}/approve / …/reject (rejects are permanent: creative_rejected)
• GET /api/v1/mediation/adapters — attached sources, modes, tiers.

Behaviors fixed by fiat

/apk/getAd wiring

Set KIOSKX_MEDIATION_ENABLED=true and getAd's programmatic stage (step 3, after direct campaigns and operator ads) fills through the engine via mediation.request_fill(machine, unsold_slots) instead of the single-SSP adapter. Winning slots register mediation leases so the firmware's existing /apk/saveAdRecord report settles PoP with the winning network through the dispatch queue. Flag off (default) keeps the legacy Vistar-style single-SSP path — behavior is byte-identical to before this module existed.

Standalone use (no getAd): await mediation.select_slot(screen_ctx) decides one slot; build screen_ctx with mediation.slot_context_for(machine).

Config

Verification

• tests/test_mediation_matrix.py — the exhaustive scenario matrix (131 tests): zero/disabled/one/many adapters, all five price models, floors, ties, timeouts, crashes, direct-sold interplay, burst concurrency, participation modes (waterfall/reservation ordering and no-lease-and-drop), PoP deadlines/retries/expiry, the four real-network payload mappings, creative approval, runtime config lifecycle, and the getAd wiring.
• scripts/mediation_dry_run.py — a simulated 24h day for a 3-machine fleet stepping through adapter mixes (none → one → three → three + one flaky), printing fill breakdown and eCPM by source and asserting the matrix holds together end to end.