Postpaid Rating Engine: Disputes, Bundles and Shared Family Allowances

Postpaid Rating Engine: Disputes, Bundles and Shared Family Allowances

You've joined the billing team at a mobile carrier. The rating engine turns call detail records (CDRs) from the network switch into bill line items. Customer care has three open dispute tickets, and two roadmap features are queued behind them. All money is integer cents.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh biller and returns exactly one result per operation. Errors are returned as "error: <code>" strings, never raised. An unknown operation name, or an operation that is not a list starting with a string, returns "error: unknown operation" / "error: invalid arguments" respectively.

CDR operations (call, sms, data) check in this order: invalid arguments (wrong argument count, ids that are not non-empty strings, start/seconds/megabytes that are not integers, seconds < 0, megabytes <= 0), unknown line, duplicate cdr, outside period, invalid destination, no international rate. A failed CDR changes nothing and does not reserve its cdr_id. cdr_ids are unique across the whole system.

• start is in seconds since the start of the billing period, which is a Monday 00:00:00. A CDR is in the period if 0 <= start < 2592000 (30 days). A call that starts in the period is billed in full even if it runs past the end.
• dest is "on" (same network), "off" (other network) or an international number: + followed by 7-15 digits. sms accepts only "on"/"off". Any other dest is invalid destination; a well-formed international number whose prefix is not in config.INTERNATIONAL_RATES is no international rate.
• cdr_repeat imports a recurring usage pattern: record i (for i in 0..count-1) has id "<prefix>-<i padded to 5 digits>", starts at start + i*step, and its quantity (seconds for a call, megabytes for data) is cycle[i % len(cycle)]; an sms ignores cycle. Each record goes through exactly the same checks as the single-CDR operations; the first failing record's error is returned and records before it stay ingested. kind is "call", "sms" or "data"; dest is "" for data. 1 <= count <= 100000 and step >= 0.
• cdr_ids sort by plain string comparison.

Bill items are [cdr_id, band, qty, bundled, cents]: qty units of band, of which bundled were covered by the plan allowance (Part 2; always 0 before that), costing cents. Bands are "peak" and "offpeak" (domestic voice, qty in seconds), "intl" (international voice, seconds), "sms" (qty 1) and "data" (qty in MB). A call with 0 seconds produces no items. bill lists the line's items ordered by (start, cdr_id) of their CDR, a call's segments in time order, and total is the sum of their cents.

Rating rules

1. Billing increments. Domestic calls are 60/30, international calls 60/60 (config). A call of d seconds is billed 0 if d = 0, 60 if 1 <= d <= 60, otherwise 60 + 30 * ceil((d - 60) / 30) (international: step 60). Rounding is always up.
2. Peak / off-peak. Peak is Monday to Friday from 08:00:00 inclusive to 20:00:00 exclusive; everything else is off-peak. Domestic voice only; international calls are one flat rate and are never split.
3. Calls that straddle a boundary are cut into maximal runs of one band: adjacent stretches in the same band (e.g. 23:50 Tuesday to 00:10 Wednesday, all off-peak) are *one* segment.
4. Increment rounding applies once, to the whole call, never per segment. The call's real seconds are divided between its segments; the padding added by rule 1 (billable minus real seconds) is billed in the last segment, at that segment's rate.
5. Voice cost of a segment is qty * cents_per_minute / 60, rounded half-up to a whole cent ((qty * rate + 30) // 60), once per segment item. SMS costs its per-message rate, data megabytes * DATA_RATE. Rates are in config.py.
6. International calls use the rate of the longest matching prefix in INTERNATIONAL_RATES (+441624... is Isle of Man, not UK; +1242... is the Bahamas, not US/Canada).

Worked example (Monday 10:00 is 36000; Friday 19:58 is 417480)

[["line", "L1", "payg"],
 ["call", "c1", "L1", 36000, 90, "on"],
 ["call", "c3", "L1", 36100, 100, "+441624998877"],
 ["call", "c2", "L1", 417480, 250, "off"],
 ["bill", "L1"]]

returns

[true, true, true, true,
 {"total": 173, "items": [["c1","peak",90,0,12], ["c3","intl",120,0,116],
                          ["c2","peak",120,0,30], ["c2","offpeak",150,0,15]]}]

(c2 ran 120 s in peak and 130 s off-peak; 250 s bills as 270, so the 20 s of padding lands in the off-peak segment.)

Part 1 - Three billing disputes (BILL-512, BILL-530, BILL-541)

Goal: make the engine follow the rating rules above. Records arrive for a line in (start, cdr_id) order, and nothing is bundled yet.

Tickets:

1. BILL-512 (Finance audit): "Some 70-75 second calls are billed as 60 seconds, and calls that never connected (0 seconds) are billed a full minute."
2. BILL-530 (Customer care): "A customer called at 19:58 on a Friday for four minutes and was billed far more than the same call on a Wednesday afternoon. Another got two items for a call that ran across midnight on a Tuesday, and a call that began at exactly 20:00:00 was billed as peak."
3. BILL-541 (Customer care): "Calls to the Isle of Man and the Bahamas are billed at the UK and US rates."

tests/ contains unit tests for the helpers; several currently fail.

Part 2 - Monthly bundles (PRODUCT-88)

Goal: plans now carry a monthly allowance, and each line's usage draws on it before anything is charged.

Plans and allowances are in config.PLANS as (voice seconds, sms count, data MB). payg has none.

Rules

1. Allowances cover domestic voice, sms and data only. International calls never use or reduce an allowance.
2. Records are consumed in chronological order, by (start, cdr_id). Part 2 guarantees records of a line arrive in that order.
3. Voice allowance is measured in billable seconds: rule 4's padding counts. A call's segments draw on it in time order. One allowance covers peak and off-peak time alike.
4. The record that crosses the limit is split: the item's bundled is the part still covered and its cents charge only the remaining qty - bundled, with the half-up rounding applied to the charged part only. Once an allowance kind is exhausted, every further record of that kind is charged in full (bundled = 0). An sms is covered if at least one sms remains. Each kind (voice, sms, data) has its own balance.
5. Items still list qty as the full quantity of the segment, even when entirely bundled (cents = 0).

Example (lite plan: 600 voice seconds, 5 sms, 50 MB)

[["line", "L1", "lite"],
 ["call", "c1", "L1", 36000, 500, "on"],
 ["call", "c2", "L1", 37000, 120, "off"],
 ["data", "c3", "L1", 38000, 60],
 ["bill", "L1"]]

returns

[true, true, true, true,
 {"total": 48, "items": [["c1","peak",510,510,0], ["c2","peak",120,90,8], ["c3","data",60,50,40]]}]

(500 s bills as 510 and is fully covered; 90 s of allowance remain for c2, whose other 30 s cost 30 * 15 / 60 = 7.5, rounded to 8; 10 of the 60 MB are charged at 4 cents.)

Part 3 - Family pools and late CDRs (PRODUCT-102, OPS-3317)

Goal: lines can share one allowance, and CDRs may now arrive late.

line takes an optional third argument, group_id (a non-empty string; otherwise invalid arguments). All lines in the same group share a single allowance equal to their plan's, not one per line. Lines without a group keep a private allowance.

Rules

1. line errors become: invalid arguments, unknown plan, line exists, then plan mismatch if the group already exists with a different plan. The first line of a group fixes its plan.
2. A group's records, from all its lines, are consumed in the global order (start, line_id, cdr_id) (plain string comparison for ties). A line's bill shows only its own items and total, but they depend on its sibling lines' usage.
3. The ordered-arrival guarantee of Part 2 is withdrawn. CDRs for any line may arrive in any order and may be older than ones already ingested (network re-sends, roaming partners). Every bill must equal what you would get if all CDRs received so far had arrived sorted by the consumption order above, so a late CDR can change items and totals of later usage, including other lines' in the group. All errors from the CDR operations (including invalid destination) are still reported by the operation that carries the record, at ingestion.
4. bill is repeatable: asking twice without new CDRs returns the same answer. Hidden tests ingest thousands of records (via cdr_repeat) interleaved with many bills over many lines in one run; the whole suite has a few seconds.

Example (lite plan; c2 arrives after c1)

[["line", "A", "lite", "fam"],
 ["line", "B", "lite", "fam"],
 ["call", "c1", "A", 1000, 400, "on"],
 ["bill", "A"],
 ["call", "c2", "B", 500, 300, "on"],
 ["bill", "A"],
 ["bill", "B"]]

returns

[true, true, true,
 {"total": 0, "items": [["c1","offpeak",420,420,0]]},
 true,
 {"total": 4, "items": [["c1","offpeak",420,300,4]]},
 {"total": 0, "items": [["c2","offpeak",300,300,0]]}]

(c2 starts first, so it consumes 300 of the shared 600 seconds; c1 then has only 300 of its 420 covered and 120 s are charged at 2 cents a minute.)

Notes

• config.py is the signed-off tariff and is correct; so are the wire shapes in models.py.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones; hidden tests re-check earlier behaviour.