Work

[Start] "run() called"

The public entry point. Kicks off the whole season's weekly optimization loop;

returns a pandas DataFrame of every selected markdown across all weeks.

[Reset] "Reset per-run state"

Clears every accumulator (output rows, unlimited budget, bd frozen, md frozen,

md at funding, first candidate week, funding week, per-key spend/budget tallies, settled products, first markdown week, timing log, weekly output

error) before the loop starts. Needed because a second run() call on the same object would otherwise silently start contaminated by the previous run's

state.

[LoopStart] "for week in the sorted weeks list"

The main iteration: one pass of everything inside "Per-week iteration" runs

once per scheduled week, in chronological order.

[ForcedCalc] "Compute forced this week and blocked this week"

forced this week = keys whose date-triggered forced-markdown deadline is

exactly this week and aren't funded yet. blocked this week = keys with a

deadline elsewhere whose eligible weeks doesn't include this week — they still

get evaluated by MDO, just can't be budget-funded this week.

[BudgetCheck] "week budget < 0, or budget = 0 with nothing forced?"

Cheap short-circuit before doing any real work. A negative budget always

skips the week, forced keys or not. A budget of exactly zero skips too,

UNLESS something is forced this week — that's the only carve-out, and it does

not extend to negative budgets.

[SkipZero] "Record 'zero budget', record forced-no-candidate"

Logs the skip reason to the timing log. Still calls the forced-no-candidate

recorder so forced-key bookkeeping doesn't silently under-count.

[NextWeek] "continue to next week"

The loop-back point every branch eventually funnels into, whether it skipped

early or ran the full pipeline.

[Prepare] "prepare iteration dataframes(week)"

Builds this week's three working frames: eligible business rules (filtered to effective/exit dates, INNER-JOINED to product/store groups still flagged is_eligible — this join, not the date filter, is what actually drops

previously-funded products, and it's also anti-joined against settled products), eligible product-location rows, and eligible product-location-week rows (restricted to week end date at or after this week, so past weeks can't leak back in).

[PrepCheck] "any eligible products?"

The prepare-iteration step returns nothing if there's no eligible product this

week — nothing left to optimize.

[SkipNoElig] "Record 'no eligible products'"

Logs the skip reason to the timing log AND still calls the forced-no-candidate

recorder — same forced-key bookkeeping as SkipZero. Nothing to advance because

nothing was prepared.

[ForceJoin] "forced this week non-empty?"

Decides whether to inject the forced-markdown override before running MDO.

[Force] "Join force-first-markdown = True for forced keys"

A small broadcast join that flips the force-first-markdown flag to True on

exactly this week's forced keys' business-rules rows, telling MDOptimization

to force a discount for them.

[RunMDO] "run MDOptimization(...) to get md opt"

Runs MDOptimization.optimize() on this week's eligible pool. This is the core

pricing engine — everything downstream this week depends on its output (the

final metrics and full markdown dataframes).

[Settled] "drop settled products?"

If the flag is on, check which keys MDO just declared permanently optimal.

[CollectSettled] "collect settled keys(md opt)"

Finds keys with zero candidate rows where every row is status '2' or '5'

(current price is already the answer), adds them to the settled-products set

so future weeks skip them entirely.

[RunETL] "run budget ETL(md opt, iter plw) to get candidates"

Converts MDO's final metrics and markdown calculations into budget-optimizer-

ready candidate rows via BudgetOptimizerETL, then pulls the result to pandas.

[CandCheck] "candidates empty?"

MDO ran but produced nothing fundable for anyone this week.

[DiagEmpty1] "diagnostics + state update on empty candidates"

Four things happen here, in order: diagnostics still record the week, the

state update still runs (with an empty selection) so inventory keeps

depleting for every evaluated product, the first-markdown-week recorder runs

(a documented no-op on an empty selection), and the forced-no-candidate

recorder runs. Skipping the state update would freeze inventory for the rest

of the season for every product evaluated this week.

[Filter] "forced markdown dates in use?"

Only relevant when the date-triggered forced-markdown feature is active.

[FilterEW] "filter eligible weeks(...) to get optimizer candidates"

Strips this week's blocked keys out of the pool the budget optimizer is

allowed to pick from — but NOT out of the full candidates frame, so MDO's real

recommendation still shows up in diagnostics regardless of the restriction.

[NoFilter] "optimizer candidates = the full candidates frame"

The pass-through path when forced-markdown isn't in use — nothing to filter.

[RunOpt] "run the budget optimizer(...) to get selected rows"

The actual budget decision: which candidates get funded within this week's

dollar limit, via BudgetMarkdownOptimizer. Returns both the selected rows and a

result object carrying strategy, fallback reason, and MIP-gap diagnostics.

[SelCheck] "selected rows empty?"

Real candidates existed, but the budget optimizer funded none of them — the

docstring calls this "the most informative week in the whole artefact."

[DiagEmpty2] "diagnostics + state update on nothing selected"

Identical to DiagEmpty1, same four calls: record the week, still deplete

inventory via the state update with an empty selection, the (no-op)

first-markdown-week recorder, and the forced-no-candidate recorder.

[DiagFull] "emit weekly diagnostics(...) with real selections"

Builds this week's full diagnostic output (weekly trajectory plus unlimited-

budget accumulation) now that there's something real to report.

[Append] "Append to the output rows, record first-markdown week"

Adds this week's funded rows to the running output list (after dropping the

internal-only forced-flag column), and records the first week each key got

funded.

[CurWeek] "week equals the current week end date?"

Only relevant in "splice mode" — when the caller wants this specific week's

recommendations handed back separately.

[Capture] "capture current week recommendations(...)"

Joins funded keys back into the final metrics to get per-location recommended

prices AND projected sales, materializes eagerly so it survives the later

cache cleanup.

[UpdateState] "update state(selected rows, md opt, week)"

Advances everything for next week: inventory and units-sold for every

evaluated product, plus eligibility, further-markdown flag, and current price

for funded ones only. Ends with a Spark checkpoint to break accumulated

lineage.

[Cleanup] "finally: unpersist caches"

Always releases md opt's cached frames and this week's working frames, even

if something above raised — prevents memory buildup across weeks.

[Assemble] "assemble weekly output() to get self.weekly output"

Runs once, after every week is done. Builds the full key-by-week rectangle and

splices the constrained (actual) path from the frozen trajectories. Guarded —

a failure here is recorded, not raised, so it can never take down the real

selections.

[BuildUB] "Build self.unlimited budget output"

Converts the unlimited-budget dict into the public output dataframe — one row

per key, the "money no object" counterfactual.

[Return] "return the concatenated output rows"

The final output: every week's funded selections, stacked into one dataframe

(or an empty one if nothing was ever funded all season).