README.md

metadata

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 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 ✓)

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

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.