# The ZRA Tax Desk

> A tax assistant for Zambian small businesses that answers only from ZRA’s published guides, cites the page behind every answer, and hands every calculation to tested code.

Canonical: https://www.zambrite.com/ai-training/lessons/capstone-zra-tax-desk

B8Beginner capstone 20 to 30 hours

A tax assistant for Zambian small businesses that answers only from ZRA’s published guides, cites the page behind every answer, and hands every calculation to tested code.

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

25

Retrieval quality

Recall@5 on your 50-question set, reported with the misses

20

Citation correctness

Share of claims whose cited page actually says it

20

Tool correctness

Unit tests pass; the model never computes a figure itself

20

Contract and schema

Every response validates; refusals follow the contract

15

Honest uncertainty

Questions outside the documents get a refusal, not a guess

Weights out of 100

## Get it reviewed

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

[B7 Function Calling & Tool Use](https://www.zambrite.com/ai-training/lessons/function-calling)[Next · I1 Advanced RAG (Chunking, Reranking, Hybrid Search)](https://www.zambrite.com/ai-training/lessons/advanced-rag)

Adapted from open-source work: AI Engineering from Scratch by Rohit Ghumare (MIT, lesson text, code and quizzes); Awesome LLM Apps by Shubham Saboo (Apache-2.0, starter code); AI Engineering Interview Questions by Outcome School (Apache-2.0, interview questions). Capstones, milestones, data packs and Zambian context by Zambrite.

ZRA Tax Desk starter pack

- seed-questions.csv (20 questions with expected sources)
- document-list.md (which ZRA guides and Acts to download, and why)
- answer-schema.json (a starting response schema)

[Download the pack](https://www.zambrite.com/downloads/lessons/beginner-pack.zip)

All data is synthetic. No real people or businesses.

## Related
- [Home](https://www.zambrite.com/)
- [Contact](https://www.zambrite.com/contact)