Download platform/modules/finance_spine.py from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 12.1 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/platform/modules/finance_spine.py
- Command line
-
hf download hf://spaces/fsanyoto/loopable/platform/modules/finance_spine.py
-
curl -L -o finance_spine.py https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/platform/modules/finance_spine.py
12.1 kB
| """Canonical Finance fact, proof, freshness, lineage, and drill plane. | |
| Applications name facts from this module; they never copy numbers into an application store. | |
| Interactive values come only from the tenant mirror through ``harness.semantic``. Independent | |
| reconciliation reads live Odoo only when the caller explicitly requests it. | |
| """ | |
| from copy import deepcopy | |
| _COMMON = { | |
| "source": {"observation": "tenant_mirror", "proof": "odoo_read_only"}, | |
| "drillThrough": {"kind": "source_records"}, | |
| } | |
| FINANCE_FACTS = { | |
| "ar_outstanding": { | |
| "label": "AR outstanding", "topic": "receivables", "metric": "ar_outstanding", | |
| "format": "usd", "scope": "hq_consolidated", "sourceEntities": ["account_move"], | |
| "reconciliationMethod": "ar_outstanding", | |
| }, | |
| "ap_outstanding": { | |
| "label": "AP outstanding", "topic": "odoo_bills", "metric": "ap_outstanding", | |
| "format": "usd", "scope": "hq_consolidated", "sourceEntities": ["account_move"], | |
| "reconciliationMethod": "ap_outstanding", | |
| }, | |
| "invoiced_sales": { | |
| "label": "Invoiced sales", "topic": "customer_invoices", "metric": "invoiced_sales", | |
| "format": "usd", "scope": "hq_consolidated", "sourceEntities": ["account_move"], | |
| "reconciliationMethod": "invoiced_sales", | |
| }, | |
| "revenue": { | |
| "label": "Wholesale revenue", "topic": "sales_lines", "metric": "revenue", | |
| "format": "usd", "scope": "business_unit", "sourceEntities": ["sale_order_line", "sale_order"], | |
| "reconciliationMethod": "order_level_revenue", | |
| }, | |
| "opex": { | |
| "label": "Operating expense", "topic": "gl_lines", "metric": "opex", | |
| "format": "usd", "scope": "hq_consolidated", "sourceEntities": ["account_move_line"], | |
| "reconciliationMethod": "gl_opex", | |
| }, | |
| "commission_accrued": { | |
| "label": "Commission accrued", "topic": "commission_lines", "metric": "commission_accrued", | |
| "format": "usd", "scope": "business_unit", "sourceEntities": ["account_invoice_line_agent", "account_move_line", "sale_order"], | |
| "reconciliationMethod": "commission_accrued", | |
| }, | |
| "stock_in": { | |
| "label": "Stock moved in", "topic": "stock_moves", "metric": "stock_in", | |
| "format": "int", "scope": "all_channel_inventory", "sourceEntities": ["stock_move", "stock_location"], | |
| "reconciliationMethod": "stock_movement_in", "scalarAvailable": False, "drillMeasures": [], | |
| "requiredGrain": "product_code", | |
| }, | |
| "stock_out": { | |
| "label": "Stock moved out", "topic": "stock_moves", "metric": "stock_out", | |
| "format": "int", "scope": "all_channel_inventory", "sourceEntities": ["stock_move", "stock_location"], | |
| "reconciliationMethod": "stock_movement_out", "scalarAvailable": False, "drillMeasures": [], | |
| "requiredGrain": "product_code", | |
| }, | |
| "stock_net": { | |
| "label": "Stock moved net", "topic": "stock_moves", "metric": "stock_net", | |
| "format": "int", "scope": "all_channel_inventory", "sourceEntities": ["stock_move", "stock_location"], | |
| "reconciliationMethod": "stock_movement_net", "drillMeasures": [], | |
| "scalarAvailable": False, "requiredGrain": "product_code", | |
| }, | |
| } | |
| def fact_spec(key): | |
| """Return the governed descriptor for a Finance fact.""" | |
| if key not in FINANCE_FACTS: | |
| raise KeyError(key) | |
| item = {"key": key, **_COMMON, **FINANCE_FACTS[key]} | |
| item["lineage"] = { | |
| "topic": item["topic"], "metric": item["metric"], | |
| "sourceEntities": list(item["sourceEntities"]), | |
| } | |
| item["drillThrough"] = { | |
| **item["drillThrough"], | |
| "href": f"/api/v1/finance/facts/{key}/records", | |
| } | |
| item["freshness"] = {"state": "not_observed", "sources": list(item["sourceEntities"])} | |
| item["reconciliation"] = { | |
| "state": "not_checked", "method": item["reconciliationMethod"], | |
| "href": f"/api/v1/finance/facts/{key}/reconciliation", | |
| } | |
| return deepcopy(item) | |
| def fact_specs(keys=None): | |
| return [fact_spec(key) for key in (FINANCE_FACTS if keys is None else keys)] | |
| def effective_team_id(spec, requested_team_id): | |
| """Apply the declared scope. Company and stock facts cannot wear a BU label.""" | |
| if requested_team_id is not None: | |
| import core.odoo as O | |
| if requested_team_id not in O.active_team_ids(): | |
| raise ValueError("Finance business-unit scope must be one of the tenant's sales teams") | |
| if spec["scope"] == "business_unit": | |
| return requested_team_id | |
| if spec["scope"] == "hq_consolidated" and requested_team_id is not None: | |
| raise PermissionError("A business-unit-scoped account cannot read consolidated Finance facts") | |
| # Inventory is one physical, all-channel warehouse basis. It is intentionally not allocated | |
| # to Fisch or Royal; a pinned user receives the same company stock rows with no BU label. | |
| return None | |
| def freshness(cursor, entities): | |
| """Describe mirror readiness from its own sync ledger; never synthesize an as-of time.""" | |
| try: | |
| rows = cursor.execute( | |
| "SELECT entity, phase, cursor_wd, updated_at FROM _sync_state WHERE entity IN (" | |
| + ",".join("?" for _ in entities) + ")", list(entities)).fetchall() | |
| except Exception: | |
| return {"state": "missing", "asOf": None, "sources": []} | |
| found = {str(row[0]): row for row in rows} | |
| sources = [] | |
| for entity in entities: | |
| row = found.get(entity) | |
| sources.append({"entity": entity, "state": str(row[1]) if row else "missing", | |
| "asOf": (row[2] or row[3]) if row else None}) | |
| phases = {src["state"] for src in sources} | |
| if sources and phases == {"live"}: | |
| state = "ready" | |
| elif "running" in phases or "pending" in phases: | |
| state = "warming" | |
| else: | |
| state = "missing" | |
| stamps = [src["asOf"] for src in sources if src["asOf"]] | |
| return {"state": state, "asOf": min(stamps) if stamps else None, "sources": sources} | |
| def observe(key, cursor, *, date_from=None, date_to=None, team_id=None): | |
| """Read one governed fact from the canonical mirror and attach its proof metadata.""" | |
| from harness import semantic | |
| spec = fact_spec(key) | |
| sync = freshness(cursor, spec["sourceEntities"]) | |
| spec["freshness"] = sync | |
| if sync["state"] != "ready": | |
| return {**spec, "state": sync["state"], "value": None} | |
| if spec.get("scalarAvailable") is False: | |
| return {**spec, "state": "requires_sku", "value": None, | |
| "message": "Movement quantities use mixed units and are available at SKU grain."} | |
| try: | |
| scoped_team_id = effective_team_id(spec, team_id) | |
| except PermissionError: | |
| return {**spec, "state": "restricted", "value": None, | |
| "message": "This fact is available only to consolidated Finance viewers."} | |
| except ValueError as exc: | |
| return {**spec, "state": "unavailable", "value": None, "message": str(exc)} | |
| try: | |
| result = semantic.store_query( | |
| spec["topic"], [spec["metric"]], date_from=date_from, date_to=date_to, | |
| team_id=scoped_team_id, limit=1) | |
| rows = result.get("rows") or [] | |
| if not rows or rows[0].get(spec["metric"]) is None: | |
| return {**spec, "state": "missing", "value": None} | |
| return {**spec, "state": "ready", "value": rows[0][spec["metric"]]} | |
| except Exception as exc: | |
| return {**spec, "state": "unavailable", "value": None, | |
| "message": _safe_message(exc)} | |
| def source_records(key, *, date_from=None, date_to=None, team_id=None, limit=100, offset=0): | |
| """Return source-grain records plus whole-scope counts/totals from the same governed topic.""" | |
| from harness import semantic | |
| spec = fact_spec(key) | |
| measures = (spec.get("drillMeasures") if "drillMeasures" in spec | |
| else [spec["metric"]]) | |
| payload = semantic.store_rows( | |
| spec["topic"], date_from=date_from, date_to=date_to, | |
| team_id=effective_team_id(spec, team_id), limit=limit, offset=offset, | |
| aggregates=measures) | |
| return {"fact": spec, **payload} | |
| def reconcile(key, *, date_from=None, date_to=None, team_id=None): | |
| """Run the declared independent, read-only Odoo proof on explicit request.""" | |
| from harness import semantic | |
| spec = fact_spec(key) | |
| try: | |
| result = semantic.validate_metric( | |
| spec["metric"], date_from=date_from, date_to=date_to, | |
| team_id=effective_team_id(spec, team_id)) | |
| return {"state": "passed" if result.get("ok") else "failed", **result} | |
| except Exception as exc: | |
| return {"state": "unavailable", "message": _safe_message(exc)} | |
| def _safe_message(exc): | |
| text = str(exc).lower() | |
| if "sync" in text or "store" in text or "table" in text: | |
| return "The tenant mirror is still warming." | |
| return "The fact is temporarily unavailable." | |
| def _store_value(topic, metric, date_from, date_to, team_id=None): | |
| from harness import semantic | |
| rows = semantic.store_query(topic, [metric], date_from=date_from, date_to=date_to, | |
| team_id=team_id, limit=1).get("rows") or [] | |
| return (rows[0].get(metric) if rows else None) or 0 | |
| def _date_domain(field, date_from, date_to): | |
| dom = [] | |
| if date_from: | |
| dom.append((field, ">=", date_from)) | |
| if date_to: | |
| dom.append((field, "<=", date_to)) | |
| return dom | |
| def _v_commission_accrued(date_from, date_to, team_id): | |
| import core.odoo as O | |
| ours = _store_value("commission_lines", "commission_accrued", date_from, date_to, team_id) | |
| dom = _date_domain("invoice_date", date_from, date_to) | |
| if team_id: | |
| dom.append(("object_id.sale_line_ids.order_id.team_id", "=", team_id)) | |
| return ours, O.sum_field("account.invoice.line.agent", dom, "amount") | |
| def _v_invoiced_sales(date_from, date_to, team_id): | |
| import core.odoo as O | |
| ours = _store_value("customer_invoices", "invoiced_sales", date_from, date_to) | |
| dom = [("state", "=", "posted"), ("move_type", "=", "out_invoice")] | |
| dom += _date_domain("invoice_date", date_from, date_to) | |
| return ours, O.sum_field("account.move", dom, "amount_untaxed_signed") | |
| def _stock_live(date_from, date_to, inbound): | |
| import core.odoo as O | |
| dom = [("state", "=", "done")] | |
| dom += _date_domain("date", date_from, date_to) | |
| if inbound: | |
| dom += [("location_dest_id.usage", "=", "internal"), | |
| ("location_id.usage", "!=", "internal")] | |
| else: | |
| dom += [("location_id.usage", "=", "internal"), | |
| ("location_dest_id.usage", "!=", "internal")] | |
| return O.sum_field("stock.move", dom, "quantity_done") | |
| def _v_stock_in(date_from, date_to, team_id): | |
| return _store_value("stock_moves", "stock_in", date_from, date_to), _stock_live(date_from, date_to, True) | |
| def _v_stock_out(date_from, date_to, team_id): | |
| return _store_value("stock_moves", "stock_out", date_from, date_to), _stock_live(date_from, date_to, False) | |
| def _v_stock_net(date_from, date_to, team_id): | |
| return (_store_value("stock_moves", "stock_net", date_from, date_to), | |
| _stock_live(date_from, date_to, True) - _stock_live(date_from, date_to, False)) | |
| def _v_ap_outstanding(date_from, date_to, team_id): | |
| import core.odoo as O | |
| ours = _store_value("odoo_bills", "ap_outstanding", date_from, date_to) | |
| dom = [("state", "=", "posted"), ("move_type", "in", ["in_invoice", "in_refund"])] | |
| dom += _date_domain("invoice_date", date_from, date_to) | |
| return ours, -O.sum_field("account.move", dom, "amount_residual_signed") | |
| FINANCE_VALIDATORS = { | |
| "commission_accrued": _v_commission_accrued, | |
| "invoiced_sales": _v_invoiced_sales, | |
| "stock_movement_in": _v_stock_in, | |
| "stock_movement_out": _v_stock_out, | |
| "stock_movement_net": _v_stock_net, | |
| "ap_outstanding": _v_ap_outstanding, | |
| } | |
| def register_semantic_validators(): | |
| """Compatibility adapter until the out-of-fence semantic registry imports this module.""" | |
| from harness import semantic | |
| semantic._VALIDATORS.update(FINANCE_VALIDATORS) | |
| return tuple(FINANCE_VALIDATORS) | |