Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download platform/modules/customer_decline.py from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 15.4 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/platform/modules/customer_decline.py
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/platform/modules/customer_decline.py
-
curl -L -o customer_decline.py https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/platform/modules/customer_decline.py
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} | |