Relocation Scout
A governed AI workflow for house-hunting. Not a chatbot. Not a prompt wrapper.
Production-oriented proof-of-concept demonstrating how to build agentic systems where code handles determinism, agents provide judgment, and humans retain authority.
The Architectural Thesis
Use code for determinism, agents for judgment, and humans for authority.
Most "AI agent" demos hand the LLM a prompt, a tool list, and hope for the best. That's not engineering — that's vibes.
Relocation Scout demonstrates a different approach:
| Plane | What it handles | How |
|---|---|---|
| Deterministic | Normalization, dedup, commute, hard constraints, scoring, state machine, idempotency | Pure Python functions — no LLM |
| Agentic | Neighbourhood assessment, qualitative ranking, shortlist synthesis, message drafting | Narrowly-scoped LLM calls with Pydantic-validated outputs |
| Human | Approval of any external side effect | Code-level gateway — not a prompt |
The LLM is a narrowly-scoped component inside a larger software system. The workflow state machine, persistence, contracts, and security boundaries are all conventional engineering.
What It Does
- Create a search — set budget, bedrooms, commute max, preferred neighborhoods, priorities
- Watch the pipeline run — 10 automated steps from fetching listings to drafting messages
- Inspect results — ranked shortlist with deterministic scores + agent qualitative assessments
- Approve and execute — human reviews and approves the realtor message before it's sent
- Trust the system — prompt injection defense, idempotent actions, crash recovery, full audit trail
Key Invariants
- Agents never execute external side effects
- All side effects pass through the approval gateway
- All LLM outputs are schema-validated (Pydantic v2)
- External content is treated as untrusted
- Workflow state lives in SQLite, not LLM context
- Every external action has an idempotency key
- Approved payloads cannot change without invalidating approval
Quick Start
git clone https://github.com/rmax-ai/relocation-scout.git
cd relocation-scout
make demo- Backend:
http://localhost:8000/docs(OpenAPI) - Frontend:
http://localhost:5173
Mock mode is the default — no API keys required. Set AGENT_RUNTIME=adk + GOOGLE_API_KEY for live Gemini 2.5 Flash.
By The Numbers
| Metric | Count |
|---|---|
| Backend modules | 29 |
| Frontend pages | 10 |
| Unit tests | 26 (all passing) |
| Acceptance criteria | 71 |
| ADRs | 4 |
| Threat model entries | 10 |
Architecture at a Glance
┌─────────────────────────────────────────────────────┐
│ API Layer (FastAPI) │
├──────────┬──────────────────┬───────────────────────┤
│ Contracts│ Workflow │ Persistence │
│ Pydantic │ State Machine │ SQLAlchemy + SQLite │
├──────────┼──────────────────┼───────────────────────┤
│ Agents │ Deterministic │ Tools │
│ Mock/ADK │ Pipeline │ Listing/Maps/Email │
├──────────┴──────────────────┴───────────────────────┤
│ Security │ Observability │ Approval GW │
│ Injection Def │ Audit + Metrics │ Idempotency │
└─────────────────────────────────────────────────────┘Explore the full architecture →
Built With
Backend: Python 3.12 · FastAPI · Pydantic v2 · SQLAlchemy 2.0 · Tenacity · Structlog · Google ADK
Frontend: React 18 · TypeScript · Vite · TanStack Query v5 · Tailwind CSS
Infra: Docker · docker-compose · GitHub Actions