collinewait/igniters-squad-02-naija-tax-ai
Domain:
socioeconomicRecord type:
software
Creator:
col
Host:
NaijaTax AI is a multi-agent system designed to help Nigerian citizens navigate the newly introduced tax laws. The system autonomously extracts financial data from user-uploaded bank statements, cross-references it with up-to-date Nigerian tax legislation, and provides a highly secure, Human-In-The-Loop (HITL).
# Naija Tax AI
Privacy-aware Nigerian tax assistance built during a 72-hour sprint as the Agentic AI Engineering Bootcamp capstone. The system helps users work through newly introduced tax rules by combining bank-statement ingestion, PII-safe processing, and a **Human-in-the-Loop (HITL)** flow before any simulated filing step.
**Stack:** **Streamlit** (`ui/`) for uploads, chat, and confirmations; **LangGraph** (`agentic_core/`) orchestrating three logical agents; a local **MCP server** (`mcp_server/`); shared guardrails in `utils/` (exceptions, PII-safe logging).
---
## Architecture
Orchestration uses **LangGraph** with a linear `guardian → strategist → sidekick` graph.
### Agents
1. **Guardian (intake & privacy)** — Only path that should touch raw uploads; scrubs PII before downstream agents see content.
2. **Strategist (tax & law)** — Produces structured tax drafts. The repo currently ships a **placeholder**; wire in LLM + retrieval over official FIRS/NTA sources for production.
3. **Sidekick (filing / HITL)** — Presents figures for explicit user confirmation before a simulated filing step.
### MCP server
Custom **FastMCP** server (`mcp_server/`) exposes tools used by the agents:
| Tool | Role |
|------|------|
| `scrub_pii` | Masks BVN/NUBAN-like sequences in text (see `mcp_server/tools/pii_scrubber.py`). |
| `parse_bank_pdf` | Extracts tables (Camelot) or page text (PyMuPDF) from bank PDFs (`mcp_server/tools/bank_parser.py`). |
| `query_nigerian_tax_law` | Finance Act retrieval via Chroma (`mcp_server/tools/tax_rag.py`; stub until the vector collection is wired). |
| `attach_chrome_cdp` | CDP attach to user Chrome (`mcp_server/tools/browser_tools.py`; stub until Playwright is wired). |
Implementation modules are also referred to as `pii_scrubber`, `bank_parser`, `tax_rag`, and `browser_tools` in squad ownership below.
### Diagram
Add an architecture image (e.g. `architecture.png`) in the repo root and link it here when available.
---
## Guardr …