Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
File size: 15,419 Bytes
dec006b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 | """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}
|