README.md

---
title: Oracle
emoji: 💸
colorFrom: green
colorTo: indigo
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
short_description: Expense tracking and budget coaching over Telegram
---

# coco-finbot

> Deployed as the **Oracle** Space on `sdk: gradio`.
>
> The bot is FastAPI; Gradio is only there to satisfy the platform. Since
> mid-2026, Docker Spaces require PRO, and the one free hardware tier for
> personal accounts — ZeroGPU — refuses any SDK but Gradio. So `app.py` builds
> the FastAPI app, mounts a one-page Gradio UI at `/` via
> `gr.mount_gradio_app`, and serves both. No GPU is used: inference goes out
> over HTTP to HF Inference Providers.
>
> The `Dockerfile` is still current and is what you'd use to self-host.

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 |
| `HF_DATASET_REPO` | ✅ | `<you>/finbot-data` — **without this your data is lost on restart** |
| `HF_TOKEN` | ✅ | **Write**-scoped token. Needed to mirror the ledger; also used for remote inference if you pick that backend |
| `ALLOWED_TELEGRAM_USERNAMES` | ✅ | Your Telegram @handle (comma-separated for more). Not needed if `OPEN_ACCESS=true` |
| `ALLOWED_TELEGRAM_USER_IDS` | | Numeric IDs — the only option for users with no @handle set |
| `PUBLIC_BASE_URL` | | Origin for dashboard links. Derived from `SPACE_HOST` on a Space |
| `DASHBOARD_LINK_MINUTES` | | Sign-in link lifetime. Default `30` |
| `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 |
| `LLM_BACKEND` | | `auto` (default), `local`, `remote`, `off`. See below |
| `LOCAL_LLM_MODEL` / `LOCAL_VISION_MODEL` | | Override the on-GPU models |
| `DEFAULT_CURRENCY` | | ISO code for bare amounts. Default `INR` |
| `TIMEZONE` | | Decides what "today" means. Default `Asia/Kolkata` |

A read-only token is not enough: `CommitScheduler` writes the ledger with it,
and a read token means your data silently never persists.

Generate a webhook secret with:

```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 inference is unavailable, text
logging and every summary still work.

**Two interchangeable inference backends.** `local` runs a small instruct model
(Qwen2.5-3B, plus a 3B VL model for receipts) on the Space's own borrowed A10G;
`remote` calls HF Inference Providers. Same interface, chosen by `LLM_BACKEND`,
and `auto` picks local whenever a CUDA device is present. Local is the default
on a Space because it costs nothing per call — which is what makes
`OPEN_ACCESS` affordable, since otherwise every stranger's receipt would spend
your inference credits.

**Money is never a float.** Amounts are integer minor units (paise, cents, fils)
plus an ISO 4217 code. Currencies are never summed together — a multi-currency
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.
- **Free Spaces sleep** after 48h idle, and the first request after that pays a
  cold start plus a model load. Telegram retries, so the message lands — it is
  just slow.
- **A 3B model is not a frontier model.** It is good enough for "which column is
  the amount" and short coaching; expect worse statement extraction than the
  remote backend. Switch with `LLM_BACKEND=remote` if you would rather spend
  credits for quality.
- **ZeroGPU has a daily GPU-second quota** on free accounts. Heavy statement
  days can exhaust it; typed expenses keep working regardless.
- **`ssr_mode=False` is load-bearing.** Spaces sets `GRADIO_SSR_MODE`, which
  switches the frontend to a Node-rendered SvelteKit build served from
  `/_app/immutable/*`. Because this app calls `demo.launch()` itself rather than
  going through Gradio's standard Space entrypoint, that SSR server never
  starts, so every CSS/JS asset 404s. The symptom is nasty: the page still
  returns HTTP 200 with a server-rendered shell, so it looks "up" while no
  JavaScript ever runs — meaning `demo.load` never fires and the dashboard
  silently ignores its sign-in token. Do not remove it.