AgentProof

An agent-side tool that turns Texas county data (Dallas + Collin) into client-ready pricing, offer, and value-justification reports. Not a listing portal — the intelligence layer between one and a real client conversation.

Portals help people browse. AgentProof helps agents prove.

The design rule everything follows from

[Ingestion] → [Storage] → [Deterministic engine] → [LLM interpretation] → [Render]
 jobs/         SQLite /    engine/                  api/app/llm.py         PDF + web
               Postgres    every number starts here  formats, adds none

The engine computes; the LLM only formats the engine's computed_facts. A guard (ground_check) extracts every figure from generated prose and rejects the output if a number isn't in the facts — a violation falls back to a deterministic template. An agent puts their license behind these numbers, so this is enforced in code and locked by tests, not left to the prompt.

The same rule is why the optional RAG layer only ever changes wording: retrieved text is stripped of digits before it can reach the prompt.

Layout

Dir	What	Stack
engine/	Pure, I/O-free core. Every number in every report originates here.	Python, zero runtime deps
api/	App + data layer, auth/tenancy, the LLM boundary, snapshots, share links, PDF	FastAPI + SQLAlchemy
web/	Dashboard, report workspace, property intel, editor, share view	Vite + React 18 + TypeScript
jobs/	Ingestion (Collin CAD, Dallas DCAD, FEMA flood, tax rates, geocoding)	Python
rag/	Optional retrieval lab — embeddings, a pluggable vector store, hybrid search, reranking	Python, stdlib-only core
rageval/	Retrieval evaluation — precision/recall@k, MRR, nDCG, faithfulness	Python
infra/	PostGIS + pgvector migration	SQL

Requirements

• Python 3.11+ (3.12 recommended — see the note under RAG)
• Node 18+
• No database server needed: it defaults to a local SQLite file.
• No API key needed: without ANTHROPIC_API_KEY the report prose is produced by a deterministic template generator, fully offline.

Quickstart

git clone <your-repo-url> agentproof && cd agentproof

# 1. Python deps
python3 -m venv .venv
.venv/bin/pip install -r api/requirements.txt
.venv/bin/pip install -e engine                        # the deterministic core
.venv/bin/pip install -e "rag[fast]" -e rageval        # optional: the retrieval lab

# 2. API on :8000 — creates and seeds api/agentproof.db on first run
cd api && ../.venv/bin/uvicorn app.main:app --port 8000

# 3. Web on :3000, in a second shell — proxies /api/* to :8000
cd web && npm ci && npm run dev

Open http://localhost:3000 and sign in as demo@agentproof.app / password123. Then: create a report → review property intelligence → add comps → generate → override anything → export a branded PDF or a revocable share link.

Deploying this anywhere? AGENTPROOF_SEED defaults to 1, which creates that demo super-admin with a password published in this README, and the login form pre-fills it. Set AGENTPROOF_SEED=0 for anything reachable from the internet.

Copy .env.example to .env for the full list of settings.

Running the tests

(cd engine && ../.venv/bin/python -m pytest)   # 46 — the liability-shield suite
(cd api    && ../.venv/bin/python -m pytest)   # 47
.venv/bin/python -m pytest jobs/tests          # 42
.venv/bin/python -m pytest rag/tests           # 18
.venv/bin/python -m pytest rageval/tests       #  7
(cd web    && npm test)                        #  4

The engine suite is the one that matters most: comp integrity, no price fabrication, tax-stack correctness (MUD surfacing, a golden parcel within $1), cost math, and purity — same inputs produce byte-identical computed_facts.

The non-disclosure rule, enforced in code

Texas is a non-disclosure state: sale prices are not public record. A cad_estimate listing can therefore never carry a close_price, so a comp query (which requires close_price IS NOT NULL) can never surface a county modeled value as a sale. Enforced in select_comps, re-checked in validate_facts, and asserted at the database level by a CHECK constraint in infra/postgis.sql.

Optional: the RAG lab

rag/ and rageval/ are a self-contained retrieval lab built on the app's own data: embeddings, a vector store with SQLite and pgvector backends, hybrid (BM25 + vector) search fused with RRF, MMR/LLM reranking, and an evaluation harness. It is off by default — the app is fully functional without it — and turns on with AGENTPROOF_RAG=1.

It runs offline out of the box using a deterministic hashing embedder, with no model download. The optional real model (all-MiniLM-L6-v2) needs fastembed or torch, neither of which publishes wheels for Python 3.13+; on 3.11/3.12 just pip install -e "rag[onnx,fast]", and on 3.13+ either stay on the hashing embedder or put the model in a side venv. See rag/README.md.

Data sources

Ingestion runs against public endpoints: Collin CAD and Dallas DCAD appraisal data, Texas Comptroller / CAD entity tax rates, TEA district ratings, FEMA NFHL flood zones, and the US Census geocoder. No third-party data is redistributed here — the SQLite database and vector indexes are gitignored and rebuilt locally. The test fixtures mirror the real upstream schemas with synthetic owners and addresses.

Socrata endpoints are rate-limited without a SOCRATA_APP_TOKEN.

Status

Built: the deterministic engine, all three report types (seller pricing, buyer offer, agent value), the live ingestion pipeline, telemetry, server-side branded PDF and revocable share links, and the optional RAG lab.

Not built: Dallas DCAD bulk ZIP import, TEA attendance-zone polygons, the full TCEQ MUD registry, and the NTREIS MLS feed (the adapter exists but stays dormant until a licensed vendor feed is configured — see jobs/README.md).

License

MIT — see LICENSE.