loopable / platform /modules /customer_decline.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
81a8217 verified
Raw History Blame Contribute Delete
15.4 kB
"""Explain one customer's invoiced revenue with an exact ordered bridge."""
from contextlib import nullcontext
from decimal import Decimal
from fractions import Fraction
_DRIVERS = ("order frequency", "basket size", "product mix", "quantity", "price", "margin")
def _number(value):
"""Refuse missing observations instead of turning them into zero."""
if value is None or isinstance(value, bool):
raise ValueError("The invoice observation is incomplete.")
value = Decimal(str(value))
if not value.is_finite():
raise ValueError("The invoice observation is not finite.")
return Fraction(value)
def _money(cents):
return format(Decimal(cents) / 100, ".2f")
def _group_count(row, first_group):
"""Accept source count names without inventing a count for an incomplete group."""
count = row.get("__count", row.get(first_group + "_count"))
if type(count) is not int or count < 0:
raise ValueError("The source group count is unavailable.")
return count
def _document_group_id(row):
"""Read the source group identity from its field or exact conjunctive domain."""
identifier = row.get("id")
if "id" not in row:
# Odoo can omit id even when requested, but returns its equality in __domain.
domain = row.get("__domain")
if not isinstance(domain, (list, tuple)) or any(
term != "&" and not (isinstance(term, (list, tuple)) and len(term) == 3)
for term in domain):
raise ValueError("The source invoice identity is unavailable.")
identities = [term for term in domain if isinstance(term, (list, tuple)) and term[0] == "id"]
if len(identities) != 1 or identities[0][1] != "=":
raise ValueError("The source invoice identity is unavailable.")
identifier = identities[0][2]
if type(identifier) is not int or identifier <= 0:
raise ValueError("The source invoice identity is unavailable.")
return identifier
def _period(observation):
"""Tie every included invoice line to its own untaxed document total."""
documents = {row["id"]: row for row in observation["documents"]}
if len(documents) != len(observation["documents"]):
raise ValueError("The invoice observation contains duplicate documents.")
by_document = {key: [] for key in documents}
seen = set()
for line in observation["lines"]:
if line["id"] in seen or line["move_id"] not in documents:
raise ValueError("The invoice line observation is incomplete or duplicated.")
seen.add(line["id"])
subtotal = _number(line["price_subtotal"])
# Cost-of-sales journal rows remain in source validation and outside revenue.
if line["display_type"] == "cogs":
continue
if line["display_type"] not in (None, False, "", "product"):
if subtotal:
raise ValueError("An unsupported invoice line carries an untaxed amount.")
continue
by_document[line["move_id"]].append(line)
groups, total, count = {}, Fraction(0), 0
for identifier, document in documents.items():
untaxed = _number(document["amount_untaxed"])
signed = _number(document["amount_untaxed_signed"])
lines = by_document[identifier]
subtotals = [_number(line["price_subtotal"]) for line in lines]
if sum(subtotals, Fraction(0)) != untaxed:
raise ValueError("Invoice lines do not reconcile to their untaxed document total.")
if not untaxed and (signed or any(subtotals)):
raise ValueError("A zero-total invoice needs a verified currency conversion.")
conversion = signed / untaxed if untaxed else Fraction(1)
if conversion <= 0:
raise ValueError("The invoice currency conversion is unavailable.")
for line, subtotal in zip(lines, subtotals):
quantity = _number(line["quantity"])
if quantity and line["product_id"] is not None and line["product_uom_id"] is None:
raise ValueError("A product quantity has no observed unit of measure.")
# Zero-quantity amounts use charge incidence, never a fabricated unit price.
key = (line["product_id"], line["product_uom_id"],
"charge" if not quantity else ("positive" if quantity > 0 else "negative"))
group = groups.setdefault(key, {"lines": 0, "units": Fraction(0), "revenue": Fraction(0)})
group["lines"] += 1
group["units"] += quantity if quantity else 1
group["revenue"] += subtotal * conversion
count += 1
total += signed
return {"invoices": len(documents), "lines": count, "groups": groups, "revenue": total}
def bridge(previous, current):
"""Attribute differences between rounded cumulative states without a residual bucket."""
periods = [_period(previous), _period(current)]
keys = set(periods[0]["groups"]) | set(periods[1]["groups"])
factors = []
for index, period in enumerate(periods):
other = periods[1 - index]
basket = (Fraction(period["lines"], period["invoices"]) if period["invoices"] else
Fraction(other["lines"], other["invoices"]) if other["invoices"] else Fraction(0))
mix, units, prices = {}, {}, {}
for key in keys:
group = period["groups"].get(key)
donor = group or other["groups"][key]
mix[key] = (Fraction(group["lines"] if group else 0, period["lines"])
if period["lines"] else Fraction(donor["lines"], other["lines"]))
units[key] = donor["units"] / donor["lines"]
prices[key] = donor["revenue"] / donor["units"]
factors.append([period["invoices"], basket, mix, units, prices])
def value(state):
invoices, basket, mix, units, prices = state
return invoices * basket * sum((mix[key] * units[key] * prices[key] for key in keys), Fraction(0))
state = list(factors[0])
cumulative = [round(value(state) * 100)]
for index in range(5):
state[index] = factors[1][index]
cumulative.append(round(value(state) * 100))
totals = [round(period["revenue"] * 100) for period in periods]
if cumulative[0] != totals[0] or cumulative[-1] != totals[1]:
raise ValueError("The invoice bridge does not reconcile.")
changes = [cumulative[index + 1] - cumulative[index] for index in range(5)] + [0]
margin = {"available": False, "previous": None, "current": None, "change": None,
"reason": "Historical invoice cost is unavailable. Linked order costs require verified "
"allocation, currency, date and unit conversion."}
drivers = [{"driver": name, "revenue_change_cents": change, "revenue_change": _money(change),
"revenue_lost_cents": -change, "revenue_lost": _money(-change)}
for name, change in zip(_DRIVERS, changes)]
drivers[-1]["diagnostic"] = margin
drivers.sort(key=lambda row: -row["revenue_lost_cents"])
return {"status": "no history" if not any(period["invoices"] for period in periods) else "ok",
"basis": "invoiced", "history_scope": "requested periods",
"previous_revenue": _money(totals[0]), "current_revenue": _money(totals[1]),
"revenue_change": _money(totals[1] - totals[0]), "revenue_change_cents": totals[1] - totals[0],
"attribution_order": list(_DRIVERS), "drivers": drivers, "margin": margin,
"previous_invoice_count": periods[0]["invoices"], "current_invoice_count": periods[1]["invoices"],
"method": "Sequential substitution: invoice count, lines per invoice, product, unit and quantity-sign mix, "
"units per line, realized company-currency price. Basket size means invoice lines per invoice. "
"Each cumulative revenue state rounds half even to cents before differences are taken. "
"Missing product-period prices and quantities use the observed other period, so entry and exit "
"belong to product mix. An empty period borrows composition from the observed period. "
"Zero-quantity lines form separate charge cohorts with one charge per line. Their price "
"means amount per charge. Product-less charges remain included. Refunds are separate. "
"Margin is a profit diagnostic with zero independent revenue attribution. "
"Invoice count measures frequency over the requested windows without normalizing their length."}
def validate(observations, *, runtime=None, client=None):
"""Reconcile pinned mirror documents and line cohorts to independent Odoo read_group results."""
import core.odoo as O
if runtime is not None:
if client is not None:
raise ValueError("An explicit client cannot override the tenant source.")
runtime.assert_datastore_matches()
source = runtime.odoo_source()
if source is None:
raise ValueError("The invoice source is unavailable.")
binding = source._bound()
else:
binding = nullcontext()
checks = []
pin = observations["pin"]
identity = [("partner_id.name", "=", pin["name"])]
if pin.get("id") is not None:
identity.append(("partner_id", "=", pin["id"]))
with binding:
reader = client if client is not None else O.get_odoo()
base = [("state", "=", "posted"), ("move_type", "=", "out_invoice"), *identity]
identities = reader.read_group("account.move", base, ["partner_id"], ["partner_id"], lazy=False)
ids = {row["partner_id"][0] if isinstance(row["partner_id"], (tuple, list)) else row["partner_id"]
for row in identities if row.get("partner_id")}
checks.append({"check": "customer identity stays pinned", "ok": ids == set(observations["history_ids"])})
for observation in observations["periods"]:
window = observation["window"]
dates = [("invoice_date", ">=", window["date_from"]), ("invoice_date", "<=", window["date_to"])]
groups = reader.read_group("account.move", base + dates,
["id", "amount_untaxed_signed:sum", "amount_untaxed:sum"], ["id"], lazy=False,
orderby="amount_untaxed_signed")
if any(field not in row for row in groups
for field in ("amount_untaxed_signed", "amount_untaxed")):
raise ValueError("The source invoice total is unavailable.")
documents = {row["id"]: row for row in observation["documents"]}
live_documents = {_document_group_id(row): row for row in groups}
documents_tied = (len(live_documents) == len(groups) and documents.keys() == live_documents.keys()
and all(_group_count(row, "id") == 1 and all(
round(_number(row[field]) * 100) == round(_number(documents[key][field]) * 100)
for field in ("amount_untaxed_signed", "amount_untaxed"))
for key, row in live_documents.items()))
count = sum(_group_count(row, "id") for row in groups)
theirs = sum((_number(row["amount_untaxed_signed"]) for row in groups), Fraction(0))
ours = _period(observation)["revenue"]
checks.append({"check": "posted invoice total and count", "window": window,
"ours": _money(round(ours * 100)), "independent": _money(round(theirs * 100)),
"ok": documents_tied and round(ours * 100) == round(theirs * 100) and count == len(documents)})
line_domain = [("move_id.state", "=", "posted"), ("move_id.move_type", "=", "out_invoice"),
("move_id.partner_id.name", "=", pin["name"]),
("partner_id.name", "=", pin["name"]),
("move_id.invoice_date", ">=", window["date_from"]),
("move_id.invoice_date", "<=", window["date_to"])]
if pin.get("id") is not None:
line_domain += [("partner_id", "=", pin["id"]), ("move_id.partner_id", "=", pin["id"])]
live = []
line_fields = ["move_id", "product_id", "product_uom_id", "display_type"]
for sign, comparison in (("positive", ">"), ("negative", "<"), ("charge", "=")):
groups = reader.read_group("account.move.line", line_domain + [("quantity", comparison, 0)],
[*line_fields, "price_subtotal:sum", "quantity:sum"],
line_fields, lazy=False)
live.extend((sign, row) for row in groups)
def relation(value):
return value[0] if isinstance(value, (list, tuple)) else (value or None)
expected = {}
for row in observation["lines"]:
quantity_value = _number(row["quantity"])
sign = "positive" if quantity_value > 0 else "negative" if quantity_value < 0 else "charge"
key = (row["move_id"], row["product_id"], row["product_uom_id"], row["display_type"] or None, sign)
subtotal, quantity, number = expected.get(key, (Fraction(0), Fraction(0), 0))
expected[key] = (subtotal + _number(row["price_subtotal"]), quantity + _number(row["quantity"]), number + 1)
actual = {}
for sign, row in live:
if any(field not in row for field in (*line_fields, "price_subtotal", "quantity")):
raise ValueError("The source invoice line groups are incomplete.")
key = tuple(relation(row[field]) for field in line_fields) + (sign,)
if key in actual:
raise ValueError("The source invoice line groups are incomplete.")
actual[key] = (_number(row["price_subtotal"]), _number(row["quantity"]), _group_count(row, "move_id"))
tied = actual.keys() == expected.keys() and all(
round(actual[key][0] * 100) == round(expected[key][0] * 100)
and abs(actual[key][1] - expected[key][1]) <= Fraction(1, 10**9)
and actual[key][2] == expected[key][2] for key in expected)
checks.append({"check": "posted invoice line cohorts", "window": window, "ok": tied})
return checks
def explain_customer(customer, previous_window, window, *, runtime, user, customer_id=None):
"""Serve a customer bridge only after its mirror observations reconcile independently."""
from harness import semantic
observations = semantic.customer_invoice_periods(customer, previous_window, window,
customer_id=customer_id, runtime=runtime, user=user)
checks = validate(observations, runtime=runtime)
if not checks or any(check.get("ok") is not True for check in checks):
raise ValueError("The customer invoice observation has not reconciled.")
result = bridge(*observations["periods"])
return {**result, "customer_id": observations["pin"].get("id"),
"previous_window": previous_window, "window": window, "validation": checks}