build-small-hackathon/PocketAccountant

🧮 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 · Instagram
• —Team (HF usernames): @eldinosaur · @Fred1e4

Models (≤ 32B total ✓)

Bonus badges claimed

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

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

Run the engine tests

python -m unittest discover -s tests

Try the engine

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)

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.