Spaces:
Paused
Paused
Download platform/modules/agent.py from aios-loopable/cfo-os: direct link, hf CLI and curl.
- Browser
- Download file 14.4 kB
-
https://huggingface.co/spaces/aios-loopable/cfo-os/resolve/main/platform/modules/agent.py
- Command line
-
hf download hf://spaces/aios-loopable/cfo-os/platform/modules/agent.py
-
curl -L -o agent.py https://huggingface.co/spaces/aios-loopable/cfo-os/resolve/main/platform/modules/agent.py
14.4 kB
| """Agent module — per-agent (res.partner.agent_ids) analytics. | |
| An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This | |
| module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard | |
| with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales | |
| trend, returns, top SKUs (with profit/order) and the FULL customer list — INCLUDING inactive | |
| accounts (no recent orders) so a rep sees who they've stopped selling to. | |
| Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done) | |
| so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged); | |
| everything else is BU-filterable via team_id. | |
| """ | |
| import sys | |
| import datetime as dt | |
| from pathlib import Path | |
| sys.path.insert(0, str(Path(__file__).resolve().parents[1])) | |
| import core.odoo as O | |
| import core.periods as P | |
| import modules.sales as sales_mod | |
| import modules.customers as cust_mod | |
| def options(t=None, team_id=None): | |
| """Agent names with book activity — for the page/drawer picker.""" | |
| return cust_mod.agent_options(t, team_id) | |
| def _book(name): | |
| """frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'.""" | |
| return cust_mod.agent_partner_ids(name) | |
| def _rev(date_from, date_to, team_id, book): | |
| return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book), | |
| 'amount_untaxed') | |
| def _orders(date_from, date_to, team_id, book): | |
| return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book)) | |
| def _custs(date_from, date_to, team_id, book): | |
| return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book), | |
| 'partner_id') | |
| # ------------------------------------------------------------ period scorecard (custom dating) | |
| # Today / WTD / Last week / MTD / QTD / YTD — each carries its window so the UI can decompose it | |
| # and so "what did this agent sell this/last week" is a click, not a date-math exercise. | |
| _PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'), | |
| ('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')] | |
| def _window(key, t): | |
| if key == 'today': | |
| return P._d(t), P._d(t) | |
| if key == 'lwk': # the full prior Mon–Sun week | |
| f, _tt = P.wtd(t) | |
| start = dt.date.fromisoformat(f) - dt.timedelta(days=7) | |
| return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat() | |
| return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t) | |
| def scorecard(name, t=None, team_id=None): | |
| """Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD.""" | |
| t = t or P.today() | |
| book = _book(name) | |
| out = [] | |
| for label, key in _PERIODS: | |
| f, tt = _window(key, t) | |
| wk = key in ('today', 'wtd', 'lwk') # weekday-align the short windows' LY compare | |
| cf, ct = P.shift_year(f, tt, weeks=wk) | |
| rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book) | |
| out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct, | |
| 'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly), | |
| 'orders': _orders(f, tt, team_id, book)}) | |
| return out | |
| def headline(name, date_from, date_to, team_id=None): | |
| """Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders, | |
| active customers, AOV and returns $ / return rate.""" | |
| book = _book(name) | |
| cf, ct = P.shift_year(date_from, date_to, weeks=False) | |
| rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book) | |
| orders = _orders(date_from, date_to, team_id, book) | |
| ret = sales_mod._returns_amt(date_from, date_to, book) | |
| return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct, | |
| 'revenue': rev, 'revenue_ly': rev_ly, | |
| 'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders, | |
| 'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0, | |
| 'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0} | |
| # ------------------------------------------------------------ sales trend | |
| def _book_monthly_rev(book, date_from, date_to, team_id=None): | |
| g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book), | |
| ['amount_untaxed:sum'], ['date_order:month'], lazy=False) | |
| out = {} | |
| for r in g: | |
| ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7] | |
| if ym: | |
| out[ym] = r.get('amount_untaxed') or 0.0 | |
| return out | |
| def monthly(name, n=13, t=None, team_id=None): | |
| """Book sales per month vs the same month last year (one month-grouped query over 2 years).""" | |
| t = t or P.today() | |
| book = _book(name) | |
| mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id) | |
| rows = [] | |
| for ym, _s, _e in P.month_starts(n, t): | |
| y, m = int(ym[:4]) - 1, int(ym[5:7]) | |
| this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0) | |
| rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)}) | |
| return rows | |
| # ------------------------------------------------------------ full customer book (incl. inactive) | |
| def customers(name, t=None, team_id=None): | |
| """EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) — those | |
| show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and | |
| carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last).""" | |
| t = t or P.today() | |
| book = _book(name) | |
| yf, yt = P.ytd(t) | |
| lf, lt = P.ytd_last_year(t) | |
| this = cust_mod._cust_rev(yf, yt, team_id, book) | |
| last = cust_mod._cust_rev(lf, lt, team_id, book) | |
| lastord = cust_mod._last_order_dates(None, None, team_id, book) # all-time last order = recency | |
| ids = list(book) if book is not None else list(set(this) | set(last)) | |
| attrs = cust_mod._partner_attrs(set(ids)) | |
| namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])} | |
| rows = [] | |
| for p in ids: | |
| tr = this.get(p, {}).get('rev', 0.0) | |
| lr = last.get(p, {}).get('rev', 0.0) | |
| a = attrs.get(p, {}) | |
| lo = lastord.get(p, '') | |
| recency = (t - dt.date.fromisoformat(lo)).days if lo else None | |
| status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive') | |
| rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'), | |
| 'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr), | |
| 'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency, | |
| 'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'), | |
| 'agent': a.get('agent', name)}) | |
| rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly']))) | |
| return rows | |
| # ------------------------------------------------------------ top SKUs (with profit/order) | |
| def top_skus(name, t=None, team_id=None, top=30): | |
| """The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order.""" | |
| t = t or P.today() | |
| book = _book(name) | |
| if book is not None and not book: | |
| return [] | |
| yf, yt = P.ytd(t) | |
| lex = [('order_partner_id', 'in', list(book))] if book is not None else None | |
| return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus'] | |
| # ------------------------------------------------------------ returns (book-scoped, consolidated) | |
| def returns_trend(name, n=13, t=None): | |
| return sales_mod.returns_monthly(n, t, partner_ids=_book(name)) | |
| def returns_headline(name, t=None): | |
| return sales_mod.returns_headline(t, partner_ids=_book(name)) | |
| # ------------------------------------------------------------ all-agents rollup (the page table) | |
| def _returns_by_agent(t=None): | |
| """{agent_name: returns$ YTD} — credit notes mapped to each customer's agent.""" | |
| by_p = sales_mod.returns_by_partner(t) | |
| attrs = cust_mod._partner_attrs(list(by_p)) | |
| agg = {} | |
| for pid, amt in by_p.items(): | |
| a = (attrs.get(pid) or {}).get('agent') or '(none)' | |
| agg[a] = agg.get(a, 0.0) + amt | |
| return agg | |
| def rollup(t=None, team_id=None): | |
| """Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return | |
| rate. Reuses the Customers MECE agent rollup, so Σ(agents) == total YTD revenue.""" | |
| rows = cust_mod.by_dimension('agent', t, team_id=team_id) | |
| ret = _returns_by_agent(t) | |
| for r in rows: | |
| r['agent'] = r['group'] | |
| r['returns'] = ret.get(r['group'], 0.0) | |
| r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0 | |
| return rows | |
| # ------------------------------------------------------------ VALIDATION | |
| def validate(t=None, team_id=None): | |
| """Reconcile the agent rollup to Odoo. (1) Σ(agent book revenue) == total YTD revenue — the | |
| rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD.""" | |
| t = t or P.today() | |
| yf, yt = P.ytd(t) | |
| checks = [] | |
| rows = rollup(t, team_id=team_id) | |
| agent_sum = sum(r['revenue'] for r in rows) | |
| total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed') | |
| checks.append({'check': 'YTD revenue: Σ(agent book) == total', 'a': round(agent_sum, 2), | |
| 'b': round(total, 2), 'gap': round(agent_sum - total, 2), | |
| 'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))}) | |
| # sampled agent: scorecard YTD == headline YTD for the same window | |
| sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None) | |
| if sample: | |
| sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0) | |
| hl = headline(sample, yf, yt, team_id)['revenue'] | |
| checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2), | |
| 'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0}) | |
| return checks | |
| # ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28) | |
| # A SECOND agent source. Everything above this line attributes by BOOK — the customer's assigned | |
| # agent (res.partner.agent_ids) — over confirmed SALES ORDERS. This section attributes per INVOICE | |
| # LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines / | |
| # commission_lines). The two disagree on purpose and answer different questions: | |
| # | |
| # book -> "whose customer is this / who owns the relationship" (order basis) | |
| # invoice -> "what was actually credited to an agent on the billing" + the ONLY source that can | |
| # say what is NOT allocated to an agent (invoice basis) | |
| # | |
| # ⚠ A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT — `res.partner.agent` is the flag. | |
| # "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent` | |
| # dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant. | |
| # See [[invoice-line-agent-commission]]. | |
| _ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only', | |
| 'none': 'Not allocated'} | |
| def invoice_line_rollup(t=None, team_id=None, include_salespeople=False): | |
| """Per-name invoice-line revenue + the MECE allocation split, for a YTD window. | |
| Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float, | |
| 'unallocated': float, 'basis': str} — or {'error': msg} when the tenant store is not | |
| ready (this path is store-only; there is no live fallback that stays honest about the | |
| unallocated bucket). | |
| """ | |
| import harness.semantic as S | |
| t = t or P.today() | |
| yf, yt = P.ytd(t) | |
| dim = 'commission_name' if include_salespeople else 'agent' | |
| try: | |
| by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim], | |
| date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or [] | |
| alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'], | |
| date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or [] | |
| tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt, | |
| team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0 | |
| except Exception as e: # store not ready / model error — say so, don't fake | |
| return {'error': str(e)} | |
| # store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value | |
| # (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name` | |
| # returns None for every row and silently renders the whole table as "no agent". | |
| rows = [{'agent': (r.get(dim) or '(no agent on the line)'), | |
| 'revenue': r.get('invoiced_line_sales') or 0.0} for r in by] | |
| rows.sort(key=lambda r: -r['revenue']) | |
| amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc} | |
| allocated = amap.get('agent', 0.0) | |
| return { | |
| 'by_agent': rows, | |
| 'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)} | |
| for k in ('agent', 'salesperson', 'none') if k in amap or True], | |
| 'total': tot, 'allocated': allocated, 'unallocated': tot - allocated, | |
| 'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0), | |
| 'window': (yf, yt), | |
| 'basis': ('invoice line · commission names incl. salespeople' if include_salespeople | |
| else 'invoice line · real agents only'), | |
| } | |