docs(13-01): complete AI foundation layer plan — extract-text, field-placement, unit tests
- Create 13-01-SUMMARY.md with TDD execution results and decisions - Update STATE.md: phase 13 in progress, plan 1/4 complete - Update ROADMAP.md: phase 13 status set to In Progress (1/4 summaries) - Mark AI-01, AI-02 requirements complete in REQUIREMENTS.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Chandler Copeland
@@ -0,0 +1,121 @@
|
||||
---
|
||||
phase: 13-ai-field-placement-and-pre-fill
|
||||
plan: 01
|
||||
subsystem: ai
|
||||
tags: [openai, pdfjs-dist, coordinate-conversion, tdd, gpt-4o-mini, structured-output]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 12.1-per-field-text-editing-and-quick-fill
|
||||
provides: textFillData keyed by field UUID, DocumentPageClient state architecture
|
||||
- phase: 10-expanded-field-types-end-to-end
|
||||
provides: SignatureFieldType union, SignatureFieldData interface
|
||||
provides:
|
||||
- extractPdfText(filePath) — pdfjs-dist server-side text extraction returning PageText[]
|
||||
- aiCoordsToPagePdfSpace() — AI top-left pct to PDF bottom-left points with Y-axis flip
|
||||
- classifyFieldsWithAI() — GPT-4o-mini structured output call returning SignatureFieldData[] + textFillData
|
||||
- AiFieldCoords interface
|
||||
- Unit test for coordinate conversion (3 cases, US Letter dimensions)
|
||||
affects: [13-02-ai-route, 13-03-ui-button, 13-04-integration-test]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: [openai@6.32.0]
|
||||
patterns:
|
||||
- pdfjs-dist legacy build with GlobalWorkerOptions.workerSrc='' for Node.js server-side use
|
||||
- Manual json_schema response_format with strict=true (NOT zodResponseFormat — broken with Zod v4)
|
||||
- Standard field sizes override AI dimensions (checkbox=24x24pt, others=144x36pt)
|
||||
- textFillData keyed by crypto.randomUUID() field ID (not label)
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- teressa-copeland-homes/src/lib/ai/extract-text.ts
|
||||
- teressa-copeland-homes/src/lib/ai/field-placement.ts
|
||||
- teressa-copeland-homes/src/lib/pdf/__tests__/ai-coords.test.ts
|
||||
modified:
|
||||
- teressa-copeland-homes/package.json (openai dependency added)
|
||||
- teressa-copeland-homes/package-lock.json
|
||||
|
||||
key-decisions:
|
||||
- "openai 6.32.0 installed as production dependency (not devDependency)"
|
||||
- "GlobalWorkerOptions.workerSrc = '' required for Node.js server-side pdfjs-dist — do NOT share with browser components"
|
||||
- "Manual json_schema response_format confirmed required — zodResponseFormat broken with Zod v4 (issues #1540 #1602 #1709)"
|
||||
- "Standard field sizes (checkbox=24x24, others=144x36pt) override AI widthPct/heightPct for consistency"
|
||||
- "textFillData keyed by UUID assigned in route handler — not by label — matches Phase 12.1 design"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: lib/ai/* files carry // server-only guard comment — never imported from client components"
|
||||
- "Pattern: aiCoordsToPagePdfSpace is the single named utility for AI-to-PDF coord conversion — replicated from FieldPlacer.tsx formula"
|
||||
|
||||
requirements-completed: [AI-01, AI-02]
|
||||
|
||||
# Metrics
|
||||
duration: 2min
|
||||
completed: 2026-03-21
|
||||
---
|
||||
|
||||
# Phase 13 Plan 01: AI Field Placement Foundation Summary
|
||||
|
||||
**openai SDK installed, pdfjs-dist server-side text extraction module, and GPT-4o-mini structured output field classifier with Y-axis-flip coordinate conversion verified by TDD unit tests**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 2 min
|
||||
- **Started:** 2026-03-21T22:58:46Z
|
||||
- **Completed:** 2026-03-21T23:01:00Z
|
||||
- **Tasks:** 2 (TDD: RED then GREEN)
|
||||
- **Files modified:** 5
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- TDD RED phase: wrote 3 failing unit tests for aiCoordsToPagePdfSpace with US Letter (612x792pt) dimensions
|
||||
- TDD GREEN phase: implemented extract-text.ts and field-placement.ts passing all 3 tests
|
||||
- openai 6.32.0 installed as production dependency
|
||||
- TypeScript compiles without errors (npx tsc --noEmit passes)
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Write failing unit test for aiCoordsToPagePdfSpace** - `f7d74c0` (test)
|
||||
2. **Task 2: Implement extract-text.ts and field-placement.ts (GREEN)** - `c1e1e5e` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `teressa-copeland-homes/src/lib/ai/extract-text.ts` - extractPdfText() using pdfjs-dist legacy build; GlobalWorkerOptions.workerSrc='' for Node.js; PageText interface; text capped at 2000 chars/page
|
||||
- `teressa-copeland-homes/src/lib/ai/field-placement.ts` - AiFieldCoords interface; aiCoordsToPagePdfSpace() with Y-axis flip; classifyFieldsWithAI() calling GPT-4o-mini with manual json_schema; standard field sizes; textFillData keyed by UUID
|
||||
- `teressa-copeland-homes/src/lib/pdf/__tests__/ai-coords.test.ts` - 3 unit tests: text field near top, checkbox near bottom-right, client-sig at center
|
||||
- `teressa-copeland-homes/package.json` - openai 6.32.0 added to dependencies
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- Manual json_schema response_format confirmed (NOT zodResponseFormat) — broken with Zod v4.3.6 per issues #1540, #1602, #1709; this is a locked decision from STATE.md research phase
|
||||
- Standard field sizes override AI-returned widthPct/heightPct: checkbox=24x24pt, all others=144x36pt — consistent with FieldPlacer defaults, prevents poorly-sized AI fields
|
||||
- textFillData built with UUID keys assigned in route handler — matches Phase 12.1 design where DocumentPageClient uses field.id as the key
|
||||
- GlobalWorkerOptions.workerSrc='' set at module level in extract-text.ts — this is the Node.js fake-worker pattern; client components (PdfViewer, PreviewModal) set their own workerSrc independently
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
**OPENAI_API_KEY must be set in .env.local** before the AI auto-place feature works. The classifyFieldsWithAI() function throws `'OPENAI_API_KEY not configured'` if the key is absent — this is a clear error that surfaces to the agent in the browser. No silent failures.
|
||||
|
||||
No other external service configuration required for this plan.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Both AI utility modules exist and are importable from the server-only route handler (Plan 02)
|
||||
- Coordinate conversion is unit-tested and correct for US Letter dimensions
|
||||
- openai SDK ready for use in `/api/documents/[id]/ai-prepare` route (Plan 02)
|
||||
- FieldPlacer + DocumentPageClient unchanged — Plan 03 will add the UI button and state wiring
|
||||
- Blocker from STATE.md still active: AI coordinate accuracy on real Utah forms is untested — Plan 04 integration test required before Phase 13 ships to production
|
||||
|
||||
---
|
||||
*Phase: 13-ai-field-placement-and-pre-fill*
|
||||
*Completed: 2026-03-21*
|
||||
Reference in New Issue
Block a user