---
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.*