Document the ZeroGPU/local-model architecture

README.md

@@ -100,14 +100,18 @@ they stay out of your shell history):
 | --- | --- | --- |
 | `TELEGRAM_BOT_TOKEN` | ✅ | From BotFather |
 | `TELEGRAM_WEBHOOK_SECRET` | ✅ | Any random string; rejects forged webhook calls |
+| `HF_DATASET_REPO` | ✅ | `<you>/finbot-data` — **without this your data is lost on restart** |
+| `HF_TOKEN` | ✅ | **Write**-scoped token. Needed to mirror the ledger; also used for remote inference if you pick that backend |
 | `ALLOWED_TELEGRAM_USER_IDS` | ✅ | Your numeric Telegram ID (comma-separated for more). Not needed if `OPEN_ACCESS=true` |
 | `OPEN_ACCESS` | | `true` lets anyone use the bot, each with their own ledger. Default `false` |
 | `UPLOADS_PER_USER_PER_DAY` | | Caps model-backed uploads per user. Default `20`, `0` disables |
-| `HF_DATASET_REPO` | ✅ | `<you>/finbot-data` — **without this your data is lost on restart** |
-| `HF_TOKEN` | ⚠️ | Write-scoped token with Inference Providers access. Without it, receipts/statements/advice are off; typing expenses still works |
+| `LLM_BACKEND` | | `auto` (default), `local`, `remote`, `off`. See below |
+| `LOCAL_LLM_MODEL` / `LOCAL_VISION_MODEL` | | Override the on-GPU models |
 | `DEFAULT_CURRENCY` | | ISO code for bare amounts. Default `INR` |
 | `TIMEZONE` | | Decides what "today" means. Default `Asia/Kolkata` |
-| `LLM_MODEL` / `LLM_VISION_MODEL` | | Override the models |
+
+A read-only token is not enough: `CommitScheduler` writes the ledger with it,
+and a read token means your data silently never persists.
 
 Generate a webhook secret with:
 
@@ -174,8 +178,16 @@ Telegram ──webhook──▶ FastAPI (:7860)
 **Deterministic first, model second.** The regex parser handles `coffee 250`
 instantly and identically every time. Inference is spent only where judgement
 is genuinely needed: reading a receipt, or working out which column of an
-unfamiliar bank export holds the amount. If `HF_TOKEN` is unset or a provider is
-down, text logging and every summary still work.
+unfamiliar bank export holds the amount. If inference is unavailable, text
+logging and every summary still work.
+
+**Two interchangeable inference backends.** `local` runs a small instruct model
+(Qwen2.5-3B, plus a 3B VL model for receipts) on the Space's own borrowed A10G;
+`remote` calls HF Inference Providers. Same interface, chosen by `LLM_BACKEND`,
+and `auto` picks local whenever a CUDA device is present. Local is the default
+on a Space because it costs nothing per call — which is what makes
+`OPEN_ACCESS` affordable, since otherwise every stranger's receipt would spend
+your inference credits.
 
 **Money is never a float.** Amounts are integer minor units (paise, cents, fils)
 plus an ISO 4217 code. Currencies are never summed together — a multi-currency
@@ -255,3 +267,12 @@ a stubbed Telegram transport. None of them touch the network.
   `Netflix`, but not `AMZN Mktp` with `Amazon`.
 - **Advice is budgeting only.** It comments on your logged spending and is
   explicitly prevented from recommending investments or giving tax advice.
+- **Free Spaces sleep** after 48h idle, and the first request after that pays a
+  cold start plus a model load. Telegram retries, so the message lands — it is
+  just slow.
+- **A 3B model is not a frontier model.** It is good enough for "which column is
+  the amount" and short coaching; expect worse statement extraction than the
+  remote backend. Switch with `LLM_BACKEND=remote` if you would rather spend
+  credits for quality.
+- **ZeroGPU has a daily GPU-second quota** on free accounts. Heavy statement
+  days can exhaust it; typed expenses keep working regardless.