SME Treasury: How to Build It

from datetime import date, timedelta
from decimal import Decimal

# STEP 1. THE FOUR LINES, AS CODE RATHER THAN AS A POLICY DOCUMENT.
# Each of these is a single feature away from a licence you do not hold.

def assert_boundaries(action, ctx):
    # 1. Money never rests with you. Not for an hour, not "in transit".
    assert action["settlement_account_owner"] == "customer", \
        "holding customer funds makes you a payment aggregator"
    # 2. You may show options and arithmetic. You may not rank, default-sort,
    #    badge, or personalise them. See the robo-advisory guide.
    assert not action.get("recommends_instrument"), \
        "ranking an investment for a specific customer is investment advice"
    # 3. Bridging a gap with your own balance sheet is lending.
    assert action["funding_source"] != "platform_balance_sheet", \
        "advancing funds is lending"
    # 4. Conversion belongs to an authorised dealer bank.
    assert action.get("fx_conversion_by") in (None, "customer_ad_bank"), \
        "converting currency requires an AD bank"
    return True

# STEP 2. ONE POSITION, ACROSS BANKS.
# The whole reason this product exists: a business with four accounts at three
# banks has four balances and no position.

def position(accounts, as_of=None):
    as_of = as_of or date.today()
    total = Decimal(0); stale = []
    for a in accounts:
        # A balance is only as good as its timestamp. Say so on the screen.
        age_h = (as_of - a["balance_as_of"]).days * 24
        if age_h > 24:
            stale.append({"account": a["id"], "age_hours": age_h})
        total += Decimal(a["balance_paise"])
    return {
        "as_of_ist": as_of.isoformat(),
        "total_paise": total,
        "by_account": [{"id": a["id"], "bank": a["bank"],
                        "balance_paise": a["balance_paise"],
                        "as_of": a["balance_as_of"].isoformat()} for a in accounts],
        # Never present a stale figure as current. An SME will make a payroll
        # decision on this number.
        "stale_accounts": stale,
        "confidence": "LOW" if stale else "OK",
    }

# WHAT TO CHECK
# [ ] every one of the four assertions runs on every money-adjacent action,
#     not in a design review
# [ ] a balance carries its own timestamp all the way to the screen
# [ ] "available" is not "balance" -- subtract uncleared cheques, holds, and
#     the minimum the bank requires
# [ ] one currency base, converted at a STORED rate with a timestamp, never
#     at today's rate applied to yesterday's balance
# [ ] read-only access by default. The consent to SEE money and the consent
#     to MOVE money are different permissions and should look different
# [ ] aggregate in IST against bank cut-offs, not a UTC calendar day

# STEP 5. FORECAST. A NUMBER IS A LIE; A RANGE IS A FORECAST.
# The useful output is not "you will have 42 lakh on the 30th". It is "payroll
# on the 30th is covered unless these two invoices slip, and here they are".

def cash_forecast(position, receivables, payables, horizon_days=45):
    base = position["total_paise"]
    rows = []
    for d in range(horizon_days):
        day = date.today() + timedelta(days=d)
        inflow_p50 = sum(r["amount_paise"] * r["p_pay_by"](day) for r in receivables)
        outflow = sum(p["amount_paise"] for p in payables if p["due"] == day)
        base = base + inflow_p50 - outflow
        rows.append({"date": day.isoformat(), "expected_paise": base,
                     "committed_outflow_paise": outflow})
    return {"rows": rows,
            "confidence": position["confidence"],      # inherits its inputs
            "drivers": top_swing_factors(receivables), # WHICH invoices decide it
            "breach_dates": [r["date"] for r in rows if r["expected_paise"] < 0]}

# The single most useful screen in the product is not the chart. It is:
# "these three invoices decide whether the 30th works."

# STEP 6. THE SURPLUS, WITHOUT BECOMING AN ADVISER.
def surplus_options(customer, amount_paise, days_until_needed):
    opts = customer["bank"].deposit_products(amount_paise, days_until_needed)
    return {
        "amount_paise": amount_paise,
        "days_until_needed": days_until_needed,
        # Arithmetic, in a stable order, with the assumptions visible.
        "options": [{"name": o["name"], "rate_pa": o["rate_pa"],
                     "lock_in_days": o["lock_in_days"],
                     "interest_paise": simple_interest(amount_paise, o["rate_pa"],
                                                       days_until_needed),
                     "breaks_before_needed": o["lock_in_days"] > days_until_needed}
                    for o in opts],
        "sort": "stable_by_lock_in",     # NOT by return. A default sort ranks.
        "recommended": None,             # and it stays None
        "disclaimer_is_not_the_control": True,
    }

# STEP 7. CURRENCY -- if they trade abroad, there is a queue waiting for them.
def fx_exposure(invoices, base="INR"):
    open_entries = [i for i in invoices if i["edpms_idpms_status"] == "OPEN"]
    return {"by_currency": bucket(invoices, "currency"),
            # Entries stay open until somebody closes them, and resurface as a
            # bank declining the next transaction. Queue, owner, age.
            "open_regulatory_entries": len(open_entries),
            "oldest_open_days": max([i["age_days"] for i in open_entries] or [0])}

# STEP 8. CLOSE THE LOOP.
def close(period, ledger, statements):
    # FULL OUTER JOIN. A bank line matching no ledger entry is the interesting
    # case -- money that moved and nobody can explain.
    matched, only_ledger, only_bank = full_outer_match(ledger, statements)
    assert control_total(statements) == expected_total(period), "abort: file incomplete"
    return {"matched": len(matched), "unexplained_bank_lines": len(only_bank),
            "unmatched_ledger": len(only_ledger),
            "decisions_log": period["decisions"]}   # what was decided, and why

# WHAT TO CHECK
# [ ] a forecast carries the confidence of its worst input, not its best
# [ ] name the invoices that decide the outcome. That is the product
# [ ] surplus options are never ranked, sorted by return, or badged. Stable
#     order, visible assumptions, nothing recommended
# [ ] control totals BEFORE matching, and abort on mismatch -- a truncated
#     statement reconciles perfectly on the rows it contains
# [ ] full outer join, never left. The unexplained bank line is the point
# [ ] EDPMS and IDPMS entries tracked as a queue with an owner and an age
# [ ] log the DECISION, not only the transaction: what was chosen, on what
#     figures, by whom. That log is the difference between a tool and a record