Deploy coco-finbot

.env.example

@@ -0,0 +1,64 @@
+# coco-finbot configuration.
+# Locally: copy to .env. On Hugging Face: set these under Space Settings > Secrets.
+# Never commit the real .env.
+
+# --- Telegram -------------------------------------------------------------
+# From @BotFather.
+TELEGRAM_BOT_TOKEN=
+
+# Random string you invent. Telegram echoes it back in the
+# X-Telegram-Bot-Api-Secret-Token header; requests without it are rejected.
+# Generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+TELEGRAM_WEBHOOK_SECRET=
+
+# Comma-separated Telegram numeric user IDs allowed to use the bot.
+# Leave EMPTY to allow nobody (safe default -- the bot replies with a refusal
+# and tells the sender their id, so you can read your own id off the reply).
+# Ignored when OPEN_ACCESS=true.
+ALLOWED_TELEGRAM_USER_IDS=
+
+# Let ANYONE on Telegram use the bot. Each user gets their own isolated ledger,
+# so this makes the bot multi-tenant -- it does NOT expose your spending to
+# other people. What it does expose is your wallet: every stranger's receipt
+# and statement is read using YOUR HF_TOKEN. Cap that below.
+# Must be set explicitly, so an unconfigured allowlist stays closed.
+OPEN_ACCESS=false
+
+# Model-backed uploads (receipt photos, statements) per user per day.
+# Typed expenses are parsed locally and are never counted. 0 disables the cap.
+UPLOADS_PER_USER_PER_DAY=20
+
+# --- Inference (Hugging Face Inference Providers) --------------------------
+# A HF token with "Make calls to Inference Providers" permission.
+# On a Space you can leave this unset and the bot still works -- it falls back
+# to the deterministic parser and skips receipt/statement understanding.
+HF_TOKEN=
+
+# OpenAI-compatible base URL. HF's router fans one token out to many providers.
+LLM_BASE_URL=https://router.huggingface.co/v1
+
+# Text model used for extraction, categorisation and advice.
+LLM_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507
+
+# Vision model used for receipt photos. Must accept image_url content parts.
+LLM_VISION_MODEL=Qwen/Qwen2.5-VL-72B-Instruct
+
+# --- Durable storage ------------------------------------------------------
+# Spaces disk is EPHEMERAL -- it is wiped on every restart, sleep or rebuild.
+# The bot keeps SQLite locally and mirrors it to a PRIVATE dataset repo so your
+# data survives. Set to a repo you own, e.g. "your-username/finbot-data".
+# Leave empty to run purely local (fine for dev; DATA LOSS on a Space).
+HF_DATASET_REPO=
+
+# How often (minutes) to push the database to the dataset repo.
+SYNC_EVERY_MINUTES=5
+
+# Where the local SQLite file lives inside the container.
+DATA_DIR=/home/user/data
+
+# --- Behaviour ------------------------------------------------------------
+# Default currency for bare amounts like "coffee 250". ISO 4217 code.
+DEFAULT_CURRENCY=INR
+
+# IANA timezone used to decide what "today" and "this month" mean.
+TIMEZONE=Asia/Kolkata

.gitignore

@@ -0,0 +1,25 @@
+# Secrets -- never commit. On Spaces these come from Settings > Secrets.
+.env
+*.env
+!.env.example
+
+# Local SQLite working copy and any restored snapshots
+data/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+# Hugging Face Spaces runs containers as uid 1000. Create a matching user so the
+# app owns its own HOME -- the SQLite working copy lives under $HOME/data.
+RUN useradd -m -u 1000 user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR $HOME/app
+
+COPY --chown=user:user requirements.txt .
+
+USER user
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user:user . .
+
+# Spaces routes public traffic to app_port (see README.md frontmatter).
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,15 +1,248 @@
 ---
 title: Oracle
-emoji: 👁
-colorFrom: indigo
-colorTo: blue
-sdk: gradio
-sdk_version: 6.24.0
-python_version: '3.12'
-app_file: app.py
+emoji: 💸
+colorFrom: green
+colorTo: indigo
+sdk: docker
+app_port: 7860
 pinned: false
-license: mit
-short_description: Oracle for personal use
+short_description: Expense tracking and budget coaching over Telegram
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# coco-finbot
+
+> Deployed as the **Oracle** Space. `sdk: docker` above is what switches the
+> Space off Gradio — do not drop it.
+
+A personal finance bot that lives in Telegram and runs as a Hugging Face Docker
+Space. Tell it what you spent, send it receipts and bank statements, and ask it
+what your money is doing.
+
+```
+you  ▸ coffee 250
+bot  ▸ ✅ Logged ₹250.00 — coffee
+       Food & Dining · 2026-08-15
+
+you  ▸ [photo of a restaurant bill]
+bot  ▸ ✅ Logged ₹1,840.00 — Toit Brewpub
+       Food & Dining · 2026-08-14
+
+you  ▸ [statement.pdf]
+bot  ▸ Found 47 transactions in that PDF · ₹68,204.00
+       3 already logged (skipped)
+       These were read by a model and not saved yet.
+       /confirm to save · /cancel to discard
+```
+
+---
+
+## Read this before you deploy
+
+**Space disk is ephemeral.** Hugging Face wipes it on every restart, sleep and
+rebuild. If you do not set `HF_DATASET_REPO`, your entire ledger disappears the
+first time the Space sleeps — silently, because nothing errors. The bot mirrors
+SQLite to a **private** dataset repo on a timer and restores it on boot. `/status`
+tells you which mode you are in.
+
+**Make the Space private.** This is your spending history. A public Space exposes
+the container, its logs and its `/health` endpoint to anyone.
+
+**Decide who can use it.** `ALLOWED_TELEGRAM_USER_IDS` starts empty, which
+authorises nobody — a forgotten allowlist stays closed rather than silently
+opening to the world.
+
+Set `OPEN_ACCESS=true` to let anyone message the bot. Ledgers are keyed by
+Telegram user id, so open access makes the bot **multi-tenant**: each person
+gets their own private ledger and nobody can see yours. What open access does
+expose is your **wallet** — every stranger's receipt and statement is read using
+your `HF_TOKEN`. `UPLOADS_PER_USER_PER_DAY` (default 20) caps that; typed
+expenses are parsed locally and never metered. Note also that running an open
+bot makes you the custodian of other people's financial data in your dataset
+repo.
+
+---
+
+## Deploy
+
+**1. Create the bot.** Message [@BotFather](https://t.me/BotFather) → `/newbot` →
+keep the token.
+
+**2. Push the Space and dataset.** `deploy.sh` creates both (private, Docker SDK)
+and uploads the source. It takes the owner from your logged-in account:
+
+```bash
+./.venv/bin/hf auth login && ./deploy.sh
+```
+
+```bash
+./deploy.sh --dry-run          # show the target repos, create nothing
+./deploy.sh Uniphy             # deploy under an org instead of your account
+```
+
+> Use this rather than `git push`. This directory lives inside the larger UniPhy
+> repo, so a `git push` from here would send that entire tree — unrelated repos
+> and any secrets they hold — to a public-by-default host. `deploy.sh` uploads
+> only this folder, minus `.venv`, `.env`, caches and any local database.
+
+**3. Set secrets** under Space Settings → Secrets (use the UI, not the CLI, so
+they stay out of your shell history):
+
+| Secret | Required | What it does |
+| --- | --- | --- |
+| `TELEGRAM_BOT_TOKEN` | ✅ | From BotFather |
+| `TELEGRAM_WEBHOOK_SECRET` | ✅ | Any random string; rejects forged webhook calls |
+| `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 |
+| `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 |
+
+Generate a webhook secret with:
+
+```bash
+python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+**4. Restart the Space** so it picks up the secrets. On boot it reads
+`SPACE_HOST` and registers its own Telegram webhook — nothing else to wire up.
+
+**5. Message the bot.** Don't know your Telegram ID? Send it anything: it
+replies with the ID to paste into `ALLOWED_TELEGRAM_USER_IDS`. Then send
+`/status` and confirm storage reads *mirroring*, not *local only*.
+
+---
+
+## Using it
+
+Anything with a number in it is logged. No command needed.
+
+```
+coffee 250
+₹1,240 groceries at bigbasket
+45.50 lunch yesterday
+320 uber #transport          ← #tag overrides the category guess
+€40 dinner 12 aug
+```
+
+Send a **photo** of a receipt and a vision model reads the total. Send a
+**PDF/CSV/XLSX** statement and it extracts the transactions, drops any already
+in your ledger, and shows you the total before saving — nothing model-extracted
+is written until you `/confirm`.
+
+| Command | |
+| --- | --- |
+| `/today` `/week` `/month` | Spending summaries with a category breakdown |
+| `/report <period>` | `today`, `week`, `month`, `last_month`, `30d`, `year`, `all` |
+| `/list [n]` | Recent transactions |
+| `/recurring` | Subscriptions and repeat charges, with the annual cost |
+| `/advice [question]` | Observations grounded in your own numbers |
+| `/budget <category> <amount>` | Set a monthly cap |
+| `/budgets` | How you're tracking |
+| `/categories` | Category names for tags and budgets |
+| `/undo` | Remove the last entry, or the last import wholesale |
+| `/export` | Everything as CSV |
+| `/status` | Config and storage health |
+
+---
+
+## How it works
+
+```
+Telegram ──webhook──▶ FastAPI (:7860)
+                          │
+                          ├─ registry ──▶ features: expenses │ budgets │ coaching │ core
+                          │                    │
+                          │                    ├─ parser      deterministic, free, first
+                          │                    ├─ extract     CSV · XLSX · PDF
+                          │                    └─ llm ──▶ router.huggingface.co/v1
+                          │
+                          └─ store: SQLite ──CommitScheduler──▶ private HF dataset
+```
+
+**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.
+
+**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
+month reports one total per currency rather than a fictional combined figure.
+
+**Statements are staged, not trusted.** A model that misreads a column would
+otherwise quietly poison months of history, so imports become a pending batch
+you confirm, tagged with a `batch_id` so `/undo` can reverse the whole thing.
+
+**Inference is provider-agnostic.** `LLM_BASE_URL` is an OpenAI-compatible
+endpoint. It defaults to HF's router — one token, many providers — but points
+just as happily at Ollama, llama.cpp or OpenAI.
+
+---
+
+## Adding a feature
+
+The registry is the extension point. A feature declares commands and optionally
+claims plain messages or uploaded files; the first one to return a `Reply` wins.
+Nothing else in the codebase changes.
+
+```python
+from finbot.features.base import BotContext, CommandSpec, Reply, SimpleFeature
+
+class RemindersFeature(SimpleFeature):
+    name = "reminders"
+    description = "⏰ Reminders"
+
+    def commands(self):
+        return (CommandSpec("remind", "Set a reminder", "<when> <what>"),)
+
+    def cmd_remind(self, ctx: BotContext) -> Reply:
+        return Reply(f"Noted: {ctx.args}")
+```
+
+Add it to `default_features()` in `finbot/features/__init__.py`. `/help` and
+Telegram's command menu build themselves from what is registered, and duplicate
+commands raise at startup rather than shadowing silently.
+
+---
+
+## Development
+
+```bash
+python3.11 -m venv .venv && ./.venv/bin/pip install -r requirements.txt pytest
+cp .env.example .env      # fill in what you need
+./.venv/bin/python -m pytest tests/ -q
+./.venv/bin/uvicorn app:app --reload --port 7860
+```
+
+To test against real Telegram locally, expose port 7860 with a tunnel and
+register the webhook:
+
+```bash
+curl -X POST localhost:7860/admin/setup -H "X-Admin-Secret: $TELEGRAM_WEBHOOK_SECRET" -H 'Content-Type: application/json' -d '{"url":"https://<your-tunnel>/telegram/webhook"}'
+```
+
+268 tests cover the pure logic — money arithmetic, parsing, categorisation,
+analytics, the registry contract — plus an end-to-end pass over the webhook with
+a stubbed Telegram transport. None of them touch the network.
+
+---
+
+## Known limits
+
+- **Credits are not stored.** Statement imports keep debits only; incoming money
+  is counted and reported but not written, because mixing it into the same table
+  would corrupt every "total spent" figure. Income tracking is a real feature,
+  not a small one.
+- **Scanned PDFs** have no text layer. The bot detects this and tells you to send
+  it as a photo instead.
+- **Legacy `.xls`** is not supported — re-save as `.xlsx` or CSV.
+- **20 MB** is Telegram's own cap on bot file downloads.
+- **Pending imports live in memory**, so a Space restart between the preview and
+  `/confirm` drops them. Re-send the file.
+- **Recurring detection is lexical.** It unifies `NETFLIX.COM 447192` with
+  `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.

app.py

@@ -0,0 +1,346 @@
+"""FastAPI entrypoint -- the Hugging Face Space serves this on port 7860.
+
+The webhook answers Telegram immediately and does the real work in a background
+task. Reading a statement can take a minute; holding the webhook open that long
+makes Telegram time out and redeliver, which would import the same file twice.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import BackgroundTasks, FastAPI, Header, Request
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from finbot import __version__
+from finbot.advice import Advisor
+from finbot.analytics import today_in
+from finbot.config import get_settings
+from finbot.features import default_features
+from finbot.features.base import Attachment, BotContext, Services
+from finbot.ingest import Ingestor
+from finbot.limits import RateLimiter
+from finbot.llm import LLMClient
+from finbot.registry import FeatureRegistry
+from finbot.store import open_store
+from finbot.telegram import (
+    MAX_DOWNLOAD_BYTES,
+    ParsedUpdate,
+    SeenUpdates,
+    TelegramClient,
+    parse_update,
+)
+
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO"),
+    format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
+)
+log = logging.getLogger("finbot")
+
+WEBHOOK_PATH = "/telegram/webhook"
+
+
+def build_services() -> Services:
+    settings = get_settings()
+    registry = FeatureRegistry()
+    llm = LLMClient(settings)
+
+    services = Services(
+        settings=settings,
+        store=open_store(settings),
+        llm=llm,
+        ingestor=Ingestor(llm, settings.default_currency),
+        advisor=Advisor(llm),
+        registry=registry,
+    )
+    registry.register_all(default_features())
+    return services
+
+
+def space_webhook_url() -> str:
+    """Public URL of this Space, if we are running on one."""
+    if host := os.environ.get("SPACE_HOST"):
+        return f"https://{host.rstrip('/')}{WEBHOOK_PATH}"
+    return ""
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    services = build_services()
+    settings = services.settings
+    telegram = TelegramClient(settings.telegram_bot_token)
+
+    app.state.services = services
+    app.state.telegram = telegram
+    app.state.seen = SeenUpdates()
+    app.state.limiter = RateLimiter(settings.uploads_per_user_per_day)
+
+    for gap in settings.missing_required():
+        log.warning("Not configured: %s", gap)
+
+    if settings.open_access:
+        log.warning(
+            "OPEN ACCESS: anyone on Telegram may use this bot. Ledgers are "
+            "isolated per user, but uploads spend this Space's inference "
+            "credits (capped at %s/user/day).",
+            settings.uploads_per_user_per_day or "unlimited",
+        )
+
+    if telegram.enabled:
+        try:
+            me = await telegram.get_me()
+            log.info("Connected to Telegram as @%s", me.get("username"))
+            await telegram.set_my_commands(services.registry.telegram_commands())
+
+            if (url := space_webhook_url()) and settings.telegram_webhook_secret:
+                await telegram.set_webhook(url, settings.telegram_webhook_secret)
+                log.info("Webhook registered at %s", url)
+            elif not settings.telegram_webhook_secret:
+                log.warning("TELEGRAM_WEBHOOK_SECRET unset; webhook not registered.")
+            else:
+                log.info(
+                    "No SPACE_HOST; register the webhook manually via POST /admin/setup"
+                )
+        except Exception as exc:
+            # A Telegram hiccup must not stop the Space from booting -- a live
+            # container that reports the problem beats a crash loop.
+            log.error("Telegram bootstrap failed: %s", exc)
+    else:
+        log.warning("TELEGRAM_BOT_TOKEN unset; running without a bot connection.")
+
+    try:
+        yield
+    finally:
+        log.info("Shutting down; flushing ledger to the Hub.")
+        await telegram.close()
+        services.llm.close()
+        await run_in_threadpool(services.store.close)
+
+
+app = FastAPI(title="coco-finbot", version=__version__, lifespan=lifespan)
+
+
+# --------------------------------------------------------------------- pages
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index() -> str:
+    """Deliberately stateless.
+
+    This Space may be public, and transaction counts, configuration gaps and
+    sync state are personal operational detail. They are available to the owner
+    over Telegram via /status, and here only behind /admin/diagnostics.
+    """
+    return f"""<!doctype html>
+<meta charset="utf-8"><title>Oracle</title>
+<style>
+ body {{ font: 16px/1.6 system-ui, sans-serif; max-width: 40rem;
+        margin: 4rem auto; padding: 0 1rem; }}
+ a {{ color: inherit; }}
+</style>
+<h1>💸 Oracle</h1>
+<p>A private expense-tracking and budget-coaching bot. It runs on Telegram —
+   there is nothing to use on this page.</p>
+<p>Built with <code>coco-finbot</code> v{__version__}.</p>
+"""
+
+
+@app.get("/health")
+async def health() -> JSONResponse:
+    """Liveness only. No ledger or configuration detail — this may be public."""
+    return JSONResponse({"status": "ok", "version": __version__})
+
+
+@app.get("/admin/diagnostics")
+async def diagnostics(
+    x_admin_secret: Optional[str] = Header(default=None),
+) -> JSONResponse:
+    """Operational detail, gated on the webhook secret."""
+    services: Services = app.state.services
+    settings = services.settings
+
+    if not settings.telegram_webhook_secret or x_admin_secret != settings.telegram_webhook_secret:
+        return JSONResponse({"ok": False, "error": "forbidden"}, status_code=403)
+
+    return JSONResponse(
+        {
+            "ok": True,
+            "version": __version__,
+            "llm_enabled": settings.llm_enabled,
+            "sync_enabled": settings.sync_enabled,
+            "sync_status": services.store.sync_status,
+            "rows": services.store.count(),
+            "missing": settings.missing_required(),
+        }
+    )
+
+
+# ------------------------------------------------------------------ webhook
+
+
+@app.post(WEBHOOK_PATH)
+async def telegram_webhook(
+    request: Request,
+    background: BackgroundTasks,
+    x_telegram_bot_api_secret_token: Optional[str] = Header(default=None),
+) -> JSONResponse:
+    services: Services = app.state.services
+    settings = services.settings
+
+    expected = settings.telegram_webhook_secret
+    if not expected or x_telegram_bot_api_secret_token != expected:
+        log.warning("Rejected webhook call with a bad secret token.")
+        return JSONResponse({"ok": False}, status_code=403)
+
+    try:
+        update = await request.json()
+    except Exception:
+        return JSONResponse({"ok": False, "error": "bad json"}, status_code=400)
+
+    telegram: TelegramClient = app.state.telegram
+    parsed = parse_update(update, telegram.username)
+    if parsed is None:
+        return JSONResponse({"ok": True, "skipped": "unsupported update"})
+
+    if not app.state.seen.add_if_new(parsed.update_id):
+        log.info("Ignoring redelivered update %s", parsed.update_id)
+        return JSONResponse({"ok": True, "skipped": "duplicate"})
+
+    # Answer now, work later: Telegram redelivers if we hold this open.
+    background.add_task(handle_update, parsed)
+    return JSONResponse({"ok": True})
+
+
+async def handle_update(parsed: ParsedUpdate) -> None:
+    services: Services = app.state.services
+    telegram: TelegramClient = app.state.telegram
+    settings = services.settings
+
+    if not settings.is_authorised(parsed.user_id):
+        log.warning("Unauthorised user %s attempted access", parsed.user_id)
+        await telegram.send_message(
+            parsed.chat_id,
+            "This is a private bot and you're not on its allowlist.\n\n"
+            f"If it's yours, add <code>{parsed.user_id}</code> to "
+            "<code>ALLOWED_TELEGRAM_USER_IDS</code> in the Space secrets "
+            "and restart it.",
+        )
+        return
+
+    try:
+        attachment = None
+        if parsed.has_file:
+            if parsed.file_size > MAX_DOWNLOAD_BYTES:
+                await telegram.send_message(
+                    parsed.chat_id,
+                    "That file is over Telegram's 20 MB bot limit. "
+                    "Try exporting a narrower date range.",
+                )
+                return
+
+            # Reading files costs the Space owner real inference credits, so
+            # cap it per user. Typing expenses stays unmetered and free.
+            if not app.state.limiter.check(parsed.user_id):
+                await telegram.send_message(
+                    parsed.chat_id,
+                    "You've hit today's limit for reading receipts and "
+                    "statements. It resets in 24 hours — you can still log "
+                    "expenses by typing them.",
+                )
+                return
+
+            await telegram.send_typing(parsed.chat_id)
+            data, file_path = await telegram.download(parsed.file_id)
+            attachment = Attachment(
+                data=data,
+                filename=parsed.file_name or file_path.rsplit("/", 1)[-1],
+                mime_type=parsed.mime_type,
+                kind=parsed.file_kind,
+                caption=parsed.caption,
+            )
+
+        ctx = BotContext(
+            user_id=parsed.user_id,
+            chat_id=parsed.chat_id,
+            services=services,
+            today=today_in(settings.timezone),
+            text=parsed.text or parsed.caption,
+            command=parsed.command,
+            args=parsed.args,
+            attachment=attachment,
+        )
+
+        if attachment is not None or parsed.command in {"advice", "report"}:
+            await telegram.send_typing(parsed.chat_id)
+
+        reply = await run_in_threadpool(services.registry.dispatch, ctx)
+
+        if reply is None:
+            if not parsed.command and ctx.text.strip():
+                await telegram.send_message(
+                    parsed.chat_id,
+                    "I couldn't find an amount in that. Try "
+                    "<code>250 coffee</code>, or /help.",
+                )
+            return
+
+        if reply.document is not None:
+            filename, payload = reply.document
+            await telegram.send_document(
+                parsed.chat_id, filename, payload, caption=reply.text
+            )
+            return
+
+        await telegram.send_message(parsed.chat_id, reply.text, reply.parse_mode)
+
+    except Exception:
+        log.exception("Failed handling update %s", parsed.update_id)
+        try:
+            await telegram.send_message(
+                parsed.chat_id,
+                "Something went wrong on my side. The details are in the Space logs.",
+            )
+        except Exception:
+            pass
+
+
+# -------------------------------------------------------------------- admin
+
+
+@app.post("/admin/setup")
+async def admin_setup(
+    request: Request,
+    x_admin_secret: Optional[str] = Header(default=None),
+) -> JSONResponse:
+    """Register the webhook manually (local dev behind a tunnel, or no SPACE_HOST).
+
+    Authorised with the same webhook secret, so no extra credential to manage.
+    """
+    services: Services = app.state.services
+    settings = services.settings
+    telegram: TelegramClient = app.state.telegram
+
+    if not settings.telegram_webhook_secret or x_admin_secret != settings.telegram_webhook_secret:
+        return JSONResponse({"ok": False, "error": "forbidden"}, status_code=403)
+
+    body = {}
+    try:
+        body = await request.json()
+    except Exception:
+        pass
+
+    url = body.get("url") or space_webhook_url()
+    if not url:
+        return JSONResponse(
+            {"ok": False, "error": "no url given and SPACE_HOST is unset"},
+            status_code=400,
+        )
+
+    await telegram.set_webhook(url, settings.telegram_webhook_secret)
+    await telegram.set_my_commands(services.registry.telegram_commands())
+    info = await telegram.get_webhook_info()
+    return JSONResponse({"ok": True, "webhook": info})

deploy.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# Push coco-finbot to a Hugging Face Space.
+#
+# Uses `hf upload` rather than git, deliberately: this directory sits inside the
+# larger UniPhy repo, so `git push` here would try to push that entire tree --
+# unrelated repos and any secrets they hold -- to a public-by-default host.
+#
+# Run `hf auth login` first. Secrets are NOT set here; put them in the Space
+# Settings > Secrets UI so they never land in your shell history.
+#
+# Usage:
+#   ./deploy.sh                      # deploy under your own account
+#   ./deploy.sh Uniphy               # deploy under an org you belong to
+#   ./deploy.sh "" my-bot my-data    # custom space / dataset names
+#   ./deploy.sh --dry-run            # show what would happen, create nothing
+
+set -euo pipefail
+
+DRY_RUN=0
+if [[ "${1:-}" == "--dry-run" ]]; then
+  DRY_RUN=1
+  shift
+fi
+
+OWNER="${1:-}"
+SPACE_NAME="${2:-coco-finbot}"
+DATA_NAME="${3:-finbot-data}"
+
+HF="./.venv/bin/hf"
+PY="./.venv/bin/python"
+[[ -x "$HF" ]] || HF="hf"
+[[ -x "$PY" ]] || PY="python3"
+
+echo "▸ Checking authentication"
+# `hf auth whoami` prints ANSI-coloured labelled lines ("user: name") and exits
+# 0 even when logged out, so ask the API for a clean value instead of scraping.
+ACCOUNT="$(
+  "$PY" - <<'PY' 2>/dev/null || true
+try:
+    from huggingface_hub import HfApi
+    print(HfApi().whoami()["name"])
+except Exception:
+    pass
+PY
+)"
+
+if [[ -z "$ACCOUNT" ]]; then
+  echo "  Not logged in. Run:  $HF auth login" >&2
+  exit 1
+fi
+echo "  logged in as: $ACCOUNT"
+
+OWNER="${OWNER:-$ACCOUNT}"
+
+SPACE_ID="${OWNER}/${SPACE_NAME}"
+DATA_ID="${OWNER}/${DATA_NAME}"
+
+# Fail early with a readable message rather than a validation traceback.
+if [[ ! "$OWNER" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+  echo "  Invalid owner name: '$OWNER'" >&2
+  exit 1
+fi
+
+echo "▸ Target Space:   $SPACE_ID  (docker, private)"
+echo "▸ Target dataset: $DATA_ID   (private, durable ledger)"
+
+if [[ "$DRY_RUN" == "1" ]]; then
+  echo
+  echo "(dry run — nothing created or uploaded)"
+  exit 0
+fi
+
+echo "▸ Creating Space"
+"$HF" repo create "$SPACE_ID" --repo-type space --space_sdk docker --private --exist-ok
+
+echo "▸ Creating dataset"
+"$HF" repo create "$DATA_ID" --repo-type dataset --private --exist-ok
+
+echo "▸ Uploading source"
+# Everything the container does not need, or that must never leave this machine.
+"$HF" upload "$SPACE_ID" . . \
+  --repo-type space \
+  --commit-message "Deploy coco-finbot" \
+  --exclude \
+    ".venv/*" \
+    "**/__pycache__/*" \
+    ".pytest_cache/*" \
+    ".ruff_cache/*" \
+    "data/*" \
+    "*.db" \
+    ".env" \
+    ".git/*"
+
+SECRET="$("$PY" -c "import secrets; print(secrets.token_urlsafe(32))" 2>/dev/null || echo "<generate a random string>")"
+
+cat <<EOF
+
+✅ Uploaded to https://huggingface.co/spaces/${SPACE_ID}
+
+Still to do (only you can do these):
+
+  1. Space Settings > Secrets, add:
+       TELEGRAM_BOT_TOKEN         from @BotFather
+       TELEGRAM_WEBHOOK_SECRET    ${SECRET}
+       ALLOWED_TELEGRAM_USER_IDS  your numeric Telegram id
+       HF_DATASET_REPO            ${DATA_ID}
+       HF_TOKEN                   a write token with Inference Providers access
+
+  2. Confirm the Space is Private (Settings > Change visibility).
+
+  3. Restart the Space. It registers its own Telegram webhook on boot.
+
+  4. Message your bot. If you don't know your Telegram id, send it anything --
+     it replies with the id to paste into ALLOWED_TELEGRAM_USER_IDS, then
+     restart the Space once more.
+
+  5. Send /status and confirm storage says "mirroring", not "local only".
+EOF

finbot/__init__.py

@@ -0,0 +1,13 @@
+"""coco-finbot -- personal expense tracking and budget coaching over Telegram.
+
+Designed to run as a Hugging Face Docker Space. Two constraints from that
+environment shape the whole design:
+
+* Space disk is **ephemeral** -- wiped on every restart, sleep and rebuild. All
+  durable state therefore lives in a private Hub dataset (see
+  :mod:`finbot.store`), with SQLite as a local working copy.
+* Free Spaces **sleep** after inactivity, so the bot is webhook-driven rather
+  than long-polling.
+"""
+
+__version__ = "0.1.0"

finbot/advice.py

@@ -0,0 +1,243 @@
+"""Budget coaching grounded in the user's own numbers.
+
+Two deliberate constraints:
+
+* **Grounded.** The model is handed a computed brief -- real totals, real
+  categories, real recurring charges -- and told to comment only on that. It
+  never sees a free-form question it can answer from general knowledge, so it
+  cannot invent a number that looks authoritative and is wrong.
+* **Scoped to budgeting.** This is a spending coach, not a financial adviser.
+  The prompt forbids investment, tax and legal recommendations, and the
+  fallback path below is pure arithmetic over the ledger.
+
+If inference is unavailable the deterministic observations still fire, so
+``/advice`` always returns something useful.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+from typing import Optional
+
+from .analytics import (
+    BudgetStatus,
+    Recurring,
+    by_category,
+    dominant_currency,
+    month_bounds,
+    project_month_end,
+    top_merchants,
+    total_minor,
+)
+from .categories import label as category_label
+from .llm import LLMClient, LLMUnavailable
+from .models import Expense
+from .money import format_money
+
+log = logging.getLogger(__name__)
+
+DISCLAIMER = (
+    "_General budgeting observations based only on what you've logged — "
+    "not financial advice._"
+)
+
+_SYSTEM = """You are a personal budgeting coach embedded in a Telegram bot.
+
+You will be given a factual brief computed from one person's own logged
+spending. Comment ONLY on that brief.
+
+Hard rules:
+- Never recommend specific investments, securities, funds, stocks, crypto,
+  insurance or financial products, and never suggest how to allocate savings.
+  You are not a licensed financial adviser. If the user seems to want that,
+  say plainly that it is outside what you do.
+- Never give tax or legal advice.
+- Never invent a number. Every figure you cite must appear in the brief.
+- If the brief is thin, say the data is thin rather than padding it out.
+- Do not moralise about the spending. The user asked for observations, not
+  judgement about whether their choices were wise.
+
+Style: 120 words or fewer, plain sentences, at most three short bullets. Lead
+with the single most useful observation. Be concrete and specific."""
+
+
+def _fmt_pct(value: float) -> str:
+    return f"{value:+.0f}%"
+
+
+def build_brief(
+    expenses_this_month: list[Expense],
+    expenses_last_month: list[Expense],
+    recurring: list[Recurring],
+    budgets: list[BudgetStatus],
+    currency: str,
+    today: date,
+) -> str:
+    """Compose the factual brief the model is allowed to talk about."""
+    start, _ = month_bounds(today)
+    this_total = total_minor(expenses_this_month)
+    last_total = total_minor(expenses_last_month)
+
+    lines: list[str] = [
+        f"Date: {today.isoformat()}",
+        f"Currency: {currency}",
+        f"Month to date ({start.isoformat()} to {today.isoformat()}): "
+        f"{format_money(this_total, currency)} across {len(expenses_this_month)} transactions",
+        f"Same period last month: {format_money(last_total, currency)}",
+    ]
+
+    if last_total:
+        change = (this_total - last_total) / last_total * 100
+        lines.append(f"Change vs last month: {_fmt_pct(change)}")
+
+    projected = project_month_end(expenses_this_month, today)
+    lines.append(f"Projected month-end at current pace: {format_money(projected, currency)}")
+
+    if categories := by_category(expenses_this_month):
+        lines.append("Top categories this month:")
+        for name, amount in categories[:6]:
+            share = amount / this_total * 100 if this_total else 0
+            lines.append(
+                f"  - {category_label(name)}: {format_money(amount, currency)} ({share:.0f}%)"
+            )
+
+    if merchants := top_merchants(expenses_this_month, limit=5):
+        lines.append("Top merchants this month:")
+        for name, amount in merchants:
+            lines.append(f"  - {name}: {format_money(amount, currency)}")
+
+    if recurring:
+        lines.append("Recurring charges detected:")
+        for item in recurring[:8]:
+            lines.append(
+                f"  - {item.label}: {format_money(item.typical_minor, item.currency)}/month "
+                f"(seen in {item.months} months, last {item.last_seen.isoformat()})"
+            )
+
+    if budgets:
+        lines.append("Budgets this month:")
+        for status in budgets:
+            state = "OVER" if status.over else "within"
+            lines.append(
+                f"  - {category_label(status.category)}: "
+                f"{format_money(status.spent_minor, status.currency)} of "
+                f"{format_money(status.limit_minor, status.currency)} ({status.pct:.0f}%, {state})"
+            )
+
+    return "\n".join(lines)
+
+
+def deterministic_observations(
+    expenses_this_month: list[Expense],
+    expenses_last_month: list[Expense],
+    recurring: list[Recurring],
+    budgets: list[BudgetStatus],
+    currency: str,
+    today: date,
+) -> list[str]:
+    """Rule-based findings. Always available, no inference required."""
+    notes: list[str] = []
+    this_total = total_minor(expenses_this_month)
+    last_total = total_minor(expenses_last_month)
+
+    if not expenses_this_month:
+        return ["Nothing logged this month yet — send me an expense to get started."]
+
+    if last_total:
+        change = (this_total - last_total) / last_total * 100
+        if abs(change) >= 10:
+            direction = "up" if change > 0 else "down"
+            notes.append(
+                f"Spending is {direction} {abs(change):.0f}% on last month "
+                f"({format_money(this_total, currency)} vs {format_money(last_total, currency)})."
+            )
+
+    projected = project_month_end(expenses_this_month, today)
+    if projected > this_total:
+        notes.append(
+            f"At this pace you'll finish the month around {format_money(projected, currency)}."
+        )
+
+    categories = by_category(expenses_this_month)
+    if categories and this_total:
+        name, amount = categories[0]
+        share = amount / this_total * 100
+        if share >= 30:
+            notes.append(
+                f"{category_label(name)} is {share:.0f}% of this month's spend "
+                f"({format_money(amount, currency)})."
+            )
+
+    for status in budgets:
+        if status.over:
+            notes.append(
+                f"{category_label(status.category)} is over budget by "
+                f"{format_money(-status.remaining_minor, status.currency)}."
+            )
+        elif status.pct >= 80:
+            notes.append(
+                f"{category_label(status.category)} is at {status.pct:.0f}% of budget."
+            )
+
+    if recurring:
+        annual = sum(r.annualised_minor for r in recurring if r.currency == currency)
+        if annual:
+            notes.append(
+                f"{len(recurring)} recurring charges detected, "
+                f"about {format_money(annual, currency)} a year if all continue."
+            )
+
+    return notes or ["Nothing unusual stands out this month."]
+
+
+class Advisor:
+    def __init__(self, llm: LLMClient):
+        self.llm = llm
+
+    def advise(
+        self,
+        expenses_this_month: list[Expense],
+        expenses_last_month: list[Expense],
+        recurring: list[Recurring],
+        budgets: list[BudgetStatus],
+        default_currency: str,
+        today: date,
+        question: Optional[str] = None,
+    ) -> str:
+        currency = dominant_currency(expenses_this_month, default_currency)
+        facts = deterministic_observations(
+            expenses_this_month, expenses_last_month, recurring, budgets, currency, today
+        )
+
+        if not self.llm.enabled or not expenses_this_month:
+            return "\n".join(f"• {note}" for note in facts)
+
+        brief = build_brief(
+            expenses_this_month, expenses_last_month, recurring, budgets, currency, today
+        )
+        user_block = f"Brief:\n{brief}"
+        if question:
+            user_block += (
+                f"\n\nThe user asked: {question}\n"
+                "Answer only if the brief supports it; otherwise say what you'd "
+                "need them to log."
+            )
+
+        try:
+            response = self.llm.chat(
+                [
+                    {"role": "system", "content": _SYSTEM},
+                    {"role": "user", "content": user_block},
+                ],
+                temperature=0.3,
+                max_tokens=500,
+            )
+        except LLMUnavailable as exc:
+            log.info("Advice fell back to deterministic notes: %s", exc)
+            return "\n".join(f"• {note}" for note in facts)
+
+        response = (response or "").strip()
+        if not response:
+            return "\n".join(f"• {note}" for note in facts)
+        return response

finbot/analytics.py

@@ -0,0 +1,288 @@
+"""Aggregation over the ledger.
+
+All pure functions over lists of expenses -- no I/O, no model calls -- so the
+numbers are testable and always reproducible. Everything is computed
+per-currency: summing INR and USD into one figure would be meaningless, so a
+multi-currency ledger yields one summary per currency rather than a fictional
+total.
+"""
+
+from __future__ import annotations
+
+import re
+from calendar import monthrange
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import Iterable, Optional
+from zoneinfo import ZoneInfo
+
+from .models import Expense, Summary
+
+PERIODS = ("today", "yesterday", "week", "month", "last_month", "year", "30d", "all")
+
+
+def today_in(timezone: str) -> date:
+    """Current date in the user's timezone.
+
+    The container runs in UTC; for a user in Asia/Kolkata a spend logged at
+    2am local would otherwise land on the previous day.
+    """
+    try:
+        return datetime.now(ZoneInfo(timezone)).date()
+    except Exception:
+        return date.today()
+
+
+def month_bounds(day: date) -> tuple[date, date]:
+    return day.replace(day=1), day.replace(day=monthrange(day.year, day.month)[1])
+
+
+def previous_month_bounds(day: date) -> tuple[date, date]:
+    first = day.replace(day=1)
+    last_prev = first - timedelta(days=1)
+    return month_bounds(last_prev)
+
+
+def period_bounds(name: str, today: date) -> tuple[date, date, str]:
+    """Resolve a period keyword to (start, end, human label)."""
+    name = (name or "month").lower().strip()
+
+    if name == "today":
+        return today, today, "Today"
+    if name == "yesterday":
+        day = today - timedelta(days=1)
+        return day, day, "Yesterday"
+    if name == "week":
+        start = today - timedelta(days=today.weekday())
+        return start, today, "This week"
+    if name == "last_month":
+        start, end = previous_month_bounds(today)
+        return start, end, start.strftime("%B %Y")
+    if name == "year":
+        return today.replace(month=1, day=1), today, str(today.year)
+    if name == "30d":
+        return today - timedelta(days=29), today, "Last 30 days"
+    if name == "all":
+        return date(1970, 1, 1), today, "All time"
+
+    start, _ = month_bounds(today)
+    return start, today, today.strftime("%B %Y")
+
+
+def split_by_currency(expenses: Iterable[Expense]) -> dict[str, list[Expense]]:
+    buckets: dict[str, list[Expense]] = defaultdict(list)
+    for expense in expenses:
+        buckets[expense.currency.upper()].append(expense)
+    return dict(buckets)
+
+
+def dominant_currency(expenses: Iterable[Expense], fallback: str) -> str:
+    buckets = split_by_currency(expenses)
+    if not buckets:
+        return fallback.upper()
+    return max(buckets.items(), key=lambda kv: (len(kv[1]), sum(e.amount_minor for e in kv[1])))[0]
+
+
+def total_minor(expenses: Iterable[Expense]) -> int:
+    return sum(e.amount_minor for e in expenses)
+
+
+def by_category(expenses: Iterable[Expense]) -> list[tuple[str, int]]:
+    totals: dict[str, int] = defaultdict(int)
+    for expense in expenses:
+        totals[expense.category] += expense.amount_minor
+    return sorted(totals.items(), key=lambda kv: kv[1], reverse=True)
+
+
+def summarise(
+    expenses: list[Expense],
+    currency: str,
+    label: str,
+    start: date,
+    end: date,
+    previous: Optional[list[Expense]] = None,
+) -> Summary:
+    scoped = [e for e in expenses if e.currency.upper() == currency.upper()]
+    previous_total = None
+    if previous is not None:
+        previous_total = total_minor(
+            [e for e in previous if e.currency.upper() == currency.upper()]
+        )
+
+    return Summary(
+        label=label,
+        start=start,
+        end=end,
+        currency=currency.upper(),
+        total_minor=total_minor(scoped),
+        count=len(scoped),
+        by_category=by_category(scoped),
+        previous_total_minor=previous_total,
+    )
+
+
+# ----------------------------------------------------------------- recurring
+
+
+@dataclass
+class Recurring:
+    label: str
+    category: str
+    currency: str
+    typical_minor: int
+    occurrences: int
+    months: int
+    last_seen: date
+
+    @property
+    def annualised_minor(self) -> int:
+        return self.typical_minor * 12
+
+
+_NOISE_RE = re.compile(r"\b(?:\d{4,}|ref|txn|upi|no|id)\b[-\s]*\w*", re.I)
+_TLD_RE = re.compile(r"\.(?:com|in|co|net|org|io|app|me|shop|store)\b", re.I)
+
+#: Structural filler that appears in card narrations regardless of merchant.
+#: Deliberately not locale-specific -- no city or country names, which would
+#: only work for whichever market we happened to hardcode.
+_NOISE_TOKENS = frozenset(
+    {
+        "com", "www", "net", "org", "ltd", "pvt", "inc", "llc", "limited",
+        "the", "pos", "pay", "payment", "purchase", "online", "debit",
+        "card", "transaction", "auto", "recurring",
+    }
+)
+
+
+def _merchant_key(expense: Expense) -> str:
+    """Normalise a merchant so 'NETFLIX.COM 447192' and 'Netflix' collapse.
+
+    Purely lexical, so it will not unify names that share no words
+    ("AMZN Mktp" vs "Amazon"). Keeping only the first few significant tokens
+    absorbs the trailing reference numbers and city suffixes banks append.
+    """
+    raw = (expense.merchant or expense.description or "").lower()
+    raw = _TLD_RE.sub(" ", raw)
+    raw = _NOISE_RE.sub(" ", raw)
+    raw = re.sub(r"[^a-z ]+", " ", raw)
+    tokens = [
+        t for t in raw.split() if len(t) > 2 and t not in _NOISE_TOKENS
+    ]
+    return " ".join(tokens[:3])
+
+
+def detect_recurring(
+    expenses: Iterable[Expense],
+    min_months: int = 3,
+    tolerance: float = 0.20,
+) -> list[Recurring]:
+    """Find charges that repeat monthly at a similar amount.
+
+    Requires hits in at least ``min_months`` distinct calendar months so that
+    three coffees in one week don't register as a subscription.
+    """
+    groups: dict[tuple[str, str], list[Expense]] = defaultdict(list)
+    for expense in expenses:
+        key = _merchant_key(expense)
+        if not key:
+            continue
+        groups[(key, expense.currency.upper())].append(expense)
+
+    found: list[Recurring] = []
+    for (key, currency), items in groups.items():
+        months = {(e.occurred_on.year, e.occurred_on.month) for e in items}
+        if len(months) < min_months:
+            continue
+
+        amounts = sorted(e.amount_minor for e in items)
+        median = amounts[len(amounts) // 2]
+        if median <= 0:
+            continue
+
+        # Consistent amount is what separates a subscription from ordinary
+        # repeat spending at the same shop.
+        consistent = [a for a in amounts if abs(a - median) <= median * tolerance]
+        if len(consistent) < len(amounts) * 0.6:
+            continue
+
+        best = max(items, key=lambda e: e.occurred_on)
+        found.append(
+            Recurring(
+                label=(best.merchant or best.description or key).strip()[:60],
+                category=best.category,
+                currency=currency,
+                typical_minor=median,
+                occurrences=len(items),
+                months=len(months),
+                last_seen=best.occurred_on,
+            )
+        )
+
+    return sorted(found, key=lambda r: r.typical_minor, reverse=True)
+
+
+# ------------------------------------------------------------------- budgets
+
+
+@dataclass
+class BudgetStatus:
+    category: str
+    currency: str
+    limit_minor: int
+    spent_minor: int
+
+    @property
+    def pct(self) -> float:
+        if self.limit_minor <= 0:
+            return 0.0
+        return self.spent_minor / self.limit_minor * 100.0
+
+    @property
+    def remaining_minor(self) -> int:
+        return self.limit_minor - self.spent_minor
+
+    @property
+    def over(self) -> bool:
+        return self.spent_minor > self.limit_minor
+
+
+def budget_status(
+    budgets: Iterable, month_expenses: Iterable[Expense]
+) -> list[BudgetStatus]:
+    spent: dict[tuple[str, str], int] = defaultdict(int)
+    for expense in month_expenses:
+        spent[(expense.category, expense.currency.upper())] += expense.amount_minor
+
+    statuses = [
+        BudgetStatus(
+            category=budget.category,
+            currency=budget.currency.upper(),
+            limit_minor=budget.amount_minor,
+            spent_minor=spent.get((budget.category, budget.currency.upper()), 0),
+        )
+        for budget in budgets
+    ]
+    return sorted(statuses, key=lambda s: s.pct, reverse=True)
+
+
+def daily_burn(expenses: list[Expense], start: date, end: date) -> float:
+    """Average spend per elapsed day, in minor units."""
+    days = max(1, (end - start).days + 1)
+    return total_minor(expenses) / days
+
+
+def project_month_end(expenses: list[Expense], today: date) -> int:
+    """Straight-line projection of this month's total from spend so far."""
+    start, end = month_bounds(today)
+    elapsed = max(1, (today - start).days + 1)
+    days_in_month = (end - start).days + 1
+    return int(total_minor(expenses) / elapsed * days_in_month)
+
+
+def top_merchants(expenses: Iterable[Expense], limit: int = 5) -> list[tuple[str, int]]:
+    totals: dict[str, int] = defaultdict(int)
+    for expense in expenses:
+        label = (expense.merchant or expense.description or "unlabelled").strip()[:40]
+        totals[label] += expense.amount_minor
+    return sorted(totals.items(), key=lambda kv: kv[1], reverse=True)[:limit]

finbot/categories.py

@@ -0,0 +1,243 @@
+"""Category taxonomy and deterministic keyword matching.
+
+Rules run before any model call. Most everyday spend ("uber", "netflix",
+"petrol") is unambiguous, and a lookup is free, instant and reproducible where
+a model call is none of those. The LLM only sees what the rules could not
+place.
+"""
+
+from __future__ import annotations
+
+import re
+
+#: Canonical categories. Keep this list short -- a taxonomy nobody can hold in
+#: their head produces inconsistent categorisation, which makes trends lie.
+CATEGORIES: tuple[str, ...] = (
+    "groceries",
+    "food_dining",
+    "transport",
+    "fuel",
+    "shopping",
+    "utilities",
+    "rent",
+    "health",
+    "entertainment",
+    "subscriptions",
+    "education",
+    "travel",
+    "fees_charges",
+    "transfers",
+    "cash",
+    "income",
+    "other",
+)
+
+#: Human labels for display.
+LABELS: dict[str, str] = {
+    "groceries": "Groceries",
+    "food_dining": "Food & Dining",
+    "transport": "Transport",
+    "fuel": "Fuel",
+    "shopping": "Shopping",
+    "utilities": "Utilities",
+    "rent": "Rent & Housing",
+    "health": "Health",
+    "entertainment": "Entertainment",
+    "subscriptions": "Subscriptions",
+    "education": "Education",
+    "travel": "Travel",
+    "fees_charges": "Fees & Charges",
+    "transfers": "Transfers",
+    "cash": "Cash",
+    "income": "Income",
+    "other": "Other",
+}
+
+# Ordered most-specific first: "fuel" must win over "transport" for a petrol
+# pump, and "subscriptions" over "entertainment" for Netflix.
+_RULES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (
+        "subscriptions",
+        (
+            "netflix", "spotify", "prime video", "hotstar", "disney+", "youtube premium",
+            "icloud", "google one", "dropbox", "notion", "figma", "adobe", "github",
+            "openai", "chatgpt", "claude", "anthropic", "midjourney", "subscription",
+            "patreon", "substack", "audible", "kindle unlimited",
+        ),
+    ),
+    (
+        "fuel",
+        (
+            "petrol", "diesel", "fuel", "gas station", "shell", "bharat petroleum",
+            "hp petrol", "indian oil", "iocl", "bpcl", "hpcl", "chevron", "exxon",
+        ),
+    ),
+    (
+        "transport",
+        (
+            "uber", "ola", "lyft", "rapido", "taxi", "cab", "metro", "bus", "train",
+            "irctc", "railway", "toll", "fastag", "parking", "auto rickshaw", "grab",
+            "bolt", "blablacar",
+        ),
+    ),
+    (
+        "groceries",
+        (
+            "grocery", "groceries", "supermarket", "bigbasket", "blinkit", "zepto",
+            "dmart", "reliance fresh", "more retail", "spencer", "tesco", "aldi",
+            "lidl", "walmart", "costco", "sainsbury", "kroger", "instacart",
+            "vegetables", "fruits", "milk", "kirana",
+        ),
+    ),
+    (
+        "food_dining",
+        (
+            "swiggy", "zomato", "doordash", "ubereats", "deliveroo", "just eat",
+            "restaurant", "cafe", "coffee", "starbucks", "mcdonald", "kfc", "domino",
+            "pizza", "burger", "dinner", "lunch", "breakfast", "snack", "chai",
+            "bakery", "biryani", "food", "dining", "brunch", "takeaway",
+        ),
+    ),
+    (
+        "utilities",
+        (
+            "electricity", "water bill", "gas bill", "broadband", "internet", "wifi",
+            "airtel", "jio", "vodafone", "vi postpaid", "bsnl", "act fibernet",
+            "recharge", "mobile bill", "phone bill", "dth", "tata power", "adani",
+            "utility", "council tax",
+        ),
+    ),
+    (
+        "rent",
+        ("rent", "landlord", "lease", "maintenance charge", "society charge", "mortgage"),
+    ),
+    (
+        "health",
+        (
+            "pharmacy", "chemist", "apollo", "medplus", "1mg", "pharmeasy", "hospital",
+            "clinic", "doctor", "dentist", "medicine", "medical", "diagnostic", "lab test",
+            "insurance premium", "gym", "fitness", "cult.fit", "physio", "optician",
+        ),
+    ),
+    (
+        "entertainment",
+        (
+            "movie", "cinema", "pvr", "inox", "bookmyshow", "concert", "theatre",
+            "game", "steam", "playstation", "xbox", "nintendo", "bar", "pub", "club",
+        ),
+    ),
+    (
+        "shopping",
+        (
+            "amazon", "flipkart", "myntra", "ajio", "meesho", "nykaa", "ikea", "zara",
+            "h&m", "uniqlo", "decathlon", "croma", "reliance digital", "apple store",
+            "ebay", "etsy", "aliexpress", "shein", "clothes", "shoes", "electronics",
+        ),
+    ),
+    (
+        "travel",
+        (
+            "flight", "airline", "indigo", "vistara", "air india", "spicejet", "emirates",
+            "makemytrip", "goibibo", "cleartrip", "booking.com", "airbnb", "oyo", "hotel",
+            "hostel", "visa fee", "passport", "travel",
+        ),
+    ),
+    (
+        "education",
+        (
+            "course", "udemy", "coursera", "tuition", "school fee", "college", "university",
+            "textbook", "exam fee", "byju", "unacademy", "edx", "workshop",
+        ),
+    ),
+    (
+        "fees_charges",
+        (
+            "bank charge", "service charge", "convenience fee", "processing fee",
+            "late fee", "penalty", "interest charge", "gst", "atm charge", "annual fee",
+            "overdraft", "forex markup",
+        ),
+    ),
+    (
+        "transfers",
+        (
+            "transfer", "neft", "imps", "rtgs", "upi to", "sent to", "paytm wallet",
+            "self transfer", "credit card payment", "loan emi", "emi",
+        ),
+    ),
+    ("cash", ("atm", "cash withdrawal", "withdrawal", "cash")),
+    (
+        "income",
+        ("salary", "payroll", "credited", "refund", "cashback", "interest earned", "dividend"),
+    ),
+)
+
+
+def _normalise(text: str) -> str:
+    return re.sub(r"\s+", " ", text.lower()).strip()
+
+
+def categorise(text: str, merchant: str = "") -> tuple[str, float]:
+    """Map free text to a category deterministically.
+
+    Returns (category, confidence). Confidence is 1.0 for a keyword hit and 0.0
+    for the ``other`` fallback, which is the signal the caller uses to decide
+    whether to spend a model call on it.
+    """
+    haystack = _normalise(f"{merchant} {text}")
+    if not haystack:
+        return "other", 0.0
+
+    for category, keywords in _RULES:
+        for keyword in keywords:
+            # Word-boundary match so "gas" doesn't fire on "gasket" and
+            # "cash" doesn't fire on "cashew".
+            if re.search(rf"(?<![a-z0-9]){re.escape(keyword)}(?![a-z0-9])", haystack):
+                return category, 1.0
+    return "other", 0.0
+
+
+def is_valid(category: str) -> bool:
+    return category in CATEGORIES
+
+
+def coerce(category: str) -> str:
+    """Force an arbitrary string onto the taxonomy.
+
+    Models are asked for a category from the list but do not always comply;
+    this keeps a stray label out of the ledger where it would fragment totals.
+    """
+    if not category:
+        return "other"
+    candidate = _normalise(category).replace(" ", "_").replace("&", "").strip("_")
+    if candidate in CATEGORIES:
+        return candidate
+    aliases = {
+        "food": "food_dining",
+        "dining": "food_dining",
+        "restaurants": "food_dining",
+        "eating_out": "food_dining",
+        "grocery": "groceries",
+        "commute": "transport",
+        "travel_transport": "transport",
+        "petrol": "fuel",
+        "bills": "utilities",
+        "housing": "rent",
+        "medical": "health",
+        "healthcare": "health",
+        "fitness": "health",
+        "leisure": "entertainment",
+        "subscription": "subscriptions",
+        "fees": "fees_charges",
+        "charges": "fees_charges",
+        "transfer": "transfers",
+        "salary": "income",
+        "misc": "other",
+        "miscellaneous": "other",
+        "uncategorized": "other",
+        "uncategorised": "other",
+    }
+    return aliases.get(candidate, "other")
+
+
+def label(category: str) -> str:
+    return LABELS.get(category, category.replace("_", " ").title())

finbot/config.py

@@ -0,0 +1,100 @@
+"""Runtime configuration, read once from the environment.
+
+On Hugging Face these come from Space Settings > Secrets; locally from a .env
+file. Everything has a default that keeps the app bootable, so a missing
+optional secret degrades a feature rather than crashing the container -- a
+Space that won't boot is much harder to debug than one that boots and says
+what it is missing.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", extra="ignore"
+    )
+
+    # --- Telegram ---
+    telegram_bot_token: str = ""
+    telegram_webhook_secret: str = ""
+    allowed_telegram_user_ids: str = ""
+    #: Let anyone message the bot. Each Telegram user still gets their own
+    #: isolated ledger -- open access makes this multi-tenant, it does not
+    #: expose one user's spending to another. It does mean strangers spend the
+    #: Space owner's inference credits, which is what uploads_per_user_per_day
+    #: is for. Must be set explicitly, so a forgotten allowlist stays closed
+    #: rather than silently opening to the world.
+    open_access: bool = False
+    #: Model-backed uploads (receipts, statements) allowed per user per day.
+    #: 0 or less disables the cap.
+    uploads_per_user_per_day: int = 20
+
+    # --- Inference ---
+    hf_token: str = ""
+    llm_base_url: str = "https://router.huggingface.co/v1"
+    llm_model: str = "Qwen/Qwen3-235B-A22B-Instruct-2507"
+    llm_vision_model: str = "Qwen/Qwen2.5-VL-72B-Instruct"
+
+    # --- Storage ---
+    hf_dataset_repo: str = ""
+    sync_every_minutes: int = 5
+    data_dir: str = "/home/user/data"
+
+    # --- Behaviour ---
+    default_currency: str = "INR"
+    timezone: str = "Asia/Kolkata"
+
+    @property
+    def allowed_user_ids(self) -> frozenset[int]:
+        """Telegram user IDs permitted to talk to the bot.
+
+        Empty means nobody. This is deliberate: an open finance bot would let
+        any stranger who finds the username write to your ledger and read your
+        spending back out.
+        """
+        ids: set[int] = set()
+        for chunk in self.allowed_telegram_user_ids.split(","):
+            chunk = chunk.strip()
+            if not chunk:
+                continue
+            try:
+                ids.add(int(chunk))
+            except ValueError:
+                continue
+        return frozenset(ids)
+
+    def is_authorised(self, user_id: int) -> bool:
+        return self.open_access or user_id in self.allowed_user_ids
+
+    @property
+    def llm_enabled(self) -> bool:
+        return bool(self.hf_token)
+
+    @property
+    def sync_enabled(self) -> bool:
+        return bool(self.hf_dataset_repo and self.hf_token)
+
+    def missing_required(self) -> list[str]:
+        """Config gaps that stop the bot doing its job, worst first."""
+        gaps: list[str] = []
+        if not self.telegram_bot_token:
+            gaps.append("TELEGRAM_BOT_TOKEN (bot cannot send or receive)")
+        if not self.telegram_webhook_secret:
+            gaps.append("TELEGRAM_WEBHOOK_SECRET (webhook cannot be verified)")
+        if not self.open_access and not self.allowed_user_ids:
+            gaps.append("ALLOWED_TELEGRAM_USER_IDS (nobody is authorised yet)")
+        if not self.hf_dataset_repo:
+            gaps.append("HF_DATASET_REPO (data will be lost when the Space restarts)")
+        if not self.hf_token:
+            gaps.append("HF_TOKEN (receipts, statements and advice are disabled)")
+        return gaps
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

finbot/extract.py

@@ -0,0 +1,203 @@
+"""Turn an uploaded file into text and rows.
+
+Deliberately format-agnostic and bank-agnostic: this module only gets the
+content *out* of the file. Deciding which column is a date and which is an
+amount is :mod:`finbot.ingest`'s job, and is done by the model so that any
+bank's export works without a hand-written layout per institution.
+
+Nothing here calls the network, so all of it is unit-testable offline.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import logging
+from dataclasses import dataclass, field
+
+log = logging.getLogger(__name__)
+
+#: Guard rails. A personal statement is a few hundred rows; anything far past
+#: that is either a mistake or would blow the model's context and the user's
+#: token budget, so it is truncated with a visible note rather than silently.
+MAX_ROWS = 1500
+MAX_TEXT_CHARS = 120_000
+MAX_PDF_PAGES = 40
+
+
+@dataclass
+class ExtractedDocument:
+    kind: str
+    text: str = ""
+    rows: list[list[str]] = field(default_factory=list)
+    pages: int = 0
+    truncated: bool = False
+    note: str = ""
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.text.strip() and not self.rows
+
+
+def _decode(data: bytes) -> str:
+    for encoding in ("utf-8-sig", "utf-8", "cp1252", "latin-1"):
+        try:
+            return data.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return data.decode("utf-8", errors="replace")
+
+
+def _clean_row(row: list) -> list[str]:
+    return [("" if c is None else str(c)).strip() for c in row]
+
+
+def _is_blank(row: list[str]) -> bool:
+    return not any(cell for cell in row)
+
+
+def extract_csv(data: bytes) -> ExtractedDocument:
+    text = _decode(data)
+    sample = text[:8192]
+
+    try:
+        dialect = csv.Sniffer().sniff(sample, delimiters=",;\t|")
+    except csv.Error:
+        # Sniffing fails on single-column or irregular exports; comma is the
+        # safe default and the model tolerates a wrong split better than a crash.
+        dialect = csv.excel
+
+    rows: list[list[str]] = []
+    truncated = False
+    for row in csv.reader(io.StringIO(text), dialect):
+        cleaned = _clean_row(row)
+        if _is_blank(cleaned):
+            continue
+        rows.append(cleaned)
+        if len(rows) >= MAX_ROWS:
+            truncated = True
+            break
+
+    return ExtractedDocument(kind="csv", rows=rows, truncated=truncated)
+
+
+def extract_xlsx(data: bytes) -> ExtractedDocument:
+    from openpyxl import load_workbook
+
+    workbook = load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+    rows: list[list[str]] = []
+    truncated = False
+
+    try:
+        for sheet in workbook.worksheets:
+            if truncated:
+                break
+            if len(workbook.worksheets) > 1:
+                rows.append([f"# sheet: {sheet.title}"])
+            for row in sheet.iter_rows(values_only=True):
+                cleaned = _clean_row(list(row))
+                if _is_blank(cleaned):
+                    continue
+                rows.append(cleaned)
+                if len(rows) >= MAX_ROWS:
+                    truncated = True
+                    break
+    finally:
+        workbook.close()
+
+    return ExtractedDocument(kind="xlsx", rows=rows, truncated=truncated)
+
+
+def extract_pdf(data: bytes) -> ExtractedDocument:
+    """Pull tables (preferred) and text out of a PDF statement.
+
+    Scanned statements contain no text layer. That is detected and reported
+    rather than silently returning nothing, because "0 transactions found" and
+    "this file is a photograph of a statement" need very different user advice.
+    """
+    import pdfplumber
+
+    rows: list[list[str]] = []
+    text_parts: list[str] = []
+    truncated = False
+    page_count = 0
+
+    with pdfplumber.open(io.BytesIO(data)) as pdf:
+        page_count = len(pdf.pages)
+        for index, page in enumerate(pdf.pages):
+            if index >= MAX_PDF_PAGES:
+                truncated = True
+                break
+
+            try:
+                for table in page.extract_tables() or []:
+                    for row in table:
+                        cleaned = _clean_row(list(row))
+                        if _is_blank(cleaned):
+                            continue
+                        rows.append(cleaned)
+                        if len(rows) >= MAX_ROWS:
+                            truncated = True
+                            break
+                    if truncated:
+                        break
+            except Exception as exc:
+                log.warning("Table extraction failed on page %d: %s", index + 1, exc)
+
+            try:
+                if page_text := page.extract_text():
+                    text_parts.append(page_text)
+            except Exception as exc:
+                log.warning("Text extraction failed on page %d: %s", index + 1, exc)
+
+            if truncated:
+                break
+
+    text = "\n".join(text_parts)[:MAX_TEXT_CHARS]
+    doc = ExtractedDocument(
+        kind="pdf", text=text, rows=rows, pages=page_count, truncated=truncated
+    )
+
+    if doc.is_empty:
+        doc.note = (
+            "This PDF has no selectable text, so it is almost certainly a scan "
+            "or photo of a statement. Send it as a photo instead and I'll read "
+            "it with the vision model, or export a CSV/XLSX from your bank."
+        )
+    return doc
+
+
+def extract(data: bytes, filename: str = "", mime_type: str = "") -> ExtractedDocument:
+    """Dispatch on filename extension, falling back to MIME type."""
+    name = (filename or "").lower()
+    mime = (mime_type or "").lower()
+
+    if name.endswith(".csv") or name.endswith(".tsv") or "csv" in mime:
+        return extract_csv(data)
+    if name.endswith((".xlsx", ".xlsm", ".xltx")) or "spreadsheet" in mime or "excel" in mime:
+        return extract_xlsx(data)
+    if name.endswith(".pdf") or "pdf" in mime:
+        return extract_pdf(data)
+    if name.endswith((".txt", ".md")) or mime.startswith("text/"):
+        return ExtractedDocument(kind="text", text=_decode(data)[:MAX_TEXT_CHARS])
+
+    # .xls (old binary format) is not readable by openpyxl -- say so precisely.
+    if name.endswith(".xls"):
+        return ExtractedDocument(
+            kind="unsupported",
+            note=(
+                "Old .xls files aren't supported. Open it and re-save as .xlsx "
+                "or export CSV, then send it again."
+            ),
+        )
+
+    return ExtractedDocument(
+        kind="unsupported",
+        note=f"I can't read {filename or 'that file'}. Send a CSV, XLSX, PDF or a photo.",
+    )
+
+
+def rows_to_text(rows: list[list[str]], limit: int = MAX_ROWS) -> str:
+    """Render rows as pipe-delimited lines for a model prompt."""
+    lines = [" | ".join(cell for cell in row) for row in rows[:limit]]
+    return "\n".join(lines)[:MAX_TEXT_CHARS]

finbot/features/__init__.py

@@ -0,0 +1,47 @@
+"""Bundled features.
+
+To add your own: subclass :class:`~finbot.features.base.Feature`, then include
+it in the list passed to the registry (see ``finbot.app.build_services``).
+Nothing else in the codebase needs to change.
+"""
+
+from __future__ import annotations
+
+from .base import (
+    Attachment,
+    BotContext,
+    CommandSpec,
+    Feature,
+    Reply,
+    Services,
+    SimpleFeature,
+)
+from .budgets import BudgetsFeature
+from .coaching import CoachingFeature
+from .core import CoreFeature
+from .expenses import ExpensesFeature
+
+__all__ = [
+    "Attachment",
+    "BotContext",
+    "BudgetsFeature",
+    "CoachingFeature",
+    "CommandSpec",
+    "CoreFeature",
+    "ExpensesFeature",
+    "Feature",
+    "Reply",
+    "Services",
+    "SimpleFeature",
+    "default_features",
+]
+
+
+def default_features() -> list[Feature]:
+    """The stock feature set, in registration order."""
+    return [
+        ExpensesFeature(),
+        BudgetsFeature(),
+        CoachingFeature(),
+        CoreFeature(),
+    ]

finbot/features/base.py

@@ -0,0 +1,150 @@
+"""The extension point.
+
+A *feature* is a self-contained bundle of bot behaviour: some commands, and
+optionally an interest in plain messages or uploaded files. Adding one means
+subclassing :class:`Feature` and registering it -- no edits to the router, the
+webhook, or any other feature.
+
+Expense tracking is simply the first feature registered. Anything else a bot
+needs to do (reminders, notes, standups, ops alerts) drops in beside it on
+equal terms.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import date
+from typing import TYPE_CHECKING, Optional, Sequence
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..advice import Advisor
+    from ..config import Settings
+    from ..ingest import Ingestor
+    from ..llm import LLMClient
+    from ..models import PendingImport
+    from ..store import Store
+    from ..registry import FeatureRegistry
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """One slash command, and enough metadata to build /help and setMyCommands."""
+
+    name: str
+    help: str
+    args: str = ""
+    aliases: tuple[str, ...] = ()
+    #: Hidden commands still work but stay out of the menu (e.g. /confirm).
+    hidden: bool = False
+
+    @property
+    def usage(self) -> str:
+        return f"/{self.name} {self.args}".strip()
+
+
+@dataclass
+class Attachment:
+    """A file the user sent, already downloaded."""
+
+    data: bytes
+    filename: str = ""
+    mime_type: str = ""
+    kind: str = "document"  # "photo" | "document"
+    caption: str = ""
+
+    @property
+    def is_image(self) -> bool:
+        return self.kind == "photo" or self.mime_type.startswith("image/")
+
+
+@dataclass
+class Services:
+    """Shared dependencies handed to every feature."""
+
+    settings: "Settings"
+    store: "Store"
+    llm: "LLMClient"
+    ingestor: "Ingestor"
+    advisor: "Advisor"
+    registry: "FeatureRegistry"
+    #: Imports awaiting /confirm, keyed by user id. Held in memory only -- a
+    #: Space restart drops them, which is acceptable because the user simply
+    #: re-sends the file, and it keeps unconfirmed model output out of storage.
+    pending: dict[int, "PendingImport"] = field(default_factory=dict)
+
+
+@dataclass
+class BotContext:
+    """Everything a feature needs to answer one update."""
+
+    user_id: int
+    chat_id: int
+    services: Services
+    today: date
+    text: str = ""
+    command: str = ""
+    args: str = ""
+    attachment: Optional[Attachment] = None
+
+    @property
+    def settings(self) -> "Settings":
+        return self.services.settings
+
+    @property
+    def store(self) -> "Store":
+        return self.services.store
+
+
+@dataclass
+class Reply:
+    """What to send back. HTML parse mode -- see finbot.render for why."""
+
+    text: str
+    parse_mode: Optional[str] = "HTML"
+    disable_preview: bool = True
+    #: Optional file to send alongside the text, as (filename, bytes).
+    document: Optional[tuple[str, bytes]] = None
+
+
+class Feature(ABC):
+    #: Stable identifier, used in logs and /help grouping.
+    name: str = "feature"
+    #: One line shown in /help.
+    description: str = ""
+
+    def commands(self) -> Sequence[CommandSpec]:
+        """Slash commands this feature owns."""
+        return ()
+
+    def handle_command(self, ctx: BotContext) -> Optional[Reply]:
+        """Handle one of this feature's commands. Return None to decline."""
+        return None
+
+    def handle_message(self, ctx: BotContext) -> Optional[Reply]:
+        """Handle plain (non-command) text. Return None to let others try."""
+        return None
+
+    def handle_attachment(self, ctx: BotContext) -> Optional[Reply]:
+        """Handle an uploaded file. Return None to let others try."""
+        return None
+
+    #: Lower runs first when several features want the same plain message.
+    priority: int = 100
+
+
+class SimpleFeature(Feature):
+    """Convenience base that routes commands to ``cmd_<name>`` methods."""
+
+    @abstractmethod
+    def commands(self) -> Sequence[CommandSpec]:  # pragma: no cover - abstract
+        ...
+
+    def handle_command(self, ctx: BotContext) -> Optional[Reply]:
+        for spec in self.commands():
+            if ctx.command == spec.name or ctx.command in spec.aliases:
+                handler = getattr(self, f"cmd_{spec.name}", None)
+                if handler is None:
+                    return None
+                return handler(ctx)
+        return None

finbot/features/budgets.py

@@ -0,0 +1,81 @@
+"""Monthly budgets per category."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .. import render
+from ..analytics import budget_status, month_bounds
+from ..categories import CATEGORIES, coerce
+from ..categories import label as category_label
+from ..models import Budget
+from ..money import parse_amount
+from .base import BotContext, CommandSpec, Reply, SimpleFeature
+
+
+class BudgetsFeature(SimpleFeature):
+    name = "budgets"
+    description = "🎯 Budgets"
+    priority = 20
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (
+            CommandSpec("budget", "Set a monthly budget", "<category> <amount>"),
+            CommandSpec("budgets", "How you're tracking against budgets"),
+            CommandSpec("unbudget", "Remove a budget", "<category>"),
+            CommandSpec("categories", "List the category names"),
+        )
+
+    def cmd_budget(self, ctx: BotContext) -> Reply:
+        args = ctx.args.strip()
+        if not args:
+            return Reply(
+                "Set a monthly cap, e.g. <code>/budget food_dining 8000</code>.\n"
+                "/categories lists the names."
+            )
+
+        parts = args.split()
+        category = coerce(parts[0])
+        if category == "other" and parts[0].lower() not in ("other",):
+            return Reply(
+                f"I don't recognise the category <code>{render.escape(parts[0])}</code>.\n"
+                "/categories lists what I understand."
+            )
+
+        amount = parse_amount(" ".join(parts[1:]), ctx.settings.default_currency)
+        if amount is None or amount.minor <= 0:
+            return Reply("I need an amount, e.g. <code>/budget groceries 12000</code>.")
+
+        budget = Budget(
+            user_id=ctx.user_id,
+            category=category,
+            amount_minor=amount.minor,
+            currency=amount.currency or ctx.settings.default_currency,
+        )
+        ctx.store.set_budget(budget)
+        return Reply(
+            f"🎯 Budget set: {render.escape(category_label(category))} "
+            f"{render.money(budget.amount_minor, budget.currency)}/month."
+        )
+
+    def cmd_budgets(self, ctx: BotContext) -> Reply:
+        budgets = ctx.store.get_budgets(ctx.user_id)
+        start, _ = month_bounds(ctx.today)
+        expenses = ctx.store.list_expenses(ctx.user_id, start, ctx.today)
+        return Reply(render.budget_list(budget_status(budgets, expenses)))
+
+    def cmd_unbudget(self, ctx: BotContext) -> Reply:
+        category = coerce(ctx.args.strip())
+        if ctx.store.delete_budget(ctx.user_id, category):
+            return Reply(f"Removed the {render.escape(category_label(category))} budget.")
+        return Reply("No budget set for that category.")
+
+    def cmd_categories(self, ctx: BotContext) -> Reply:
+        lines = ["<b>Categories</b>"]
+        lines.extend(
+            f"<code>{name}</code> — {render.escape(category_label(name))}"
+            for name in CATEGORIES
+        )
+        lines.append("")
+        lines.append("Tag an entry to override: <code>250 lunch #transport</code>")
+        return Reply("\n".join(lines))

finbot/features/coaching.py

@@ -0,0 +1,51 @@
+"""Budget coaching over the user's own logged spending."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .. import render
+from ..advice import DISCLAIMER
+from ..analytics import (
+    budget_status,
+    detect_recurring,
+    month_bounds,
+    previous_month_bounds,
+)
+from .base import BotContext, CommandSpec, Reply, SimpleFeature
+
+
+class CoachingFeature(SimpleFeature):
+    name = "coaching"
+    description = "🧭 Coaching"
+    priority = 30
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (
+            CommandSpec("advice", "Observations on your spending", "[question]"),
+        )
+
+    def cmd_advice(self, ctx: BotContext) -> Reply:
+        start, _ = month_bounds(ctx.today)
+        this_month = ctx.store.list_expenses(ctx.user_id, start, ctx.today)
+
+        prev_start, prev_end = previous_month_bounds(ctx.today)
+        last_month = ctx.store.list_expenses(ctx.user_id, prev_start, prev_end)
+
+        all_expenses = ctx.store.list_expenses(ctx.user_id)
+        recurring = detect_recurring(all_expenses)
+        budgets = budget_status(ctx.store.get_budgets(ctx.user_id), this_month)
+
+        text = ctx.services.advisor.advise(
+            expenses_this_month=this_month,
+            expenses_last_month=last_month,
+            recurring=recurring,
+            budgets=budgets,
+            default_currency=ctx.settings.default_currency,
+            today=ctx.today,
+            question=ctx.args.strip() or None,
+        )
+
+        body = render.escape(text)
+        footer = render.escape(DISCLAIMER.replace("_", ""))
+        return Reply(f"{body}\n\n<i>{footer}</i>")

finbot/features/core.py

@@ -0,0 +1,111 @@
+"""Onboarding, help and diagnostics. Registered last so /help sees everything."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .. import render
+from ..analytics import month_bounds
+from .base import BotContext, CommandSpec, Reply, SimpleFeature
+
+_WELCOME = """<b>Hello 👋</b>
+
+Just tell me what you spent and I'll keep track.
+
+<b>Log it</b>
+<code>250 coffee</code>
+<code>₹1,240 groceries at bigbasket</code>
+<code>45.50 lunch yesterday</code>
+<code>320 uber #transport</code>
+
+<b>Send me things</b>
+📷 a receipt photo — I'll read the total
+📄 a bank statement (PDF, CSV, XLSX) — I'll pull out the transactions and ask before saving
+
+<b>See it back</b>
+/today · /week · /month · /recurring · /advice
+
+/help for everything."""
+
+
+class CoreFeature(SimpleFeature):
+    name = "core"
+    description = "⚙️ General"
+    priority = 90
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (
+            CommandSpec("start", "What this bot does"),
+            CommandSpec("help", "All commands"),
+            CommandSpec("status", "Configuration and storage health"),
+            CommandSpec("whoami", "Your Telegram user ID", hidden=True),
+        )
+
+    def cmd_start(self, ctx: BotContext) -> Reply:
+        return Reply(_WELCOME)
+
+    def cmd_help(self, ctx: BotContext) -> Reply:
+        body = ctx.services.registry.help_text()
+        tail = (
+            "\n\n<i>Plain text with a number is logged as an expense. "
+            "Add #category to override the guess.</i>"
+        )
+        return Reply(body + tail)
+
+    def cmd_whoami(self, ctx: BotContext) -> Reply:
+        return Reply(f"Your Telegram user ID is <code>{ctx.user_id}</code>.")
+
+    def cmd_status(self, ctx: BotContext) -> Reply:
+        settings = ctx.settings
+        store = ctx.store
+
+        start, _ = month_bounds(ctx.today)
+        month_count = len(ctx.store.list_expenses(ctx.user_id, start, ctx.today))
+
+        lines = [
+            "<b>Status</b>",
+            f"Transactions logged: {store.count(ctx.user_id)} ({month_count} this month)",
+            f"Today (in {render.escape(settings.timezone)}): {ctx.today.isoformat()}",
+            "",
+            "<b>Inference</b>",
+        ]
+
+        if settings.llm_enabled:
+            lines.append(f"✅ {render.escape(settings.llm_model)}")
+            lines.append(f"   vision: {render.escape(settings.llm_vision_model)}")
+            lines.append(f"   via {render.escape(settings.llm_base_url)}")
+        else:
+            lines.append("⚠️ No HF_TOKEN — receipts, statements and advice are off.")
+            lines.append("   Plain-text logging still works.")
+
+        lines.append("")
+        lines.append("<b>Access</b>")
+        if settings.open_access:
+            cap = settings.uploads_per_user_per_day
+            lines.append("🌍 Open — anyone on Telegram can use this bot.")
+            lines.append("   Each person's ledger is separate; nobody sees yours.")
+            lines.append(
+                f"   Uploads capped at {cap}/user/day."
+                if cap > 0
+                else "   ⚠️ Uploads uncapped — strangers can spend your inference credits."
+            )
+        else:
+            lines.append(f"🔒 Allowlist — {len(settings.allowed_user_ids)} user(s).")
+
+        lines.append("")
+        lines.append("<b>Storage</b>")
+        if settings.sync_enabled:
+            lines.append(f"✅ {render.escape(store.sync_status)}")
+        else:
+            lines.append(
+                "🔴 <b>Local only — Space disk is ephemeral.</b>\n"
+                "   Your data will be lost on the next restart or sleep.\n"
+                "   Set HF_DATASET_REPO to fix this."
+            )
+
+        if gaps := settings.missing_required():
+            lines.append("")
+            lines.append("<b>Not configured</b>")
+            lines.extend(f"• {render.escape(gap)}" for gap in gaps)
+
+        return Reply("\n".join(lines))

finbot/features/expenses.py

@@ -0,0 +1,256 @@
+"""Expense logging, summaries and imports -- the first registered feature."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional, Sequence
+
+from .. import render
+from ..analytics import (
+    detect_recurring,
+    dominant_currency,
+    period_bounds,
+    previous_month_bounds,
+    summarise,
+)
+from ..extract import extract
+from ..models import Expense
+from ..money import format_money
+from .base import BotContext, CommandSpec, Reply, SimpleFeature
+
+log = logging.getLogger(__name__)
+
+#: Above this many rows, remind the user that /undo drops the whole batch.
+LARGE_IMPORT = 50
+
+
+class ExpensesFeature(SimpleFeature):
+    name = "expenses"
+    description = "💸 Spending"
+    priority = 10
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (
+            CommandSpec("spend", "Log an expense", "<amount> <what>"),
+            CommandSpec("today", "What you spent today"),
+            CommandSpec("week", "This week's spending"),
+            CommandSpec("month", "This month's spending"),
+            CommandSpec(
+                "report",
+                "Summary for a period",
+                "[today|week|month|last_month|30d|year|all]",
+            ),
+            CommandSpec("list", "Recent transactions", "[count]"),
+            CommandSpec("recurring", "Subscriptions and repeat charges"),
+            CommandSpec("undo", "Remove the last entry or import"),
+            CommandSpec("export", "Download everything as CSV"),
+            CommandSpec("confirm", "Save a pending import", hidden=True),
+            CommandSpec("cancel", "Discard a pending import", hidden=True),
+        )
+
+    # ------------------------------------------------------------- logging
+
+    def _log_draft(self, ctx: BotContext, draft, source: str) -> Expense:
+        expense = draft.to_expense(ctx.user_id, source=source, batch_id="")
+        ctx.store.add_expense(expense)
+        return expense
+
+    def cmd_spend(self, ctx: BotContext) -> Reply:
+        if not ctx.args.strip():
+            return Reply(
+                "Tell me what to log, e.g. <code>/spend 250 coffee</code>.\n"
+                "You can also just send <code>250 coffee</code> with no command."
+            )
+        return self._log_text(ctx, ctx.args)
+
+    def handle_message(self, ctx: BotContext) -> Optional[Reply]:
+        """Plain text is treated as an expense if it contains an amount."""
+        if not ctx.text.strip():
+            return None
+        return self._log_text(ctx, ctx.text)
+
+    def _log_text(self, ctx: BotContext, text: str) -> Optional[Reply]:
+        draft = ctx.services.ingestor.from_text(text, ctx.today)
+        if draft is None:
+            return None  # no amount found -- let another feature try
+
+        expense = self._log_draft(ctx, draft, source="text")
+        note = ""
+        if expense.category == "other":
+            note = "Couldn't categorise it — add #groceries etc. next time to pin it."
+        return Reply(render.logged(expense, note))
+
+    # --------------------------------------------------------- attachments
+
+    def handle_attachment(self, ctx: BotContext) -> Optional[Reply]:
+        attachment = ctx.attachment
+        if attachment is None:
+            return None
+
+        if attachment.is_image:
+            return self._handle_receipt(ctx, attachment)
+        return self._handle_statement(ctx, attachment)
+
+    def _handle_receipt(self, ctx: BotContext, attachment) -> Reply:
+        draft, error = ctx.services.ingestor.from_receipt(
+            attachment.data, attachment.mime_type or "image/jpeg", ctx.today
+        )
+        if draft is None:
+            return Reply(render.escape(error))
+
+        if attachment.caption:
+            draft.description = attachment.caption[:200]
+
+        expense = self._log_draft(ctx, draft, source="photo")
+        confidence = ""
+        if expense.confidence < 0.7:
+            confidence = "I wasn't fully confident reading that — check the amount."
+        return Reply(render.logged(expense, confidence))
+
+    def _handle_statement(self, ctx: BotContext, attachment) -> Reply:
+        doc = extract(attachment.data, attachment.filename, attachment.mime_type)
+        pending, error = ctx.services.ingestor.from_document(
+            doc, ctx.user_id, ctx.today, label=attachment.filename
+        )
+        if pending is None:
+            return Reply(render.escape(error))
+
+        # Drop rows already in the ledger so re-sending a statement is safe.
+        # Paired as a list, not a dict: ExpenseDraft is an unhashable dataclass.
+        pairs = [
+            (
+                draft,
+                draft.to_expense(
+                    ctx.user_id, pending.source, pending.batch_id
+                ).dedupe_key,
+            )
+            for draft in pending.drafts
+        ]
+        existing = ctx.store.existing_dedupe_keys(ctx.user_id, [k for _, k in pairs])
+
+        kept = [draft for draft, key in pairs if key not in existing]
+        pending.duplicates = len(pending.drafts) - len(kept)
+        pending.drafts = kept
+
+        if not pending.drafts:
+            return Reply(
+                f"Every transaction in that file is already logged "
+                f"({pending.duplicates} duplicates). Nothing to add."
+            )
+
+        ctx.services.pending[ctx.user_id] = pending
+        return Reply(render.pending_import(pending))
+
+    def cmd_confirm(self, ctx: BotContext) -> Reply:
+        pending = ctx.services.pending.pop(ctx.user_id, None)
+        if pending is None:
+            return Reply("Nothing waiting to be confirmed.")
+
+        expenses = [
+            draft.to_expense(ctx.user_id, pending.source, pending.batch_id)
+            for draft in pending.drafts
+        ]
+        ctx.store.add_expenses(expenses)
+        ctx.store.flush()  # push straight to the Hub; imports are expensive to redo
+
+        totals = pending.total_by_currency()
+        total_str = " + ".join(
+            format_money(v, k) for k, v in sorted(totals.items())
+        )
+        note = ""
+        if len(expenses) >= LARGE_IMPORT:
+            note = "\n<i>/undo removes this whole import.</i>"
+        return Reply(
+            f"✅ Saved {len(expenses)} transactions · {render.escape(total_str)}{note}"
+        )
+
+    def cmd_cancel(self, ctx: BotContext) -> Reply:
+        pending = ctx.services.pending.pop(ctx.user_id, None)
+        if pending is None:
+            return Reply("Nothing pending.")
+        return Reply(f"Discarded {len(pending.drafts)} unsaved transactions.")
+
+    # ---------------------------------------------------------- summaries
+
+    def _summary_reply(self, ctx: BotContext, period: str) -> Reply:
+        start, end, label = period_bounds(period, ctx.today)
+        expenses = ctx.store.list_expenses(ctx.user_id, start, end)
+        currency = dominant_currency(expenses, ctx.settings.default_currency)
+
+        previous = None
+        if period == "month":
+            prev_start, prev_end = previous_month_bounds(ctx.today)
+            # Compare like with like: the same elapsed slice of last month, not
+            # a full month against a partial one.
+            clipped_end = min(prev_end, prev_start + (ctx.today - start))
+            previous = ctx.store.list_expenses(ctx.user_id, prev_start, clipped_end)
+
+        summ = render.summary(
+            summarise(expenses, currency, label, start, end, previous)
+        )
+
+        others = [c for c in {e.currency.upper() for e in expenses} if c != currency]
+        if others:
+            extra = []
+            for code in sorted(others):
+                subtotal = sum(
+                    e.amount_minor for e in expenses if e.currency.upper() == code
+                )
+                extra.append(format_money(subtotal, code))
+            summ += f"\n<i>Also: {render.escape(' · '.join(extra))}</i>"
+
+        return Reply(summ)
+
+    def cmd_today(self, ctx: BotContext) -> Reply:
+        return self._summary_reply(ctx, "today")
+
+    def cmd_week(self, ctx: BotContext) -> Reply:
+        return self._summary_reply(ctx, "week")
+
+    def cmd_month(self, ctx: BotContext) -> Reply:
+        return self._summary_reply(ctx, "month")
+
+    def cmd_report(self, ctx: BotContext) -> Reply:
+        period = (ctx.args.strip().lower() or "month").replace(" ", "_")
+        if period in {"lastmonth", "last-month"}:
+            period = "last_month"
+        return self._summary_reply(ctx, period)
+
+    def cmd_list(self, ctx: BotContext) -> Reply:
+        try:
+            count = max(1, min(50, int(ctx.args.strip()))) if ctx.args.strip() else 15
+        except ValueError:
+            count = 15
+        expenses = ctx.store.list_expenses(ctx.user_id, limit=count)
+        return Reply(render.expense_list(expenses, f"Last {len(expenses)} transactions"))
+
+    def cmd_recurring(self, ctx: BotContext) -> Reply:
+        expenses = ctx.store.list_expenses(ctx.user_id)
+        currency = dominant_currency(expenses, ctx.settings.default_currency)
+        return Reply(render.recurring_list(detect_recurring(expenses), currency))
+
+    # -------------------------------------------------------------- undo
+
+    def cmd_undo(self, ctx: BotContext) -> Reply:
+        last = ctx.store.last_expense(ctx.user_id)
+        if last is None:
+            return Reply("Nothing to undo.")
+
+        if last.batch_id:
+            removed = ctx.store.delete_batch(ctx.user_id, last.batch_id)
+            return Reply(f"Removed the last import — {removed} transactions.")
+
+        ctx.store.delete_expense(ctx.user_id, last.id)
+        return Reply(f"Removed: {render.expense_line(last)}")
+
+    # ------------------------------------------------------------ export
+
+    def cmd_export(self, ctx: BotContext) -> Reply:
+        expenses = ctx.store.list_expenses(ctx.user_id)
+        if not expenses:
+            return Reply("Nothing to export yet.")
+        payload = render.csv_export(expenses).encode("utf-8")
+        return Reply(
+            f"📄 {len(expenses)} transactions.",
+            document=(f"finbot-export-{ctx.today.isoformat()}.csv", payload),
+        )

finbot/ingest.py

@@ -0,0 +1,292 @@
+"""Turn user input into expense drafts.
+
+Order of preference throughout: deterministic parsing first, model second. The
+regex parser handles "coffee 250" instantly, for free, and identically every
+time. The model is spent only on what actually needs judgement -- reading a
+receipt photo, or working out which column of an unfamiliar bank export is the
+amount.
+
+Statement imports never write straight to the ledger. They produce a
+:class:`~finbot.models.PendingImport` that the user confirms, because a model
+that misreads a column would otherwise quietly poison months of history.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime
+from typing import Any, Optional
+
+from .categories import CATEGORIES, categorise, coerce
+from .extract import ExtractedDocument, rows_to_text
+from .llm import LLMClient, LLMUnavailable
+from .models import ExpenseDraft, PendingImport
+from .money import to_minor
+from .parser import parse_expense
+
+log = logging.getLogger(__name__)
+
+_CATEGORY_LIST = ", ".join(CATEGORIES)
+
+_STATEMENT_SYSTEM = f"""You extract transactions from bank and card statements.
+
+The statement may come from any bank in any country, in any currency, with any
+column order or language. Work out the structure yourself from the content.
+
+Return a JSON object with one key, "transactions", whose value is an array.
+Each element must have exactly these fields:
+  "date":        ISO 8601 date, YYYY-MM-DD
+  "description": the merchant or narration, cleaned of reference numbers
+  "amount":      a positive number in major units (e.g. 1234.56), never a string
+  "currency":    ISO 4217 code, e.g. INR, USD, EUR
+  "direction":   "debit" if money left the account, "credit" if it came in
+  "category":    one of: {_CATEGORY_LIST}
+
+Rules:
+- Infer the currency from symbols or codes in the document. If genuinely absent,
+  use "{{default_currency}}".
+- Amounts are always positive; use "direction" to express the sign.
+- Ambiguous dates are day-first unless the document proves otherwise.
+- Skip opening/closing balances, subtotals, carried-forward lines and headers.
+- If you cannot read a row confidently, omit it rather than guessing.
+- Return only the JSON object."""
+
+_RECEIPT_SYSTEM = f"""You read receipts and bills from photographs.
+
+Return a JSON object with these fields:
+  "merchant":  the shop or business name, "" if unreadable
+  "date":      ISO 8601 date YYYY-MM-DD, or "" if not visible
+  "amount":    the FINAL TOTAL paid, positive, in major units, as a number
+  "currency":  ISO 4217 code inferred from the receipt
+  "category":  one of: {_CATEGORY_LIST}
+  "confidence": 0.0-1.0, how sure you are of the total
+
+Take the grand total actually paid -- not a subtotal, not a single line item,
+not the tax. If the image is not a receipt, set amount to 0."""
+
+_FREETEXT_SYSTEM = f"""You turn a person's shorthand note into one expense record.
+
+Return a JSON object with:
+  "amount":      positive number in major units
+  "currency":    ISO 4217 code
+  "description": short, human-readable
+  "date":        ISO 8601 YYYY-MM-DD
+  "category":    one of: {_CATEGORY_LIST}
+
+If the note contains no spend at all, return {{"amount": 0}}."""
+
+
+def _parse_any_date(value: Any, fallback: date) -> date:
+    if isinstance(value, date) and not isinstance(value, datetime):
+        return value
+    if isinstance(value, datetime):
+        return value.date()
+    text = str(value or "").strip()
+    if not text:
+        return fallback
+    try:
+        return date.fromisoformat(text[:10])
+    except ValueError:
+        pass
+    try:
+        from dateutil import parser as dateparser
+
+        return dateparser.parse(text, dayfirst=True, fuzzy=True).date()
+    except Exception:
+        return fallback
+
+
+def _coerce_amount(value: Any) -> Optional[float]:
+    if isinstance(value, (int, float)):
+        return abs(float(value))
+    text = str(value or "").strip()
+    if not text:
+        return None
+    # Strip everything that isn't numeric, then reuse the shared separator logic.
+    from .money import _normalise_number  # local import: private helper
+
+    cleaned = "".join(ch for ch in text if ch.isdigit() or ch in ".,-")
+    cleaned = cleaned.lstrip("-")
+    normalised = _normalise_number(cleaned)
+    if normalised is None:
+        return None
+    try:
+        return abs(float(normalised))
+    except ValueError:
+        return None
+
+
+def _draft_from_obj(
+    obj: dict, default_currency: str, today: date
+) -> Optional[ExpenseDraft]:
+    """Validate one model-emitted record into a draft, or drop it."""
+    if not isinstance(obj, dict):
+        return None
+
+    amount = _coerce_amount(obj.get("amount"))
+    if not amount or amount <= 0:
+        return None
+
+    currency = str(obj.get("currency") or default_currency).upper()[:3]
+    if not currency.isalpha():
+        currency = default_currency.upper()
+
+    description = str(obj.get("description") or obj.get("merchant") or "").strip()
+    description = " ".join(description.split())[:200] or "unlabelled"
+
+    category = coerce(str(obj.get("category") or ""))
+    if category == "other":
+        # The model's label was unusable; keyword rules often still know this one.
+        guessed, hit = categorise(description)
+        if hit:
+            category = guessed
+
+    return ExpenseDraft(
+        amount_minor=to_minor(amount, currency),
+        currency=currency,
+        description=description,
+        occurred_on=_parse_any_date(obj.get("date"), today),
+        category=category,
+        merchant=str(obj.get("merchant") or "").strip()[:120],
+        confidence=float(obj.get("confidence") or 0.7),
+    )
+
+
+class Ingestor:
+    def __init__(self, llm: LLMClient, default_currency: str = "INR"):
+        self.llm = llm
+        self.default_currency = default_currency
+
+    # ------------------------------------------------------------ free text
+
+    def from_text(self, text: str, today: Optional[date] = None) -> Optional[ExpenseDraft]:
+        """Deterministic parse, with a model fallback only if that fails."""
+        today = today or date.today()
+
+        draft = parse_expense(text, self.default_currency, today)
+        if draft is not None:
+            return draft
+
+        if not self.llm.enabled:
+            return None
+
+        try:
+            obj = self.llm.chat_json(
+                _FREETEXT_SYSTEM,
+                f"Today is {today.isoformat()}.\n\nNote: {text}",
+                max_tokens=400,
+            )
+        except (LLMUnavailable, ValueError) as exc:
+            log.info("Free-text model fallback unavailable: %s", exc)
+            return None
+
+        return _draft_from_obj(obj, self.default_currency, today)
+
+    # -------------------------------------------------------------- receipts
+
+    def from_receipt(
+        self, image_bytes: bytes, mime_type: str, today: Optional[date] = None
+    ) -> tuple[Optional[ExpenseDraft], str]:
+        """Read a receipt photo. Returns (draft, error_message)."""
+        today = today or date.today()
+
+        if not self.llm.enabled:
+            return None, (
+                "Reading receipt photos needs an inference token. "
+                "Set HF_TOKEN in the Space secrets, or type the amount instead."
+            )
+
+        try:
+            obj = self.llm.vision_json(
+                _RECEIPT_SYSTEM,
+                f"Today is {today.isoformat()}. Read this receipt.",
+                image_bytes,
+                mime_type,
+            )
+        except (LLMUnavailable, ValueError) as exc:
+            log.warning("Receipt read failed: %s", exc)
+            return None, f"I couldn't read that receipt ({exc}). Try a clearer photo?"
+
+        draft = _draft_from_obj(obj, self.default_currency, today)
+        if draft is None:
+            return None, (
+                "I couldn't find a total on that image. If it is a receipt, "
+                "try a straighter, better-lit photo, or just type the amount."
+            )
+        return draft, ""
+
+    # ------------------------------------------------------------ statements
+
+    def from_document(
+        self,
+        doc: ExtractedDocument,
+        user_id: int,
+        today: Optional[date] = None,
+        label: str = "",
+    ) -> tuple[Optional[PendingImport], str]:
+        """Map an extracted statement into drafts. Returns (pending, error)."""
+        today = today or date.today()
+
+        if doc.kind == "unsupported" or doc.is_empty:
+            return None, doc.note or "There was nothing readable in that file."
+
+        if not self.llm.enabled:
+            return None, (
+                "Reading statements needs an inference token. Set HF_TOKEN in "
+                "the Space secrets and send the file again."
+            )
+
+        payload = rows_to_text(doc.rows) if doc.rows else doc.text
+        if not payload.strip():
+            return None, "There was nothing readable in that file."
+
+        system = _STATEMENT_SYSTEM.replace("{default_currency}", self.default_currency)
+        try:
+            result = self.llm.chat_json(
+                system,
+                f"Today is {today.isoformat()}. Extract every transaction.\n\n{payload}",
+                max_tokens=8000,
+            )
+        except (LLMUnavailable, ValueError) as exc:
+            log.warning("Statement extraction failed: %s", exc)
+            return None, f"I couldn't read that statement ({exc})."
+
+        records = result.get("transactions") if isinstance(result, dict) else result
+        if not isinstance(records, list):
+            return None, "The extractor returned an unexpected shape. Try again?"
+
+        drafts: list[ExpenseDraft] = []
+        skipped = 0
+        credits = 0
+        for record in records:
+            if not isinstance(record, dict):
+                skipped += 1
+                continue
+            # Credits are money coming in. Storing them alongside spend would
+            # corrupt every "total spent" figure, so they are counted and
+            # reported rather than written.
+            if str(record.get("direction", "debit")).lower().startswith("cred"):
+                credits += 1
+                continue
+            draft = _draft_from_obj(record, self.default_currency, today)
+            if draft is None:
+                skipped += 1
+                continue
+            drafts.append(draft)
+
+        if not drafts:
+            detail = f" ({credits} credits, {skipped} unreadable rows)" if (credits or skipped) else ""
+            return None, f"I found no spending transactions in that file{detail}."
+
+        pending = PendingImport(
+            user_id=user_id,
+            drafts=drafts,
+            source=doc.kind,
+            skipped=skipped,
+            label=label,
+        )
+        if credits:
+            pending.label = (pending.label + f" · {credits} credits skipped").strip(" ·")
+        if doc.truncated:
+            pending.label = (pending.label + " · file truncated").strip(" ·")
+        return pending, ""

finbot/limits.py

@@ -0,0 +1,55 @@
+"""Per-user throttling for model-backed work.
+
+Only relevant in open-access mode. Reading a receipt or a statement spends the
+Space owner's inference credits, so without a cap a single stranger with a
+folder of PDFs can run up an unbounded bill on someone else's token.
+
+Deliberately in-memory: it resets when the Space restarts or sleeps, which is
+fine for a budget guard and avoids putting other people's usage records in the
+owner's dataset. Plain text costs nothing (the deterministic parser handles it)
+and is never throttled.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict
+
+WINDOW_SECONDS = 24 * 60 * 60
+
+
+class RateLimiter:
+    def __init__(self, per_day: int):
+        #: Zero or negative disables the limiter entirely.
+        self.per_day = per_day
+        self._hits: dict[int, list[float]] = defaultdict(list)
+        self._lock = threading.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        return self.per_day > 0
+
+    def _prune(self, user_id: int, now: float) -> list[float]:
+        recent = [t for t in self._hits[user_id] if now - t < WINDOW_SECONDS]
+        self._hits[user_id] = recent
+        return recent
+
+    def check(self, user_id: int, now: float | None = None) -> bool:
+        """Record an attempt. False means the user is over their daily cap."""
+        if not self.enabled:
+            return True
+        now = now if now is not None else time.time()
+        with self._lock:
+            recent = self._prune(user_id, now)
+            if len(recent) >= self.per_day:
+                return False
+            recent.append(now)
+            return True
+
+    def remaining(self, user_id: int, now: float | None = None) -> int:
+        if not self.enabled:
+            return -1  # unlimited
+        now = now if now is not None else time.time()
+        with self._lock:
+            return max(0, self.per_day - len(self._prune(user_id, now)))

finbot/llm.py

@@ -0,0 +1,246 @@
+"""Inference against Hugging Face Inference Providers.
+
+The router at ``https://router.huggingface.co/v1`` is OpenAI-compatible, so one
+HF token fans out across Cerebras, Together, Fireworks and friends without any
+provider-specific code. Point ``LLM_BASE_URL`` somewhere else -- Ollama, a
+llama.cpp server, OpenAI proper -- and everything here still works.
+
+Every entry point degrades rather than raising into the request path: if no
+token is configured, or the provider is down, the caller gets
+:class:`LLMUnavailable` and falls back to deterministic parsing. Losing receipt
+understanding is an inconvenience; a bot that stops accepting "coffee 250"
+because an inference provider is having a bad day is a broken bot.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import re
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .config import Settings
+
+log = logging.getLogger(__name__)
+
+_RETRY_STATUS = {408, 409, 425, 429, 500, 502, 503, 504}
+_MAX_ATTEMPTS = 3
+_FENCE_RE = re.compile(r"```(?:json)?\s*(.*?)\s*```", re.S)
+
+
+class LLMUnavailable(RuntimeError):
+    """Inference could not be performed. Callers must degrade gracefully."""
+
+
+def _extract_json_blob(text: str) -> Any:
+    """Parse JSON out of a model response that may be wrapped in prose or fences."""
+    text = (text or "").strip()
+    if not text:
+        raise ValueError("empty response")
+
+    if match := _FENCE_RE.search(text):
+        text = match.group(1).strip()
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    # Fall back to the first balanced {...} or [...] in the response.
+    for opener, closer in (("{", "}"), ("[", "]")):
+        start = text.find(opener)
+        if start == -1:
+            continue
+        depth = 0
+        in_string = False
+        escape = False
+        for i in range(start, len(text)):
+            ch = text[i]
+            if escape:
+                escape = False
+                continue
+            if ch == "\\":
+                escape = True
+                continue
+            if ch == '"':
+                in_string = not in_string
+                continue
+            if in_string:
+                continue
+            if ch == opener:
+                depth += 1
+            elif ch == closer:
+                depth -= 1
+                if depth == 0:
+                    return json.loads(text[start : i + 1])
+    raise ValueError(f"no JSON found in response: {text[:200]}")
+
+
+class LLMClient:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self._client: Optional[httpx.Client] = None
+
+    @property
+    def enabled(self) -> bool:
+        return self.settings.llm_enabled
+
+    def _http(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.settings.llm_base_url.rstrip("/"),
+                headers={
+                    "Authorization": f"Bearer {self.settings.hf_token}",
+                    "Content-Type": "application/json",
+                },
+                timeout=httpx.Timeout(90.0, connect=15.0),
+            )
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def _post_chat(self, payload: dict) -> str:
+        if not self.enabled:
+            raise LLMUnavailable("HF_TOKEN is not set")
+
+        last_error: Optional[str] = None
+        for attempt in range(1, _MAX_ATTEMPTS + 1):
+            try:
+                response = self._http().post("/chat/completions", json=payload)
+            except httpx.RequestError as exc:
+                last_error = f"network error: {exc}"
+                log.warning("Inference attempt %d failed: %s", attempt, last_error)
+                time.sleep(min(2 ** attempt, 8))
+                continue
+
+            if response.status_code in _RETRY_STATUS and attempt < _MAX_ATTEMPTS:
+                retry_after = response.headers.get("retry-after")
+                delay = float(retry_after) if retry_after and retry_after.isdigit() else min(2 ** attempt, 8)
+                last_error = f"HTTP {response.status_code}"
+                log.warning("Inference attempt %d got %s; retrying", attempt, last_error)
+                time.sleep(delay)
+                continue
+
+            if response.status_code >= 400:
+                raise LLMUnavailable(
+                    f"HTTP {response.status_code}: {response.text[:300]}"
+                )
+
+            data = response.json()
+            try:
+                return data["choices"][0]["message"]["content"] or ""
+            except (KeyError, IndexError, TypeError) as exc:
+                raise LLMUnavailable(f"unexpected response shape: {exc}") from exc
+
+        raise LLMUnavailable(last_error or "exhausted retries")
+
+    def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: Optional[str] = None,
+        temperature: float = 0.2,
+        max_tokens: int = 1200,
+    ) -> str:
+        payload = {
+            "model": model or self.settings.llm_model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        return self._post_chat(payload)
+
+    def chat_json(
+        self,
+        system: str,
+        user: str,
+        *,
+        model: Optional[str] = None,
+        temperature: float = 0.0,
+        max_tokens: int = 4000,
+    ) -> Any:
+        """Chat constrained to JSON, with a repair attempt on malformed output."""
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        payload: dict[str, Any] = {
+            "model": model or self.settings.llm_model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "response_format": {"type": "json_object"},
+        }
+
+        try:
+            raw = self._post_chat(payload)
+        except LLMUnavailable as exc:
+            # Not every provider on the router honours response_format. Retry
+            # once without it before giving up.
+            if "response_format" not in str(exc):
+                payload.pop("response_format", None)
+                raw = self._post_chat(payload)
+            else:
+                raise
+
+        try:
+            return _extract_json_blob(raw)
+        except ValueError as exc:
+            log.warning("Malformed JSON from model, attempting repair: %s", exc)
+            repair = [
+                {"role": "system", "content": "Return only valid JSON. No prose, no code fences."},
+                {"role": "user", "content": f"Fix this into valid JSON:\n\n{raw[:6000]}"},
+            ]
+            repaired = self._post_chat(
+                {
+                    "model": model or self.settings.llm_model,
+                    "messages": repair,
+                    "temperature": 0.0,
+                    "max_tokens": max_tokens,
+                }
+            )
+            return _extract_json_blob(repaired)
+
+    def vision_json(
+        self,
+        system: str,
+        user: str,
+        image_bytes: bytes,
+        mime_type: str = "image/jpeg",
+        *,
+        max_tokens: int = 1500,
+    ) -> Any:
+        """Send an image plus instructions and parse a JSON reply."""
+        if not self.enabled:
+            raise LLMUnavailable("HF_TOKEN is not set")
+
+        encoded = base64.b64encode(image_bytes).decode("ascii")
+        messages = [
+            {"role": "system", "content": system},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": user},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:{mime_type};base64,{encoded}"},
+                    },
+                ],
+            },
+        ]
+        raw = self._post_chat(
+            {
+                "model": self.settings.llm_vision_model,
+                "messages": messages,
+                "temperature": 0.0,
+                "max_tokens": max_tokens,
+            }
+        )
+        return _extract_json_blob(raw)

finbot/models.py

@@ -0,0 +1,158 @@
+"""Domain records. Plain dataclasses -- the storage layer maps them to SQLite."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import uuid
+from dataclasses import dataclass, field
+from datetime import date, datetime, timezone
+from typing import Optional
+
+from .money import format_money
+
+#: Where a record came from. Kept on every expense so a bad import can be
+#: found and reversed as a unit.
+SOURCES = ("text", "photo", "pdf", "csv", "xlsx", "manual")
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _slug(text: str) -> str:
+    """Loose normalisation for dedupe: case, punctuation and spacing-insensitive."""
+    return re.sub(r"[^a-z0-9]+", "", text.lower())
+
+
+@dataclass
+class Expense:
+    user_id: int
+    amount_minor: int
+    currency: str
+    description: str
+    category: str
+    occurred_on: date
+    id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    merchant: str = ""
+    source: str = "text"
+    #: Groups rows that arrived together, so /undo can drop a whole import.
+    batch_id: str = ""
+    note: str = ""
+    #: 1.0 for deterministic parses, lower for model-extracted rows.
+    confidence: float = 1.0
+    created_at: datetime = field(default_factory=_now)
+
+    @property
+    def dedupe_key(self) -> str:
+        """Stable identity for 'the same transaction'.
+
+        Deliberately excludes id, source and confidence so that the same row
+        re-imported from a re-downloaded statement collapses onto the original.
+        """
+        basis = "|".join(
+            [
+                str(self.user_id),
+                str(self.amount_minor),
+                self.currency.upper(),
+                self.occurred_on.isoformat(),
+                _slug(self.merchant or self.description),
+            ]
+        )
+        return hashlib.sha256(basis.encode("utf-8")).hexdigest()[:32]
+
+    def display(self) -> str:
+        amount = format_money(self.amount_minor, self.currency)
+        label = self.merchant or self.description or self.category
+        return f"{amount} · {label} · {self.category} · {self.occurred_on.isoformat()}"
+
+
+@dataclass
+class Budget:
+    user_id: int
+    category: str
+    amount_minor: int
+    currency: str
+    period: str = "monthly"
+    created_at: datetime = field(default_factory=_now)
+
+
+@dataclass
+class ExpenseDraft:
+    """A candidate row awaiting confirmation.
+
+    Statement and receipt imports land here first. Nothing model-extracted is
+    written to the ledger without the user seeing the total and saying yes.
+    """
+
+    amount_minor: int
+    currency: str
+    description: str
+    occurred_on: date
+    category: str = "other"
+    merchant: str = ""
+    confidence: float = 0.5
+    raw: str = ""
+
+    def to_expense(
+        self, user_id: int, source: str, batch_id: str, note: str = ""
+    ) -> Expense:
+        return Expense(
+            user_id=user_id,
+            amount_minor=self.amount_minor,
+            currency=self.currency,
+            description=self.description,
+            category=self.category,
+            occurred_on=self.occurred_on,
+            merchant=self.merchant,
+            source=source,
+            batch_id=batch_id,
+            note=note,
+            confidence=self.confidence,
+        )
+
+
+@dataclass
+class PendingImport:
+    """Drafts held between 'here is your statement' and '/confirm'."""
+
+    user_id: int
+    drafts: list[ExpenseDraft]
+    source: str
+    batch_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    created_at: datetime = field(default_factory=_now)
+    #: Rows dropped because they already exist in the ledger.
+    duplicates: int = 0
+    #: Rows the extractor emitted but could not be made sense of.
+    skipped: int = 0
+    label: str = ""
+
+    def total_by_currency(self) -> dict[str, int]:
+        totals: dict[str, int] = {}
+        for d in self.drafts:
+            totals[d.currency] = totals.get(d.currency, 0) + d.amount_minor
+        return totals
+
+
+@dataclass
+class Summary:
+    """Aggregated spend for a period, ready to render."""
+
+    label: str
+    start: date
+    end: date
+    currency: str
+    total_minor: int
+    count: int
+    by_category: list[tuple[str, int]]
+    previous_total_minor: Optional[int] = None
+
+    @property
+    def delta_pct(self) -> Optional[float]:
+        if self.previous_total_minor is None or self.previous_total_minor == 0:
+            return None
+        return (
+            (self.total_minor - self.previous_total_minor)
+            / self.previous_total_minor
+            * 100.0
+        )

finbot/money.py

@@ -0,0 +1,180 @@
+"""Multi-currency amounts as integer minor units.
+
+Money is never a float here. 0.1 + 0.2 != 0.3 in binary floating point, and a
+ledger that drifts by a paisa per transaction is worse than useless -- so every
+amount is an int of the currency's smallest unit (paise, cents, fils) plus an
+ISO 4217 code.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple, Optional
+
+# Currencies whose minor unit is not 1/100. Anything absent is assumed to have
+# two decimal places, which is true for the large majority of ISO 4217.
+_EXPONENTS: dict[str, int] = {
+    "JPY": 0, "KRW": 0, "VND": 0, "CLP": 0, "ISK": 0, "UGX": 0,
+    "PYG": 0, "RWF": 0, "XAF": 0, "XOF": 0, "XPF": 0, "KMF": 0,
+    "DJF": 0, "GNF": 0, "BIF": 0, "VUV": 0,
+    "BHD": 3, "IQD": 3, "JOD": 3, "KWD": 3, "LYD": 3, "OMR": 3, "TND": 3,
+}
+
+# Symbols that map to exactly one currency. Deliberately excludes bare "$",
+# which is ambiguous across USD/CAD/AUD/SGD/HKD and many more -- see
+# _AMBIGUOUS_SYMBOLS.
+_SYMBOLS: dict[str, str] = {
+    "₹": "INR", "€": "EUR", "£": "GBP", "¥": "JPY", "₽": "RUB",
+    "₩": "KRW", "₪": "ILS", "₫": "VND", "₺": "TRY", "₦": "NGN",
+    "₴": "UAH", "₸": "KZT", "฿": "THB", "₡": "CRC", "₱": "PHP",
+    "﷼": "SAR", "Rs": "INR", "R$": "BRL", "CHF": "CHF",
+}
+
+# Symbols that need the configured default to disambiguate.
+_AMBIGUOUS_SYMBOLS = {"$"}
+
+_ISO_RE = re.compile(r"\b([A-Z]{3})\b")
+
+# A maximal run of digits and separators; _normalise_number then decides what
+# each separator meant. Handles 1234 / 1,234.56 / 1.234,56 / 1,23,456.78
+# (Indian lakh grouping) / 1\xa0234,56.
+#
+# A plain ASCII space is deliberately NOT a group separator: French-style
+# "1 234" is indistinguishable from two separate numbers, and reading
+# "250 300" as 250300 is a far worse failure than missing that one format.
+_NUMBER_RE = re.compile(r"\d[\d,.\xa0\u202f]*\d|\d")
+
+
+class ParsedAmount(NamedTuple):
+    minor: int
+    currency: Optional[str]
+    #: The exact substring that produced this amount, so callers can strip it
+    #: out of a description without re-guessing.
+    span: tuple[int, int]
+
+
+def exponent(currency: str) -> int:
+    """Number of decimal places for an ISO 4217 code."""
+    return _EXPONENTS.get(currency.upper(), 2)
+
+
+def to_minor(value: float | str, currency: str) -> int:
+    """Convert a major-unit value to integer minor units, half-up.
+
+    Uses string/Decimal arithmetic rather than float rounding so that values
+    like 8.345 land where a human would expect.
+    """
+    from decimal import Decimal, ROUND_HALF_UP
+
+    exp = exponent(currency)
+    quantum = Decimal(1).scaleb(-exp)
+    dec = Decimal(str(value)).quantize(quantum, rounding=ROUND_HALF_UP)
+    return int(dec.scaleb(exp))
+
+
+def from_minor(minor: int, currency: str) -> float:
+    """Minor units back to a major-unit float. Display only -- never for maths."""
+    return minor / (10 ** exponent(currency))
+
+
+def format_money(minor: int, currency: str) -> str:
+    """Human-readable amount, e.g. 123456 INR -> '₹1,234.56'."""
+    exp = exponent(currency)
+    sign = "-" if minor < 0 else ""
+    whole, frac = divmod(abs(minor), 10 ** exp)
+    symbol = _symbol_for(currency)
+    body = f"{whole:,}" if exp == 0 else f"{whole:,}.{frac:0{exp}d}"
+    if symbol:
+        return f"{sign}{symbol}{body}"
+    return f"{sign}{body} {currency.upper()}"
+
+
+def _symbol_for(currency: str) -> str:
+    for sym, code in _SYMBOLS.items():
+        # Only single-glyph symbols read well as prefixes.
+        if code == currency.upper() and len(sym) == 1:
+            return sym
+    if currency.upper() == "USD":
+        return "$"
+    return ""
+
+
+def _normalise_number(raw: str) -> Optional[str]:
+    """Turn a grouped numeric string into a plain decimal string.
+
+    The hard case is telling a decimal separator from a thousands separator.
+    Rules, in order:
+      1. If both ',' and '.' appear, the rightmost one is the decimal point.
+      2. If one appears once and is followed by exactly 2 digits, it is decimal.
+      3. Otherwise it is grouping and gets stripped.
+    """
+    text = re.sub(r"[\s\xa0\u202f]", "", raw)
+    if not text:
+        return None
+
+    has_comma, has_dot = "," in text, "." in text
+
+    if has_comma and has_dot:
+        dec_sep = "," if text.rfind(",") > text.rfind(".") else "."
+        grp_sep = "." if dec_sep == "," else ","
+        text = text.replace(grp_sep, "").replace(dec_sep, ".")
+    elif has_comma or has_dot:
+        sep = "," if has_comma else "."
+        head, _, tail = text.rpartition(sep)
+        if text.count(sep) == 1 and len(tail) in (1, 2):
+            text = f"{head}.{tail}"
+        else:
+            text = text.replace(sep, "")
+
+    if not re.fullmatch(r"\d+(?:\.\d+)?", text):
+        return None
+    return text
+
+
+def detect_currency(text: str, default: str) -> str:
+    """Best-effort currency for a free-text fragment."""
+    upper = text.upper()
+    for sym, code in _SYMBOLS.items():
+        symbol = sym.upper()
+        if symbol.isalpha():
+            # Letter symbols ("Rs", "CHF") need boundaries, or "cars" reads as
+            # rupees and "chfoo" as francs.
+            if re.search(rf"(?<![A-Z]){re.escape(symbol)}(?![A-Z])", upper):
+                return code
+        elif symbol in upper:
+            return code
+    for match in _ISO_RE.finditer(upper):
+        code = match.group(1)
+        if code in _EXPONENTS or code in set(_SYMBOLS.values()) or code in _COMMON_ISO:
+            return code
+    if any(sym in text for sym in _AMBIGUOUS_SYMBOLS):
+        return default.upper()
+    return default.upper()
+
+
+_COMMON_ISO = {
+    "USD", "EUR", "GBP", "INR", "JPY", "CNY", "AUD", "CAD", "SGD", "CHF",
+    "HKD", "NZD", "SEK", "NOK", "DKK", "ZAR", "AED", "SAR", "MYR", "THB",
+    "IDR", "PHP", "VND", "KRW", "BRL", "MXN", "RUB", "TRY", "PLN", "CZK",
+    "ILS", "NGN", "KES", "EGP", "PKR", "BDT", "LKR", "NPR",
+}
+
+
+def parse_amount(text: str, default_currency: str = "INR") -> Optional[ParsedAmount]:
+    """Pull the most plausible monetary amount out of free text.
+
+    Returns None when nothing numeric is present. Currency is resolved from an
+    explicit symbol or ISO code when one is given, else the supplied default.
+    """
+    best: Optional[ParsedAmount] = None
+    for match in _NUMBER_RE.finditer(text):
+        normalised = _normalise_number(match.group(0))
+        if normalised is None:
+            continue
+        currency = detect_currency(text, default_currency)
+        minor = to_minor(normalised, currency)
+        candidate = ParsedAmount(minor=minor, currency=currency, span=match.span())
+        # Prefer the largest magnitude: in "2 coffees 250" the spend is 250.
+        if best is None or candidate.minor > best.minor:
+            best = candidate
+    return best

finbot/parser.py

@@ -0,0 +1,188 @@
+"""Deterministic parsing of free-text expense entry.
+
+This is the fast path: "coffee 250", "₹1,200 groceries at bigbasket",
+"spent 45.50 on lunch yesterday". It runs before any model call, costs
+nothing, and is reproducible. Anything it cannot make sense of is handed to
+the LLM by :mod:`finbot.ingest`.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, timedelta
+from typing import Optional
+
+from .categories import categorise, coerce
+from .models import ExpenseDraft
+from .money import parse_amount
+
+_WEEKDAYS = {
+    "monday": 0, "mon": 0,
+    "tuesday": 1, "tue": 1, "tues": 1,
+    "wednesday": 2, "wed": 2,
+    "thursday": 3, "thu": 3, "thurs": 3,
+    "friday": 4, "fri": 4,
+    "saturday": 5, "sat": 5,
+    "sunday": 6, "sun": 6,
+}
+
+_MONTHS = {
+    "jan": 1, "january": 1, "feb": 2, "february": 2, "mar": 3, "march": 3,
+    "apr": 4, "april": 4, "may": 5, "jun": 6, "june": 6, "jul": 7, "july": 7,
+    "aug": 8, "august": 8, "sep": 9, "sept": 9, "september": 9,
+    "oct": 10, "october": 10, "nov": 11, "november": 11, "dec": 12, "december": 12,
+}
+
+# Words that carry no meaning in a description once the amount is removed.
+_FILLER = {
+    "spent", "spend", "paid", "pay", "bought", "buy", "for", "on", "at", "in",
+    "of", "the", "a", "an", "to", "rs", "rs.", "inr", "cost", "costs", "was",
+    "were", "i", "my", "me", "some", "and", "with", "got",
+}
+
+_ISO_DATE_RE = re.compile(r"\b(\d{4})-(\d{1,2})-(\d{1,2})\b")
+_DMY_RE = re.compile(r"\b(\d{1,2})[/-](\d{1,2})(?:[/-](\d{2,4}))?\b")
+_DAY_MONTH_RE = re.compile(
+    r"\b(\d{1,2})(?:st|nd|rd|th)?\s+(" + "|".join(_MONTHS) + r")\b", re.I
+)
+_MONTH_DAY_RE = re.compile(
+    r"\b(" + "|".join(_MONTHS) + r")\s+(\d{1,2})(?:st|nd|rd|th)?\b", re.I
+)
+_DAYS_AGO_RE = re.compile(r"\b(\d{1,3})\s+days?\s+ago\b", re.I)
+_LAST_WEEKDAY_RE = re.compile(
+    r"\b(?:last\s+)?(" + "|".join(_WEEKDAYS) + r")\b", re.I
+)
+_TAG_RE = re.compile(r"#([a-z_][a-z0-9_]*)", re.I)
+
+
+def _clamp_year(year: int) -> int:
+    if year < 100:
+        return 2000 + year
+    return year
+
+
+def parse_date_hint(
+    text: str, today: Optional[date] = None
+) -> tuple[date, Optional[tuple[int, int]]]:
+    """Resolve a date reference in ``text``.
+
+    Returns (resolved_date, span_of_the_phrase). Span is None when no hint was
+    found, in which case the date defaults to today. Dates that would land in
+    the future are pulled back a year -- "12 dec" typed in August means last
+    December, not a spend that has not happened yet.
+    """
+    today = today or date.today()
+    lowered = text.lower()
+
+    if m := re.search(r"\bday before yesterday\b", lowered):
+        return today - timedelta(days=2), m.span()
+    if m := re.search(r"\byesterday\b", lowered):
+        return today - timedelta(days=1), m.span()
+    if m := re.search(r"\btoday\b", lowered):
+        return today, m.span()
+
+    if m := _DAYS_AGO_RE.search(lowered):
+        return today - timedelta(days=int(m.group(1))), m.span()
+
+    if m := _ISO_DATE_RE.search(lowered):
+        try:
+            return date(int(m.group(1)), int(m.group(2)), int(m.group(3))), m.span()
+        except ValueError:
+            pass
+
+    if m := _DAY_MONTH_RE.search(lowered):
+        day, month = int(m.group(1)), _MONTHS[m.group(2).lower()]
+        try:
+            candidate = date(today.year, month, day)
+            if candidate > today:
+                candidate = date(today.year - 1, month, day)
+            return candidate, m.span()
+        except ValueError:
+            pass
+
+    if m := _MONTH_DAY_RE.search(lowered):
+        month, day = _MONTHS[m.group(1).lower()], int(m.group(2))
+        try:
+            candidate = date(today.year, month, day)
+            if candidate > today:
+                candidate = date(today.year - 1, month, day)
+            return candidate, m.span()
+        except ValueError:
+            pass
+
+    if m := _DMY_RE.search(lowered):
+        first, second, year_s = int(m.group(1)), int(m.group(2)), m.group(3)
+        year = _clamp_year(int(year_s)) if year_s else today.year
+        # Ambiguous d/m vs m/d. Prefer day-first, which covers most of the
+        # world, and fall back to month-first when day-first is impossible.
+        for day, month in ((first, second), (second, first)):
+            try:
+                candidate = date(year, month, day)
+            except ValueError:
+                continue
+            if not year_s and candidate > today:
+                candidate = date(year - 1, month, day)
+            return candidate, m.span()
+
+    if m := _LAST_WEEKDAY_RE.search(lowered):
+        target = _WEEKDAYS[m.group(1).lower()]
+        delta = (today.weekday() - target) % 7
+        delta = delta or 7  # bare weekday name means the most recent past one
+        return today - timedelta(days=delta), m.span()
+
+    return today, None
+
+
+def _clean_description(text: str, cuts: list[tuple[int, int]]) -> str:
+    """Remove consumed spans, currency noise and filler words."""
+    chars = list(text)
+    for start, end in cuts:
+        for i in range(start, min(end, len(chars))):
+            chars[i] = " "
+    remaining = "".join(chars)
+
+    remaining = re.sub(r"[₹$€£¥₽₩₪₫₺₦₴₸฿₡₱﷼]", " ", remaining)
+    remaining = re.sub(r"\b[A-Z]{3}\b", " ", remaining)
+    remaining = _TAG_RE.sub(" ", remaining)
+    remaining = re.sub(r"[^\w\s&'-]", " ", remaining)
+
+    words = [w for w in remaining.split() if w.lower() not in _FILLER]
+    return re.sub(r"\s+", " ", " ".join(words)).strip()
+
+
+def parse_expense(
+    text: str, default_currency: str = "INR", today: Optional[date] = None
+) -> Optional[ExpenseDraft]:
+    """Parse one free-text line into a draft, or None if no amount is present."""
+    if not text or not text.strip():
+        return None
+
+    amount = parse_amount(text, default_currency)
+    if amount is None:
+        return None
+
+    occurred_on, date_span = parse_date_hint(text, today)
+
+    cuts = [amount.span]
+    if date_span:
+        cuts.append(date_span)
+
+    description = _clean_description(text, cuts)
+
+    # An explicit #tag overrides keyword matching.
+    tag_match = _TAG_RE.search(text)
+    if tag_match:
+        category = coerce(tag_match.group(1))
+        confidence = 1.0
+    else:
+        category, confidence = categorise(description)
+
+    return ExpenseDraft(
+        amount_minor=amount.minor,
+        currency=amount.currency or default_currency.upper(),
+        description=description or "unlabelled",
+        occurred_on=occurred_on,
+        category=category,
+        confidence=1.0 if confidence > 0 else 0.6,
+        raw=text.strip(),
+    )

finbot/registry.py

@@ -0,0 +1,128 @@
+"""Feature registration and update routing.
+
+Dispatch order for one incoming update:
+
+1. If it carries a file -> ``handle_attachment`` on each feature by priority.
+2. If it starts with a slash -> the feature that owns that command.
+3. Otherwise -> ``handle_message`` on each feature by priority.
+
+First non-``None`` reply wins. A feature that returns ``None`` is declining,
+which lets several features coexist over the same input without knowing about
+each other.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterable, Optional
+
+from .features.base import BotContext, CommandSpec, Feature, Reply
+
+log = logging.getLogger(__name__)
+
+
+class DuplicateCommand(ValueError):
+    pass
+
+
+class FeatureRegistry:
+    def __init__(self) -> None:
+        self._features: list[Feature] = []
+        self._commands: dict[str, tuple[Feature, CommandSpec]] = {}
+
+    def register(self, feature: Feature) -> Feature:
+        for spec in feature.commands():
+            for name in (spec.name, *spec.aliases):
+                if name in self._commands:
+                    owner = self._commands[name][0].name
+                    raise DuplicateCommand(
+                        f"/{name} is already provided by feature '{owner}'"
+                    )
+                self._commands[name] = (feature, spec)
+        self._features.append(feature)
+        self._features.sort(key=lambda f: f.priority)
+        return feature
+
+    def register_all(self, features: Iterable[Feature]) -> None:
+        for feature in features:
+            self.register(feature)
+
+    @property
+    def features(self) -> list[Feature]:
+        return list(self._features)
+
+    def known_command(self, name: str) -> bool:
+        return name in self._commands
+
+    def dispatch(self, ctx: BotContext) -> Optional[Reply]:
+        if ctx.attachment is not None:
+            for feature in self._features:
+                try:
+                    if reply := feature.handle_attachment(ctx):
+                        return reply
+                except Exception:
+                    log.exception("Feature %s failed on attachment", feature.name)
+                    return Reply(
+                        "Something went wrong reading that file. "
+                        "The error is in the Space logs."
+                    )
+            return None
+
+        if ctx.command:
+            entry = self._commands.get(ctx.command)
+            if entry is None:
+                return Reply(
+                    f"I don't know /{_escape(ctx.command)}. Try /help for what I can do."
+                )
+            feature, _spec = entry
+            try:
+                return feature.handle_command(ctx)
+            except Exception:
+                log.exception("Feature %s failed on /%s", feature.name, ctx.command)
+                return Reply(
+                    "Something went wrong running that command. "
+                    "The error is in the Space logs."
+                )
+
+        for feature in self._features:
+            try:
+                if reply := feature.handle_message(ctx):
+                    return reply
+            except Exception:
+                log.exception("Feature %s failed on message", feature.name)
+                return Reply(
+                    "Something went wrong handling that. The error is in the Space logs."
+                )
+        return None
+
+    def help_text(self) -> str:
+        """Grouped /help built from whatever is registered."""
+        blocks: list[str] = []
+        for feature in self._features:
+            visible = [s for s in feature.commands() if not s.hidden]
+            if not visible:
+                continue
+            lines = [f"<b>{_escape(feature.description or feature.name)}</b>"]
+            for spec in visible:
+                lines.append(f"<code>{_escape(spec.usage)}</code> — {_escape(spec.help)}")
+            blocks.append("\n".join(lines))
+        return "\n\n".join(blocks)
+
+    def telegram_commands(self) -> list[dict[str, str]]:
+        """Payload for Telegram's setMyCommands."""
+        seen: set[str] = set()
+        out: list[dict[str, str]] = []
+        for feature in self._features:
+            for spec in feature.commands():
+                if spec.hidden or spec.name in seen:
+                    continue
+                seen.add(spec.name)
+                # Telegram caps descriptions at 256 chars.
+                out.append({"command": spec.name, "description": spec.help[:256]})
+        return out
+
+
+def _escape(text: str) -> str:
+    from .render import escape
+
+    return escape(text)

finbot/render.py

@@ -0,0 +1,207 @@
+"""Telegram message rendering.
+
+Uses Telegram's **HTML** parse mode rather than MarkdownV2. MarkdownV2 requires
+escaping ``. - ( ) ! +`` and more, which appear in virtually every line of
+financial output (``₹1,234.56``, ``-12%``, ``(30%)``); one missed escape and
+Telegram rejects the whole message. HTML needs only ``< > &`` escaped, so the
+failure surface is far smaller.
+"""
+
+from __future__ import annotations
+
+import html
+from datetime import date
+from typing import Iterable
+
+from .analytics import BudgetStatus, Recurring
+from .categories import label as category_label
+from .models import Expense, PendingImport, Summary
+from .money import format_money
+
+BAR_WIDTH = 10
+
+
+def escape(text: str) -> str:
+    return html.escape(str(text or ""), quote=False)
+
+
+def bar(fraction: float, width: int = BAR_WIDTH) -> str:
+    filled = max(0, min(width, round(fraction * width)))
+    return "█" * filled + "░" * (width - filled)
+
+
+def money(minor: int, currency: str) -> str:
+    return escape(format_money(minor, currency))
+
+
+def expense_line(expense: Expense) -> str:
+    label = expense.merchant or expense.description or "unlabelled"
+    return (
+        f"{money(expense.amount_minor, expense.currency)} · {escape(label)} "
+        f"<i>{escape(category_label(expense.category))}</i> · "
+        f"{expense.occurred_on.isoformat()}"
+    )
+
+
+def logged(expense: Expense, note: str = "") -> str:
+    parts = [
+        f"✅ Logged {money(expense.amount_minor, expense.currency)} — "
+        f"{escape(expense.description or expense.merchant or 'unlabelled')}",
+        f"<i>{escape(category_label(expense.category))}</i> · {expense.occurred_on.isoformat()}",
+    ]
+    if note:
+        parts.append(escape(note))
+    parts.append("<i>/undo to remove</i>")
+    return "\n".join(parts)
+
+
+def summary(summ: Summary) -> str:
+    if summ.count == 0:
+        return (
+            f"<b>{escape(summ.label)}</b>\nNothing logged "
+            f"({summ.start.isoformat()} → {summ.end.isoformat()})."
+        )
+
+    lines = [
+        f"<b>{escape(summ.label)}</b> · {money(summ.total_minor, summ.currency)} "
+        f"<i>({summ.count} txns)</i>"
+    ]
+
+    if (delta := summ.delta_pct) is not None:
+        arrow = "▲" if delta > 0 else "▼"
+        lines.append(
+            f"{arrow} {abs(delta):.0f}% vs previous "
+            f"({money(summ.previous_total_minor or 0, summ.currency)})"
+        )
+
+    lines.append("")
+    top = summ.by_category[:8]
+    for name, amount in top:
+        fraction = amount / summ.total_minor if summ.total_minor else 0
+        lines.append(
+            f"<code>{bar(fraction)}</code> {escape(category_label(name))} "
+            f"{money(amount, summ.currency)} <i>({fraction * 100:.0f}%)</i>"
+        )
+
+    if len(summ.by_category) > len(top):
+        rest = sum(amount for _, amount in summ.by_category[len(top):])
+        lines.append(f"<i>+{len(summ.by_category) - len(top)} more · {money(rest, summ.currency)}</i>")
+
+    return "\n".join(lines)
+
+
+def expense_list(expenses: Iterable[Expense], title: str, limit: int = 20) -> str:
+    items = list(expenses)[:limit]
+    if not items:
+        return f"<b>{escape(title)}</b>\nNothing to show."
+    lines = [f"<b>{escape(title)}</b>"]
+    lines.extend(f"• {expense_line(e)}" for e in items)
+    return "\n".join(lines)
+
+
+def pending_import(pending: PendingImport) -> str:
+    totals = pending.total_by_currency()
+    total_str = " + ".join(money(v, k) for k, v in sorted(totals.items()))
+
+    lines = [
+        f"<b>Found {len(pending.drafts)} transactions</b> in that "
+        f"{escape(pending.source.upper())} · {total_str}",
+    ]
+
+    detail = []
+    if pending.duplicates:
+        detail.append(f"{pending.duplicates} already logged (skipped)")
+    if pending.skipped:
+        detail.append(f"{pending.skipped} unreadable")
+    if pending.label:
+        detail.append(pending.label)
+    if detail:
+        lines.append(f"<i>{escape(' · '.join(detail))}</i>")
+
+    lines.append("")
+    preview = pending.drafts[:8]
+    for draft in preview:
+        lines.append(
+            f"• {money(draft.amount_minor, draft.currency)} · "
+            f"{escape(draft.description[:40])} · "
+            f"<i>{escape(category_label(draft.category))}</i> · "
+            f"{draft.occurred_on.isoformat()}"
+        )
+    if len(pending.drafts) > len(preview):
+        lines.append(f"<i>…and {len(pending.drafts) - len(preview)} more</i>")
+
+    lines.append("")
+    lines.append("These were read by a model and <b>not saved yet</b>.")
+    lines.append("/confirm to save · /cancel to discard")
+    return "\n".join(lines)
+
+
+def recurring_list(items: list[Recurring], currency: str) -> str:
+    if not items:
+        return (
+            "<b>Recurring charges</b>\nNone detected yet — this needs a few "
+            "months of history to spot a pattern."
+        )
+
+    lines = ["<b>Recurring charges</b>"]
+    for item in items[:15]:
+        lines.append(
+            f"• {money(item.typical_minor, item.currency)}/mo · {escape(item.label)} "
+            f"<i>({item.months} months, last {item.last_seen.isoformat()})</i>"
+        )
+
+    annual = sum(r.annualised_minor for r in items if r.currency == currency)
+    if annual:
+        lines.append("")
+        lines.append(f"<b>≈ {money(annual, currency)} a year</b> if all continue.")
+    return "\n".join(lines)
+
+
+def budget_list(statuses: list[BudgetStatus]) -> str:
+    if not statuses:
+        return (
+            "<b>Budgets</b>\nNone set.\n"
+            "<code>/budget food_dining 8000</code> to set one."
+        )
+
+    lines = ["<b>Budgets this month</b>"]
+    for status in statuses:
+        mark = "⚠️" if status.over else ("🟡" if status.pct >= 80 else "🟢")
+        lines.append(
+            f"{mark} <code>{bar(status.pct / 100)}</code> "
+            f"{escape(category_label(status.category))} "
+            f"{money(status.spent_minor, status.currency)}/"
+            f"{money(status.limit_minor, status.currency)} "
+            f"<i>({status.pct:.0f}%)</i>"
+        )
+    return "\n".join(lines)
+
+
+def csv_export(expenses: list[Expense]) -> str:
+    import csv
+    import io
+
+    buffer = io.StringIO()
+    writer = csv.writer(buffer)
+    writer.writerow(
+        ["date", "amount", "currency", "category", "merchant", "description", "source"]
+    )
+    for expense in expenses:
+        from .money import from_minor
+
+        writer.writerow(
+            [
+                expense.occurred_on.isoformat(),
+                f"{from_minor(expense.amount_minor, expense.currency):.2f}",
+                expense.currency,
+                expense.category,
+                expense.merchant,
+                expense.description,
+                expense.source,
+            ]
+        )
+    return buffer.getvalue()
+
+
+def period_footer(start: date, end: date) -> str:
+    return f"<i>{start.isoformat()} → {end.isoformat()}</i>"

finbot/store.py

@@ -0,0 +1,412 @@
+"""Durable storage: SQLite locally, mirrored to a private Hub dataset.
+
+Hugging Face Space disk is ephemeral -- it is wiped on every restart, sleep and
+rebuild. A finance bot that stored its ledger only on that disk would silently
+lose everything the first time the Space went to sleep, which is the worst
+possible failure for this application because it is invisible until you go
+looking for old data.
+
+So: SQLite is the working copy, and a ``CommitScheduler`` mirrors the database
+file into a **private** dataset repo on a timer. On boot the newest copy is
+pulled back down. Set ``HF_DATASET_REPO`` and this is handled; leave it unset
+and the bot runs local-only, which is fine for development and lossy on a
+Space -- ``/status`` says so out loud.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import sqlite3
+import threading
+from datetime import date, datetime, timezone
+from pathlib import Path
+from typing import Iterable, Optional, Sequence
+
+from .config import Settings
+from .models import Budget, Expense
+
+log = logging.getLogger(__name__)
+
+DB_FILENAME = "finbot.db"
+SCHEMA_VERSION = 1
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS expenses (
+    id           TEXT PRIMARY KEY,
+    user_id      INTEGER NOT NULL,
+    amount_minor INTEGER NOT NULL,
+    currency     TEXT    NOT NULL,
+    description  TEXT    NOT NULL DEFAULT '',
+    category     TEXT    NOT NULL DEFAULT 'other',
+    merchant     TEXT    NOT NULL DEFAULT '',
+    occurred_on  TEXT    NOT NULL,
+    source       TEXT    NOT NULL DEFAULT 'text',
+    batch_id     TEXT    NOT NULL DEFAULT '',
+    note         TEXT    NOT NULL DEFAULT '',
+    confidence   REAL    NOT NULL DEFAULT 1.0,
+    dedupe_key   TEXT    NOT NULL DEFAULT '',
+    created_at   TEXT    NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_expenses_user_date
+    ON expenses(user_id, occurred_on);
+CREATE INDEX IF NOT EXISTS idx_expenses_batch
+    ON expenses(batch_id);
+-- Non-unique on purpose: two identical coffees on one day are both real. Import
+-- dedupe is done explicitly against this index, so re-importing a statement
+-- collapses while manual entry stays free to repeat.
+CREATE INDEX IF NOT EXISTS idx_expenses_dedupe
+    ON expenses(user_id, dedupe_key);
+
+CREATE TABLE IF NOT EXISTS budgets (
+    user_id      INTEGER NOT NULL,
+    category     TEXT    NOT NULL,
+    amount_minor INTEGER NOT NULL,
+    currency     TEXT    NOT NULL,
+    period       TEXT    NOT NULL DEFAULT 'monthly',
+    created_at   TEXT    NOT NULL,
+    PRIMARY KEY (user_id, category, period)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+"""
+
+
+def _row_to_expense(row: sqlite3.Row) -> Expense:
+    return Expense(
+        id=row["id"],
+        user_id=row["user_id"],
+        amount_minor=row["amount_minor"],
+        currency=row["currency"],
+        description=row["description"],
+        category=row["category"],
+        merchant=row["merchant"],
+        occurred_on=date.fromisoformat(row["occurred_on"]),
+        source=row["source"],
+        batch_id=row["batch_id"],
+        note=row["note"],
+        confidence=row["confidence"],
+        created_at=datetime.fromisoformat(row["created_at"]),
+    )
+
+
+class Store:
+    """SQLite-backed ledger with optional Hub mirroring."""
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.data_dir = Path(settings.data_dir)
+        self.db_path = self.data_dir / DB_FILENAME
+        self._lock = threading.RLock()
+        self._scheduler = None
+        self.sync_status = "disabled"
+
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        if settings.sync_enabled:
+            self._restore_from_hub()
+
+        self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._migrate()
+
+        if settings.sync_enabled:
+            self._start_sync()
+
+    # ---------------------------------------------------------------- schema
+
+    def _migrate(self) -> None:
+        with self._lock:
+            self._conn.executescript(_SCHEMA)
+            self._conn.execute(
+                "INSERT INTO meta(key, value) VALUES('schema_version', ?) "
+                "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                (str(SCHEMA_VERSION),),
+            )
+            self._conn.commit()
+
+    # ------------------------------------------------------------------ sync
+
+    def _restore_from_hub(self) -> None:
+        """Pull the last mirrored database down before opening it."""
+        from huggingface_hub import hf_hub_download
+        from huggingface_hub.utils import (
+            EntryNotFoundError,
+            RepositoryNotFoundError,
+        )
+
+        try:
+            cached = hf_hub_download(
+                repo_id=self.settings.hf_dataset_repo,
+                filename=DB_FILENAME,
+                repo_type="dataset",
+                token=self.settings.hf_token,
+            )
+        except (EntryNotFoundError, RepositoryNotFoundError):
+            log.info("No existing ledger in the dataset repo; starting fresh.")
+            return
+        except Exception as exc:  # network, auth, anything transient
+            # Do NOT clobber a local db we may already have.
+            log.warning("Could not restore ledger from Hub: %s", exc)
+            self.sync_status = f"restore failed: {exc}"
+            return
+
+        shutil.copyfile(cached, self.db_path)
+        log.info("Restored ledger from %s", self.settings.hf_dataset_repo)
+
+    def _start_sync(self) -> None:
+        from huggingface_hub import CommitScheduler, create_repo
+
+        lock = self._lock
+
+        class _LockedScheduler(CommitScheduler):
+            """Snapshot the DB only while no write is in flight.
+
+            Without this the uploader can read the file mid-transaction and
+            mirror a torn database.
+            """
+
+            def push_to_hub(self, *args, **kwargs):
+                with lock:
+                    return super().push_to_hub(*args, **kwargs)
+
+        try:
+            create_repo(
+                repo_id=self.settings.hf_dataset_repo,
+                repo_type="dataset",
+                private=True,
+                exist_ok=True,
+                token=self.settings.hf_token,
+            )
+            self._scheduler = _LockedScheduler(
+                repo_id=self.settings.hf_dataset_repo,
+                repo_type="dataset",
+                folder_path=self.data_dir,
+                path_in_repo="",
+                every=max(1, self.settings.sync_every_minutes),
+                allow_patterns=[DB_FILENAME],
+                private=True,
+                token=self.settings.hf_token,
+                squash_history=True,
+            )
+            self.sync_status = (
+                f"mirroring to {self.settings.hf_dataset_repo} "
+                f"every {self.settings.sync_every_minutes}m"
+            )
+            log.info("Ledger sync active: %s", self.sync_status)
+        except Exception as exc:
+            self.sync_status = f"failed: {exc}"
+            log.error("Could not start ledger sync: %s", exc)
+
+    def flush(self) -> None:
+        """Force an immediate mirror. Called on shutdown and after imports."""
+        if self._scheduler is None:
+            return
+        try:
+            self._scheduler.push_to_hub()
+        except Exception as exc:
+            log.error("Ledger flush failed: %s", exc)
+
+    def close(self) -> None:
+        if self._scheduler is not None:
+            try:
+                self._scheduler.stop()
+            except Exception:
+                pass
+        self.flush()
+        with self._lock:
+            self._conn.close()
+
+    # -------------------------------------------------------------- expenses
+
+    def add_expense(self, expense: Expense) -> Expense:
+        with self._lock:
+            self._conn.execute(
+                """INSERT INTO expenses
+                   (id, user_id, amount_minor, currency, description, category,
+                    merchant, occurred_on, source, batch_id, note, confidence,
+                    dedupe_key, created_at)
+                   VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                (
+                    expense.id,
+                    expense.user_id,
+                    expense.amount_minor,
+                    expense.currency.upper(),
+                    expense.description,
+                    expense.category,
+                    expense.merchant,
+                    expense.occurred_on.isoformat(),
+                    expense.source,
+                    expense.batch_id,
+                    expense.note,
+                    expense.confidence,
+                    expense.dedupe_key,
+                    expense.created_at.isoformat(),
+                ),
+            )
+            self._conn.commit()
+        return expense
+
+    def add_expenses(self, expenses: Sequence[Expense]) -> int:
+        for expense in expenses:
+            self.add_expense(expense)
+        return len(expenses)
+
+    def existing_dedupe_keys(self, user_id: int, keys: Iterable[str]) -> set[str]:
+        keys = [k for k in keys if k]
+        if not keys:
+            return set()
+        found: set[str] = set()
+        with self._lock:
+            # Chunked to stay under SQLite's variable limit on big imports.
+            for i in range(0, len(keys), 500):
+                chunk = keys[i : i + 500]
+                placeholders = ",".join("?" * len(chunk))
+                rows = self._conn.execute(
+                    f"SELECT dedupe_key FROM expenses "
+                    f"WHERE user_id = ? AND dedupe_key IN ({placeholders})",
+                    (user_id, *chunk),
+                ).fetchall()
+                found.update(r["dedupe_key"] for r in rows)
+        return found
+
+    def list_expenses(
+        self,
+        user_id: int,
+        start: Optional[date] = None,
+        end: Optional[date] = None,
+        category: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> list[Expense]:
+        clauses = ["user_id = ?"]
+        params: list[object] = [user_id]
+        if start:
+            clauses.append("occurred_on >= ?")
+            params.append(start.isoformat())
+        if end:
+            clauses.append("occurred_on <= ?")
+            params.append(end.isoformat())
+        if category:
+            clauses.append("category = ?")
+            params.append(category)
+
+        sql = (
+            f"SELECT * FROM expenses WHERE {' AND '.join(clauses)} "
+            f"ORDER BY occurred_on DESC, created_at DESC"
+        )
+        if limit:
+            sql += f" LIMIT {int(limit)}"
+
+        with self._lock:
+            rows = self._conn.execute(sql, params).fetchall()
+        return [_row_to_expense(r) for r in rows]
+
+    def last_expense(self, user_id: int) -> Optional[Expense]:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM expenses WHERE user_id = ? "
+                "ORDER BY created_at DESC LIMIT 1",
+                (user_id,),
+            ).fetchone()
+        return _row_to_expense(row) if row else None
+
+    def delete_expense(self, user_id: int, expense_id: str) -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "DELETE FROM expenses WHERE user_id = ? AND id = ?",
+                (user_id, expense_id),
+            )
+            self._conn.commit()
+        return cur.rowcount > 0
+
+    def delete_batch(self, user_id: int, batch_id: str) -> int:
+        if not batch_id:
+            return 0
+        with self._lock:
+            cur = self._conn.execute(
+                "DELETE FROM expenses WHERE user_id = ? AND batch_id = ?",
+                (user_id, batch_id),
+            )
+            self._conn.commit()
+        return cur.rowcount
+
+    def currencies_used(self, user_id: int) -> list[str]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT currency, COUNT(*) AS n FROM expenses WHERE user_id = ? "
+                "GROUP BY currency ORDER BY n DESC",
+                (user_id,),
+            ).fetchall()
+        return [r["currency"] for r in rows]
+
+    def count(self, user_id: Optional[int] = None) -> int:
+        with self._lock:
+            if user_id is None:
+                row = self._conn.execute("SELECT COUNT(*) AS n FROM expenses").fetchone()
+            else:
+                row = self._conn.execute(
+                    "SELECT COUNT(*) AS n FROM expenses WHERE user_id = ?", (user_id,)
+                ).fetchone()
+        return int(row["n"])
+
+    # --------------------------------------------------------------- budgets
+
+    def set_budget(self, budget: Budget) -> Budget:
+        with self._lock:
+            self._conn.execute(
+                """INSERT INTO budgets
+                   (user_id, category, amount_minor, currency, period, created_at)
+                   VALUES (?,?,?,?,?,?)
+                   ON CONFLICT(user_id, category, period) DO UPDATE SET
+                     amount_minor = excluded.amount_minor,
+                     currency     = excluded.currency""",
+                (
+                    budget.user_id,
+                    budget.category,
+                    budget.amount_minor,
+                    budget.currency.upper(),
+                    budget.period,
+                    budget.created_at.isoformat(),
+                ),
+            )
+            self._conn.commit()
+        return budget
+
+    def get_budgets(self, user_id: int) -> list[Budget]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM budgets WHERE user_id = ? ORDER BY category",
+                (user_id,),
+            ).fetchall()
+        return [
+            Budget(
+                user_id=r["user_id"],
+                category=r["category"],
+                amount_minor=r["amount_minor"],
+                currency=r["currency"],
+                period=r["period"],
+                created_at=datetime.fromisoformat(r["created_at"]),
+            )
+            for r in rows
+        ]
+
+    def delete_budget(self, user_id: int, category: str, period: str = "monthly") -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "DELETE FROM budgets WHERE user_id = ? AND category = ? AND period = ?",
+                (user_id, category, period),
+            )
+            self._conn.commit()
+        return cur.rowcount > 0
+
+
+def open_store(settings: Settings) -> Store:
+    return Store(settings)
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)

finbot/telegram.py

@@ -0,0 +1,252 @@
+"""Telegram Bot API client and update parsing.
+
+Webhook rather than long polling, because free Spaces sleep after inactivity
+and a sleeping container cannot poll. Telegram's POST wakes it instead.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+API_ROOT = "https://api.telegram.org"
+
+#: getFile / downloads are capped at 20 MB by the Bot API itself.
+MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024
+
+#: Telegram rejects messages over 4096 characters.
+MAX_MESSAGE_CHARS = 4096
+
+
+@dataclass
+class ParsedUpdate:
+    update_id: int
+    user_id: int
+    chat_id: int
+    text: str = ""
+    command: str = ""
+    args: str = ""
+    caption: str = ""
+    file_id: str = ""
+    file_name: str = ""
+    mime_type: str = ""
+    file_kind: str = ""
+    file_size: int = 0
+
+    @property
+    def has_file(self) -> bool:
+        return bool(self.file_id)
+
+
+def parse_update(update: dict[str, Any], bot_username: str = "") -> Optional[ParsedUpdate]:
+    """Normalise a Telegram update. Returns None for anything we don't handle."""
+    message = update.get("message") or update.get("edited_message")
+    if not isinstance(message, dict):
+        return None
+
+    sender = message.get("from") or {}
+    chat = message.get("chat") or {}
+    if not sender.get("id") or not chat.get("id"):
+        return None
+
+    parsed = ParsedUpdate(
+        update_id=int(update.get("update_id", 0)),
+        user_id=int(sender["id"]),
+        chat_id=int(chat["id"]),
+        caption=(message.get("caption") or "").strip(),
+    )
+
+    text = (message.get("text") or "").strip()
+    parsed.text = text
+
+    if text.startswith("/"):
+        head, _, rest = text.partition(" ")
+        command = head[1:]
+        # Group chats deliver "/month@MyBot"; strip the mention.
+        if "@" in command:
+            command, _, mentioned = command.partition("@")
+            if bot_username and mentioned.lower() != bot_username.lower():
+                return None
+        parsed.command = command.lower()
+        parsed.args = rest.strip()
+
+    if photos := message.get("photo"):
+        # PhotoSize list runs smallest to largest; the largest reads best.
+        largest = max(photos, key=lambda p: p.get("file_size") or 0)
+        parsed.file_id = largest.get("file_id", "")
+        parsed.file_kind = "photo"
+        parsed.mime_type = "image/jpeg"
+        parsed.file_size = int(largest.get("file_size") or 0)
+    elif document := message.get("document"):
+        parsed.file_id = document.get("file_id", "")
+        parsed.file_kind = "document"
+        parsed.file_name = document.get("file_name", "")
+        parsed.mime_type = document.get("mime_type", "")
+        parsed.file_size = int(document.get("file_size") or 0)
+
+    return parsed
+
+
+def chunk_message(text: str, limit: int = MAX_MESSAGE_CHARS) -> list[str]:
+    """Split a long reply on line boundaries so HTML tags stay balanced."""
+    if len(text) <= limit:
+        return [text]
+
+    chunks: list[str] = []
+    current: list[str] = []
+    length = 0
+    for line in text.split("\n"):
+        # +1 for the newline we will rejoin with.
+        if length + len(line) + 1 > limit and current:
+            chunks.append("\n".join(current))
+            current, length = [], 0
+        current.append(line)
+        length += len(line) + 1
+    if current:
+        chunks.append("\n".join(current))
+    return chunks
+
+
+class SeenUpdates:
+    """Bounded set of processed update ids.
+
+    We answer Telegram's webhook immediately and process in the background, so
+    a slow reply can cause Telegram to redeliver. Without this, one statement
+    could be imported twice.
+    """
+
+    def __init__(self, capacity: int = 512):
+        self.capacity = capacity
+        self._seen: OrderedDict[int, None] = OrderedDict()
+
+    def add_if_new(self, update_id: int) -> bool:
+        if update_id in self._seen:
+            return False
+        self._seen[update_id] = None
+        while len(self._seen) > self.capacity:
+            self._seen.popitem(last=False)
+        return True
+
+
+class TelegramClient:
+    def __init__(self, token: str):
+        self.token = token
+        self._client: Optional[httpx.AsyncClient] = None
+        self.username = ""
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.token)
+
+    def _http(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=f"{API_ROOT}/bot{self.token}",
+                timeout=httpx.Timeout(60.0, connect=10.0),
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def _call(self, method: str, **payload: Any) -> dict:
+        response = await self._http().post(f"/{method}", json=payload)
+        data = response.json()
+        if not data.get("ok"):
+            raise RuntimeError(f"{method} failed: {data.get('description', data)}")
+        return data.get("result") or {}
+
+    async def get_me(self) -> dict:
+        result = await self._call("getMe")
+        self.username = result.get("username", "")
+        return result
+
+    async def send_message(
+        self, chat_id: int, text: str, parse_mode: Optional[str] = "HTML"
+    ) -> None:
+        for chunk in chunk_message(text):
+            payload: dict[str, Any] = {
+                "chat_id": chat_id,
+                "text": chunk,
+                "link_preview_options": {"is_disabled": True},
+            }
+            if parse_mode:
+                payload["parse_mode"] = parse_mode
+            try:
+                await self._call("sendMessage", **payload)
+            except RuntimeError as exc:
+                # Malformed HTML from a merchant name shouldn't swallow the
+                # reply -- retry once as plain text so the user still sees it.
+                if parse_mode:
+                    log.warning("HTML send failed (%s); retrying as plain text", exc)
+                    await self._call(
+                        "sendMessage",
+                        chat_id=chat_id,
+                        text=_strip_tags(chunk),
+                    )
+                else:
+                    raise
+
+    async def send_document(
+        self, chat_id: int, filename: str, data: bytes, caption: str = ""
+    ) -> None:
+        files = {"document": (filename, data, "text/csv")}
+        form: dict[str, Any] = {"chat_id": str(chat_id)}
+        if caption:
+            form["caption"] = caption[:1024]
+            form["parse_mode"] = "HTML"
+        response = await self._http().post("/sendDocument", data=form, files=files)
+        payload = response.json()
+        if not payload.get("ok"):
+            raise RuntimeError(f"sendDocument failed: {payload.get('description')}")
+
+    async def send_typing(self, chat_id: int) -> None:
+        try:
+            await self._call("sendChatAction", chat_id=chat_id, action="typing")
+        except RuntimeError:
+            pass  # cosmetic only
+
+    async def download(self, file_id: str) -> tuple[bytes, str]:
+        """Fetch a file by id. Returns (bytes, telegram_file_path)."""
+        info = await self._call("getFile", file_id=file_id)
+        file_path = info.get("file_path")
+        if not file_path:
+            raise RuntimeError("Telegram did not return a file path")
+
+        url = f"{API_ROOT}/file/bot{self.token}/{file_path}"
+        async with httpx.AsyncClient(timeout=httpx.Timeout(120.0)) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            return response.content, file_path
+
+    async def set_webhook(self, url: str, secret: str) -> dict:
+        return await self._call(
+            "setWebhook",
+            url=url,
+            secret_token=secret,
+            allowed_updates=["message", "edited_message"],
+            drop_pending_updates=True,
+        )
+
+    async def delete_webhook(self) -> dict:
+        return await self._call("deleteWebhook", drop_pending_updates=True)
+
+    async def get_webhook_info(self) -> dict:
+        return await self._call("getWebhookInfo")
+
+    async def set_my_commands(self, commands: list[dict[str, str]]) -> dict:
+        return await self._call("setMyCommands", commands=commands)
+
+
+def _strip_tags(text: str) -> str:
+    import re
+
+    return re.sub(r"<[^>]+>", "", text)

requirements.txt

@@ -0,0 +1,9 @@
+fastapi>=0.115,<0.121
+uvicorn[standard]>=0.32,<0.40
+httpx>=0.27,<0.29
+pydantic>=2.9,<3
+pydantic-settings>=2.6,<3
+huggingface_hub>=0.34,<1.0
+pdfplumber>=0.11,<0.12
+openpyxl>=3.1,<4
+python-dateutil>=2.9,<3

tests/test_analytics.py

@@ -0,0 +1,201 @@
+from datetime import date
+
+import pytest
+
+from finbot.analytics import (
+    by_category,
+    budget_status,
+    detect_recurring,
+    dominant_currency,
+    month_bounds,
+    period_bounds,
+    previous_month_bounds,
+    project_month_end,
+    split_by_currency,
+    summarise,
+    top_merchants,
+    total_minor,
+)
+from finbot.models import Budget, Expense
+
+TODAY = date(2026, 8, 15)
+
+
+def make(amount, category="other", currency="INR", day=TODAY, merchant="", desc="x"):
+    return Expense(
+        user_id=1,
+        amount_minor=amount,
+        currency=currency,
+        description=desc,
+        category=category,
+        occurred_on=day,
+        merchant=merchant,
+    )
+
+
+class TestPeriods:
+    @pytest.mark.parametrize(
+        "name,start,end",
+        [
+            ("today", TODAY, TODAY),
+            ("yesterday", date(2026, 8, 14), date(2026, 8, 14)),
+            ("week", date(2026, 8, 10), TODAY),  # Monday of that week
+            ("month", date(2026, 8, 1), TODAY),
+            ("last_month", date(2026, 7, 1), date(2026, 7, 31)),
+            ("year", date(2026, 1, 1), TODAY),
+            ("30d", date(2026, 7, 17), TODAY),
+        ],
+    )
+    def test_bounds(self, name, start, end):
+        got_start, got_end, _label = period_bounds(name, TODAY)
+        assert (got_start, got_end) == (start, end)
+
+    def test_unknown_period_defaults_to_month(self):
+        start, end, _ = period_bounds("nonsense", TODAY)
+        assert (start, end) == (date(2026, 8, 1), TODAY)
+
+    def test_month_bounds_handles_month_length(self):
+        assert month_bounds(date(2026, 2, 10))[1] == date(2026, 2, 28)
+
+    def test_previous_month_across_a_year_boundary(self):
+        assert previous_month_bounds(date(2026, 1, 5)) == (
+            date(2025, 12, 1),
+            date(2025, 12, 31),
+        )
+
+
+class TestAggregation:
+    def test_total_and_by_category(self):
+        expenses = [
+            make(10000, "food_dining"),
+            make(5000, "food_dining"),
+            make(20000, "rent"),
+        ]
+        assert total_minor(expenses) == 35000
+        assert by_category(expenses) == [("rent", 20000), ("food_dining", 15000)]
+
+    def test_split_by_currency(self):
+        expenses = [make(100, currency="INR"), make(200, currency="USD")]
+        buckets = split_by_currency(expenses)
+        assert set(buckets) == {"INR", "USD"}
+
+    def test_dominant_currency_by_count(self):
+        expenses = [make(100, currency="INR"), make(100, currency="INR"), make(999999, currency="USD")]
+        assert dominant_currency(expenses, "EUR") == "INR"
+
+    def test_dominant_currency_falls_back_when_empty(self):
+        assert dominant_currency([], "SGD") == "SGD"
+
+    def test_summarise_only_counts_the_named_currency(self):
+        expenses = [make(10000, currency="INR"), make(50000, currency="USD")]
+        summary = summarise(expenses, "INR", "Aug", date(2026, 8, 1), TODAY)
+        assert summary.total_minor == 10000
+        assert summary.count == 1
+
+    def test_delta_pct(self):
+        current = [make(15000)]
+        previous = [make(10000)]
+        summary = summarise(current, "INR", "Aug", date(2026, 8, 1), TODAY, previous)
+        assert summary.delta_pct == pytest.approx(50.0)
+
+    def test_delta_pct_is_none_without_a_baseline(self):
+        summary = summarise([make(100)], "INR", "Aug", date(2026, 8, 1), TODAY, [])
+        assert summary.delta_pct is None
+
+    def test_top_merchants(self):
+        expenses = [
+            make(100, merchant="Swiggy"),
+            make(300, merchant="Swiggy"),
+            make(200, merchant="Uber"),
+        ]
+        assert top_merchants(expenses)[0] == ("Swiggy", 400)
+
+
+class TestProjection:
+    def test_projects_to_month_end(self):
+        # 15 days elapsed of a 31-day August, ₹150 spent -> ~₹310.
+        expenses = [make(15000, day=date(2026, 8, 5))]
+        projected = project_month_end(expenses, TODAY)
+        assert projected == pytest.approx(31000, rel=0.01)
+
+
+class TestRecurring:
+    def _monthly(self, merchant, amount, months):
+        return [
+            make(amount, day=date(2026, m, 5), merchant=merchant, desc=merchant)
+            for m in months
+        ]
+
+    def test_detects_a_monthly_subscription(self):
+        expenses = self._monthly("Netflix", 64900, [5, 6, 7])
+        found = detect_recurring(expenses)
+        assert len(found) == 1
+        assert found[0].months == 3
+        assert found[0].typical_minor == 64900
+
+    def test_ignores_charges_in_too_few_months(self):
+        expenses = self._monthly("Netflix", 64900, [6, 7])
+        assert detect_recurring(expenses) == []
+
+    def test_ignores_repeat_spending_with_erratic_amounts(self):
+        # Same shop every month, wildly different amounts -- not a subscription.
+        expenses = [
+            make(10000, day=date(2026, 5, 5), merchant="Bigbasket", desc="Bigbasket"),
+            make(90000, day=date(2026, 6, 5), merchant="Bigbasket", desc="Bigbasket"),
+            make(250000, day=date(2026, 7, 5), merchant="Bigbasket", desc="Bigbasket"),
+        ]
+        assert detect_recurring(expenses) == []
+
+    def test_three_charges_in_one_month_is_not_recurring(self):
+        expenses = [
+            make(64900, day=date(2026, 7, d), merchant="Netflix", desc="Netflix")
+            for d in (1, 10, 20)
+        ]
+        assert detect_recurring(expenses) == []
+
+    def test_normalises_noisy_merchant_strings(self):
+        expenses = [
+            make(64900, day=date(2026, 5, 5), desc="NETFLIX.COM 447192"),
+            make(64900, day=date(2026, 6, 5), desc="NETFLIX.COM 883021"),
+            make(64900, day=date(2026, 7, 5), desc="Netflix"),
+        ]
+        found = detect_recurring(expenses)
+        assert len(found) == 1
+        assert found[0].months == 3
+
+    def test_annualised(self):
+        found = detect_recurring(self._monthly("Netflix", 50000, [5, 6, 7]))
+        assert found[0].annualised_minor == 600000
+
+    def test_separates_currencies(self):
+        expenses = self._monthly("Netflix", 64900, [5, 6, 7]) + [
+            make(1000, day=date(2026, m, 5), merchant="Netflix", desc="Netflix", currency="USD")
+            for m in (5, 6, 7)
+        ]
+        found = detect_recurring(expenses)
+        assert {f.currency for f in found} == {"INR", "USD"}
+
+
+class TestBudgets:
+    def test_status_calculation(self):
+        budgets = [Budget(user_id=1, category="food_dining", amount_minor=100000, currency="INR")]
+        expenses = [make(60000, "food_dining")]
+        status = budget_status(budgets, expenses)[0]
+        assert status.spent_minor == 60000
+        assert status.pct == pytest.approx(60.0)
+        assert status.remaining_minor == 40000
+        assert not status.over
+
+    def test_over_budget(self):
+        budgets = [Budget(user_id=1, category="rent", amount_minor=10000, currency="INR")]
+        status = budget_status(budgets, [make(15000, "rent")])[0]
+        assert status.over
+        assert status.remaining_minor == -5000
+
+    def test_ignores_other_currencies(self):
+        budgets = [Budget(user_id=1, category="rent", amount_minor=10000, currency="INR")]
+        status = budget_status(budgets, [make(99999, "rent", currency="USD")])[0]
+        assert status.spent_minor == 0
+
+    def test_no_budgets_yields_no_statuses(self):
+        assert budget_status([], [make(100)]) == []

tests/test_app.py

@@ -0,0 +1,287 @@
+"""End-to-end webhook tests with a stubbed Telegram transport.
+
+Environment is configured at import time, before the app's lifespan calls
+``get_settings()`` (which is lru_cached, so the first call wins).
+"""
+
+import os
+import tempfile
+
+os.environ.update(
+    {
+        "DATA_DIR": tempfile.mkdtemp(prefix="finbot-test-"),
+        "TELEGRAM_BOT_TOKEN": "",  # keeps lifespan from calling Telegram
+        "TELEGRAM_WEBHOOK_SECRET": "test-secret",
+        "ALLOWED_TELEGRAM_USER_IDS": "42",
+        "HF_TOKEN": "",  # deterministic paths only; no network
+        "HF_DATASET_REPO": "",
+        "DEFAULT_CURRENCY": "INR",
+        "TIMEZONE": "Asia/Kolkata",
+    }
+)
+
+import pytest  # noqa: E402
+from fastapi.testclient import TestClient  # noqa: E402
+
+from app import app  # noqa: E402
+
+SECRET = {"X-Telegram-Bot-Api-Secret-Token": "test-secret"}
+
+
+class FakeTelegram:
+    """Records what would have been sent instead of calling the Bot API."""
+
+    def __init__(self):
+        self.username = "FinBotTest"
+        self.messages: list[tuple[int, str]] = []
+        self.documents: list[tuple[int, str, bytes]] = []
+        self.enabled = True
+
+    async def send_message(self, chat_id, text, parse_mode="HTML"):
+        self.messages.append((chat_id, text))
+
+    async def send_document(self, chat_id, filename, data, caption=""):
+        self.documents.append((chat_id, filename, data))
+
+    async def send_typing(self, chat_id):
+        pass
+
+    async def download(self, file_id):
+        return b"", "file.bin"
+
+    async def close(self):
+        pass
+
+    @property
+    def last(self) -> str:
+        return self.messages[-1][1] if self.messages else ""
+
+
+@pytest.fixture
+def client():
+    with TestClient(app) as test_client:
+        fake = FakeTelegram()
+        app.state.telegram = fake
+        test_client.fake = fake
+        # Isolate each test: empty the ledger and any pending imports.
+        store = app.state.services.store
+        for expense in store.list_expenses(42):
+            store.delete_expense(42, expense.id)
+        app.state.services.pending.clear()
+        yield test_client
+
+
+def send(client, text, user_id=42, update_id=None):
+    import random
+
+    payload = {
+        "update_id": update_id if update_id is not None else random.randint(1, 10**9),
+        "message": {
+            "from": {"id": user_id},
+            "chat": {"id": user_id},
+            "text": text,
+        },
+    }
+    return client.post("/telegram/webhook", json=payload, headers=SECRET)
+
+
+class TestEndpoints:
+    def test_health(self, client):
+        response = client.get("/health")
+        assert response.status_code == 200
+        assert response.json()["status"] == "ok"
+
+    def test_health_leaks_no_ledger_detail(self, client):
+        # The Space may be public; liveness must not publish personal metrics.
+        body = client.get("/health").json()
+        assert set(body) == {"status", "version"}
+
+    def test_index_renders(self, client):
+        response = client.get("/")
+        assert response.status_code == 200
+        assert "Oracle" in response.text
+
+    def test_index_leaks_no_ledger_detail(self, client):
+        send(client, "coffee 250")
+        text = client.get("/").text.lower()
+        for leak in ("rows", "ledger", "mirroring", "not configured", "hf_dataset_repo"):
+            assert leak not in text
+
+    def test_diagnostics_requires_the_secret(self, client):
+        assert client.get("/admin/diagnostics").status_code == 403
+        assert client.get(
+            "/admin/diagnostics", headers={"X-Admin-Secret": "wrong"}
+        ).status_code == 403
+
+    def test_diagnostics_with_the_secret(self, client):
+        response = client.get("/admin/diagnostics", headers={"X-Admin-Secret": "test-secret"})
+        assert response.status_code == 200
+        assert response.json()["ok"] is True
+        assert "rows" in response.json()
+
+
+class TestWebhookSecurity:
+    def test_rejects_a_missing_secret(self, client):
+        response = client.post("/telegram/webhook", json={})
+        assert response.status_code == 403
+
+    def test_rejects_a_wrong_secret(self, client):
+        response = client.post(
+            "/telegram/webhook",
+            json={},
+            headers={"X-Telegram-Bot-Api-Secret-Token": "wrong"},
+        )
+        assert response.status_code == 403
+
+    def test_rejects_malformed_json(self, client):
+        response = client.post("/telegram/webhook", content=b"not json", headers=SECRET)
+        assert response.status_code == 400
+
+    def test_unauthorised_user_is_refused_and_told_their_id(self, client):
+        send(client, "coffee 250", user_id=9999)
+        assert "9999" in client.fake.last
+        assert "allowlist" in client.fake.last
+
+    def test_unauthorised_user_writes_nothing(self, client):
+        send(client, "coffee 250", user_id=9999)
+        assert app.state.services.store.count(9999) == 0
+
+    def test_duplicate_update_is_processed_once(self, client):
+        send(client, "coffee 250", update_id=555)
+        send(client, "coffee 250", update_id=555)
+        assert app.state.services.store.count(42) == 1
+
+
+class TestLoggingFlow:
+    def test_plain_text_is_logged(self, client):
+        response = send(client, "coffee 250")
+        assert response.status_code == 200
+        assert "Logged" in client.fake.last
+        assert "₹250.00" in client.fake.last
+        assert app.state.services.store.count(42) == 1
+
+    def test_text_without_an_amount_gets_guidance(self, client):
+        send(client, "hello there")
+        assert "couldn't find an amount" in client.fake.last
+        assert app.state.services.store.count(42) == 0
+
+    def test_spend_command(self, client):
+        send(client, "/spend 450 swiggy dinner")
+        assert "Logged" in client.fake.last
+        assert app.state.services.store.count(42) == 1
+
+    def test_spend_without_args_explains(self, client):
+        send(client, "/spend")
+        assert "/spend 250 coffee" in client.fake.last
+
+    def test_undo_removes_the_last_entry(self, client):
+        send(client, "coffee 250")
+        send(client, "/undo")
+        assert "Removed" in client.fake.last
+        assert app.state.services.store.count(42) == 0
+
+    def test_undo_with_nothing_to_undo(self, client):
+        send(client, "/undo")
+        assert "Nothing to undo" in client.fake.last
+
+
+class TestSummaries:
+    def test_today(self, client):
+        send(client, "coffee 250")
+        send(client, "300 uber")
+        send(client, "/today")
+        assert "₹550.00" in client.fake.last
+
+    def test_month(self, client):
+        send(client, "1000 rent")
+        send(client, "/month")
+        assert "₹1,000.00" in client.fake.last
+
+    def test_empty_period(self, client):
+        send(client, "/today")
+        assert "Nothing logged" in client.fake.last
+
+    def test_multi_currency_is_reported_separately(self, client):
+        send(client, "coffee 250")
+        send(client, "€40 dinner")
+        send(client, "/today")
+        # Two currencies must never be summed into one figure.
+        assert "Also:" in client.fake.last
+
+    def test_list(self, client):
+        send(client, "coffee 250")
+        send(client, "/list")
+        assert "coffee" in client.fake.last
+
+    def test_report_accepts_a_period(self, client):
+        send(client, "/report last_month")
+        assert client.fake.last
+
+
+class TestBudgets:
+    def test_set_and_view(self, client):
+        send(client, "/budget food_dining 8000")
+        assert "Budget set" in client.fake.last
+        send(client, "/budgets")
+        assert "Food & Dining" in client.fake.last
+
+    def test_budget_tracks_spending(self, client):
+        send(client, "/budget food_dining 1000")
+        send(client, "500 lunch")
+        send(client, "/budgets")
+        assert "50%" in client.fake.last
+
+    def test_unknown_category_is_rejected(self, client):
+        send(client, "/budget nonsense 500")
+        assert "don't recognise" in client.fake.last
+
+    def test_budget_without_amount(self, client):
+        send(client, "/budget groceries")
+        assert "need an amount" in client.fake.last
+
+    def test_categories_listing(self, client):
+        send(client, "/categories")
+        assert "food_dining" in client.fake.last
+
+
+class TestCoreCommands:
+    def test_start(self, client):
+        send(client, "/start")
+        assert "Hello" in client.fake.last
+
+    def test_help_lists_registered_features(self, client):
+        send(client, "/help")
+        text = client.fake.last
+        assert "/spend" in text
+        assert "/budget" in text
+        assert "/advice" in text
+
+    def test_unknown_command(self, client):
+        send(client, "/nonsense")
+        assert "don't know" in client.fake.last
+
+    def test_status_warns_about_ephemeral_storage(self, client):
+        send(client, "/status")
+        # HF_DATASET_REPO is unset in this environment, so it must say so.
+        assert "ephemeral" in client.fake.last.lower()
+
+    def test_whoami(self, client):
+        send(client, "/whoami")
+        assert "42" in client.fake.last
+
+    def test_advice_works_without_inference(self, client):
+        send(client, "500 lunch")
+        send(client, "/advice")
+        assert client.fake.last  # deterministic observations still fire
+
+    def test_export_sends_a_csv(self, client):
+        send(client, "coffee 250")
+        send(client, "/export")
+        assert len(client.fake.documents) == 1
+        _chat, filename, payload = client.fake.documents[0]
+        assert filename.endswith(".csv")
+        assert b"coffee" in payload
+
+    def test_export_with_nothing_logged(self, client):
+        send(client, "/export")
+        assert "Nothing to export" in client.fake.last

tests/test_categories.py

@@ -0,0 +1,86 @@
+import pytest
+
+from finbot.categories import CATEGORIES, categorise, coerce, is_valid, label
+
+
+class TestCategorise:
+    @pytest.mark.parametrize(
+        "text,expected",
+        [
+            ("uber ride home", "transport"),
+            ("netflix monthly", "subscriptions"),
+            ("bigbasket order", "groceries"),
+            ("swiggy dinner", "food_dining"),
+            ("petrol pump", "fuel"),
+            ("electricity bill", "utilities"),
+            ("apollo pharmacy", "health"),
+            ("bookmyshow tickets", "entertainment"),
+            ("amazon order", "shopping"),
+            ("atm withdrawal", "cash"),
+            ("salary credited", "income"),
+        ],
+    )
+    def test_keyword_hits(self, text, expected):
+        category, confidence = categorise(text)
+        assert category == expected
+        assert confidence == 1.0
+
+    def test_unknown_returns_other_with_zero_confidence(self):
+        category, confidence = categorise("blorptastic widget")
+        assert category == "other"
+        assert confidence == 0.0
+
+    def test_empty_input(self):
+        assert categorise("") == ("other", 0.0)
+
+    def test_specificity_order_fuel_beats_transport(self):
+        # A petrol pump is fuel, even though it is transport-adjacent.
+        assert categorise("indian oil petrol")[0] == "fuel"
+
+    def test_specificity_order_subscription_beats_entertainment(self):
+        assert categorise("netflix")[0] == "subscriptions"
+
+    def test_word_boundaries_prevent_false_hits(self):
+        # "cashew" must not match the "cash" keyword.
+        assert categorise("cashew nuts")[0] != "cash"
+        # "gasket" must not match "gas station".
+        assert categorise("engine gasket")[0] != "fuel"
+
+    def test_merchant_is_considered(self):
+        category, _ = categorise("monthly charge", merchant="Spotify")
+        assert category == "subscriptions"
+
+    def test_case_insensitive(self):
+        assert categorise("UBER RIDE")[0] == "transport"
+
+
+class TestCoerce:
+    @pytest.mark.parametrize(
+        "raw,expected",
+        [
+            ("food_dining", "food_dining"),
+            ("Food", "food_dining"),
+            ("dining", "food_dining"),
+            ("grocery", "groceries"),
+            ("healthcare", "health"),
+            ("Subscription", "subscriptions"),
+            ("misc", "other"),
+            ("", "other"),
+            ("total nonsense", "other"),
+        ],
+    )
+    def test_coerce(self, raw, expected):
+        assert coerce(raw) == expected
+
+    def test_every_result_is_a_valid_category(self):
+        # A stray label from a model must never reach the ledger, or totals
+        # fragment across categories that do not exist.
+        for raw in ["", "???", "Investments", "food", "TRANSPORT", "x" * 200]:
+            assert is_valid(coerce(raw))
+
+
+class TestLabels:
+    def test_every_category_has_a_label(self):
+        for category in CATEGORIES:
+            assert label(category)
+            assert label(category) != category or "_" not in category

tests/test_extract.py

@@ -0,0 +1,101 @@
+import io
+
+from finbot.extract import extract, extract_csv, extract_xlsx, rows_to_text
+
+CSV_BYTES = (
+    b"Date,Narration,Withdrawal,Deposit\n"
+    b"01/08/2026,SWIGGY BANGALORE,450.00,\n"
+    b"03/08/2026,SALARY AUG,,85000.00\n"
+    b"05/08/2026,NETFLIX.COM,649.00,\n"
+)
+
+
+def make_xlsx() -> bytes:
+    from openpyxl import Workbook
+
+    workbook = Workbook()
+    sheet = workbook.active
+    sheet.append(["Date", "Description", "Amount"])
+    sheet.append(["2026-08-01", "Swiggy", 450])
+    sheet.append([None, None, None])  # blank row must be dropped
+    sheet.append(["2026-08-05", "Netflix", 649])
+    buffer = io.BytesIO()
+    workbook.save(buffer)
+    return buffer.getvalue()
+
+
+class TestCSV:
+    def test_parses_rows(self):
+        doc = extract_csv(CSV_BYTES)
+        assert doc.kind == "csv"
+        assert len(doc.rows) == 4  # header + 3
+        assert doc.rows[1][1] == "SWIGGY BANGALORE"
+
+    def test_semicolon_delimiter(self):
+        doc = extract_csv(b"a;b;c\n1;2;3\n4;5;6\n")
+        assert doc.rows[0] == ["a", "b", "c"]
+
+    def test_skips_blank_rows(self):
+        doc = extract_csv(b"a,b\n\n1,2\n")
+        assert len(doc.rows) == 2
+
+    def test_handles_bom(self):
+        doc = extract_csv(b"\xef\xbb\xbfDate,Amount\n2026-08-01,10\n")
+        assert doc.rows[0][0] == "Date"
+
+    def test_handles_non_utf8(self):
+        doc = extract_csv("Caf\xe9,10\n".encode("latin-1"))
+        assert "Caf" in doc.rows[0][0]
+
+    def test_single_column_does_not_crash(self):
+        doc = extract_csv(b"justonecolumn\nvalue\n")
+        assert len(doc.rows) == 2
+
+
+class TestXLSX:
+    def test_parses_rows(self):
+        doc = extract_xlsx(make_xlsx())
+        assert doc.kind == "xlsx"
+        assert doc.rows[0] == ["Date", "Description", "Amount"]
+        assert ["2026-08-05", "Netflix", "649"] in doc.rows
+
+    def test_drops_blank_rows(self):
+        doc = extract_xlsx(make_xlsx())
+        assert all(any(cell for cell in row) for row in doc.rows)
+
+
+class TestDispatch:
+    def test_by_extension(self):
+        assert extract(CSV_BYTES, "statement.csv").kind == "csv"
+        assert extract(make_xlsx(), "book.xlsx").kind == "xlsx"
+
+    def test_by_mime_when_no_extension(self):
+        assert extract(CSV_BYTES, "", "text/csv").kind == "csv"
+
+    def test_plain_text(self):
+        doc = extract(b"hello", "notes.txt")
+        assert doc.kind == "text"
+        assert doc.text == "hello"
+
+    def test_legacy_xls_is_reported_not_crashed(self):
+        doc = extract(b"\xd0\xcf\x11\xe0", "old.xls")
+        assert doc.kind == "unsupported"
+        assert ".xlsx" in doc.note
+
+    def test_unknown_type_explains_itself(self):
+        doc = extract(b"\x00\x01", "thing.bin")
+        assert doc.kind == "unsupported"
+        assert doc.note
+
+    def test_is_empty(self):
+        assert extract(b"", "empty.txt").is_empty
+
+
+class TestRowsToText:
+    def test_pipe_delimited(self):
+        text = rows_to_text([["a", "b"], ["1", "2"]])
+        assert text == "a | b\n1 | 2"
+
+    def test_respects_limit(self):
+        text = rows_to_text([["x"]] * 100, limit=3)
+        assert len(text.splitlines()) == 3

tests/test_ingest.py

@@ -0,0 +1,232 @@
+from datetime import date
+
+import pytest
+
+from finbot.extract import ExtractedDocument
+from finbot.ingest import Ingestor, _coerce_amount, _draft_from_obj, _parse_any_date
+from finbot.llm import LLMUnavailable
+
+TODAY = date(2026, 8, 15)
+
+
+class StubLLM:
+    """Stands in for LLMClient without touching the network."""
+
+    def __init__(self, payload=None, enabled=True, raises=None):
+        self.payload = payload
+        self.enabled = enabled
+        self.raises = raises
+        self.calls = []
+
+    def chat_json(self, system, user, **kwargs):
+        self.calls.append(("chat_json", system, user))
+        if self.raises:
+            raise self.raises
+        return self.payload
+
+    def vision_json(self, system, user, image_bytes, mime_type, **kwargs):
+        self.calls.append(("vision_json", system, user))
+        if self.raises:
+            raise self.raises
+        return self.payload
+
+
+class TestHelpers:
+    @pytest.mark.parametrize(
+        "raw,expected",
+        [(10, 10.0), (-10, 10.0), ("1,234.56", 1234.56), ("₹450", 450.0), ("", None), (None, None)],
+    )
+    def test_coerce_amount(self, raw, expected):
+        assert _coerce_amount(raw) == expected
+
+    @pytest.mark.parametrize(
+        "raw,expected",
+        [
+            ("2026-08-01", date(2026, 8, 1)),
+            ("01/08/2026", date(2026, 8, 1)),  # day-first
+            ("", TODAY),
+            ("garbage", TODAY),
+            (None, TODAY),
+        ],
+    )
+    def test_parse_any_date(self, raw, expected):
+        assert _parse_any_date(raw, TODAY) == expected
+
+    def test_draft_from_obj(self):
+        draft = _draft_from_obj(
+            {
+                "amount": 450,
+                "currency": "inr",
+                "description": "Swiggy order",
+                "date": "2026-08-01",
+                "category": "food_dining",
+            },
+            "USD",
+            TODAY,
+        )
+        assert draft.amount_minor == 45000
+        assert draft.currency == "INR"
+        assert draft.category == "food_dining"
+
+    def test_draft_rejects_zero_and_missing_amounts(self):
+        assert _draft_from_obj({"amount": 0}, "INR", TODAY) is None
+        assert _draft_from_obj({}, "INR", TODAY) is None
+        assert _draft_from_obj("not a dict", "INR", TODAY) is None
+
+    def test_draft_falls_back_to_keyword_category(self):
+        # Model gave an unusable category, but the text is obviously transport.
+        draft = _draft_from_obj(
+            {"amount": 100, "description": "uber ride", "category": "???"}, "INR", TODAY
+        )
+        assert draft.category == "transport"
+
+    def test_draft_defaults_currency(self):
+        draft = _draft_from_obj({"amount": 10}, "SGD", TODAY)
+        assert draft.currency == "SGD"
+
+
+class TestFromText:
+    def test_deterministic_path_does_not_call_the_model(self):
+        llm = StubLLM()
+        draft = Ingestor(llm, "INR").from_text("coffee 250", TODAY)
+        assert draft.amount_minor == 25000
+        assert llm.calls == []  # the whole point of the fast path
+
+    def test_falls_back_to_the_model_without_an_amount(self):
+        llm = StubLLM(payload={"amount": 12, "currency": "USD", "description": "a coffee"})
+        draft = Ingestor(llm, "INR").from_text("bought a coffee for twelve dollars", TODAY)
+        assert draft is not None
+        assert draft.amount_minor == 1200
+        assert len(llm.calls) == 1
+
+    def test_returns_none_when_the_model_is_disabled(self):
+        llm = StubLLM(enabled=False)
+        assert Ingestor(llm, "INR").from_text("no numbers here", TODAY) is None
+
+    def test_model_failure_degrades_quietly(self):
+        llm = StubLLM(raises=LLMUnavailable("down"))
+        assert Ingestor(llm, "INR").from_text("no numbers here", TODAY) is None
+
+
+class TestFromReceipt:
+    def test_reads_a_total(self):
+        llm = StubLLM(
+            payload={
+                "merchant": "Blue Tokai",
+                "amount": 480,
+                "currency": "INR",
+                "date": "2026-08-14",
+                "category": "food_dining",
+                "confidence": 0.9,
+            }
+        )
+        draft, error = Ingestor(llm, "INR").from_receipt(b"jpeg", "image/jpeg", TODAY)
+        assert error == ""
+        assert draft.amount_minor == 48000
+        assert draft.merchant == "Blue Tokai"
+
+    def test_explains_when_disabled(self):
+        llm = StubLLM(enabled=False)
+        draft, error = Ingestor(llm, "INR").from_receipt(b"x", "image/jpeg", TODAY)
+        assert draft is None
+        assert "HF_TOKEN" in error
+
+    def test_explains_an_unreadable_image(self):
+        llm = StubLLM(payload={"amount": 0})
+        draft, error = Ingestor(llm, "INR").from_receipt(b"x", "image/jpeg", TODAY)
+        assert draft is None
+        assert "couldn't find a total" in error
+
+
+class TestFromDocument:
+    def _doc(self):
+        return ExtractedDocument(kind="csv", rows=[["Date", "Desc", "Amt"], ["01/08/2026", "Swiggy", "450"]])
+
+    def test_extracts_debits(self):
+        llm = StubLLM(
+            payload={
+                "transactions": [
+                    {
+                        "date": "2026-08-01",
+                        "description": "Swiggy",
+                        "amount": 450,
+                        "currency": "INR",
+                        "direction": "debit",
+                        "category": "food_dining",
+                    }
+                ]
+            }
+        )
+        pending, error = Ingestor(llm, "INR").from_document(self._doc(), user_id=1, today=TODAY)
+        assert error == ""
+        assert len(pending.drafts) == 1
+        assert pending.total_by_currency() == {"INR": 45000}
+
+    def test_credits_are_counted_not_stored(self):
+        # Storing income alongside spend would corrupt every total.
+        llm = StubLLM(
+            payload={
+                "transactions": [
+                    {"date": "2026-08-01", "description": "Swiggy", "amount": 450,
+                     "currency": "INR", "direction": "debit"},
+                    {"date": "2026-08-03", "description": "Salary", "amount": 85000,
+                     "currency": "INR", "direction": "credit"},
+                ]
+            }
+        )
+        pending, error = Ingestor(llm, "INR").from_document(self._doc(), user_id=1, today=TODAY)
+        assert len(pending.drafts) == 1
+        assert "credits skipped" in pending.label
+
+    def test_counts_unreadable_rows(self):
+        llm = StubLLM(
+            payload={
+                "transactions": [
+                    {"date": "2026-08-01", "description": "Swiggy", "amount": 450,
+                     "currency": "INR", "direction": "debit"},
+                    {"description": "junk"},  # no amount
+                ]
+            }
+        )
+        pending, _ = Ingestor(llm, "INR").from_document(self._doc(), user_id=1, today=TODAY)
+        assert len(pending.drafts) == 1
+        assert pending.skipped == 1
+
+    def test_accepts_a_bare_array(self):
+        llm = StubLLM(
+            payload=[{"date": "2026-08-01", "description": "Swiggy", "amount": 450,
+                      "currency": "INR", "direction": "debit"}]
+        )
+        pending, error = Ingestor(llm, "INR").from_document(self._doc(), user_id=1, today=TODAY)
+        assert error == ""
+        assert len(pending.drafts) == 1
+
+    def test_reports_when_nothing_spendable_is_found(self):
+        llm = StubLLM(payload={"transactions": []})
+        pending, error = Ingestor(llm, "INR").from_document(self._doc(), user_id=1, today=TODAY)
+        assert pending is None
+        assert "no spending transactions" in error
+
+    def test_unsupported_document_short_circuits(self):
+        llm = StubLLM()
+        doc = ExtractedDocument(kind="unsupported", note="nope")
+        pending, error = Ingestor(llm, "INR").from_document(doc, user_id=1, today=TODAY)
+        assert pending is None
+        assert error == "nope"
+        assert llm.calls == []  # never spend a call on a file we cannot read
+
+    def test_flags_truncation(self):
+        llm = StubLLM(
+            payload={"transactions": [{"date": "2026-08-01", "description": "x",
+                                       "amount": 1, "currency": "INR", "direction": "debit"}]}
+        )
+        doc = self._doc()
+        doc.truncated = True
+        pending, _ = Ingestor(llm, "INR").from_document(doc, user_id=1, today=TODAY)
+        assert "truncated" in pending.label
+
+    def test_disabled_model_explains_itself(self):
+        llm = StubLLM(enabled=False)
+        pending, error = Ingestor(llm, "INR").from_document(self._doc(), user_id=1, today=TODAY)
+        assert pending is None
+        assert "HF_TOKEN" in error

tests/test_limits.py

@@ -0,0 +1,96 @@
+import pytest
+
+from finbot.config import Settings
+from finbot.limits import WINDOW_SECONDS, RateLimiter
+
+
+def settings(**overrides):
+    base = dict(
+        telegram_bot_token="",
+        telegram_webhook_secret="",
+        allowed_telegram_user_ids="",
+        hf_token="",
+        hf_dataset_repo="",
+        open_access=False,
+    )
+    base.update(overrides)
+    return Settings(**base)
+
+
+class TestAuthorisation:
+    def test_empty_allowlist_authorises_nobody(self):
+        # The safe default: a forgotten allowlist must not mean "open to all".
+        assert settings().is_authorised(42) is False
+
+    def test_allowlist_match(self):
+        s = settings(allowed_telegram_user_ids="42, 99")
+        assert s.is_authorised(42)
+        assert s.is_authorised(99)
+        assert not s.is_authorised(7)
+
+    def test_open_access_authorises_anyone(self):
+        s = settings(open_access=True)
+        assert s.is_authorised(1)
+        assert s.is_authorised(123456789)
+
+    def test_open_access_ignores_the_allowlist(self):
+        s = settings(open_access=True, allowed_telegram_user_ids="42")
+        assert s.is_authorised(7)
+
+    def test_malformed_ids_are_dropped_not_fatal(self):
+        s = settings(allowed_telegram_user_ids="42,,abc, 99 ,")
+        assert s.allowed_user_ids == frozenset({42, 99})
+
+    def test_open_access_removes_the_allowlist_warning(self):
+        assert any("ALLOWED" in g for g in settings().missing_required())
+        assert not any(
+            "ALLOWED" in g for g in settings(open_access=True).missing_required()
+        )
+
+
+class TestRateLimiter:
+    def test_allows_up_to_the_cap(self):
+        limiter = RateLimiter(3)
+        assert [limiter.check(1) for _ in range(3)] == [True, True, True]
+
+    def test_blocks_past_the_cap(self):
+        limiter = RateLimiter(2)
+        limiter.check(1)
+        limiter.check(1)
+        assert limiter.check(1) is False
+
+    def test_users_are_independent(self):
+        limiter = RateLimiter(1)
+        assert limiter.check(1) is True
+        assert limiter.check(2) is True
+        assert limiter.check(1) is False
+
+    def test_zero_disables_the_cap(self):
+        limiter = RateLimiter(0)
+        assert not limiter.enabled
+        assert all(limiter.check(1) for _ in range(500))
+
+    def test_negative_disables_the_cap(self):
+        assert not RateLimiter(-1).enabled
+
+    def test_window_expires(self):
+        limiter = RateLimiter(1)
+        assert limiter.check(1, now=1000.0) is True
+        assert limiter.check(1, now=1000.0) is False
+        # Just past the 24h window, the old hit no longer counts.
+        assert limiter.check(1, now=1000.0 + WINDOW_SECONDS + 1) is True
+
+    def test_remaining(self):
+        limiter = RateLimiter(3)
+        assert limiter.remaining(1) == 3
+        limiter.check(1)
+        assert limiter.remaining(1) == 2
+
+    def test_remaining_is_unlimited_when_disabled(self):
+        assert RateLimiter(0).remaining(1) == -1
+
+    @pytest.mark.parametrize("cap", [1, 5, 20])
+    def test_never_exceeds_cap(self, cap):
+        limiter = RateLimiter(cap)
+        granted = sum(1 for _ in range(cap * 3) if limiter.check(1, now=500.0))
+        assert granted == cap

tests/test_money.py

@@ -0,0 +1,157 @@
+import pytest
+
+from finbot.money import (
+    detect_currency,
+    exponent,
+    format_money,
+    from_minor,
+    parse_amount,
+    to_minor,
+)
+
+
+class TestExponent:
+    @pytest.mark.parametrize(
+        "currency,expected",
+        [("INR", 2), ("USD", 2), ("EUR", 2), ("JPY", 0), ("KRW", 0), ("KWD", 3), ("xyz", 2)],
+    )
+    def test_exponent(self, currency, expected):
+        assert exponent(currency) == expected
+
+
+class TestToMinor:
+    @pytest.mark.parametrize(
+        "value,currency,expected",
+        [
+            (250, "INR", 25000),
+            ("250.50", "INR", 25050),
+            (1234.56, "USD", 123456),
+            (1000, "JPY", 1000),  # zero-decimal currency
+            (1.5, "KWD", 1500),  # three-decimal currency
+            ("0.01", "USD", 1),
+        ],
+    )
+    def test_to_minor(self, value, currency, expected):
+        assert to_minor(value, currency) == expected
+
+    def test_rounds_half_up_not_bankers(self):
+        # Python's round() would give 8.34 here; money should round half up.
+        assert to_minor("8.345", "USD") == 835
+
+    def test_no_float_drift(self):
+        # The classic 0.1 + 0.2 problem must not reach the ledger.
+        total = to_minor("0.1", "USD") + to_minor("0.2", "USD")
+        assert total == 30
+        assert from_minor(total, "USD") == 0.3
+
+
+class TestFormatMoney:
+    @pytest.mark.parametrize(
+        "minor,currency,expected",
+        [
+            (25000, "INR", "₹250.00"),
+            (123456, "USD", "$1,234.56"),
+            (1000, "JPY", "¥1,000"),
+            (-5000, "INR", "-₹50.00"),
+            (99, "USD", "$0.99"),
+        ],
+    )
+    def test_format(self, minor, currency, expected):
+        assert format_money(minor, currency) == expected
+
+    def test_unknown_currency_uses_suffix(self):
+        assert format_money(150000, "AED") == "1,500.00 AED"
+
+
+class TestDetectCurrency:
+    @pytest.mark.parametrize(
+        "text,expected",
+        [
+            ("₹250 coffee", "INR"),
+            ("€40 dinner", "EUR"),
+            ("£12 book", "GBP"),
+            ("paid 50 USD", "USD"),
+            ("Rs 300 chai", "INR"),
+        ],
+    )
+    def test_explicit(self, text, expected):
+        assert detect_currency(text, "SGD") == expected
+
+    def test_falls_back_to_default(self):
+        assert detect_currency("coffee 250", "SGD") == "SGD"
+
+    def test_letter_symbols_need_word_boundaries(self):
+        # "cars" contains "rs" -- it must not be read as rupees.
+        assert detect_currency("cars 250", "USD") == "USD"
+        assert detect_currency("chfoo 12", "USD") == "USD"
+
+    def test_ambiguous_dollar_uses_default(self):
+        assert detect_currency("$40 lunch", "SGD") == "SGD"
+
+
+class TestParseAmount:
+    @pytest.mark.parametrize(
+        "text,expected_minor",
+        [
+            ("coffee 250", 25000),
+            ("₹1,200 groceries", 120000),
+            ("45.50 lunch", 4550),
+            ("1,234.56 spent", 123456),
+            ("1.234,56 gekocht", 123456),  # European separators
+            ("1,23,456.78 rent", 12345678),  # Indian lakh grouping
+        ],
+    )
+    def test_amounts(self, text, expected_minor):
+        parsed = parse_amount(text, "INR")
+        assert parsed is not None
+        assert parsed.minor == expected_minor
+
+    def test_returns_none_without_a_number(self):
+        assert parse_amount("just some words", "INR") is None
+
+    def test_prefers_the_largest_number(self):
+        # "2 coffees 250" -- the spend is 250, not 2.
+        parsed = parse_amount("2 coffees 250", "INR")
+        assert parsed is not None
+        assert parsed.minor == 25000
+
+    def test_reports_the_span_it_consumed(self):
+        parsed = parse_amount("coffee 250", "INR")
+        assert parsed is not None
+        start, end = parsed.span
+        assert "coffee 250"[start:end] == "250"
+
+    def test_thousands_vs_decimal_disambiguation(self):
+        # 3 digits after a single comma is grouping, 2 digits is decimal.
+        assert parse_amount("1,500", "INR").minor == 150000
+        assert parse_amount("1,50", "INR").minor == 150
+
+    @pytest.mark.parametrize(
+        "text,expected_minor",
+        [
+            ("1000", 100_000),
+            ("rent 25000", 2_500_000),
+            ("123456", 12_345_600),
+            ("9999999 wire", 999_999_900),
+        ],
+    )
+    def test_unseparated_large_numbers(self, text, expected_minor):
+        # Regression: the old regex capped the integer part at three digits,
+        # so "1000" silently became 100 and every large amount was wrong.
+        parsed = parse_amount(text, "INR")
+        assert parsed is not None
+        assert parsed.minor == expected_minor
+
+    def test_space_separated_numbers_are_not_merged(self):
+        # "250 300" must read as two numbers (largest wins), never as 250300.
+        parsed = parse_amount("250 300", "INR")
+        assert parsed is not None
+        assert parsed.minor == 30000
+
+    def test_non_breaking_space_is_a_group_separator(self):
+        assert parse_amount("1 234,56", "EUR").minor == 123456
+
+    def test_trailing_punctuation_is_not_consumed(self):
+        parsed = parse_amount("spent 250.", "INR")
+        assert parsed is not None
+        assert parsed.minor == 25000

tests/test_parser.py

@@ -0,0 +1,123 @@
+from datetime import date
+
+import pytest
+
+from finbot.parser import parse_date_hint, parse_expense
+
+TODAY = date(2026, 8, 15)  # a Saturday
+
+
+class TestParseDateHint:
+    def test_defaults_to_today(self):
+        resolved, span = parse_date_hint("coffee 250", TODAY)
+        assert resolved == TODAY
+        assert span is None
+
+    @pytest.mark.parametrize(
+        "text,expected",
+        [
+            ("lunch yesterday", date(2026, 8, 14)),
+            ("coffee today", TODAY),
+            ("dinner day before yesterday", date(2026, 8, 13)),
+            ("paid 3 days ago", date(2026, 8, 12)),
+            ("rent on 2026-08-01", date(2026, 8, 1)),
+            ("bought 12 aug", date(2026, 8, 12)),
+            ("bought aug 12", date(2026, 8, 12)),
+        ],
+    )
+    def test_resolves(self, text, expected):
+        resolved, span = parse_date_hint(text, TODAY)
+        assert resolved == expected
+        assert span is not None
+
+    def test_future_dates_roll_back_a_year(self):
+        # "12 dec" typed in August means last December, not a future spend.
+        resolved, _ = parse_date_hint("gift 12 dec", TODAY)
+        assert resolved == date(2025, 12, 12)
+
+    def test_bare_weekday_means_the_most_recent_past_one(self):
+        # TODAY is a Saturday; "friday" is yesterday.
+        resolved, _ = parse_date_hint("drinks friday", TODAY)
+        assert resolved == date(2026, 8, 14)
+
+    def test_same_weekday_goes_back_a_full_week(self):
+        resolved, _ = parse_date_hint("shopping saturday", TODAY)
+        assert resolved == date(2026, 8, 8)
+
+    def test_day_first_preferred_for_ambiguous_slashes(self):
+        resolved, _ = parse_date_hint("paid 03/04", TODAY)
+        assert resolved == date(2026, 4, 3)
+
+    def test_falls_back_to_month_first_when_day_first_impossible(self):
+        # 25 is not a month, so 12/25 can only be December 25th.
+        resolved, _ = parse_date_hint("gift 12/25", TODAY)
+        assert resolved == date(2025, 12, 25)
+
+    def test_invalid_date_does_not_crash(self):
+        resolved, _ = parse_date_hint("paid 2026-02-30", TODAY)
+        assert resolved == TODAY
+
+
+class TestParseExpense:
+    def test_returns_none_without_an_amount(self):
+        assert parse_expense("hello there", "INR", TODAY) is None
+
+    def test_returns_none_for_empty(self):
+        assert parse_expense("", "INR", TODAY) is None
+        assert parse_expense("   ", "INR", TODAY) is None
+
+    def test_simple_entry(self):
+        draft = parse_expense("coffee 250", "INR", TODAY)
+        assert draft is not None
+        assert draft.amount_minor == 25000
+        assert draft.currency == "INR"
+        assert "coffee" in draft.description
+        assert draft.category == "food_dining"
+        assert draft.occurred_on == TODAY
+
+    def test_strips_the_amount_from_the_description(self):
+        draft = parse_expense("₹1,200 groceries at bigbasket", "INR", TODAY)
+        assert draft is not None
+        assert "1" not in draft.description
+        assert "₹" not in draft.description
+        assert draft.category == "groceries"
+
+    def test_strips_filler_words(self):
+        draft = parse_expense("spent 500 on dinner", "INR", TODAY)
+        assert draft is not None
+        assert draft.description == "dinner"
+
+    def test_date_phrase_leaves_the_description(self):
+        draft = parse_expense("45.50 lunch yesterday", "INR", TODAY)
+        assert draft is not None
+        assert draft.occurred_on == date(2026, 8, 14)
+        assert "yesterday" not in draft.description
+        assert draft.description == "lunch"
+
+    def test_hashtag_overrides_the_keyword_guess(self):
+        draft = parse_expense("320 lunch #transport", "INR", TODAY)
+        assert draft is not None
+        # "lunch" would normally be food_dining; the tag wins.
+        assert draft.category == "transport"
+        assert "#" not in draft.description
+
+    def test_unknown_hashtag_falls_back_to_other(self):
+        draft = parse_expense("100 thing #nonsense", "INR", TODAY)
+        assert draft is not None
+        assert draft.category == "other"
+
+    def test_explicit_currency_beats_the_default(self):
+        draft = parse_expense("€40 dinner", "INR", TODAY)
+        assert draft is not None
+        assert draft.currency == "EUR"
+        assert draft.amount_minor == 4000
+
+    def test_description_never_empty(self):
+        draft = parse_expense("250", "INR", TODAY)
+        assert draft is not None
+        assert draft.description == "unlabelled"
+
+    def test_keeps_the_raw_input(self):
+        draft = parse_expense("  coffee 250  ", "INR", TODAY)
+        assert draft is not None
+        assert draft.raw == "coffee 250"

tests/test_registry.py

@@ -0,0 +1,183 @@
+"""The registry is the extension point, so its contract is worth pinning down."""
+
+from datetime import date
+from typing import Optional, Sequence
+
+import pytest
+
+from finbot.features.base import (
+    Attachment,
+    BotContext,
+    CommandSpec,
+    Feature,
+    Reply,
+    Services,
+    SimpleFeature,
+)
+from finbot.registry import DuplicateCommand, FeatureRegistry
+
+TODAY = date(2026, 8, 15)
+
+
+class Greeter(SimpleFeature):
+    name = "greeter"
+    description = "Greetings"
+    priority = 10
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (
+            CommandSpec("hello", "Say hello", aliases=("hi",)),
+            CommandSpec("secret", "Hidden thing", hidden=True),
+        )
+
+    def cmd_hello(self, ctx: BotContext) -> Reply:
+        return Reply(f"hello {ctx.args or 'world'}")
+
+    def cmd_secret(self, ctx: BotContext) -> Reply:
+        return Reply("shh")
+
+
+class Echo(Feature):
+    name = "echo"
+    description = "Echo"
+    priority = 50
+
+    def handle_message(self, ctx: BotContext) -> Optional[Reply]:
+        if ctx.text.startswith("say "):
+            return Reply(ctx.text[4:])
+        return None
+
+
+class Filer(Feature):
+    name = "filer"
+    description = "Files"
+    priority = 5
+
+    def handle_attachment(self, ctx: BotContext) -> Optional[Reply]:
+        return Reply(f"got {ctx.attachment.filename}")
+
+
+class Exploder(Feature):
+    name = "exploder"
+    priority = 1
+
+    def commands(self) -> Sequence[CommandSpec]:
+        return (CommandSpec("boom", "Raises"),)
+
+    def handle_command(self, ctx: BotContext) -> Reply:
+        raise RuntimeError("intentional")
+
+
+def make_ctx(registry, text="", command="", args="", attachment=None) -> BotContext:
+    services = Services(
+        settings=None, store=None, llm=None, ingestor=None, advisor=None, registry=registry
+    )
+    return BotContext(
+        user_id=1,
+        chat_id=1,
+        services=services,
+        today=TODAY,
+        text=text,
+        command=command,
+        args=args,
+        attachment=attachment,
+    )
+
+
+@pytest.fixture
+def registry():
+    reg = FeatureRegistry()
+    reg.register_all([Greeter(), Echo(), Filer()])
+    return reg
+
+
+class TestRegistration:
+    def test_features_sorted_by_priority(self, registry):
+        assert [f.name for f in registry.features] == ["filer", "greeter", "echo"]
+
+    def test_duplicate_command_is_rejected(self, registry):
+        class Clash(SimpleFeature):
+            name = "clash"
+
+            def commands(self):
+                return (CommandSpec("hello", "clashing"),)
+
+        with pytest.raises(DuplicateCommand, match="greeter"):
+            registry.register(Clash())
+
+    def test_duplicate_alias_is_rejected(self, registry):
+        class Clash(SimpleFeature):
+            name = "clash"
+
+            def commands(self):
+                return (CommandSpec("other", "x", aliases=("hi",)),)
+
+        with pytest.raises(DuplicateCommand):
+            registry.register(Clash())
+
+    def test_known_command(self, registry):
+        assert registry.known_command("hello")
+        assert registry.known_command("hi")
+        assert not registry.known_command("nope")
+
+
+class TestDispatch:
+    def test_command(self, registry):
+        reply = registry.dispatch(make_ctx(registry, command="hello", args="there"))
+        assert reply.text == "hello there"
+
+    def test_alias(self, registry):
+        reply = registry.dispatch(make_ctx(registry, command="hi"))
+        assert reply.text == "hello world"
+
+    def test_unknown_command_is_reported(self, registry):
+        reply = registry.dispatch(make_ctx(registry, command="nonsense"))
+        assert "don't know" in reply.text
+
+    def test_plain_message_routes_to_a_message_handler(self, registry):
+        reply = registry.dispatch(make_ctx(registry, text="say cheese"))
+        assert reply.text == "cheese"
+
+    def test_declined_message_returns_none(self, registry):
+        assert registry.dispatch(make_ctx(registry, text="unhandled")) is None
+
+    def test_attachment_routes_to_attachment_handler(self, registry):
+        attachment = Attachment(data=b"x", filename="a.csv")
+        reply = registry.dispatch(make_ctx(registry, attachment=attachment))
+        assert reply.text == "got a.csv"
+
+    def test_a_failing_feature_does_not_crash_the_bot(self, registry):
+        registry.register(Exploder())
+        reply = registry.dispatch(make_ctx(registry, command="boom"))
+        assert "went wrong" in reply.text
+
+
+class TestHelpGeneration:
+    def test_help_lists_visible_commands(self, registry):
+        text = registry.help_text()
+        assert "/hello" in text
+        assert "Greetings" in text
+
+    def test_help_omits_hidden_commands(self, registry):
+        assert "/secret" not in registry.help_text()
+
+    def test_telegram_commands_payload(self, registry):
+        payload = registry.telegram_commands()
+        names = {c["command"] for c in payload}
+        assert "hello" in names
+        assert "secret" not in names
+        assert all(len(c["description"]) <= 256 for c in payload)
+
+    def test_help_escapes_html(self):
+        class Sneaky(SimpleFeature):
+            name = "sneaky"
+            description = "<b>bold</b>"
+
+            def commands(self):
+                return (CommandSpec("x", "a & b"),)
+
+        reg = FeatureRegistry()
+        reg.register(Sneaky())
+        text = reg.help_text()
+        assert "&lt;b&gt;bold&lt;/b&gt;" in text
+        assert "a &amp; b" in text

tests/test_store.py

@@ -0,0 +1,190 @@
+from datetime import date
+
+import pytest
+
+from finbot.config import Settings
+from finbot.models import Budget, Expense
+from finbot.store import Store
+
+TODAY = date(2026, 8, 15)
+
+
+@pytest.fixture
+def store(tmp_path):
+    settings = Settings(
+        data_dir=str(tmp_path),
+        hf_dataset_repo="",  # sync off: no network in tests
+        hf_token="",
+        telegram_bot_token="",
+        telegram_webhook_secret="",
+        allowed_telegram_user_ids="",
+    )
+    store = Store(settings)
+    yield store
+    store.close()
+
+
+def make(amount=25000, category="food_dining", day=TODAY, merchant="", batch=""):
+    return Expense(
+        user_id=1,
+        amount_minor=amount,
+        currency="INR",
+        description="coffee",
+        category=category,
+        occurred_on=day,
+        merchant=merchant,
+        batch_id=batch,
+    )
+
+
+class TestExpenses:
+    def test_add_and_read_back(self, store):
+        expense = store.add_expense(make())
+        rows = store.list_expenses(1)
+        assert len(rows) == 1
+        assert rows[0].id == expense.id
+        assert rows[0].amount_minor == 25000
+        assert rows[0].occurred_on == TODAY
+
+    def test_isolated_per_user(self, store):
+        store.add_expense(make())
+        other = make()
+        other.user_id = 2
+        store.add_expense(other)
+        assert len(store.list_expenses(1)) == 1
+        assert len(store.list_expenses(2)) == 1
+
+    def test_date_filtering(self, store):
+        store.add_expense(make(day=date(2026, 8, 1)))
+        store.add_expense(make(day=date(2026, 7, 1)))
+        rows = store.list_expenses(1, date(2026, 8, 1), date(2026, 8, 31))
+        assert len(rows) == 1
+
+    def test_category_filtering(self, store):
+        store.add_expense(make(category="rent"))
+        store.add_expense(make(category="food_dining"))
+        assert len(store.list_expenses(1, category="rent")) == 1
+
+    def test_limit(self, store):
+        for _ in range(5):
+            store.add_expense(make())
+        assert len(store.list_expenses(1, limit=3)) == 3
+
+    def test_last_expense(self, store):
+        store.add_expense(make(amount=100))
+        latest = store.add_expense(make(amount=999))
+        assert store.last_expense(1).id == latest.id
+
+    def test_last_expense_none_when_empty(self, store):
+        assert store.last_expense(1) is None
+
+    def test_delete(self, store):
+        expense = store.add_expense(make())
+        assert store.delete_expense(1, expense.id) is True
+        assert store.list_expenses(1) == []
+
+    def test_delete_wrong_user_is_a_no_op(self, store):
+        expense = store.add_expense(make())
+        assert store.delete_expense(999, expense.id) is False
+        assert len(store.list_expenses(1)) == 1
+
+    def test_delete_batch(self, store):
+        for _ in range(3):
+            store.add_expense(make(batch="batch-1"))
+        store.add_expense(make(batch=""))
+        assert store.delete_batch(1, "batch-1") == 3
+        assert len(store.list_expenses(1)) == 1
+
+    def test_delete_batch_ignores_empty_id(self, store):
+        store.add_expense(make(batch=""))
+        assert store.delete_batch(1, "") == 0
+
+    def test_count(self, store):
+        store.add_expense(make())
+        store.add_expense(make())
+        assert store.count(1) == 2
+        assert store.count() == 2
+
+    def test_currencies_used(self, store):
+        store.add_expense(make())
+        usd = make()
+        usd.currency = "USD"
+        store.add_expense(usd)
+        assert set(store.currencies_used(1)) == {"INR", "USD"}
+
+
+class TestDedupe:
+    def test_matching_transactions_share_a_key(self, store):
+        a = make(merchant="Swiggy")
+        b = make(merchant="swiggy!")  # different case and punctuation
+        assert a.dedupe_key == b.dedupe_key
+
+    def test_key_changes_with_amount(self, store):
+        assert make(amount=100).dedupe_key != make(amount=200).dedupe_key
+
+    def test_key_changes_with_date(self, store):
+        assert make(day=date(2026, 8, 1)).dedupe_key != make(day=date(2026, 8, 2)).dedupe_key
+
+    def test_existing_keys_lookup(self, store):
+        expense = store.add_expense(make(merchant="Swiggy"))
+        found = store.existing_dedupe_keys(1, [expense.dedupe_key, "nope"])
+        assert found == {expense.dedupe_key}
+
+    def test_existing_keys_empty_input(self, store):
+        assert store.existing_dedupe_keys(1, []) == set()
+
+    def test_duplicates_are_still_insertable(self, store):
+        # Two identical coffees on one day are both real -- dedupe is advisory
+        # at import time, not a database constraint.
+        store.add_expense(make())
+        store.add_expense(make())
+        assert store.count(1) == 2
+
+    def test_chunks_large_key_lists(self, store):
+        expense = store.add_expense(make())
+        keys = [f"k{i}" for i in range(1200)] + [expense.dedupe_key]
+        assert store.existing_dedupe_keys(1, keys) == {expense.dedupe_key}
+
+
+class TestBudgets:
+    def test_set_and_get(self, store):
+        store.set_budget(Budget(1, "food_dining", 100000, "INR"))
+        budgets = store.get_budgets(1)
+        assert len(budgets) == 1
+        assert budgets[0].amount_minor == 100000
+
+    def test_upsert_replaces(self, store):
+        store.set_budget(Budget(1, "food_dining", 100000, "INR"))
+        store.set_budget(Budget(1, "food_dining", 250000, "INR"))
+        budgets = store.get_budgets(1)
+        assert len(budgets) == 1
+        assert budgets[0].amount_minor == 250000
+
+    def test_delete(self, store):
+        store.set_budget(Budget(1, "rent", 100, "INR"))
+        assert store.delete_budget(1, "rent") is True
+        assert store.get_budgets(1) == []
+
+    def test_delete_missing(self, store):
+        assert store.delete_budget(1, "rent") is False
+
+
+class TestPersistence:
+    def test_survives_reopen(self, tmp_path):
+        settings = Settings(
+            data_dir=str(tmp_path),
+            hf_dataset_repo="",
+            hf_token="",
+            telegram_bot_token="",
+            telegram_webhook_secret="",
+        )
+        first = Store(settings)
+        first.add_expense(make())
+        first.close()
+
+        second = Store(settings)
+        assert second.count(1) == 1
+        second.close()
+
+    def test_sync_disabled_without_config(self, store):
+        assert store.sync_status == "disabled"

tests/test_telegram.py

@@ -0,0 +1,119 @@
+from finbot.telegram import SeenUpdates, chunk_message, parse_update
+
+
+def message_update(update_id=1, **message):
+    base = {"from": {"id": 42}, "chat": {"id": 99}}
+    base.update(message)
+    return {"update_id": update_id, "message": base}
+
+
+class TestParseUpdate:
+    def test_plain_text(self):
+        parsed = parse_update(message_update(text="coffee 250"))
+        assert parsed.user_id == 42
+        assert parsed.chat_id == 99
+        assert parsed.text == "coffee 250"
+        assert parsed.command == ""
+
+    def test_command_with_args(self):
+        parsed = parse_update(message_update(text="/report last_month"))
+        assert parsed.command == "report"
+        assert parsed.args == "last_month"
+
+    def test_bare_command(self):
+        parsed = parse_update(message_update(text="/month"))
+        assert parsed.command == "month"
+        assert parsed.args == ""
+
+    def test_command_is_lowercased(self):
+        assert parse_update(message_update(text="/MONTH")).command == "month"
+
+    def test_group_mention_is_stripped(self):
+        parsed = parse_update(message_update(text="/month@FinBot"), bot_username="FinBot")
+        assert parsed.command == "month"
+
+    def test_mention_of_another_bot_is_ignored(self):
+        assert parse_update(message_update(text="/month@OtherBot"), bot_username="FinBot") is None
+
+    def test_photo_picks_the_largest_size(self):
+        parsed = parse_update(
+            message_update(
+                photo=[
+                    {"file_id": "small", "file_size": 100},
+                    {"file_id": "large", "file_size": 9000},
+                ],
+                caption="lunch",
+            )
+        )
+        assert parsed.file_id == "large"
+        assert parsed.file_kind == "photo"
+        assert parsed.mime_type == "image/jpeg"
+        assert parsed.caption == "lunch"
+        assert parsed.has_file
+
+    def test_document(self):
+        parsed = parse_update(
+            message_update(
+                document={
+                    "file_id": "doc1",
+                    "file_name": "statement.pdf",
+                    "mime_type": "application/pdf",
+                    "file_size": 2048,
+                }
+            )
+        )
+        assert parsed.file_kind == "document"
+        assert parsed.file_name == "statement.pdf"
+        assert parsed.file_size == 2048
+
+    def test_edited_message_is_handled(self):
+        update = {"update_id": 5, "edited_message": {"from": {"id": 42}, "chat": {"id": 99}, "text": "x"}}
+        assert parse_update(update).text == "x"
+
+    def test_non_message_updates_are_skipped(self):
+        assert parse_update({"update_id": 1, "poll": {}}) is None
+
+    def test_malformed_update_is_skipped(self):
+        assert parse_update({"update_id": 1, "message": {"text": "hi"}}) is None
+        assert parse_update({}) is None
+
+    def test_no_file_means_no_file(self):
+        assert not parse_update(message_update(text="hi")).has_file
+
+
+class TestChunkMessage:
+    def test_short_message_is_untouched(self):
+        assert chunk_message("hello") == ["hello"]
+
+    def test_splits_on_line_boundaries(self):
+        text = "\n".join(f"line {i}" for i in range(500))
+        chunks = chunk_message(text, limit=200)
+        assert len(chunks) > 1
+        assert all(len(c) <= 200 for c in chunks)
+        # No content lost.
+        assert "\n".join(chunks) == text
+
+    def test_never_splits_mid_line(self):
+        chunks = chunk_message("aaa\nbbb\nccc", limit=8)
+        for chunk in chunks:
+            for line in chunk.split("\n"):
+                assert line in ("aaa", "bbb", "ccc")
+
+
+class TestSeenUpdates:
+    def test_first_time_is_new(self):
+        seen = SeenUpdates()
+        assert seen.add_if_new(1) is True
+
+    def test_redelivery_is_rejected(self):
+        seen = SeenUpdates()
+        seen.add_if_new(1)
+        assert seen.add_if_new(1) is False
+
+    def test_evicts_oldest_beyond_capacity(self):
+        seen = SeenUpdates(capacity=3)
+        for i in range(5):
+            seen.add_if_new(i)
+        # 0 and 1 were evicted, so they read as new again.
+        assert seen.add_if_new(0) is True
+        assert seen.add_if_new(4) is False