Run request analysis on demand on the VPS

2026-06-27 00:18:41 -04:00 · 2026-06-27 00:18:41 -04:00 · d899e902a0
commit d899e902a0
parent 9f9b13aa01
21 changed files with 2485 additions and 4 deletions
--- a/docs/kb/queue-workflow.md
+++ b/docs/kb/queue-workflow.md
@ -0,0 +1,130 @@
+# Request Queue Workflow
+
+This document describes a practical first pass for automated request analysis using the KB scaffold.
+
+## Goal
+
+Turn raw launcher submissions into structured request items that are:
+
+- titled
+- categorized
+- tagged
+- explained in plain language
+- paired with a realistic implementation approach
+
+## Recommended Pipeline
+
+1. Read one pending submission.
+2. Split it into candidate atomic requests.
+3. Retrieve likely systems from `docs/kb/systems.json`.
+4. Load the matching `docs/kb/systems/*.md` files.
+5. Ask the local model for JSON that matches `docs/kb/request-analysis-schema.json`.
+6. Validate the JSON.
+7. Promote high-confidence items and hold low-confidence items for review.
+
+## Suggested Confidence Rules
+
+- `>= 0.85`
+  - auto-promote to active
+- `0.65 - 0.84`
+  - store as needs review
+- `< 0.65`
+  - keep as pending or send to manual triage
+
+## Retrieval Hints
+
+Search `systems.json` using:
+
+- request text
+- obvious UI words like "layer", "chunk", "overview", "graphics", "animation"
+- aliases
+- past tags from similar requests
+
+If a submission touches multiple subsystems, feed the model the top two to four matching docs instead of the whole KB.
+
+## Prompt Skeleton
+
+Use a strict instruction similar to this:
+
+```text
+You are processing Worldshaper editor requests.
+
+You must:
+- split the submission into one or more atomic requests
+- assign one primary category per item
+- assign tags grounded in the provided KB
+- write a short descriptive title
+- explain the user intent in plain language
+- propose a likely implementation path
+- avoid inventing systems that are not in the KB
+- return only valid JSON matching the provided schema
+
+If you are unsure, lower confidence and use statusRecommendation = "needs_review".
+```
+
+Then provide:
+
+- the raw submission
+- the JSON schema
+- the retrieved KB docs
+
+## Good First Storage Shape
+
+Keep the existing launcher request record, but add optional analysis metadata:
+
+- `analysisStatus`
+- `analysisConfidence`
+- `analysisModel`
+- `analysisCreatedAt`
+- `analysisUpdatedAt`
+- `analysisPayload`
+
+This lets you keep the current user-facing `pending` and `active` states while adding a back-office workflow.
+
+## First Implementation Target
+
+The simplest useful worker would:
+
+1. read pending requests from the launcher request API/store
+2. analyze one request at a time
+3. write structured analysis back to the same store
+4. never delete the original `sourceText`
+
+The current first-pass implementation is:
+
+```bash
+npm run analyze:requests
+```
+
+Useful environment variables:
+
+- `REQUEST_ANALYZER_API_BASE`
+- `REQUEST_ANALYZER_PROVIDER`
+- `REQUEST_ANALYZER_MODEL_BASE_URL`
+- `REQUEST_ANALYZER_MODEL`
+- `REQUEST_ANALYZER_API_KEY`
+- `REQUEST_ANALYZER_MAX_TOKENS`
+- `REQUEST_ANALYZER_THINKING`
+- `REQUEST_ANALYZER_PROMOTE_THRESHOLD`
+- `DEEPSEEK_API_KEY`
+
+DeepSeek path:
+
+- set `DEEPSEEK_API_KEY`
+- leave the provider on its default auto-detect setting
+- the worker will use DeepSeek-hosted chat completions automatically
+
+Behavior:
+
+- high-confidence all-active results replace the pending submission with active request rows
+- mixed or lower-confidence results stay on the pending submission as review metadata
+- failures are stored as analysis errors instead of silently disappearing
+
+## What Not To Automate First
+
+- automatic deletion
+- automatic deduplication with destructive merges
+- direct code generation
+- automatic schema migrations
+
+The first win is dependable triage, not full autonomy.