Harden multilingual customer capture (recover from raw message)

A customer name is a proper noun that survives translation, so recover it
directly from the raw message as a belt-and-suspenders fill, independent of
language — fixes Shona/Swahili sales losing the customer (and thus credit
tracking / "who owes me").

- _recover_customer_name: recipient markers to|for, kuna|kune|kuye|kunaye (Shona),
kwa (Swahili/Chewa) + a Capitalised name (so "kwa ajili", "for cash" don't match);
supports multi-word names ("Mai Chisomo").
- _fill_missing_customer runs on every sale path (deterministic, LLM, vision) over
both raw and translated text; only fills when customer is empty, never overrides,
never sets the item as the customer.
- Translate prompt: keep names/numbers verbatim, preserve "kuna <Name>" -> "to <Name>".
- ADR 0012.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/decisions/0012-language-agnostic-customer-recovery.md

@@ -0,0 +1,42 @@
+# 12. Language-agnostic customer-name recovery from the raw message
+
+Date: 2026-06-25
+Status: Accepted
+
+## Context
+Multilingual / code-switched input is a core selling point, but customer capture leaned on
+the English deterministic parser or the LLM, both running on the *translated* text. When
+translation reworded or dropped the recipient — Shona "ndatengesa … kuna Chipo akandipa 2
+dollars", "sold … to Audry and she paid …" — the customer was lost, so credit sales never
+landed on a party balance and "who owes me" came back empty. Relying on translation quality
+or the model remembering to fill `details.customer` was too fragile for the headline feature.
+
+## Decision
+A customer name is a **proper noun that survives translation**, so recover it directly from
+the **raw** message as a belt-and-suspenders fill, independent of language.
+- `_recover_customer_name(text)` scans for a recipient marker followed by a **Capitalised**
+  name: English `to|for`, Shona `kuna|kune|kuye|kunaye`, Swahili/Chewa `kwa`. Markers are
+  case-insensitive; the name must be capitalised so "kwa ajili" / "for cash" / "to me" don't
+  match. Bare `ku` is excluded as too ambiguous. Names up to 3 words ("Mai Chisomo").
+- `_fill_missing_customer(txns, *texts)` runs on every sale path (deterministic, LLM, vision)
+  and only fills `details.customer` when it's **empty** — it never overrides the parser/LLM,
+  and never sets the customer to the item being sold.
+- It runs against both the raw `message_text` and the translated `english_text`, so a name
+  is caught whether it survived translation or only exists in the original.
+- The translate prompt now also instructs the model to keep names/numbers verbatim and
+  preserve "kuna <Name>" → "to <Name>".
+
+## Consequences
+- Credit sales, repayments, and "who owes me" work for Shona/Swahili/English phrasings, not
+  just clean English — the multilingual promise holds end to end.
+- Three independent layers now capture the customer (deterministic parser, LLM with examples,
+  raw-text recovery); a miss in one is caught by another.
+- Marker/name heuristics are conservative (capitalised names only) to avoid false positives;
+  a lower-case native name in casual text still relies on the parser/LLM layers.
+
+## Rejected alternatives
+- **Trust translation + LLM only** — the original failure; one reword drops the name.
+- **Run NER / a name model** — heavyweight and another dependency for what a marker + capital
+  heuristic handles for the languages we serve.
+- **Match any word after a marker (no capitalisation)** — false-positives on common phrases
+  like Swahili "kwa ajili ya" ("for the sake of").

docs/decisions/README.md

@@ -32,3 +32,4 @@ Context · Decision · Consequences · Rejected alternatives.
 | [0009](0009-preserve-english-text-and-pretranslation-crud.md) | Preserve raw English input; parse CRUD-by-id before translation | Accepted |
 | [0010](0010-capture-and-remember-stock-cost-price.md) | Capture the stock-in cost price once, then remember it | Superseded by [0011](0011-two-price-model-cost-and-selling.md) |
 | [0011](0011-two-price-model-cost-and-selling.md) | Two-price model: cost from the purchase, a prompt for the selling price | Accepted |
+| [0012](0012-language-agnostic-customer-recovery.md) | Language-agnostic customer-name recovery from the raw message | Accepted |

main.py

@@ -40,6 +40,7 @@ from utility import (
     apply_price_override,
     resolve_sale_prices,
     resolve_stock_costs,
+    _fill_missing_customer,
     check_sale_stock,
     _infer_prices,
     _money_to_float,
@@ -1384,6 +1385,7 @@ def _handle_vision_result(mobile: str, result: str, caption: Optional[str]) -> N
         sale_txns = parse_vision_sale_transactions(result, currency=currency)
 
         if sale_txns:
+            _fill_missing_customer(sale_txns, caption or "")
             resolve_sale_prices(db, mobile, sale_txns)
             sale_txns = _enforce_stock(mobile, sale_txns)
             if not sale_txns:
@@ -1595,6 +1597,7 @@ def process_text_message(message_text: str, mobile: str,
         direct_txns = parse_direct_sale_text(english_text, currency=user_currency) or \
                       parse_stock_in_text(english_text, currency=user_currency)
     if direct_txns:
+        _fill_missing_customer(direct_txns, message_text, english_text)
         resolve_sale_prices(db, mobile, direct_txns)
         resolve_stock_costs(db, mobile, direct_txns)
         direct_txns = _enforce_stock(mobile, direct_txns)
@@ -1633,6 +1636,7 @@ def process_text_message(message_text: str, mobile: str,
     llm_response_str = generateResponse(english_text, currency=user_currency)
     parsed_trans_data = parse_multiple_transactions(llm_response_str)
     parsed_trans_data = _correct_sale_stock_mix(parsed_trans_data, english_text)
+    _fill_missing_customer(parsed_trans_data, message_text, english_text)
 
     response_msg = ""
     send_image   = False

utility.py

@@ -184,6 +184,9 @@ def detect_and_translate_input(text: str) -> Dict[str, str]:
     prompt = (
         'Detect the language of the following text and translate it to English.\n'
         'If the text is already in English, set detected_lang to "English".\n'
+        'Keep every personal name, item name, number, and currency EXACTLY as written — '
+        'never translate, drop, or alter a name. Preserve "to <Name>" relationships '
+        '(e.g. Shona "kuna Chipo" -> "to Chipo").\n'
         'Return ONLY a JSON object: {"detected_lang": "...", "english_text": "..."}\n'
         'No explanation, no markdown.\n\n'
         f'Text: {stripped}'
@@ -550,6 +553,75 @@ def _extract_customer(work: str) -> Tuple[str, Optional[str]]:
     return cleaned, cand
 
 
+# A customer name is a proper noun that survives translation, so we can recover it from
+# the RAW message using recipient markers in several languages — even when translation or
+# the LLM drops it. Shona/Ndebele/Swahili/Chewa "to <person>" markers + English to/for.
+_NAME_TAIL = r"(?:\s+[A-Z][a-zA-Z.'\-]*){0,2}"
+# Markers are case-insensitive (inline (?i:...)) but the NAME must be Capitalised (a proper
+# noun) so "kwa ajili"/"for cash"/"to me" don't match. Bare "ku" is excluded — too ambiguous.
+# Shona kuna/kune/kuye, Swahili/Chewa kwa; English to/for.
+_NATIVE_MARKER_RE = re.compile(r"\b(?i:kuna|kune|kuye|kunaye|kwa)\s+([A-Z][a-zA-Z.'\-]*" + _NAME_TAIL + r")")
+_EN_MARKER_RE = re.compile(r"\b(?:to|for)\s+([A-Z][a-zA-Z.'\-]*" + _NAME_TAIL + r")")
+_NOT_A_NAME = {"cash", "credit", "free", "change", "nothing", "stock", "resale", "today",
+               "tomorrow", "school", "church", "home", "work"}
+
+
+def _recover_customer_name(text: str) -> Optional[str]:
+    """Find a recipient/customer name after a 'to <person>' marker in any supported
+    language. Returns a Title-cased name or None. Language-agnostic on purpose."""
+    if not text:
+        return None
+    for rx in (_NATIVE_MARKER_RE, _EN_MARKER_RE):
+        for m in rx.finditer(text):
+            words: List[str] = []
+            for w in m.group(1).split():
+                lw = w.lower()
+                if lw in _CUSTOMER_STOP or lw in _NON_CUSTOMER_TOKENS or lw in _CURRENCY_TOKENS or lw in _NOT_A_NAME:
+                    break
+                if any(ch.isdigit() for ch in w):
+                    break
+                words.append(w)
+                if len(words) >= 2:
+                    break
+            if words:
+                cand = " ".join(words)
+                if cand.lower() not in _NOT_A_NAME:
+                    return cand.title()
+    return None
+
+
+def _fill_missing_customer(transactions: List[Dict], *texts: str) -> List[Dict]:
+    """If a sale names a recipient (incl. non-English markers like Shona 'kuna') but the
+    parser/LLM left details.customer empty, recover it from the raw/translated text."""
+    if not transactions:
+        return transactions
+    recovered = None
+    computed = False
+    for txn in transactions:
+        if (txn.get("transaction_type") or "").lower() != "sale":
+            continue
+        det = txn.get("details") or {}
+        if det.get("customer"):
+            continue
+        if not computed:
+            computed = True
+            for t in texts:
+                nm = _recover_customer_name(t)
+                if nm:
+                    recovered = nm
+                    break
+        if not recovered:
+            continue
+        # Never mistake the item being sold for the customer.
+        item_names = {normalise_item_name(str(it.get("item") or it.get("name") or ""))
+                      for it in (det.get("items") or [])}
+        if normalise_item_name(recovered) in item_names:
+            continue
+        det["customer"] = recovered
+        txn["details"] = det
+    return transactions
+
+
 # Verb groups used to detect mixed/multi-type messages. The deterministic
 # single-type parsers must defer to the LLM when more than one group is present,
 # otherwise they grab one fragment and silently drop the rest of the message.