RECORDGOD/docs/RECORDGOD_AI_AGENT_PLAN.md

# RecordGod AI assistant — honest assessment & plan (2026-06-24)

OpenRouter key stored in the vault (`openrouter_api_key` + `openrouter_model`), reachable like every other
credential. This doc is the "durry and a short black" think: what's genuinely dope, what's hype, what breaks
things, and how to build it so it only helps.

## The one-paragraph honest take

The LLM is a **commodity** — anyone can call OpenRouter. The moat is that RecordGod can **ground** the model in
proprietary, structured, *vectorised* data: the full Discogs mirror, the live cross-store market intelligence in
DealGod (pgvector lives there, reached via the DealGod API — **RecordGod-db itself has no pgvector**), real sales
and stock. A WooCommerce plugin with a chatbot is a toy; "talk to your shop, and it answers with *your* numbers and
*the market's* numbers, then drafts the copy/newsletter/price for you to approve" is a product. **So the sell isn't
"AI" — it's "AI that can't lie to you because it's reading the database, and can't break anything because it can
only propose."**

## The non-negotiable architecture: tools, not free SQL

The exciting line — "it can run actual Postgres queries for the exact info it needs" — is right in spirit and a
foot-gun in the literal. The safe, equally-powerful pattern is a **tool-calling agent**: the model picks from a set
of vetted, parameterised functions; *our* code runs the query. The model never sees a raw `psql` prompt.

- **Phase 1 — fixed read tools (safest, ~90% of the value).** `stock_query`, `release_lookup`,
  `market_value`(DealGod API), `semantic_search`(DealGod pgvector API), `sales_summary`, `customer_wants`,
  `catalog_health`. The model composes them; results are real rows, so it summarises rather than hallucinates.
- **Phase 2 — constrained text-to-SQL for power questions.** Only against a **read-only role**, over a curated set
  of **VIEWS** (not raw tables), with the generated SQL parsed (reject anything not a single `SELECT`), a forced
  `LIMIT`, and a `statement_timeout`. Even then, the fixed tools answer most real questions more reliably.
- **Never — free SQL execution.** One `UPDATE`/`DELETE`/`DROP` from a hallucination or an injected instruction and
  the shop is down. Not happening.

## Writes: propose, never commit

RecordGod is *already* the right shape for this — intake **stages**, publish is a separate non-destructive step.
The AI just becomes another stager/proposer. Every write-flavoured capability lands in a **review queue** a human
approves; nothing the agent does is live without a click.

- `propose_price(sku, price, reason)` → a `proposals` row → human applies.
- `propose_intake(...)` → `staged` inventory (already non-destructive).
- `draft_newsletter` / `draft_product_copy` / `draft_wantlist_emails` → text only, human sends.

## The dope things, honestly rated

**Tier A — genuine value, low risk, ship first:**
1. **Ask-your-data.** "DnB 12-inches under $10 not sold in 90 days?" → tools → a table. Huge for a shop owner.
   Semantic angle (DealGod pgvector): "records with a *vibe* like this one," not just keyword.
2. **Product copy / hype spiels.** Feed the model the *real* artist/label/year/tracklist/condition + DealGod
   rarity → a punchy description or social caption, grounded in facts. The killer low-risk content win.
3. **Newsletters.** "New techno arrivals + 3 staff picks" → query new stock → draft HTML → human reviews → send via
   the existing mailer. Draft-only.
4. **Stock-hygiene assistant.** Surface Heal-sweep gaps, flag below-market/mispriced items (DealGod median), find
   dupes. Read + propose.
5. **Intake helper.** "Box of these" → describe → semantic search the Discogs mirror → propose matches → human
   confirms → stage. Pairs with the intake we built.

**Tier B — valuable, needs the propose-gate:**
6. **Auto-pricing suggestions** (propose, not apply) using DealGod cross-store median × condition.
7. **Wantlist matching** — "these 4 customers want what just arrived" → draft the notify emails.

**Tier C — flashy, lower ROI / higher risk:**
8. **Autonomous "site maintenance"** = write access. Honest answer: don't. Keep it propose + human-apply. Full
   autonomy is exactly where it breaks shit.
9. **Free text-to-SQL on master.** Great demo, real foot-gun; covered better by fixed tools + Phase-2 read-only views.

## Guardrails (so it only helps)

| Risk | Guardrail |
|---|---|
| Destructive writes | Agent gets a **read-only DB role**; all writes are **propose → human apply** |
| Bad/expensive SQL (Phase 2) | read-only role · curated VIEWS only · parse-and-reject non-SELECT · forced LIMIT · `statement_timeout` |
| Tool abuse | hard **allowlist** of tools; no shell, no file write, no arbitrary HTTP |
| Hallucination | answers are **grounded** in returned rows; "AI draft — review" label on all output |
| Prompt injection (notes, customer msgs, web text are untrusted) | untrusted text can't trigger a write — the human gate absorbs it |
| Cost creep | per-call **cost + token log** (`ai_log`), daily **budget cap**, cheap models for bulk |
| PII leakage | customer tools return **de-identified** data unless a task needs more (matches DealGod privacy posture) |
| Over-trust | every agent action is **logged and reversible**; proposals show their reasoning + source rows |

## Model routing (OpenRouter's real advantage)

Route per task, don't pick one model:
- **Bulk / tool-calling / SQL reasoning** → DeepSeek V3 or Gemini 2.5 Flash (fast, dirt cheap, plenty smart).
- **Nuanced copy / newsletters** → Gemini Flash or a mid model; hype spiels don't need a frontier model.
- **Hard multi-step analysis** → route up to a stronger model (incl. Claude via OpenRouter) for that call only.
Store a default in `openrouter_model`; let specific tools override.

## Build phases

- **Phase 0 (done):** Connect page stores `openrouter_api_key` + `openrouter_model`; test button shows usage.
- **Phase 1:** `app/ai_routes.py` agent loop + the 7 read tools + `draft_*` tools. One `/admin` "Ask RecordGod"
  panel (chat box → grounded answer + the tool trace). `ai_log` table (prompt, tools, tokens, cost, user, ts).
  Everything read/draft. **This is the demo that sells.**
- **Phase 2:** `proposals` review queue + propose tools (price/intake/wantlist). Constrained text-to-SQL over
  read-only VIEWS for power users.
- **Phase 3:** Scheduled agent jobs (weekly newsletter draft, daily mispriced-stock report) — still draft/propose.

## Honest bottom line

Worth building, and a real differentiator — **because of the data, not the model.** Start with read + draft
(Phase 1): all upside, no blast radius, and it's the version you can put in a sales demo. Add propose-and-apply
only behind the review queue. Keep the agent read-only and human-gated and it can't break the shop — it can only
make it faster to run. Links: [[openrouter-llm-backend]], [[recordgod-engine]], [[recordgod-intake-three-source]].