Ty
f0f891f80e
UAT requires prompt tuning, so the iteration system is M3; only the editing UI is deferred. - METADATA-105 now covers storage, append-only revisions, and recording the revision used. - METADATA-106 adds the REST revision interface (append, activate, read); no prompt UI. - METADATA-107 records the missing authentication as a later row; there is no M4 yet, so the PoR carries it. - PROMPTS.md owns the seed text as revision 0, the seed mechanism, and the interface; sections renumbered after inserting them. - DATA-MODEL.md §7 cites PROMPTS.md, adds content_hash, and states the append-only rule. - task_breakdown.md notes the S7 interface and the deferred auth. 155 requirements; both gates pass.
130 lines
6.3 KiB
Markdown
130 lines
6.3 KiB
Markdown
# 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 output, inputs, dimension safety, inference-off path |
|
||
| METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95 | non-blocking, deterministic copy, pattern selection, fact block, overlay exclusion |
|
||
| METADATA-105, METADATA-106, METADATA-107 | prompt storage, revision interface, auth |
|
||
| 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. Storage shape is
|
||
`docs/contracts/DATA-MODEL.md` §7 (`METADATA-105`).
|
||
- Revisions are append-only. Editing saves a new revision and moves the active pointer; a revision
|
||
is never updated or deleted. Reset to default and reset to revision are pointer moves.
|
||
- Each call reads the active revision fresh, and the revision used is recorded on the call
|
||
(`METADATA-66`).
|
||
- The seed text in §6 is read once on first run and written as revision 0 for each call. It is the
|
||
only prompt content that ships with the application.
|
||
|
||
## 2. Revision interface
|
||
|
||
REST, no UI (`METADATA-106`):
|
||
|
||
1. `POST /api/v1/prompts/{call}/revisions` appends a revision and returns it.
|
||
2. `POST /api/v1/prompts/{call}/activate` moves the active pointer to a revision.
|
||
3. `GET /api/v1/prompts/{call}` returns the active prompt and the revision list.
|
||
|
||
The interface is reachable on the trusted network only until it is authenticated (`METADATA-107`).
|
||
|
||
## 3. 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.
|
||
|
||
## 4. 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.**
|
||
- The clean processed photos.
|
||
- The metadata confirmed or changed in review, including the primary and secondary wood categories
|
||
and the parent-category path.
|
||
- 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.
|
||
|
||
No provider thread id is used, and Call 1's raw prompt and result are not sent (`METADATA-60`).
|
||
|
||
**Constraints.**
|
||
- The model writes prose only and never invents or alters a dimension; every number comes from the
|
||
fact block (`METADATA-65`).
|
||
- The dimension-overlay image is never sent (`METADATA-95`).
|
||
|
||
**Output.** The long `description` prose. The server assembles `name` and `short_description`
|
||
(`METADATA-55`, `METADATA-80`). The primary wood category selects the specialized prompt
|
||
(`METADATA-85`). The owner can edit the result (`REVIEW-40`).
|
||
|
||
## 5. Fallback and templates
|
||
|
||
- With inference off, the server produces the long description so create never lacks prose
|
||
(`METADATA-70`).
|
||
- The deterministic title and short-description patterns live in `docs/contracts/CONTENT-WOO.md`
|
||
(`METADATA-80`).
|
||
- The primary wood category selects the specialized Call 2 prompt (`METADATA-85`).
|
||
- All generated text stays within the field limits in `docs/contracts/WOO-API.md` §9
|
||
(`REVIEW-50`).
|
||
|
||
## 6. Seed prompt text
|
||
|
||
Read once on first run and written as revision 0 for each call (`METADATA-105`). Authored here with
|
||
the rest of the prompt discussion; the seed is the only prompt content that ships with the
|
||
application.
|
||
|
||
The seed is the starting point for tuning, not a final text. Both calls are revised ad hoc through
|
||
the §2 interface when UAT surfaces a miss.
|
||
|
||
**`call1` seed.** Classify the slab's species, wood categories, edge type, figure, and grade from
|
||
the supplied photos, choosing only from the supplied synced taxonomy lists, and return the result
|
||
fields in §3 as JSON. Report a confidence for each classified field. Map free-text observations
|
||
(character, inclusions, voids, checks) to the supplied feature-tag list only. Invent no category or
|
||
term.
|
||
|
||
**`call2` seed.** Write the long product description for the slab from the supplied photos and
|
||
listing facts. The name and short description are already built, so do not repeat them. Use the
|
||
brand voice and geo context given. The dimensions in the fact block are exact: use those strings
|
||
and invent no numbers. Write prose a premium lumber buyer would read.
|
||
|
||
## 7. Prompt management
|
||
|
||
- The active Call 1 and Call 2 revisions are editable through the §2 interface; saving creates a
|
||
new revision.
|
||
- A revision identifies its content, author, and timestamp; `inference_log` records the revision
|
||
used for each call.
|
||
- The revision interface requires authentication before it is exposed beyond the trusted network
|
||
(`METADATA-107`).
|