# 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-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.**
- 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`).

## 4. 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`).

## 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_log` records the revision
  used for each call.