descrybe/docs/support-auto/02-contract.md

# 02 — Support auto-response + rich ticket contract

**Status:** Design only — no application code in this document.  
**Agent:** 2/10 (`support-auto`)  
**Date:** 2026-08-05  
**Repo:** `F:/laragon/www/_MY/descrybe-v2`  
**Machine contract:** [02-contract.json](./02-contract.json)

---

## 0. North star

Give support tickets **richer customer context**, then on create (first response only by default) attempt:

1. **Deterministic match** against FAQ / knowledge articles or reply templates (keyword + intent).
2. If match confidence is below threshold → **AI assist** using the platform admin **`support`** AI role.
3. If AI fails / is low-confidence / customer replies again → **human handoff** (queue + claim desk from [11-support-design](../admin-roles-support/11-support-design.md)).

Auto replies are always **clearly labeled** (`author_role=system` + `auto_*` metadata). Staff may **disable auto per ticket**.

```
Customer Create ticket (+ tags / category / optional SKU / context snapshot)
        │
        ▼
  [sync] FAQ / template matcher ──confidence ≥ T_match──► post labeled system reply
        │ below threshold
        ▼
  [async job] AI assist (AIRoleSupport) ──ok──► draft internal note OR auto-send (admin)
        │ fail / low conf
        ▼
  Human handoff (open/unassigned queue; no further auto unless staff re-enables)
```

---

## 1. Inventory basis

| Source | Status |
|--------|--------|
| [01-inventory.md](./01-inventory.md) / [01-extension-points.json](./01-extension-points.json) | **Authoritative** desk + AI inventory (agent 1). Confirms stub gate, `ai_roles.support`, no FAQ matcher, Create post-commit as natural hook. |
| [11-support-design.md](../admin-roles-support/11-support-design.md) / [11-support-api-contract.json](../admin-roles-support/11-support-api-contract.json) | Desk roles, claim queue, CSAT, message `author_role ∈ user\|agent\|system`. |
| Schema `025` + `027`/`029`/`030` | Tickets/messages/notifications + desk indexes, `staff_role`, CSAT. No tags / SKU / KB / auto flags. |
| `support.Ticket` / `CreateInput` (`apps/api/internal/support/types.go`) | Priority + category already on create; no tags/SKU/context. |
| `support.Create` (`tickets.go`) | Post-commit extension point for matcher → optional `TryAutoReplyLLM` (never Completer in Create). |
| `support.TryAutoReplyLLM` (`ai_auto_reply.go`) | **Only** allowed LLM entry for tickets; currently returns `ErrAIAutoReplyDisabled`. |
| `platformsettings.AIRoleSupport` = `"support"` | Admin-configurable slot in `ai_roles` (GET/PUT `/api/admin/settings` via `admin_settings_handlers.go`). |
| `aiprovider.ResolveCompleterForRole(..., RoleSupport)` | Platform completer for support role; **no env fallback** when unset (tests assert). |
| Web admin | `apps/web/src/lib/admin-ai-roles.ts` — role `support`; UI `/admin/settings` → AI roles tab. |
| Docs Ask | Rule tree (`DocsAskGuide` / `docs-guide`) — pattern for content match **before** LLM; must not use `AIRoleSupport`. |
| FAQ today | Marketing `FaqSection` only — **no** support knowledge base / canned ticket replies. |
| Jobs | Postgres poller / `jobs.Queue` pattern (River deferred) — prefer same style for AI auto jobs. |
| Plan keys | `support.center|ticket_create|ticket_thread` only — **no** plan key for auto-reply (platform admin gate). |

**ASSUMPTION:** Extending `TryAutoReplyLLM` remains the single AI gate; FAQ matching is a sibling `TryAutoReplyMatch` (or internal stages of one orchestrator) that never calls an LLM. Explicit product gate = `support_auto.enabled` **and** `ai_roles.support.enabled` (inventory §4.3).

---

## 2. Richer ticket fields

### 2.1 Additive fields on `support_tickets`

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `priority` | enum `low\|normal\|high` | yes (default `normal`) | **Exists** — preserve. |
| `tags` | `TEXT[]` or join table | no | Max 10 tags; each ≤ 40 runes; lowercase slug-ish; staff + customer may set on create; staff may PATCH. |
| `related_product_id` | `UUID` nullable | no | Company-scoped catalog product when resolvable. Validate `company_id` match — never cross-tenant. |
| `related_sku` | `TEXT` nullable | no | Free-text SKU (≤ 128). Stored even if product id unknown; used for match features + staff UI. |
| `category` | taxonomy slug | yes | See §2.2. |
| `customer_context` | `JSONB` | no (server-filled) | Snapshot at create — see §2.3. Immutable after create (staff-visible; customers see limited subset). |
| `auto_reply_disabled` | `BOOLEAN NOT NULL DEFAULT false` | — | Staff toggle; also set automatically on human handoff / customer follow-up after auto. |
| `auto_reply_status` | enum | — | `none\|matched\|ai_draft\|ai_sent\|skipped\|failed\|handed_off`. |
| `auto_reply_attempted_at` | `TIMESTAMPTZ` | — | Last orchestrator run. |
| `auto_reply_message_id` | `UUID` nullable | — | Public auto message when posted. |

**Contracts preserved:** existing create body (`subject`, `category`, `priority`, `body`) remains valid. New fields are additive optional.

### 2.2 Category taxonomy

Today’s CHECK: `billing | bug | account | other`.

**Chosen approach:** keep seed slugs for backward compatibility; move allow-list to **`support_categories`** (platform-scoped admin taxonomy):

| Column | Purpose |
|--------|---------|
| `slug` | Stable API value (PK) |
| `label` | Admin/UI display |
| `parent_slug` | Optional hierarchy (1 level deep MVP) |
| `sort_order` | List order |
| `is_active` | Soft-disable without breaking historical tickets |
| `match_intents` | Optional string[] of intent keys for matcher |

Seed rows: existing four categories. Admin may add e.g. `integrations`, `processing`, `export`, `billing_credits`.

**BREAKING (soft):** create/update must reject unknown **active** slugs; historical tickets may retain inactive slugs (read-only display).

Create API: `category` still a string slug (default `other`).

### 2.3 Customer context snapshot

Filled **server-side** on `Create` from the authenticated company/user — never trust client JSON for authz-sensitive facts.

```json
{
  "captured_at": "RFC3339",
  "company_id": "uuid",
  "company_name": "string",
  "plan_slug": "string|null",
  "user_id": "uuid",
  "user_email": "string",
  "user_name": "string|null",
  "locale": "string|null",
  "timezone": "string|null",
  "related_product": {
    "id": "uuid|null",
    "sku": "string|null",
    "title": "string|null"
  },
  "signals": {
    "open_ticket_count": 0,
    "last_ticket_category": "string|null"
  }
}
```

**Rules:**

- Snapshot is denormalized; later plan changes do not rewrite it.
- Customer GET may omit `signals` / email of others; staff GET sees full snapshot.
- No API keys, SMTP secrets, BYOK material, or raw payment tokens in snapshot.
- Cap JSON size (~4 KiB); drop optional `signals` if over budget.

---

## 3. Knowledge + templates (match corpus)

New platform-scoped content (not per-tenant KB for MVP — support is platform desk):

### 3.1 `support_kb_articles`

| Field | Notes |
|-------|-------|
| `id`, `slug`, `title`, `body_md` | Public-safe answer text |
| `category_slugs` | Overlap boost with ticket category |
| `keywords` | TEXT[] — lowercase tokens |
| `intent_keys` | TEXT[] — e.g. `password_reset`, `stripe_invoice` |
| `is_published` | Matcher ignores unpublished |
| `priority_weight` | Tie-break |

### 3.2 `support_reply_templates`

| Field | Notes |
|-------|-------|
| `id`, `name`, `body` | Staff-authored reply (may include `{{subject}}` placeholders — allowlist only) |
| `keywords`, `intent_keys`, `category_slugs` | Same as KB |
| `is_active` | |

**ASSUMPTION:** MVP matcher is lexical (keyword overlap + intent + category boost), not embeddings. Vector search may reuse `AIRoleVectorization` later — out of scope here.

---

## 4. Auto-response pipeline

### 4.1 Triggers

| Event | Behavior |
|-------|----------|
| Ticket **create** | Primary: run orchestrator once. |
| Customer **first reply** after create with no prior auto | Optional admin flag `retry_on_first_customer_reply` (default **false**). |
| Customer reply **after** an auto public message | **Handoff** — set `auto_reply_disabled=true`, `auto_reply_status=handed_off`; do not re-run AI. |
| Staff public reply | Disable further auto on that ticket. |
| Staff sets `auto_reply_disabled=true` | Skip forever until staff clears flag. |

Never invoke LLM from `Create` / `ReplyAsUser` / `ReplyAsAgent` directly — only via `TryAutoReplyLLM` (AI stage) after FAQ stage.

### 4.2 Stage A — FAQ / template match (sync, cheap)

Input: subject + body + category + tags + related_sku + intent heuristics (simple regex/keyword map).

Output:

```json
{
  "kind": "kb_article|template|none",
  "ref_id": "uuid|null",
  "confidence": 0.0,
  "body": "string|null",
  "label": "string"
}
```

- If `confidence >= settings.match_confidence_threshold` and auto enabled → **post** public message:
  - `author_role = "system"`
  - `author_user_id = null`
  - `is_internal_note = false`
  - metadata: `auto_source`, `auto_confidence`, `auto_ref_type`, `auto_ref_id`
  - Prefix or footer (localized): clearly states automated reply (e.g. “Automated answer from help center”).
- Set ticket `status` → `pending` (waiting on customer), `auto_reply_status=matched`.
- Notify customer (`agent_reply` or new kind `auto_reply` — prefer **new** `auto_reply` for analytics; additive CHECK).
- **Do not** assign an agent on FAQ match (stays unassigned for claim).

**Performance:** sync inside create transaction **after** commit of ticket+first message is preferred: commit ticket → match → insert system message in a short follow-up tx so create latency stays low. Matcher must be O(corpus) with small corpus + indexes on keywords GIN; hard cap ≤ 50 ms CPU budget or abort to AI stage.

### 4.3 Confidence threshold → Stage B

If no match or `confidence < T_match`:

- If `settings.ai_enabled` and support AI configured → enqueue **async** AI job (§5).
- Else → `auto_reply_status=skipped` (or `handed_off` if desk expects human-only).

Default **`match_confidence_threshold` = 0.78** (admin-configurable 0.50–0.95).

### 4.4 Message labeling (customer + staff)

| Audience | Presentation |
|----------|----------------|
| Customer | System bubble with badge “Automated” / “AI-assisted”; never look like a named human agent. |
| Staff | Same + `auto_source`, confidence, KB/template link; AI drafts as **internal notes** when delivery=`draft`. |

Extend `support_messages` (additive):

```sql
auto_source TEXT CHECK (auto_source IS NULL OR auto_source IN ('kb','template','ai')),
auto_confidence REAL,
auto_ref_type TEXT,
auto_ref_id UUID,
is_auto_reply BOOLEAN NOT NULL DEFAULT false
```

---

## 5. AI assist

### 5.1 Provider resolution (discovered)

| Symbol / path | Role |
|---------------|------|
| `platformsettings.AIRoleSupport` (`"support"`) | Admin slot in `ai_roles`. |
| `platformsettings.ResolveAIConfig(ctx, AIRoleSupport)` | Decrypt key; provider/base_url/model/enabled. |
| `aiprovider.RoleSupport` / `ResolveCompleterForRole(ctx, companyID, RoleSupport)` | Completer; platform-only for support (no env fallback). |
| `support.TryAutoReplyLLM(ctx, ticketID)` | **Sole** product gate for ticket LLM sends/drafts. |
| Admin UI | `/admin/settings` + `admin-ai-roles.ts` role `support`. |
| API | `GET/PUT /api/admin/settings` → `ai_roles.support`. |

**ASSUMPTION:** Support auto uses **platform** `ai_roles.support`, never tenant BYOK. `companyID` passed to resolver is the ticket’s company for future bindings only; MVP ignores company BYOK for RoleSupport (already the case in `ResolveCompleterForRole` switch).

### 5.2 Admin AI override vs global

Under support-auto settings (§8):

| Setting | Behavior |
|---------|----------|
| `ai_use_global_support_role: true` (default) | Use `ResolveCompleterForRole(..., RoleSupport)` as configured in admin. |
| `ai_model_override` / `ai_provider_override` / `ai_base_url_override` | Optional; applied only when `ai_use_global_support_role` is true **and** overrides non-empty — still uses the **same API key** from `AIRoleSupport` (never a second secret store). |
| Role disabled / missing key | AI stage → `failed` → human handoff; log without secrets. |

### 5.3 Prompt contract

System prompt (server-owned, not admin free-text MVP):

- Answer only from provided KB snippets + ticket text.
- No inventing billing credits, invoices, or other tenants’ data.
- If unsure, say so and ask one clarifying question OR signal `handoff=true`.
- Output JSON: `{ "body": "...", "confidence": 0-1, "handoff": bool, "citations": ["kb:slug"] }`.

User/content payload:

- Redacted ticket subject + body (§6).
- Category, tags, related_sku (company-scoped).
- Top-N KB snippets from cheap lexical retrieval (even if below FAQ auto-send threshold).
- Customer context snapshot **sanitized** (no emails of other users; plan slug ok).

### 5.4 Delivery modes

| `ai_delivery` | Action |
|---------------|--------|
| `draft` (default, safer) | Insert **internal note** (`is_internal_note=true`, `author_role=system`, `is_auto_reply=true`); notify assignee or unassigned queue via staff notification; `auto_reply_status=ai_draft`. Customer sees nothing yet. |
| `auto_send` | Post **public** system message (labeled AI-assisted); status → `pending`; `auto_reply_status=ai_sent`. |

Require `ai_confidence >= settings.ai_confidence_threshold` (default **0.65**) and `handoff=false` to send/draft; else handoff.

### 5.5 Async job (preferred)

**Sync path forbidden for LLM** on the HTTP create request.

Job sketch (`support_auto_jobs` or reuse processing-style pending table):

| Column | Notes |
|--------|-------|
| `id`, `ticket_id`, `company_id` | Tenant key for isolation |
| `status` | `pending\|running\|done\|failed` |
| `attempt`, `last_error` | No PII in error; truncate |
| `created_at`, `updated_at` | |

Worker:

1. Skip if `auto_reply_disabled` or ticket closed/resolved or already matched/sent.
2. Rate-limit check (§6).
3. Call `TryAutoReplyLLM` (implementation loads ticket, snippets, completer, posts draft/send).
4. Idempotent: unique partial index on `(ticket_id) WHERE status IN ('pending','running')` or ticket-level lock.

**ASSUMPTION:** Follow existing `jobs.Queue` + worker poller pattern (`apps/api/internal/jobs/river.go` comment: River deferred). Name the worker kind `support_auto_reply`.

---

## 6. Security

| Control | Rule |
|---------|------|
| Tenant isolation | All ticket reads/writes filter `company_id`. KB is platform-global **content** but never includes other companies’ tickets in prompts. Related product id validated against ticket `company_id`. |
| Prompt isolation | Completer called with **one ticket’s** redacted text only; never batch multi-tenant prompts. |
| Secret redaction | Before match features + AI: strip patterns for API keys, Bearer tokens, `sk-`, AWS keys, private key PEM, connection strings; replace with `[REDACTED]`. Do not store raw secrets in `customer_context` or auto job logs. |
| Rate limits | Per `company_id`: default 10 AI jobs / hour; platform global: 30 AI jobs / minute. FAQ match not counted toward AI limits. Reuse sliding-window pattern (`httpapi/ratelimit.go`). Exceed → `skipped`/`failed` + handoff, HTTP create still 201. |
| Disable per ticket | Staff PATCH `{ "auto_reply_disabled": true }`; also auto-set on handoff / customer follow-up after auto. |
| AuthZ | Settings: `RequirePlatformAdmin`. Disable flag: `RequireSupportDesk` on assigned/visible ticket. KB CRUD: platform admin. |
| Customer visibility | Never expose internal AI drafts, confidence, or admin settings. |
| Logging | No API keys, no full bodies at info level; structured `ticket_id`, `company_id`, `auto_source`, `confidence`. |
| Docs Ask | Remains rule-based; must not use `AIRoleSupport` / `AIRoleDocsAPI` (existing invariant). |

---

## 7. Performance

| Path | Guidance |
|------|----------|
| FAQ/template match | **Sync**, bounded corpus, GIN on keywords; target &lt; 50 ms; no external I/O. |
| AI assist | **Async** job only; HTTP returns before LLM. |
| Create API | Do not hold open DB transactions across LLM. |
| Indexes | `(auto_reply_status)`, GIN `tags`, FK `related_product_id`, job `(status, created_at)`. |
| List endpoints | Do not embed full `customer_context` in list — detail only (or truncated). |
| N+1 | Matcher loads published KB once per process with short TTL cache (e.g. 60s) — invalidate on admin KB write. |

---

## 8. Admin settings

Stored under platform settings (JSON key `support_auto` in `values` **or** first-class object on PublicView — implementers pick one; prefer first-class for typed admin UI).

| Key | Type | Default | Purpose |
|-----|------|---------|---------|
| `enabled` | bool | `false` | Master switch for any auto first response. |
| `faq_enabled` | bool | `true` | Stage A. |
| `ai_enabled` | bool | `false` | Stage B (still requires `ai_roles.support` configured + enabled). |
| `match_confidence_threshold` | number | `0.78` | FAQ/template auto-send. |
| `ai_confidence_threshold` | number | `0.65` | Min model confidence. |
| `ai_delivery` | `draft\|auto_send` | `draft` | |
| `ai_use_global_support_role` | bool | `true` | Use admin `ai_roles.support`. |
| `ai_provider_override` | string? | null | Optional; key still from support role. |
| `ai_model_override` | string? | null | |
| `ai_base_url_override` | string? | null | |
| `rate_limit_per_company_per_hour` | int | `10` | AI jobs. |
| `rate_limit_platform_per_minute` | int | `30` | AI jobs. |
| `retry_on_first_customer_reply` | bool | `false` | |

API (additive):

| Method | Path | Auth |
|--------|------|------|
| GET/PUT | `/api/admin/settings` (embed `support_auto`) | Platform admin |
| CRUD | `/api/admin/support/kb/articles*` | Platform admin |
| CRUD | `/api/admin/support/templates*` | Platform admin |
| CRUD | `/api/admin/support/categories*` | Platform admin |
| PATCH | `/api/admin/support/tickets/{id}` | Support desk — `auto_reply_disabled`, tags, related_*, priority, category |

Customer create (additive body fields): `tags?`, `related_product_id?`, `related_sku?` (category taxonomy as today).

---

## 9. Human handoff

Set `auto_reply_status=handed_off`, `auto_reply_disabled=true` when:

1. AI returns `handoff=true` or confidence below threshold.
2. AI provider error / timeout / unset completer.
3. Rate limit exceeded for AI.
4. Customer sends another message after an automated public reply.
5. Staff claims/replies or explicitly disables auto.

Effects: ticket remains `open` (or current status); stays claimable; optional internal system note “Needs human review” (not customer-visible). No further auto jobs for that ticket unless staff sets `auto_reply_disabled=false` (rare; audit).

---

## 10. Alignment with support desk (agent 11)

- Auto does **not** assign `assignee_admin_user_id` (preserves unassigned queue + claim).
- Public auto reply may move status `open` → `pending` (same as agent public reply default).
- Internal AI drafts do **not** change status / do **not** notify customer.
- CSAT / claim / staff roles unchanged.
- `TryAutoReplyLLM` opt-in replaces the “keep disabled” note in 11-support §11.9 when this feature ships behind `support_auto.enabled`.

---

## 11. Implementation phasing (later agents)

1. Migration: ticket rich fields + message auto columns + categories + KB + templates + auto jobs.
2. Admin settings + KB/template/category CRUD.
3. Sync matcher + labeled system post on create.
4. Implement `TryAutoReplyLLM` + async worker + redaction + rate limits.
5. Staff UI: disable auto, show auto metadata, AI draft notes.
6. Customer UI: tags/SKU/category; automated badge on messages.
7. Tests: tenant isolation, redaction, threshold branches, handoff on user reply, AI disabled stub, rate limit.

**Out of scope:** per-tenant KB, embedding retrieval, multi-turn AI bot, attachments, SLA clocks.

---

## 12. Contracts preserved / breaking

**Preserved**

- Existing customer/staff ticket JSON fields; additive only.
- `author_role` enum values; system used for auto.
- Admin `ai_roles.support` shape; no new secret store.
- Desk visibility / claim rules from agent 11.

**BREAKING (soft)**

- Category allow-list may grow; clients must tolerate unknown **historical** categories.
- New notification kind `auto_reply` requires CHECK constraint migration.

**Reconciled with 01-inventory:** symbols/paths match; Create post-commit hook preferred; settings stay in platform JSON (`support_auto` + existing `ai_roles.support`); no plan-permission key for auto-reply in MVP.