archive-2026-07/ 01-mission-and-requirements.md 02-goals-and-subgoals.md 03-query-processing-masterplan.md 04-system-architecture.md 05-assessment-and-learning-spec.md 06-implementation-status.md 07-agent-build-guide.md 08-query-reference.md PROJECT.yaml README.md
[DRAFT — edit this] > **Purpose.** This folder is the authoritative, AI-readable master plan for the > PDAI query-processing, assessment, and self-improvement system. It captures the > requirements, goals, subgoals, architecture, and implementation status produced > across the design effort. It is written so that **ano Inferred stage: development. Define the specific deliverable, success state, and timeline.
Success criteria:| Code | /Users/friedrichstr/ai-mac-studio/pdai/report/archive-2026-07 |
| Check | Path | Status | Detail |
|---|---|---|---|
| code | /Users/friedrichstr/ai-mac-studio/pdai/report/archive-2026-0 | ✓ ok | 10 items, last_modified=2026-08-24 |
Superseded (Aug 2026): This document describes the pre-conductor AO*-era design (Jul 2026). It is kept as a historical record. The ai-agent-orchestrator book and the new report/ set are the authoritative architecture references.
Purpose. This folder is the authoritative, AI-readable master plan for the PDAI query-processing, assessment, and self-improvement system. It captures the requirements, goals, subgoals, architecture, and implementation status produced across the design effort. It is written so that another code-generating agent (e.g. Claude Code) can reconstruct or extend the system from this folder alone.
| # | Document | Audience | What it gives you |
|---|---|---|---|
| 0 | README.md |
everyone | this index + how to use the report |
| 1 | 01-mission-and-requirements.md |
PM / architect | the full requirement set, verbatim intent, constraints |
| 2 | 02-goals-and-subgoals.md |
PM / architect | the goal tree (goals → subgoals → acceptance) |
| 3 | 03-query-processing-masterplan.md |
builder agent | PIVOTAL — the complete, reusable query-processing design |
| 4 | 04-system-architecture.md |
builder agent | orchestrator, subagents, monitoring, data stores, ports |
| 5 | 05-assessment-and-learning-spec.md |
builder agent | catalog, DuckDB schema, metrics, golden labels, loop |
| 6 | 06-implementation-status.md |
builder agent | what exists vs planned; file map; how to run |
| 7 | 07-agent-build-guide.md |
builder agent | step-by-step build order, invariants, do/don't, prompts |
| 8 | 08-query-reference.md |
builder agent | golden starter queries tied to trail + monitoring; seed of the editable samples catalog |
PDAI ("PDF Artificial Intelligence") is a workspace for large-scale scholarly
document processing. Its centerpiece is ai-query, a hierarchical document
query system that resolves an under-specified natural-language question into an
exact, cited answer over a columnar lemma index — without ever letting an LLM
scan the corpus. The pipeline is not hardwired: it is the execution trail of
subagents an orchestrator triggers for a given query. Every run is monitored
and logged into DuckDB; a human can stamp golden verdicts in a labeling UI;
metrics are computed per subagent over only the items whose trail used it; and
a bounded (≤5) learning loop improves the weakest subagent by patching
versioned data (tunables/skills), never code.
03-query-processing-masterplan.md
first. It is self-contained and technology-portable: it specifies the theory
(cost model, selectivity funnel, CNF-over-lemmata backbone, subagent trail),
not just the current Python.07-agent-build-guide.md for the exact build
order and the invariants you must not violate.04] and [05] as the detailed component specs.06] to see what already exists in this repo so you reuse rather than
duplicate.| Concern | Path |
|---|---|
| Query-resolution theory (canonical) | pdai/skills/query/RESOLUTION.md |
| Skill hierarchy | pdai/skills/query/** |
| Pipeline code | pdai/agents/ai-query/src/ai_query/ |
| Lemma index + algebra | pdai/index/ai-lemma-index/ |
| Documents (bulk) | /Volumes/PDAI-1/pdai-collections/<collection>/ |
| Live design plan (todos) | ~/.cursor/plans/ai-query_assessment_learning_*.plan.md |
| HTML docs (Oxford-blue/gold) | pdai/agents/ai-query/docs/ |
::: note
This report is descriptive of intent and design. Where it describes
components that are planned but not yet implemented, it is marked clearly in
06-implementation-status.md. Treat the masterplan
(03) and build guide (07) as the contract; treat the current code as a partial,
authoritative reference implementation.
:::