Ty
2ba5428269
- DATA-MODEL.md: storage engine (stdlib sqlite3 + schema.sql, no ORM/migrations), pragmas, per-test isolation. - API.md: revision coupling, async job model, PUT check order, server-derived ready. - PROMPTS.md: no prompt files ship; the DB is the only prompt source.
4.3 KiB
Prompts contract
Status: SPEC · 2026-09-18. Owns prompt storage, prompt inputs, and the two inference calls.
Requirements impact
| Requirement | Impact on this design |
|---|---|
| METADATA-5, METADATA-10, METADATA-15, METADATA-30 | taxonomy choices and cardinality |
| METADATA-35, METADATA-40, METADATA-45, METADATA-50 | Call 1 inputs, constraints, pre-fill, precedence |
| METADATA-55, METADATA-60, METADATA-65, METADATA-70 | Call 2 trigger, context, constraints, fallback |
| METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95 | non-blocking, fallback title, prompt selection, fact block, overlay exclusion |
| METADATA-100, METADATA-105, METADATA-110, METADATA-115 | feat mapping, prompt storage, button, failure |
| METADATA-66 | generation logging |
| SETTINGS-30 | brand voice and geo context |
| REVIEW-40, REVIEW-50 | editability and field limits |
1. Storage and revisions
- Prompts live in the database, not in text files, with all revisions retained. Tables are in
docs/contracts/DATA-MODEL.md§7. No prompt files ship with the application; the database is the only prompt source. - Each call reads the active revision fresh.
- Editing a prompt creates a new revision; history is never overwritten.
- Every generation is logged with its inputs, the request/response when a model was used, and the final stored content.
2. Call 1 — vision classification
When. Runs automatically after a calibrated draft uploads only when inference_enabled is
true; also on demand or retry. With inference off it is skipped and the fields are filled by hand.
Inputs.
- The clean processed photos at 1024 px long edge or less.
- The synced taxonomy: species leaves, Edge Type, Figure, Grade, Thickness, Moisture terms, each with its Woo id. These are the only legal choices.
- User metadata: SKU, length, thickness.
Constraints.
- The model may only choose values from the supplied synced lists; it never invents categories or terms.
- Free-text observations (character, inclusions, voids, checks) are mapped to existing synced
feat-*tags only; Woo is authoritative for those tags.
Result fields. species_id + species_confidence; wood_category_ids;
edge_type_term_id; figure_term_ids + figure_confidence; grade_term_id +
grade_confidence; character, inclusions, voids, checks. Grade, edge, thickness, and
moisture are singular.
Pre-fill. At or above the threshold (default 0.7) the field is pre-filled and remains editable; below it the field stays empty and is not shown as a low-confidence guess. Typed values always win. Call 1 is assist-only and never gates publish. A runtime failure is classified recoverable or unrecoverable for the owner.
3. Call 2 — content prose
When. User-triggered only, via the Generate text control; never automatic. The control appears only when content generation is enabled and the endpoint is reachable.
Inputs.
- A fresh, full Call 1 context: prompt, Call 1 photos, and the Call 1 result. No provider thread id is used.
- The confirmed or changed metadata from review.
- The literal dimension fact block, exact strings for species, figure term, length, thickness, average width, width min–max, and board feet; no length-by-width-by-thickness rectangle assumption.
- Brand voice and geo context.
Constraints.
- The model writes prose only and never invents or alters a dimension; every number comes from the fact block.
- The dimension-overlay image is never sent.
Output. title, short_description, description. The owner can edit the result.
4. Fallback and templates
- With inference off, deterministic templates produce name, short_description, and description so create never lacks prose.
- The template is the fallback only; when Call 2 runs, the model writes and the template guides style.
- The fallback title uses the primary figure term name as the character, with the hyphen separator.
- The primary wood category selects a specialized Call 2 prompt.
- All generated text stays within the field limits in
docs/contracts/WOO-API.md§9.
5. Prompt management
- The active Call 1 and Call 2 revisions are editable; saving creates a new revision.
- A revision identifies its content, author, and timestamp;
inference_logrecords the revision used for each call.