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