Codebase Map

---

dp_agent/ package

#	File	Role	Key exports
1	config.py	Foundation — loads .env, exposes all constants and path objects	CHAT_MODEL, CHEAP_CHAT_MODEL, EMBED_MODEL, POSTGRES_DSN, PROMPTS_DIR, SSL_VERIFY
2	adapters/llm.py	Single gateway for all LLM calls — chat + embeddings, cost tracking	call_chat(), call_embed(), get_total_cost()
3	adapters/shortcut.py	Shortcut REST — fetch and normalise story data, post comments	fetch_story(), post_comment()
4	adapters/db.py	PostgreSQL CRUD for patch_sessions — atomic status transitions	get_session(), create_session(), update_status(), append_clarify_result(), append_extraction_round(), update_draft()
5	adapters/pgvector_client.py	Vector search on patch_corpus (V2)	search(), upsert_entry(), init_collection(), count_entries()
5b	adapters/qdrant_client.py	Same interface as above for Qdrant (V1 only — to be deleted after migration)	search(), upsert_entry(), init_collection(), count_entries()
6	prompt_builder.py	All LLM message builders + Pydantic output schemas + helper utilities	build_clarify_messages(), build_draft_messages(), build_preprocess_messages(), build_validate_messages(), build_auto_answer_messages(), detect_schema_tables(), format_clarifications_markdown()
7	server.py	V2 FastAPI app — webhook routing, state machine orchestration	/webhook, /submitextraction, /health
8	cli.py	V1 unified CLI entry point (python -m dp_agent <phase>)	main()
8b	pipeline.py	Thin bridge — calls each scripts/test_*.py main()	clarify(), auto_answer(), validate(), draft()

---

dp_agent/prompts/

#	File	Phase	Model	Active?
—	clarify.md	Clarify — infer template, generate questions, write 01_extract.sql	Sonnet	✅
—	draft.md	Draft — write 02_patch.sql, 03_revert.sql, rationale	Sonnet	✅
—	preprocess.md	Preprocess (V2) — synthesise PM comments + extraction → SessionContext	Haiku	✅ V2 only
—	auto_answer.md	Auto-answer (V1) — fill answers directly from extraction data	Haiku	✅ V1 only
—	validate.md	Validate (V1) — assess answer sufficiency, stamp RESOLVED or annotate gaps	Haiku	✅ V1 only
—	classify.md	Classify — pick template A–F from rubric	Sonnet	❌ dead code

Each .md file is the system prompt only. prompt_builder.py loads it, wraps it with reference docs (templates.md, rules.md, glossary.md), and formats the story/hits/extraction data as the user message. The .md file never runs standalone — it always goes through its matching build_*_messages() function.

---

scripts/

#	File	Role
9	test_clarify.py	V1 clarify — fetch → embed → search → LLM → write output files
10	test_auto_answer.py	V1 auto-answer — reads extraction results, fills answers via Haiku
11	test_validate.py	V1 validate — Haiku checks sufficiency, stamps RESOLVED or annotates
12	test_draft.py	V1 draft — gate check → Sonnet → writes patch + revert SQL
13	build_index.py	Indexes examples/raw/*.sql into Qdrant corpus
14	sync_schema.py	Parses ElementsModel.edmx → data/schema.json
15	eval.ps1	Runs clarify on 6 held-out stories (one per template A–F)
16	update.ps1	Full corpus refresh: start Qdrant → sync → INDEX.md → re-index → schema
17	build_index.ps1	Generates examples/INDEX.md with template labels
18	sync_examples.ps1	Mirrors .sql files from elements repo into examples/raw/

---

docs/ — reference documents injected into prompts

File	Role	Injected into
templates.md	Defines the 6 patch templates (A–F) with inputs, target tables, SQL skeletons, and exemplars	clarify, draft, validate
rules.md	Hard SQL rules and prohibitions the LLM must follow	clarify, draft
glossary.md	System scope, table acronyms (IVP, IM, ICD, ...), domain vocabulary	clarify, draft
review-checklist.md	Manual QA checklist — POC/Copilot Chat workflow only, not used by the agent	—
progression.md	Notes on how the project evolved — context for future developers	—
codebase-map.md	This file	—

---

alembic/ — database migrations

File	Role
alembic.ini	Alembic config — points at env.py, sets migration script location
env.py	Migration environment — reads POSTGRES_DSN from config, connects to DB
versions/0001_init.py	Creates patch_sessions + patch_corpus tables and ivfflat index

Run with: alembic upgrade head

---

examples/ — SQL corpus

Path	Role
raw/	All historical SQL patch scripts, synced from elements repo (gitignored locally). Organised by year/month.
stories/	Markdown story files for historical tickets — used for manual reference
INDEX.md	Auto-generated table of all corpus files with template labels and table names (built by scripts/build_index.ps1)

---

copilot/ — POC-era manual workflow (not part of V1/V2 pipeline)

Path	Role
copilot-instructions.md	VS Code Copilot system prompt used during the original POC
prompts/	Original POC prompts (intake, classify, clarify, draft) — predates dp_agent/prompts/
inputs/SC-XXXXX/	Normalised story inputs for the manual POC workflow
outputs/SC-XXXXX/	Draft outputs from the manual POC workflow

---

Infrastructure

File	Role
Dockerfile	Builds the app image (python:3.14-slim). CMD runs uvicorn only — migrations are NOT run automatically by the image.
docker-compose.yml	Local dev: spins up pgvector/pg16 + app. Overrides the image CMD to run alembic upgrade head && uvicorn ... so migrations run on docker compose up.
requirements.txt	All Python dependencies. Contains both V2 deps (fastapi, psycopg, pgvector) and V1 deps (qdrant-client, grpcio) — Qdrant entries can be removed after V1 migration.
alembic.ini	(also listed under alembic/ above)