Try PolicyTrace yourself: a step-by-step guide

This is the practical one. If you want to see PolicyTrace work, without taking my word for it, here are two ways to try it, what to check once it's running, and what to do when something goes wrong. I ran the local install below on a fresh clone before writing this, so the commands and timings are real.

One rule before you start: use the synthetic demo pack in the repo, or documents you have made up yourself. Don't upload real policy documents to the public demo or to a copy you're running for fun.

Option 1: the live demo, no install

1. Open the PolicyTrace Space on Hugging Face. If it has been idle, it can take about a minute to wake up.
2. On the upload screen, click Load demo pack. This loads the four synthetic PDFs: a Schedule, a Certificate of Motor Insurance, a Statement of Fact and a policy booklet.
3. Click Extract & review. The button says 30 to 90 seconds, but on Groq's free tier a full pack currently takes two to three minutes, mostly waiting on rate limits.
4. When it finishes, you get the review screen: the extracted record on one side and the source PDFs on the other.

That's enough to see the idea. If you want to read the code, change it or try other documents, run it yourself.

Option 2: run it on your own machine

You'll need: Python 3.11 or newer (I tested 3.13), Node.js 20 or newer, git, a free Groq API key, and about 8 GB of free disk space. Most of that is PyTorch, which Docling needs for reading PDF layouts.

1. Get the code.

git clone https://github.com/AItoolstack/ai-policytrace.git
cd ai-policytrace

2. Create a virtual environment and install. This took about eight minutes on my run.

python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate

pip install -r requirements-dev.txt
python -m spacy download en_core_web_lg

3. Add your Groq key. Copy the example file and put your key in it. The .env file is ignored by git, so it won't be committed.

# Windows PowerShell
Copy-Item .env.example .env
# macOS / Linux
cp .env.example .env

# then edit .env:
GROQ_API_KEY="your_key_here"

4. Run the tests. They don't call any model, so they take a few seconds. You should see 32 passed.

pytest -q

5. Start the API.

uvicorn api:app --app-dir src --port 8000

Open http://localhost:8000/api/health in a browser. You should see {"status":"ok","version":"1.0.0"}.

6. Start the review UI in a second terminal.

cd ui
npm ci
npm run dev

Open http://localhost:5173, click Load demo pack, then Extract & review.

The first run is slow. On its first extraction, the app downloads Docling's layout model from Hugging Face. The spaCy model in step 2 is about 400 MB; en_core_web_sm also works if you're short of space, with weaker name detection. After that, runs are limited mainly by Groq's rate limits.

Other ways to run it. docker build -t policytrace . then docker run --rm -p 7860:7860 --env-file .env policytrace builds from the same Dockerfile as the live demo and serves it at http://localhost:7860. And if you only want the JSON, there's a command-line mode:

python src/main.py --input sample_data/policytrace_demo_pack --output output/golden_record.json

What to test

Here's what I'd check, in this order:

1. The basics are right. sample_data/policytrace_demo_pack/manifest.json lists the expected policy number (NBM-DEMO-0427), registration (ZX24 DEM) and insurer. Check that the record agrees.
2. Click through the evidence. Click a few fields and look at where the highlight lands in the PDF. Most land on the value. Driver fields should land on their own row in the driver table; here's why that used to go wrong. Also look for fields marked "no source location · check manually".
3. Read the conflicts. The conflict panel lists every field where the Schedule and the Certificate disagree, both values and which one won. On the demo pack you should see none, because the Schedule and the Certificate agree. Earlier versions showed false main-driver conflicts here, caused by a bug in how drivers were matched across documents; it's fixed. Try the "make your own pack" test below to create a real disagreement.
4. Act as the reviewer. Verify one field, override another with a new value and flag a third. Then open output/sessions/<session>/review_state.json and see exactly what was stored.
5. Break it on purpose. Upload only the Certificate, or only the policy booklet, and see how the record and the logs change when a document is missing.
6. See what was masked. Set debug: enabled: true in config/settings.yaml, restart the API and run again. The session folder gets a debug/ folder with the Markdown before and after masking, so you can see what Presidio removed before anything went to the model. It's off by default because that folder holds the unmasked text.
7. Make your own pack. Edit the POLICY values at the top of scripts/generate_synthetic_policy_pack.py, for example the excesses or a driver's date of birth, and run python scripts/generate_synthetic_policy_pack.py. It overwrites the demo pack (git can restore it). Run the extraction again and check the record follows your changes.

If something goes wrong

• "Internal Server Error" straight after you click Extract. Look at the terminal running the API. "No Schedule or Certificate extracted. Check GROQ_API_KEY" usually means the key is missing or wrong in .env. Restart the API after you fix it.
• A rate-limit error from Groq. The free tier has per-minute token limits. Wait a minute and try again, or upload fewer documents.
• PowerShell won't run Activate.ps1. Use .venv\Scripts\activate.bat from Command Prompt instead.
• The UI loads but nothing happens. Check the API is still running on port 8000. The UI on port 5173 sends its requests there.

Getting help, or telling me what you found

If you hit a bug or a setup problem, open an issue on GitHub with the command you ran and the error. That keeps the answer public for the next person. For questions or ideas, leave a comment below (you'll need a free ai·toolstack account, which is also how you subscribe). If you want to follow where PolicyTrace goes next, subscribe to ai·toolstack, and if you'd like to talk about using this kind of pipeline at work, connect with me on LinkedIn.

If you're wondering why I built this in the first place, I've written about the claims problem it's aimed at.