PLAN.md

metadata

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.