com.aurgus/aurgus

Build a GOVERNED analytics report over the rebate data. Pick a MEASURE and GROUP it BY a dimension — the report is composed from a fixed semantic layer (no raw SQL), so it's deterministic, read-only, and ties to the ledger (accrued uses the SAME earned formula as the money path). measure: 'accrued' (earned rebate), 'settled' (paid), 'basis' (transaction amount), or 'count' (events). group_by: 'agreement', 'class' (a declared dimension — pass dimension_key, e.g. interchange_class), 'month', or 'quarter'. Optionally restrict to one agreement_id. Returns the grouped rows + total. Use this when the user asks to see/analyze/break down their rebates (e.g. 'rebate accrued by interchange class', 'settled by month'). Requires a connected Aurgus account.

THE one way to talk to Aurgus — the client's revenue-management controller. For ANYTHING the user says to Aurgus (a greeting, 'close Q3', 'where are we', 'what do you need from me'), call THIS with their message rather than picking a specific tool; Aurgus reads the engagement's real state, leads like a firm, and tells you the single next step. Pass entity/period/program when the user has named them (so Aurgus can open the engagement), and engagement_id once one is open. The specialized tools (ingest, compute_close, sign_close, …) are the controller's hands — reach for one only when Aurgus's reply tells you to (e.g. to ingest a CSV, compute with numbers, or sign). Free to greet; a real run on the user's data needs a connected account.

Call this the moment the user greets Aurgus or wants to start — 'Aurgus, hi', 'hello', 'hey Aurgus', 'let's start', 'I want to run a close', 'where do I begin'. Aurgus introduces itself as the client's independent revenue-management controller and LEADS into the engagement, asking who the client is, the period, and what's being closed. Free, no account needed, computes nothing — the next step is open_engagement.

Close an agreement for good — the terminal true-up at the END of its life (its term ended, or it's being wound down). Closing posts a final true-up Adjustment that matches the accrual to the settled amount (open → $0), THEN FREEZES the agreement: it moves to 'closed' and NO new transactions ever calculate against it again. This is NOT the periodic run (compute_close) or the periodic payout (settlement) — it ends the agreement. Because it MOVES MONEY (the true-up Adjustment), call WITHOUT confirm first to DRY-RUN — it reports the adjustment that would post and that the agreement will be frozen. Call again with confirm:true to post it and close. Terminal. Needs the agreement_id. Requires a connected Aurgus account.

Build a rebate/incentive agreement by talking it through — no document needed. Describe the program in plain words and Aurgus DRAFTS the terms (who qualifies, how volume is measured and over what period, the threshold, the rate or per-unit reward, any cap, and approval routing) and asks the consultant-style questions a controller would ask before assuming. IMPORTANT: these terms are DRAFTED by the model from your words — they are PROPOSED, NOT PARSED, and nothing is created. When the terms are right, call again with finalize=true and the reviewed proposal, and Aurgus stages it for a person with approval authority to approve in the browser (you can NOT approve your own). This is how you establish an agreement (ASC 606 step 1) when you have no document — before any transaction data is asked for. When a document exists, prefer ingest_agreement (its deterministic parser touches the numbers with zero LLM).

The RUN step (step 6) of an open engagement — work the governed, deterministic earned → settled → open accrual across the engagement's active agreements and certified data. Do NOT call this as the first thing when a user says 'compute the close': a firm opens the engagement first (open_engagement), establishes the agreement, requests + certifies the data, and only then runs. If no engagement is open, this refuses and leads back to open_engagement. You get back the number, how earned / claimed / credited line up, and any flag worth raising. Nothing posts to the GL; the number is prepared for approval. Requires a connected Aurgus account.

Compute a sales-commission engagement under ASC 340-40 (incremental cost to obtain a contract). Give the commission amount, the benefit period it amortizes over, and how many months have elapsed; it classifies the cost, then capitalizes a recoverable commission and amortizes it straight-line — returning the capitalized asset, amortization to date, the period expense, and the net carrying amount. This is a capitalized asset and an amortization schedule, NOT revenue. It refuses (asks) if recoverability or the amount is unclear. The result is recorded on the engagement file; a principal signs before the workpapers are delivered.

Measure a lease under ASC 842 (v1: the lessee side — real estate and equipment). Give the term, the CERTIFIED discount rate (the rate implicit in the lease, or the incremental borrowing rate — it will NOT assume one), and the payment schedule; it measures the lease liability (present value of the payments), the right-of-use asset (liability + initial direct costs − incentives), and the amortization schedule — a single straight-line lease cost for an operating lease (842-20-25-6) or amortization + interest for a finance lease (842-20-25-5). Usage-based variable payments are excluded from the liability (842-10-30-6). Whatever it can't ground — a missing rate, an undetermined classification — it logs as an OPEN ITEM rather than guessing; lessor accounting is deferred. The result is recorded on the engagement file; a principal signs before the workpapers are delivered.

Run the full ASC 606 five-step recognition for a general revenue contract: identify the performance obligations (Step 2), allocate the transaction price by standalone selling price (Step 4), and recognize over time or at a point in time (Step 5). Give the transaction price and the promised items (each with its standalone selling price). Whatever the engine can't determine from what you provide — distinctness, timing — it logs as an OPEN ITEM rather than guessing. The result is recorded on the engagement file; a principal signs before the workpapers are delivered.

Split a trade-spend payment to a customer (co-op advertising, MDF, slotting, listing allowance) under ASC 606-10-32-26 / 705-20-25-2. If the payment buys a DISTINCT good or service the customer actually provides (e.g. advertising with proof-of-performance), it's a purchase/expense UP TO that good's fair value; any EXCESS over fair value reduces revenue. Give the payment amount, whether it buys a distinct good/service, and that good's fair value — it returns the expense leg and the revenue-reduction leg. It refuses (asks) for the fair value rather than guess; if it buys nothing distinct, the whole payment reduces revenue (no split). Nothing posts; a principal signs the close.

Record the human's answer to a customer-grouping question Aurgus asked — a grouping compute_close PROPOSED ('GPG LLC resembles Global Procurement Group LLC', or 'these are the GPO's members'), OR a change to a roster Aurgus already knows ('did anything change?' → a new member joined, or one left). Aurgus never changes a group on its own — this tool is the person's approval, and what makes Aurgus remember. Added names become DATE-CONTROLLED members of the agreement's customer scope so the NEXT close matches them automatically; removing a member ENDS its membership as-of a date (never deletes — its past purchases stay attributed, only later ones stop rolling up). Use ONLY after Aurgus surfaced the question and the user answered; pass the agreement_id and the name(s) exactly as they appear in the data. Set valid_from/valid_to for a real join/leave date (a GPO join, an acquisition, a rename, a member leaving); omit valid_from for open-ended. After confirming, run compute_close again to fold the change in.

Retire a WRONG agreement that has already accrued — reverse its postings, then archive it. Voiding alone only stops FUTURE accruals; this UNWINDS what already accrued by appending a Reversal for every earning event (earned → $0, strictly append-only — the originals AND the reversals both stay on the ledger for audit), then voids the agreement. Call WITHOUT confirm first to DRY-RUN — it reports how many postings and how much $ will be reversed and warns if any was already settled (a clawback). Call again with confirm:true to apply. Refuses if the agreement is posted to the ERP (supersede it instead). Needs the agreement_id. Requires a connected Aurgus account.

Change an agreement's TERMS — its name, the counterparty (customer_name), the direction (payable_sell_side = you pay a rebate / receivable_buy_side = you earn one), the validity window (valid_from / valid_to, YYYY-MM-DD; pass valid_to:null for open-ended), or the accrual / settlement cadence. Send only the fields to change. This runs the SAME governed core as the workspace edit form (one implementation): activating is blocked if the config isn't ASC-606-conformant; a cadence/validity value must satisfy the agreement type's contract; direction and type are posting-locked once a document hits the ERP; and because a validity change re-evaluates already-accrued periods, it does NOT post money through you — it raises a gated Recalculate card the operator approves in the workspace (nothing is backdated without approval). To CHANGE RATES use edit_agreement_rates; to change STATUS use the audited status flow. Needs the agreement_id. Requires a connected Aurgus account.

Change the RATES on a rate-routed (dimension-routed) agreement — a regime's flat rate, a tiered regime's own ladder, or the shared tier ladder. Rates are given in PERCENT (1.5 = 1.5%); thresholds in dollars. Call WITHOUT confirm first to DRY-RUN: with no edits it LISTS the current regimes (their keys + rates) so you know what to change; with edits it echoes the intended change. Call again with confirm:true to apply. On apply the new rate goes live for future transactions immediately, and — because it moves money on already-accrued periods — a gated Recalculate card is raised that the operator approves in the workspace (the past-period adjustment posts only on approval; nothing is backdated through you). Structure (routing dimension, regime keys, member values) is NOT editable here — only rates. Refuses if posted to the ERP (supersede instead). Needs the agreement_id. Requires a connected Aurgus account.

Report where an engagement stands — derived from the engagement file's real events, not a stored status. With an engagement id, it shows which steps are on the chain, what's next, and any open items (the close can't be signed while any remain). With no id, it lists the client's engagements and the firm's own status. If the file's hash chain fails re-verification it refuses to report rather than vouch for a tampered record.

State the governed US-GAAP treatment FOR A PAYMENT TYPE — a rebate, incentive, chargeback, or trade-spend payment — under ASC 606 (customer rebate / consideration payable to a customer / variable consideration), ASC 705-20 (vendor rebate), or ASC 340-40 (sales commission). It CLASSIFIES the payment and returns the governed treatment, the exact ASC citation, and the rule applied — deterministic and grounded, it will not guess and asks which payment type applies when unclear. It is NOT a free-form accounting Q&A or advisory debate: it does not argue a position, weigh a contrary opinion, or answer open questions beyond the payment-type classification (the `scenario` text is context only). For anything past the treatment of a payment type, run the engagement (compose/ingest the agreement, then compute).

Put together the auditor-ready package for your tenant: the open accrual you can stand behind (earned → settled → open), where margin is leaking versus what's sitting outside any program, and sample lineage tracing back to source — all computed off the canonical ledger. Requires a connected Aurgus account.

Deliver the engagement workpapers — the certified figures and the open-items register on one page, from the hash-chained engagement file. Refuses until a principal has signed the close. This is the auditor-ready deliverable: what was concluded, and what could not be proven, together.

Call this when the user asks for help or how to use Aurgus — 'Aurgus help', 'help', 'what can you do', 'how do I use this', 'show me the manual', 'what are the commands / trigger words'. Returns the Aurgus manual: what it is, how an engagement runs step by step, the trigger phrases that fire each tool, and how to start. Free, no account needed.

Hand Aurgus one of your three rebate files (CSV) to read into your tenant: 'pos' (your POS / sell-through extract — what was earned), 'claims' (the claims you submitted), or 'credits' (credit memos / vendor invoices you received). Give it the raw CSV, which kind of file it is, and a note of which of your columns maps to which Aurgus field. Rows with blank or bad amounts are held and reported back to you — never quietly booked as $0 — and nothing touches your numbers until a person certifies the mapping. Requires a connected Aurgus account.

Hand Aurgus your rebate agreement — PASTE its text, or DROP a PDF/scanned document (pass it as file_base64). Aurgus reads the terms with its deterministic parser (and CV/OCR for a PDF/scan — a Python CPU service, ZERO LLM): customer, basis (whole-volume / incremental / cliff), rate or tier ladder, and the rebate period. A CPU parser proposes spans, deterministic rules produce every value, and anything it can't read cleanly is flagged for your eye rather than guessed. Nothing is created until a person reviews and certifies the terms in the browser — this is how the agreement (and the ASC 606 treatment it implies) gets set up, before any transaction data is asked for.

List the saved analytics reports on this tenant (name + what each measures). Use `run_report` with a name to re-run one. Requires a connected Aurgus account.

Open a revenue-management engagement for a client. Capture the intake — the client entity, the period, the program(s), the sources of truth, and who will certify — and start the engagement file (a hash-chained, append-only record of everything that follows). This is how a firm begins: a named client and a scope, before any numbers. The agreement comes next; nothing is computed here.

The engagement's open-items register — the things the close can't yet account for (a document not received, a term not found in the agreement, an unmatched figure). List them, open a new one, or resolve one by id. The register ships alongside the certified figures; no gap is ever filled on the client's behalf, and the close cannot be signed while any item remains open.

Recalculate — re-run the deterministic engine over the POS data, dispatching every row against the agreement(s) so rows that just became eligible (e.g. after a data fix or a rule change) accrue. Posts provisional accruals (the same engine compute_close uses); rows that already have a positive accrual are skipped (idempotent). Pass agreement_id to recompute ONE agreement, or omit it to recompute ALL active agreements. Returns the events created and the accrual total. Requires a connected Aurgus account.

Receive a client document into an engagement BY REFERENCE — a client-granted signed https link (or an upload handle), never the file's contents. The engine fetches it server-side, stages it inside the client's tenant for certification, and tells you only the column names and where to certify the mapping — no row of the client's data ever passes through the model. Resolves the matching PBC open item. This is how the data gets in without it ever touching the model: 'no LLM on the money path' stays literally true.

What's new in Aurgus and how to stress-test it — call this for 'what changed', 'release notes', 'what's new', 'changelog', or if you're reviewing/pressure-testing the product. Returns the current release summary (reuse-first institutional knowledge, document/PDF intake, the anti-hallucination guards, ASC coverage) plus a concrete test checklist. Free, no account needed, reads nothing from any tenant.

The portfolio report — every active agreement on the tenant (or one, by id), with its earned / settled / open accrual, basis, status, and when it last calculated. This is the book-at-a-glance a controller watches: which agreements are live, what each has earned vs paid out, and what is open. Pass agreement_id for a single agreement, or status to filter the list (active / draft / closed / superseded). Read-only — it computes nothing new, it reports the canonical ledger. Requires a connected Aurgus account.

Draft the PBC (prepared-by-client) document list for an engagement, FROM its agreement — the program decides which files the close needs (a sell-side rebate → the POS / sell-through extract; a buy-side billback → the claims file), never a generic ask. Each requested document is logged as an open item; the close can't be signed until every one is received, mapped and certified. Needs an active agreement first (the agreement is the rulebook).

Get the link to run a real close on your OWN numbers — bring a rebate / SPA / deduction extract and get back audit-defensible accruals, full lineage, and an auditor-ready export, with nothing posted to your GL. Use this when the user is ready to move from a sample to their own data. Optionally takes a work email to set up access — only what the user volunteers, and never ask for financial data inside the chat.

Re-run a SAVED analytics report by name on current data — returns the grouped rows + total, governed and read-only exactly like `analyze`. Requires a connected Aurgus account.

Save an analytics report for reuse. Give it a NAME plus the same measure / group_by (/ dimension_key / agreement_id) you'd pass to `analyze` — the governed spec is stored under that name (re-saving the same name updates it). Later, `run_report` re-runs it on current data. Requires a connected Aurgus account.

Set how often an agreement ACCRUES and SETTLES. Ask the user these when setting an agreement up (or to change them later): (1) how often to accrue — 'realtime' as sales land, or batched 'daily' / 'weekly' / 'monthly' / 'per_event'; (2) how often it settles — when the money actually hits their account — 'weekly', 'semi_monthly', 'monthly', 'quarterly', 'semi_annual', 'annual', 'threshold' (when a dollar threshold is hit), or 'ad_hoc'. Pass the agreement_id and whichever cadence(s) the user chose; you can set one or both. Requires a connected Aurgus account.

Settle an agreement — post the PAYOUT. Creates per-bucket Settlement event(s) totalling the open accrual (earned − already settled), moving the open balance to $0. This is the money-OUT step (distinct from compute_close, which accrues, and true_up, which reconciles the accrual to a prior settlement). Call WITHOUT confirm to DRY-RUN — it reports the open accrual that would be paid and any gate that blocks it (a named settlement approver, an incomplete agreement, or an anomaly hold). Call again with confirm:true to post it. Governed by the SAME gates as the workspace Settle button (one core). Needs the agreement_id. Requires a connected Aurgus account.

A principal signs the governed close for an engagement, by name, on the engagement file. It refuses while any open item remains — the open-items register gates the signature — and a close must have been computed. You cannot sign on the client's behalf; the person signs. Signing is what releases the workpapers.

Walk any accrued figure all the way back to where it came from — source row → eligibility → bucket → rate → rule → event chain — for a given transaction. This is how you show an auditor exactly why a number is what it is. Requires a connected Aurgus account.

True-up an agreement — AFTER a settlement, match the accrual account to what was ACTUALLY settled. Posts ONE Adjustment (signed = settled − earned) in the CURRENT period so earned equals settled and the open balance nets to $0. Over-accrued → a negative Adjustment; under-accrued → a positive one. Always current-period, never backdated. Append-only and idempotent (a second run finds it already matched). Call WITHOUT confirm to DRY-RUN (shows the exact Adjustment and the before/after); call again with confirm:true to apply. This is also the first step of a close-out (close does the true-up then flags the agreement closed). Needs the agreement_id. Requires a connected Aurgus account.