The ZRA Tax Desk

The problem

Small businesses in Zambia ask the same tax questions every month: do I register for VAT, what is turnover tax, what must a Smart Invoice carry, when is PAYE due. The answers exist in ZRA’s public guides and the Acts, spread across dozens of PDFs. A model on its own will answer confidently and sometimes wrongly, and a wrong tax answer costs the business money.

You build an assistant that behaves like a careful tax clerk: it answers only from the documents you ingested, cites the document and page for every claim, refuses when the documents are silent, and never does arithmetic itself. Rates live in a versioned table you source from ZRA and cite; calculations run in functions with unit tests.

Architecture

ZRA guides and Acts (PDF)
      |
      v
parse -> chunk by section (keep doc, page, heading)
      |
      v
embeddings -> vector index  +  rate table (versioned, cited)
      |
question
      |
      v
context builder: system contract + top-k chunks + tool specs
      |
      v
model -> JSON {answer, citations[], confidence, needs_human, follow_up}
      |          \
      |           tool calls: vat_on(amount), turnover_tax(turnover, period)
      v
schema validation -> citation check -> response

What you hand in

• A one-page user contract: who it serves, what it must never do, what it says when unsure
• A JSON schema every answer passes, with a validator and retry on failure
• An ingestion script for at least 30 ZRA documents, chunked by section with page numbers
• Two calculation tools with unit tests, reading rates from a cited, dated table
• A 50-question test set with expected sources, and your recall@5 and citation scores

How it is marked

Weights out of 100

Get it reviewed

Paste your capstone report. Jev scores the evidence against each rubric line; the final mark comes from your mentor’s code review.