---
title: PocketAccountant
emoji: 🧮
colorFrom: green
colorTo: indigo
sdk: gradio
sdk_version: 6.18.0
python_version: '3.12'
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - build-small-hackathon
  - track:backyard
  - achievement:welltuned
  - achievement:offbrand
  - achievement:sharing
  - achievement:llama
  - sponsor:openbmb
  - sponsor:modal
  - accounting
  - taxes
  - agent
  - mexico
  - usa
---
# 🧮 PocketAccountant — Your Pocket Accountant Agent

Mexico runs on small business: millions of people are entrepreneurs running tiny
companies — *PyMEs* — and almost all of them fear the same thing, the **SAT** (Mexico's
tax authority, the equivalent of the IRS in the US). The rules are a maze of acronyms,
most people genuinely don't know how it works, and a real accountant is expensive.

**PocketAccountant** is an AI **accountant agent** for exactly those people — serving both
**🇲🇽 Mexican** and **🇺🇸 US** freelancers and small businesses. It stores your income and
expenses as a proper double-entry ledger, classifies them to the SAT chart of accounts,
and computes taxes with a **deterministic engine** — Mexico: ISR · IVA · RESICO; USA:
Schedule C · self-employment tax · federal income tax · quarterly estimates. The language
model reasons and explains, but **never does the arithmetic**, so it can't hallucinate a
tax number. English by default; the agent answers in English or Spanish. Pick your country
and ask away.

See **[PLAN.md](PLAN.md)** for the full design, architecture, and hackathon
bonus-quest strategy.

## 🏆 Hackathon submission

- **Track:** 🏡 Backyard AI — built for a real person (a freelancer / small-business owner who tracks income in a notebook and dreads tax season).
- **Live Space:** https://huggingface.co/spaces/build-small-hackathon/PocketAccountant
- **Demo video:** https://youtu.be/1h7vfVGgiZQ
- **Social posts:** [LinkedIn](https://www.linkedin.com/posts/carlos-casta%C3%B1eda-mora_smallmodelsbigadventures-buildsmall-huggingface-share-7472421950351585280-7Ua3/) · [Instagram](https://www.instagram.com/p/DZn8g5EGjWs/)
- **Team (HF usernames):** [@eldinosaur](https://huggingface.co/eldinosaur) · [@Fred1e4](https://huggingface.co/Fred1e4)

### Models (≤ 32B total ✓)

| Role                                    | Model                                                                | Params | Runtime                                         |
| --------------------------------------- | -------------------------------------------------------------------- | ------ | ----------------------------------------------- |
| Conversational reasoning agent          | `Qwen/Qwen3-8B`                                                    | 8B     | vLLM on Modal (OpenAI-compatible, tool-calling) |
| SAT transaction classifier (fine-tuned) | `eldinosaur/cuentas-claras-sat-classifier-minicpm` (MiniCPM4.1-8B) | 8B     | transformers / GGUF (llama.cpp)                 |

### Bonus badges claimed

🎯 Well-Tuned · 🎨 Off-Brand · 📡 Sharing is Caring · 🦙 Llama Champion · 🏮 OpenBMB · 🟢 Modal

<!-- 🔌 Off the Grid: add once you demo local mode (PA_LLM_MODE=local, GGUF via llama.cpp). 📓 Field Notes: add once the blog post is written. -->

## Run the engine tests

```bash
python -m unittest discover -s tests
```

## Try the engine

```bash
python -m scripts.demo          # tax engine, standalone
python -m scripts.demo_ledger   # book a month, then compute taxes from the books
python -m scripts.demo_agent    # full agent loop (plan → tools → answer) + saved trace
python -m scripts.demo_grounding # cite-or-abstain: cites LISR Art. 34, abstains on out-of-scope
python -m scripts.demo_finetune  # SAT auto-classification + one-step categorize & book
```

## Fine-tune (🎯 Well-Tuned)

```bash
python -m scripts.build_classifier_dataset      # → data/finetune/{train,val}.jsonl
modal run modal_app/finetune_modal.py --push <org>/cuentas-claras-sat-classifier
```

> ⚠️ Educational assistant, **not** a substitute for a licensed Contador Público /
> CPA. Tax tables are dated and must be verified against the official DOF / IRS
> publications before any real filing.