Ad Server: Auction Fixes, Budget Pacing and Mid-Day Changes

Ad Server: Auction Fixes, Budget Pacing and Mid-Day Changes

You've joined the ads platform team. Their small ad server decides, for every ad request, which advertiser's campaign gets the slot and what it pays. Advertisers are complaining about overcharges and about frequency caps that are off by a second; finance wants budgets that last the whole day instead of burning out by lunchtime; and sales has just promised advertisers that "you only ever pay for what you have left". All money is integer cents.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh ad server and returns one result per operation. Every operation is [name, ts, ...args]; ts is an integer number of seconds that never decreases. Time starts at ts = 0 = 00:00 of day 0; day = ts // 86400 and hour = (ts % 86400) // 3600 (0..23). Errors are returned as "error: <code>" strings. An unknown operation returns "error: unknown operation"; a wrong number of arguments or a non-integer ts returns "error: invalid arguments".

• bid is the most the campaign will pay per impression: an integer >= 50 (the reserve). daily_budget is an integer > 0. placements is a non-empty list of non-empty strings. hours is [start, end] with integers 0 <= start < end <= 24; the campaign is active from start:00:00 up to but not including end:00:00. freq_cap is an integer >= 1.
• stats: impressions counts all impressions ever served; spent_today and remaining (daily_budget - spent_today, never below 0) are for the day of ts.

How an ad request is decided

1. Who may bid. A campaign bids only if *all* hold: the request's placement is one of its placements; the hour is inside its active hours; it has enough budget left (see below); the user has seen it fewer than freq_cap times in the rolling 24 h window (ts - 86400, ts] (an impression at exactly ts - 86400 has expired); and (Part 2) pacing allows it.
2. Winner. The highest bid wins. Equal bids go to the campaign created first.
3. Price. The winner pays one cent more than the runner-up's bid, but never more than its own bid, and never less than the reserve of 50. With a single bidder the price is the reserve. (price = max(50, min(winner_bid, runner_up_bid + 1)).)
4. The winner is charged, the impression is recorded against the user, and request returns {"campaign": id, "price": price, "charged": amount_billed}; null if nobody bids. For now charged == price.
5. Budgets are per calendar day: spend starts at 0 on every new day.
6. Until Part 3: a campaign has enough budget only if remaining >= bid (it must be able to cover its own maximum bid).

Worked example

[["campaign", 0, "c1", 200, 100000, ["home"], [0, 24], 1],
 ["campaign", 0, "c9", 150, 100000, ["home"], [0, 24], 5],
 ["campaign", 0, "c10", 150, 100000, ["home"], [0, 24], 5],
 ["request", 100, "u1", "home"],
 ["request", 200, "u1", "home"],
 ["request", 300, "u2", "feed"],
 ["request", 86499, "u1", "home"],
 ["request", 86500, "u1", "home"]]

returns

[true, true, true,
 {"campaign": "c1", "price": 151, "charged": 151},
 {"campaign": "c9", "price": 150, "charged": 150},
 null,
 {"campaign": "c9", "price": 150, "charged": 150},
 {"campaign": "c1", "price": 151, "charged": 151}]

c1 wins first (price = runner-up 150 + 1). u1 has hit c1's cap of 1, so the tied c9/c10 pair competes: c9 was created first, and pays its own bid (150 + 1 would exceed it). Nobody serves feed. c1's impression at 100 is still inside the window at 86499 but expired at 86500.

Part 1 — Advertiser complaints about the auction (ADS-2190)

Goal: make the existing server follow the rules above. Complaints from support:

1. "Two of us bid 120 and I was charged 121 for a 120 bid."
2. "My frequency cap lets a user see the ad again one second too late" / "...one second too early."
3. "Our campaign stopped serving on day 2 and never came back."
4. "Tied bids don't go to whoever signed up first (we are c9, they are c10)."

Fix whatever is wrong; the rules in this README are the spec. The failing tests in tests/ point at some of it, not all.

Part 2 — Budget pacing and a load replay (ADS-2214)

Goal: stop campaigns burning their whole daily budget in the first hour. Add pacing to the bidding rules, an operation to inspect it, and a load-replay operation to check the system at volume.

Pacing rule. At time ts, with h = hour of ts:

1. spent_before_hour = cents the campaign had spent today when the current hour began (spent_today minus what it spent in this hour).
2. quota = max(0, daily_budget - spent_before_hour) // (24 - h) (integer division). The 24 - h counts every remaining hour slot of the day, the current one included, whether or not the campaign is active in those hours. At 23:xx the quota is everything that is left.
3. A campaign may bid only while spent_this_hour < quota. Once its spend this hour reaches the quota it is throttled until the next hour (where the quota is recomputed from what is left). A throttled campaign does not bid: it cannot win and cannot set anyone's price. This is an extra eligibility condition added to rule 1 above; the quota is only a gate, so the winning impression that crosses it is billed in full.
4. "This hour" is the clock hour (ts // 3600); a new day also starts a new hour.

traffic replays count generated ad requests as if they were ordinary request operations, at times ts, ts + step, ts + 2*step, ..., using loadgen.synthetic_requests(ts, count, step, users, seed) (it already exists). count >= 1, step >= 0, users >= 1, seed >= 0, all integers, else invalid arguments. A later operation's ts is never earlier than the last generated request. It returns {"requests": count, "filled": n_requests_with_a_winner, "revenue": total_charged, "by_campaign": {id: [impressions, total_charged]}}, counting only this call and listing only campaigns that won something. The hidden tests replay over ten thousand requests in one run, and the whole suite has a few seconds.

Example (quota 2500 // 24 = 104; each win costs the 50 reserve)

[["campaign", 0, "p", 100, 2500, ["home"], [0, 24], 1000],
 ["request", 10, "u1", "home"], ["request", 20, "u1", "home"], ["request", 30, "u1", "home"],
 ["request", 40, "u1", "home"],
 ["pacing", 41, "p"],
 ["pacing", 3600, "p"],
 ["request", 3600, "u1", "home"]]

returns true, three wins at 50, then null (150 >= 104), then {"hour": 0, "quota": 104, "hour_spent": 150, "throttled": true}, {"hour": 1, "quota": 102, "hour_spent": 0, "throttled": false} ((2500 - 150) // 23), and a win at 50.

Traffic example

[["campaign", 0, "t1", 200, 1000000, ["home", "search", "feed"], [0, 24], 2],
 ["campaign", 0, "t2", 100, 1000000, ["home"], [0, 24], 5],
 ["traffic", 1000, 6, 10, 2, 1]]

generates (u0, feed) (u0, search) (u0, home) (u1, search) (u1, search) (u0, feed) and returns {"requests": 6, "filled": 5, "revenue": 250, "by_campaign": {"t1": [4, 200], "t2": [1, 50]}}.

Part 3 — "You only pay for what you have left" and mid-day edits (ADS-2260)

Goal: sales changed the budget terms, and advertisers now edit campaigns while they run. Update the rules (this replaces rule 6 of "How an ad request is decided"), and add an edit operation.

New budget rules

1. A campaign bids whenever remaining > 0, even if remaining is less than its bid. It still bids its full bid, so it can win and it counts as runner-up for pricing.
2. The clearing price is computed exactly as before. The campaign is charged min(price, remaining): when it wins with less than the price left it pays only what is left, and that leaves remaining = 0, so it takes no part in auctions until the next day. request still reports the full price, and charged shows what was billed. The impression is served and recorded for the user either way. spent_today and the hourly pacing spend increase by charged.
3. Pacing (Part 2) still applies on top of rule 1.

Editing a running campaign

• changes is an object with one or more of bid, daily_budget, freq_cap. Anything else (not an object, empty, an unknown field) is invalid arguments. Values follow the same validation as campaign. Errors are reported in the order listed, and a rejected edit changes nothing, even if some of its fields were valid.
• Edits apply to the very next request. daily_budget is the campaign's budget for the current day as well as future days: remaining is recomputed as new_budget - spent_today (not below 0). Already-served impressions still count towards freq_cap (changing the cap does not forget them).
• Pacing restart. An edit that raises daily_budget (new > old) restarts pacing for the current hour: from that moment the campaign's hour_spent is 0 and spent_before_hour equals everything it has spent today, so quota = (new_budget - spent_today) // (24 - h). Lowering the budget, leaving it unchanged, or editing only bid or freq_cap does not touch the hour's spend.

Example 1: partial charge. All requests are in hour 23, where the quota equals the whole remaining budget.

[["campaign", 0, "q", 300, 400, ["home"], [0, 24], 1000],
 ["campaign", 0, "r", 100, 10000, ["home"], [0, 24], 1000],
 ["request", 82800, "u1", "home"], ["request", 82801, "u2", "home"], ["request", 82802, "u3", "home"],
 ["request", 82803, "u4", "home"], ["request", 82804, "u5", "home"],
 ["stats", 82805, "q"]]

returns true, true, three times {"campaign": "q", "price": 101, "charged": 101}, then {"campaign": "q", "price": 101, "charged": 97} (only 97 was left), then {"campaign": "r", "price": 50, "charged": 50} (q has nothing left) and {"impressions": 4, "spent_today": 400, "remaining": 0}.

Example 2: raising the budget restarts pacing.

[["campaign", 0, "e", 100, 2400, ["home"], [0, 24], 1000],
 ["request", 10, "u1", "home"], ["request", 20, "u1", "home"], ["request", 30, "u1", "home"],
 ["edit_campaign", 40, "e", {"daily_budget": 4800}],
 ["pacing", 41, "e"],
 ["request", 50, "u1", "home"], ["request", 60, "u1", "home"], ["request", 70, "u1", "home"],
 ["request", 80, "u1", "home"], ["request", 90, "u1", "home"]]

Quota is 100, so after two wins the third request at ts 30 returns null. The raise gives {"hour": 0, "quota": 195, "hour_spent": 0, "throttled": false} ((4800 - 100) // 24), and four more wins at 50 follow (150 < 195 still bids; 200 does not), then null at 90.

Notes

• validation.py, catalog.py, targeting.py and clock.py are known-good.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones except where Part 3 says it replaces a rule; hidden tests re-check earlier behaviour.