From cf635aa0b0f35e13319b859528d066c705a05d1f Mon Sep 17 00:00:00 2001 From: Ty Date: Fri, 11 Sep 2026 13:47:31 +0000 Subject: [PATCH] docs: remove live PROMPTS.md --- docs/PROMPTS.md | 201 ------------------------------------------------ 1 file changed, 201 deletions(-) delete mode 100644 docs/PROMPTS.md diff --git a/docs/PROMPTS.md b/docs/PROMPTS.md deleted file mode 100644 index 5dc81e2..0000000 --- a/docs/PROMPTS.md +++ /dev/null @@ -1,201 +0,0 @@ -# Inference Prompts - -Status: SPEC · 2026-08-27 · SlabUploader -Prompts are server-side text files, not settings values. Read fresh on each -invocation. Shipped defaults live in `backend/app/prompts/`. - -## Management - -- **Location:** `/app/prompts/` inside the FastAPI container, mounted read-only - from host `backend/app/prompts/`. -- **Editing:** Edit the text files on the host. No server restart needed. -- **Versioning:** The inference_log stores the prompt content (or hash) with each - inference call, so you can trace which prompt version produced which result. -- **Reset-to-default:** `python -m app.prompts.reset` restores shipped defaults - from `backend/app/prompts/`. - -## Call 1 — Vision (species/character classification) - -File: `/app/prompts/call1.txt` - -### Purpose -Classify the slab's species, edge type, figure, and grade by analyzing -inventory photos. Constrained to choose from the synced Woo taxonomy lists. - -### Inputs assembled by the server -- 1–5 inventory photos, downscaled to 1024px max -- Species leaf categories from Woo (list with IDs and brief definitions) -- Edge Type attribute terms with IDs -- Figure attribute terms with IDs -- Grade attribute terms with IDs -- User metadata: SKU, length, thickness - -### System prompt (template) -``` -You are an expert wood slab classifier. Analyze the provided slab photos and -return taxonomy data. Only use the values provided in the taxonomy lists — do -not invent categories or attribute values. -``` - -### User prompt (assembled at runtime) -``` -Analyze the following wood slab photos and classify the species, edge type, -figure, and grade. - -Species options (choose ONLY from this list): - 1. [species name] — [brief definition] (woo_id: ) - 2. ... - -Edge Type options: - - Live Edge — natural, uncut bark edge - - Flat Sawn — squared, milled edges - ... - -Figure options: - - Cathedral — U-shaped grain patterns - - Burl — swirling, knotted grain - ... - -Grade options: - - Premium — minimal defects, clean grain - - Standard — some minor characteristics - ... - -Slab metadata: SKU={sku}, Length={length}in, Thickness={thickness}in - -Return valid JSON matching this schema: -{ - "species_id": , - "species_confidence": 0.0-1.0, - "wood_category_ids": [, ...], - "edge_type_term_id": , - "figure_term_ids": [, ...], - "figure_confidence": 0.0-1.0, - "grade_term_ids": [, ...], - "grade_confidence": 0.0-1.0, - "character": { "type": "string", "severity": "string" }, - "inclusions": { "type": "string", "severity": "string" }, - "voids": "string", - "checks": "string", - "wood_categories": [ - { "name": "string", "confidence": 0.0-1.0 }, - ... - ] -} -``` - -### Notes -- The taxonomy list (species, wood categories, edge type, figure, grade) is - pulled from the **synced Woo cache only**. No hardcoded mill species list. A term - not in the cache cannot be suggested or selected. -- Brief definitions help the model distinguish ambiguous cases - (e.g., "quarter-sawn" vs "cathedral"). -- Character/inclusions/voids/checks are free-text observations. The server - maps them to Woo `feat-*` product tags after the call returns. WooCommerce - is the authoritative source for feat-* tag definitions; the design does not - duplicate them. -- **Pre-population (when `inference_enabled`):** Call 1 results are the primary - source that fills the review screen for species, wood categories, edge type, - figure, grade, and mapped `feat-*` tags from free-text observations. -- **Confidence gate (default threshold 0.7):** - - Field confidence **≥ threshold** → pre-populate that field (mutable; - user may clear or change it). - - Field confidence **< threshold** → leave empty. The model's - low-confidence guess as a default. - - Call 1 does not define the ready gate. Species + figure (or any vision - subset) is assist/prefill only. Ready is the **full named set** in AGENTS §7 - / DATA-MODEL (filled manually if Call 1 left fields empty). Species + one - figure is not enough. -- Manual entry always wins. Call 1 is assist-only and does not gate publish. - Full suite must pass with inference OFF. Canonical lock: AGENTS §6–7. - ---- - -## Call 2 — Content (description prose) - -File: `/app/prompts/call2.txt` - -### Purpose -Generate compelling product description prose for the slab. The model writes -only the descriptive portion — dimensions, species, and measurements are -injected by deterministic templates. - -### Inputs assembled by the server -- Portable Call 1 context (default: **full history resend** of Call 1 turn + - images metadata + assistant JSON). `previous_response_id` only if - `test-inference` recorded stateful support. -- Explicit **confirmed vs inferred** labels for species, dimensions, and other - attributes (user overrides marked confirmed). -- Deterministic measurements: length, widths, sqft, bdft, thickness (never invented) -- Brand voice, GEO context, title/short templates -- Shared validation module rules so Call 2 assembly rejects the same invalid - values the UI would - -### System prompt (template) -``` -You are a professional product copywriter for premium, one-of-a-one wood -slabs. Write compelling, natural-sounding descriptions. Use the brand voice -provided. Measurements are not invented; only the provided data is used. -``` - -### User prompt (assembled at runtime) -``` -Write product copy for this wood slab. - -Species: {species} -Figure: {figure} -Character: {character description from Call 1} -Length: {length_ft}ft {length_in_remainder}in -Average width: {width_avg_in}in -Width range: {width_min_in}in to {width_max_in}in -Thickness: {thickness_in}in -Board feet: {bdft} bdft -Grade: {grade} - -Brand voice: {brand_voice} -GEO context: {geo_context} - -Write: -1. A compelling opening sentence about the slab -2. A paragraph describing the character, grain, color, and use cases -3. A call to action - -Keep the tone appropriate for a premium lumber buyer. The -dimensions — those are handled by the template. Focus on the beauty and -versatility of the slab. - -Return JSON: { "prose": "..." } -``` - -### Template assembly (server-side, after LLM returns) -The server assembles the final title and description from templates with -deterministic measurements, inserting the LLM prose where appropriate. - -Example title: `{species} {length_ft}ft {length_in_remainder}in × {width_avg_in}in Wood Slab — {figure}` -Example description: `{llm_prose}. Each slab is naturally shaped — width varies -along the length at {width_min_in}in to {width_max_in}in. Sold by the slab; -dimensions as measured. {geo_sentence}` - -### Notes -- The LLM never touches dimensions. Templates handle all numbers. -- No numeric-accuracy guardrail needed — dimensions never pass through the LLM. -- If `content_llm_enabled` is false, the LLM call is skipped and templates - are used with a generic description paragraph. -- **Portable Call 1 context (issue #2):** default is full resend of Call 1 (user - prompt + assistant JSON). Label each taxonomy value **confirmed** (user-edited) - vs **inferred** (still from Call 1). Stateful `previous_response_id` is opt-in - after `test-inference`. Fail closed if neither path works. - ---- - -## Tuning workflow - -1. Deploy the default prompts -2. Capture a real slab, let Call 1 run -3. Review the results against your expert judgment -4. Edit `call1.txt` to improve classification accuracy -5. Re-run Call 1 via `POST /api/v1/slabs/{id}/infer-taxon` to compare -6. Iterate until results are consistently accurate - -The inference_log stores each iteration's input/output so you can track -progress across prompt versions.