PocketAccountant: custom ledger UI + deterministic agent (engine, ledger, retrieval, classifier)
c55ab5e verified | title: Cuentas Claras | |
| emoji: 🧮 | |
| colorFrom: green | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 6.15.2 | |
| python_version: '3.12' | |
| app_file: app.py | |
| pinned: false | |
| license: apache-2.0 | |
| # 🧮 Cuentas Claras — Your Pocket Accountant Agent | |
| > *"Cuentas claras, amistades largas."* — Clear accounts make for long friendships. | |
| > Snap a receipt or paste an invoice. The agent books it, applies the right formulas, | |
| > tells you what you owe the SAT, and explains why — in plain language. | |
| A small-model **AI accountant agent** that keeps the books, applies the math, and follows | |
| the rules — built for the **Hugging Face "Small Models, Big Adventures" Hackathon (June 2026)**. | |
| It is designed for the people who *can't* afford a full-time accountant: **freelancers | |
| (personas físicas) and micro / small businesses in Mexico** — with a **bonus USA mode** | |
| for cross-border freelancers and Mexican entrepreneurs selling into the United States. | |
| --- | |
| ## Chapter Zero — Why this exists | |
| In Mexico, a freelance designer or a corner *papelería* lives in fear of two things: the | |
| **SAT** (the tax authority) and a shoebox full of receipts. Accountants are expensive, | |
| spreadsheets are intimidating, and the SAT portal is a maze of acronyms — RFC, CFDI, ISR, | |
| IVA, RESICO, DIOT. Most micro-entrepreneurs end up either overpaying, missing deadlines, or | |
| guessing. | |
| **Cuentas Claras is the accountant they can't afford.** It is not a chatbot that *talks* | |
| about taxes — it is an **agent** that: | |
| 1. **Stores** every income and expense as a proper double-entry ledger. | |
| 2. **Applies real formulas** (ISR, IVA, RESICO, ratios, depreciation) through a deterministic | |
| engine — the model *never* does the arithmetic, so it never hallucinates a number. | |
| 3. **Follows the regulation** by grounding its answers in an indexed corpus of Mexican (and US) | |
| tax rules — it cites the rule, it doesn't invent it. | |
| 4. **Explains** every result in plain Spanish or English, like a patient accountant would. | |
| All of this runs on a model small enough to fit on a laptop. **No giant LLM. No cloud | |
| API required.** | |
| --- | |
| ## Track | |
| **🏡 Chapter One — Backyard AI.** Built for a specific, real person: *(builder fills in)* — a | |
| freelance graphic designer / the owner of a small neighborhood business who currently tracks | |
| income in a notebook and dreads tax season. They will actually use it during the hack window, | |
| and that usage is part of the story. | |
| > The honest small-model fit: tax math must be *exact*, so we deliberately push the hard | |
| > numbers into a deterministic engine and use the 8B model only for what small models are | |
| > genuinely good at — language understanding, classification, and orchestration. The | |
| > constraint shapes the architecture instead of fighting it. | |
| --- | |
| ## How it works | |
| ``` | |
| ┌─────────────────────────────────────────────┐ | |
| 🧾 Receipt photo ──▶ │ ACCOUNTANT AGENT │ | |
| 📄 CFDI XML / CSV ──▶ │ (MiniCPM 8B · llama.cpp · local-first) │ | |
| 💬 "How much ISR │ │ | |
| do I owe in May?" │ plans → calls tools → grounds → explains │ | |
| └───────────────┬─────────────────────────────┘ | |
| │ (function / tool calls) | |
| ┌────────────────────────────────┼────────────────────────────────┐ | |
| ▼ ▼ ▼ ▼ ▼ | |
| ┌────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ | |
| │ Ledger │ │ Classifier │ │ Tax Engine │ │ Reg. Retriever│ │ Reports │ | |
| │ (SQLite, │ │ (fine-tuned: │ │ (ISR · IVA · │ │ (RAG over SAT │ │ (P&L, │ | |
| │ double- │ │ txn → SAT │ │ RESICO · US) │ │ + IRS corpus, │ │ balance, │ | |
| │ entry) │ │ account) │ │ DETERMINISTIC│ │ cites rules) │ │ ratios) │ | |
| └────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └───────────┘ | |
| ``` | |
| 1. **Capture** — Add a transaction by typing it, snapping a receipt (vision OCR), importing a | |
| CFDI XML, or uploading a bank/CSV export. | |
| 2. **Classify** — The fine-tuned model maps each transaction to the correct **SAT chart-of-accounts | |
| code** and expense category (deductible? IVA-bearing? which rate?). | |
| 3. **Book** — It is written to a proper double-entry ledger in SQLite — debits and credits balance. | |
| 4. **Compute** — Ask anything ("what do I owe this month?", "am I profitable?") and the agent | |
| calls the deterministic **Tax & Finance Engine**: ISR, IVA, RESICO rates, financial ratios, | |
| break-even, runway, depreciation. | |
| 5. **Ground & explain** — The answer is grounded in the indexed regulation corpus, cites the | |
| relevant article, and is explained in plain language with the math shown. | |
| --- | |
| ## The user-facing features | |
| | Feature | What it does | | |
| |---|---| | |
| | **Smart capture** | Type, photograph (receipt OCR), import CFDI 4.0 XML, or upload CSV. | | |
| | **Auto-categorization** | Fine-tuned classifier → SAT account + deductibility + IVA treatment. | | |
| | **Double-entry ledger** | Every movement booked as balanced debits/credits in SQLite. | | |
| | **Tax dashboard (MX)** | Live estimate of monthly **ISR** and **IVA** owed; **RESICO** vs general regime. | | |
| | **SAT calendar** | Upcoming declaration deadlines and what's due (provisional, DIOT, annual). | | |
| | **Financial statements** | Estado de Resultados (P&L), Balance General, Cash Flow. | | |
| | **Health check** | Liquidity ratio, profit margin, break-even point, cash runway, top expenses. | | |
| | **Plain-language Q&A** | "Can I deduct my laptop?" → grounded answer citing the rule. | | |
| | **🇺🇸 Bonus USA mode** | Schedule-C net profit, self-employment tax, federal estimated quarterly tax, sales-tax notes. | | |
| | **Export** | One-click P&L / ledger to CSV/XLSX for the human accountant or the SAT portal. | | |
| --- | |
| ## Architecture highlights — the principles that win | |
| These are lifted directly from what worked in our previous hackathon entry and hardened for finance: | |
| - **The model never does arithmetic.** Every peso of tax, every ratio, every total comes from a | |
| unit-tested deterministic Python engine. The LLM *decides which formula to call* and *explains | |
| the result* — it does not compute it. This is the single most important design choice for a | |
| financial product and the credible answer to "how do you trust a small model with taxes?" | |
| - **Grounded, not guessed.** Regulatory answers retrieve from an indexed corpus of SAT / IRS | |
| source text and **cite the article**. If the corpus doesn't support a claim, the agent says so | |
| and recommends a human CPA — it never free-styles tax law. | |
| - **Real agent loop, not a wrapper.** The model plans, calls typed tools, reads results, and | |
| decides the next step (capture → classify → book → compute → report). The tool layer is the | |
| product; the model is the orchestrator. | |
| - **One model, many roles.** A single ~8B model handles classification, tool-planning, and | |
| natural-language explanation — no redundant downloads, fits the param budget with huge headroom. | |
| - **Deterministic where it must be, generative where it helps.** Numbers and law: deterministic. | |
| Language and judgment: generative. The boundary is the architecture. | |
| - **Privacy by default.** Financial data is sensitive. The whole thing can run **fully local** | |
| (llama.cpp + on-disk SQLite) — your books never leave your machine. | |
| --- | |
| ## Models & parameter budget | |
| | Role | Model | Params | Runtime | | |
| |---|---|---|---| | |
| | Reasoning · classification · explanation | `openbmb/MiniCPM-...-8B` (**fine-tuned**) | ~8B | **llama.cpp** (GGUF, quantized) | | |
| | Receipt OCR (optional capture) | small vision model / Tesseract fallback | ≤4B | local | | |
| **Total: ~8B parameters** (≤ 32B cap ✓ — comfortable headroom). | |
| - **Why MiniCPM (OpenBMB):** strong tool-calling and multilingual (Spanish) performance at 8B, | |
| and it makes us eligible for the **OpenBMB sponsor award**. | |
| - **Why llama.cpp + GGUF:** runs the whole agent on a laptop with no GPU, unlocking the | |
| **🔌 Off the Grid** and **🦙 Llama Champion** badges at once. | |
| - **Tiny Titan path (optional stretch):** ship a ≤4B variant (e.g. a 3–4B fine-tune) as a | |
| "lite" mode to compete for the **🐜 Tiny Titan** special award. | |
| --- | |
| ## What we fine-tune (🎯 Well-Tuned) | |
| We publish a **fine-tuned transaction-classification + tool-planning model** to the Hub. | |
| - **Task 1 — SAT categorization:** map a free-text / OCR'd transaction description ("Uber al | |
| cliente", "café con proveedor", "licencia Adobe anual") to the correct **SAT chart-of-accounts | |
| code**, deductibility flag, and IVA treatment (16% / 0% / exempt). This is exactly the kind of | |
| narrow, high-value task where a fine-tune beats a generic model and a generic model embarrasses | |
| itself. | |
| - **Task 2 — tool-call planning:** teach reliable, schema-valid function-calling for our engine | |
| (the model emits clean JSON tool calls instead of prose). | |
| **Dataset:** a synthetic-plus-curated set of Mexican transaction descriptions ↔ SAT codes | |
| (generated from the official *catálogo de cuentas* + real anonymized examples), plus tool-call | |
| traces. Published as a Hub dataset for the **📡 Sharing is Caring** badge. (We already proved | |
| this pipeline: our previous entry fine-tuned a planner on 2,046 instruction pairs.) | |
| --- | |
| ## Mexican regulation coverage (the core) | |
| | Area | What the engine implements | | |
| |---|---| | |
| | **Regimes** | RESICO (Personas Físicas), Régimen de Actividad Empresarial y Profesional, Plataformas Digitales; Personas Morales basics. | | |
| | **ISR** | Monthly provisional payments; RESICO progressive rate table by income bracket; annual reconciliation estimate. | | |
| | **IVA** | 16% standard, 0% (border/exports/basic goods), exempt; IVA acreditable vs trasladado; monthly net. | | |
| | **Retenciones** | ISR/IVA withholdings on professional fees and platform income. | | |
| | **CFDI 4.0** | Parse XML invoices → auto-book income/expenses with the right tax breakdown. | | |
| | **Deductibility** | Strict vs non-strict deductions, requisitos (CFDI, payment method, business purpose). | | |
| | **Obligations calendar** | Provisional declarations, DIOT, annual return dates. | | |
| > ⚠️ **Disclaimer (shipped in-app):** Cuentas Claras is an educational assistant, **not a | |
| > substitute for a licensed Contador Público**. Tax tables are versioned and dated; the app | |
| > tells the user to confirm filings with a professional. This honesty is a feature, not a hedge. | |
| ### 🇺🇸 Bonus: USA mode | |
| Schedule-C net profit, self-employment tax (15.3%), federal income tax brackets, quarterly | |
| estimated tax (Form 1040-ES), and a sales-tax primer for the most common states — aimed at | |
| Mexican freelancers earning USD and US-based gig workers. | |
| --- | |
| ## Tech stack | |
| - **UI:** Gradio `6.x`, hosted as a **Hugging Face Space** (hard requirement ✓). | |
| - **Custom frontend (🎨 Off-Brand):** a bespoke "ledger book / receipt" aesthetic via | |
| `gr.Server` + custom CSS — monospaced numerals, green-ledger palette, tabbed accountant | |
| dashboard — pushing well past default Gradio. | |
| - **Inference:** `llama.cpp` (GGUF) for local-first; **Modal** endpoint as an optional hosted | |
| fallback for the public demo (makes us eligible for the **Modal award** and keeps the Space | |
| responsive under load). | |
| - **Storage:** SQLite (double-entry ledger, per-user, on disk). | |
| - **Engine:** pure-Python, fully unit-tested tax & finance module (no LLM in the number path). | |
| - **Retrieval:** lightweight local embedding index over the SAT/IRS corpus (no external API). | |
| - **Capture:** receipt OCR + CFDI XML parser + CSV importer. | |
| --- | |
| ## Bonus Quests — going for all six 🎖️ | |
| | Badge | Target | How | | |
| |---|:---:|---| | |
| | 🔌 **Off the Grid** | ✓ | Entire agent runs locally on llama.cpp + on-disk SQLite; no cloud API required. | | |
| | 🎯 **Well-Tuned** | ✓ | Fine-tuned MiniCPM for SAT categorization + tool-planning, published to the Hub. | | |
| | 🎨 **Off-Brand** | ✓ | Custom "ledger book" UI via `gr.Server` + CSS — not the default Gradio look. | | |
| | 🦙 **Llama Champion** | ✓ | Model served through the `llama.cpp` runtime (GGUF, quantized). | | |
| | 📡 **Sharing is Caring** | ✓ | Agent traces + the fine-tune dataset shared publicly on the Hub. | | |
| | 📓 **Field Notes** | ✓ | Blog post: *"Building a trustworthy small-model accountant — when NOT to let the LLM do the math."* | | |
| ### Stacking sponsor & special awards (one app, many podiums) | |
| - **🏮 OpenBMB Award** — built on MiniCPM. | |
| - **🟢 Modal Award** — hosted inference endpoint on Modal. | |
| - **🤖 Best Agent** — a genuine plan→tool→ground→explain loop under the 32B cap. | |
| - **🎖️ Bonus Quest Champion** — all six badges on one sash. | |
| - **🎨 Off-Brand Award** — the custom ledger UI. | |
| - **🐜 Tiny Titan** (stretch) — optional ≤4B "lite" build. | |
| --- | |
| ## Project structure (planned) | |
| ``` | |
| FinanceHelper/ | |
| ├── app.py # Gradio entry point (Space) | |
| ├── README.md # Space card (this front-matter) | |
| ├── requirements.txt | |
| ├── packages.txt | |
| ├── src/ | |
| │ ├── agent/ # planner, tool registry, agent loop | |
| │ ├── engine/ # DETERMINISTIC tax & finance math (unit-tested) | |
| │ │ ├── isr.py | |
| │ │ ├── iva.py | |
| │ │ ├── resico.py | |
| │ │ ├── ratios.py | |
| │ │ └── us_tax.py | |
| │ ├── ledger/ # SQLite double-entry store | |
| │ ├── capture/ # OCR, CFDI XML parser, CSV importer | |
| │ ├── retrieval/ # SAT/IRS corpus index + citation | |
| │ ├── models/ # llama.cpp loader, prompts | |
| │ ├── ui/ # gr.Server custom frontend + CSS | |
| │ └── config.py | |
| ├── modal_app/ # optional hosted inference endpoint | |
| ├── data/ | |
| │ ├── regulation/ # SAT + IRS source corpus (dated, versioned) | |
| │ ├── catalogo_cuentas/ # SAT chart of accounts | |
| │ └── sample/ # demo ledger for the video | |
| ├── scripts/ | |
| │ ├── build_classifier_dataset.py | |
| │ └── train_classifier.py | |
| └── tests/ # engine correctness tests (gold tax cases) | |
| ``` | |
| --- | |
| ## Implementation roadmap (to June 15) | |
| 1. **Engine first (the trust foundation).** Build and unit-test ISR / IVA / RESICO / ratios | |
| against hand-computed gold cases. *No model involved yet.* | |
| 2. **Ledger + capture.** SQLite double-entry store; CSV import; CFDI XML parser; receipt OCR. | |
| 3. **Agent loop.** Tool registry + planner; wire MiniCPM via llama.cpp; schema-valid tool calls. | |
| 4. **Retrieval + citations.** Index SAT/IRS corpus; ground answers; "cite or abstain" guardrail. | |
| 5. **Fine-tune + publish.** Train the SAT classifier; push model + dataset to the Hub. | |
| 6. **Custom UI.** `gr.Server` ledger-book frontend; tax dashboard; statements; export. | |
| 7. **USA bonus mode.** Schedule-C / SE-tax / 1040-ES estimator. | |
| 8. **Polish + Modal fallback + deploy** to the Space. | |
| 9. **Deliverables.** Demo video, social post, blog (Field Notes), shared traces. | |
| --- | |
| ## Deliverables checklist (hackathon submission) | |
| - [ ] Public **Gradio Space** under the hackathon org. | |
| - [ ] **Demo video** — capture a receipt → book it → "what do I owe this month?" → grounded answer. | |
| - [ ] **Social-media post** showing the ledger UI and the live tax estimate. | |
| - [ ] **Fine-tuned model + dataset** on the Hub (🎯 + 📡). | |
| - [ ] **Blog post / report** (📓). | |
| - [ ] **Agent traces** shared on the Hub (📡). | |
| - [ ] A real person used it during the hack window (🏡 Backyard AI evidence). | |
| --- | |
| ## Risks & mitigations | |
| | Risk | Mitigation | | |
| |---|---| | |
| | Tax math must be exact | Deterministic, unit-tested engine; model is barred from the number path. | | |
| | Tax law is nuanced / changes | Dated, versioned corpus; "cite or abstain"; explicit "confirm with a CPA" disclaimer. | | |
| | Small model tool-calling reliability | Fine-tune specifically on schema-valid tool calls; strict JSON parsing with graceful fallback. | | |
| | Space latency / ZeroGPU limits | llama.cpp quantized local path + optional Modal endpoint for the public demo. | | |
| | Sensitive financial data | Local-first by default; data stays in on-disk SQLite; no required cloud calls. | | |
| --- | |
| *Submission for the Hugging Face "Small Models, Big Adventures" Hackathon · June 5–15, 2026.* | |
| *Track: 🏡 Backyard AI. Going for all six bonus badges, plus OpenBMB / Modal / Best Agent.* | |