Poultry CRM Operations System/Module 01 of 06

src/core/model.py

Chapter 1 · Component 1 · 22:00src/core/model.py

System Context & Problem Formulation

Powell's Universal Modeling Framework — defining state, decision, and exogenous variables before writing code

In This Component

We establish the mathematical foundation that makes every downstream decision defensible. No code is written here. Following Powell’s discipline, the system’s decision problem is fully specified before any implementation begins.

The business question: A B2B wholesale poultry distributor receives bulk purchase orders continuously. Each order demands an instant response: accept or reject, at what price, and on what delivery schedule. The wrong answer costs margin. The right answer requires knowing current flock biomass, negotiated SLA constraints, customer churn risk, and what future orders might arrive.

Powell’s UMF Applied

The state $S_{t}$ is decomposed into three orthogonal components:

Component	Symbol	Contents
Physical Resource State	$R_{t}$	Flock count, live biomass (kg), slaughter capacity (kg/day)
Information State	$I_{t}$	Target margin %, SLA days, locked price per kg
Belief State	$B_{t}$	P90 demand forecast, yield estimate, CLV (USD), churn risk score

The decision variable is B2BAction: a named tuple of (accept_order: bool, quoted_price_per_kg: float | None, scheduled_slaughter_date: int | None).

Exogenous information $W_{t + 1}$ arrives as a discriminated union of two event types — a Python 3.14 pattern that enables strict structural matching:

B2BMarketEvent: order ID, segment ID, quantity (kg), delivery offset (days), competitor price index
IoTEdgeEvent: flock ID, mortality count, CV-sensor avg weight (kg), ammonia spike flag

Why This Formulation Matters

The belief state $B_{t}$ is what separates a sophisticated system from a naive rule-based one. CLV and churn risk are not just logged — they are state variables that evolve as a function of decisions. Rejecting an order raises churn risk by 0.15 and degrades CLV by 10%. This creates a real financial link between the pricing policy and the long-run customer relationship.