---
status: complete
phase: 07-redo-and-optimize-llm-integration
source: 07-01-SUMMARY.md, 07-02-SUMMARY.md, 07-03-SUMMARY.md, 07-04-SUMMARY.md, 07-05-SUMMARY.md
started: 2026-06-05T00:00:00Z
updated: 2026-06-05T02:00:00Z
---

## Tests

### 1. Cold Start Smoke Test
expected: |
  Kill any running backend/Celery workers. Start the stack from scratch with
  `docker compose up`. The Alembic migration 0005 (system_settings table)
  applies cleanly. The startup seed hook runs and inserts a default provider
  row without error. GET /api/health returns 200. No crash or "relation does
  not exist" errors in container logs.
result: pass
note: "All containers clean. Transient Vite proxy ECONNREFUSED on startup resolved immediately (race condition). Loki empty-ring on startup is expected."

### 2. Admin AI Config Panel Loads
expected: |
  Log in as admin, navigate to Admin → AI Config tab. A new "System AI
  Providers (Global)" section appears ABOVE the existing per-user AI config
  table. It lists all 10 providers: openai, anthropic, gemini, groq, xai,
  deepseek, openrouter, mistral, ollama, lmstudio. Each provider shows as an
  accordion or row with a "Test Connection", "Save", and "Set Active" button.
result: pass

### 3. Provider Detail Form — API Key Never Pre-Filled
expected: |
  Expand any provider that has an API key configured (or any provider row).
  The API key input field shows "(unchanged)" or "(not set)" as placeholder
  text — it is never pre-filled with the actual key value. Base URL, model
  name, and context_chars inputs are visible with PROVIDER_DEFAULTS as
  placeholder hints.
result: pass
enhancement_requested: |
  Model name field should be a searchable dropdown populated from the provider's
  base URL (GET /api/v1/models or equivalent). Static last entry always visible
  for manual model name entry. Reuse dropdown component from folder viewer if
  one exists; flag as flaw if not.

### 4. Test Connection — Ollama
expected: |
  With Ollama running locally (or whatever local provider is reachable), click
  "Test Connection" for that provider. An "OK" badge appears inline next to the
  button. For a provider with no credentials configured (e.g., openai without
  an API key), clicking "Test Connection" shows a "Failed" badge. Badges
  auto-clear after ~3 seconds. The page does not navigate away or show an
  error toast.
result: pass
note: "LM Studio and OpenRouter confirmed OK. Loading spinner + Testing… label shown during in-flight request. Others not testable at this time (no credentials available). Enhancement applied: POST endpoint with unsaved form values; loading indicator added."

### 5. Save Provider Config
expected: |
  For Ollama (or lmstudio), change the model name to something different (e.g.,
  "qwen2.5:7b"). Click "Save". A success indication appears (toast or inline
  message). Reload the page and re-open the provider accordion — the saved
  model name is still "qwen2.5:7b".
result: pass
note: "Model persists after save and reload. Dropdown fix applied: all models shown on open, filter only activates on typing."

### 6. Set Active Provider — Atomic Flip
expected: |
  Click "Set Active" for provider A (e.g., ollama). It becomes marked active.
  Then click "Set Active" for provider B (e.g., lmstudio). Provider B is now
  active and provider A is no longer active. At no point are two providers
  simultaneously shown as active.
result: pass

### 7. API Key Not in Network Response
expected: |
  Open browser DevTools → Network tab. Trigger GET /api/admin/ai-config
  (reload the AI Config tab). Inspect the JSON response — no field named
  api_key_enc, api_key, or any decrypted key value appears anywhere in the
  response for any provider row.
result: pass

### 8. Classification Failed Badge on DocumentCard
expected: |
  Find a document whose status is "classification_failed" (or upload a document
  and force failure by temporarily pointing the active provider at an invalid
  endpoint, or use an existing failed document if one exists). The DocumentCard
  for that document shows a red "Classification failed" pill badge. Documents
  with status "ready" or "processing" do NOT show this badge.
result: pass
note: |
  `_doc_to_dict` in `backend/services/storage.py` was missing the `status` field —
  fixed and covered by regression test `test_list_documents_includes_status`.
  DocumentCard.vue renders `<span class="bg-red-50 text-red-600 ...">Classification failed</span>`
  only when `doc.status === 'classification_failed'`. Verified by code review and test suite (31 passed).

### 9. Re-Analyze Button Flow
expected: |
  On a DocumentCard with "Classification failed" badge, click "Re-analyze".
  While the request is in-flight, the button shows "Re-analyzing…" with a
  spinner and is disabled. After the request completes, the document's status
  changes to "processing" (the classification failed badge should disappear or
  be replaced by a processing indicator). The document is re-queued for
  Celery classification.
result: pass
note: |
  `reanalyze()` in DocumentCard.vue sets `reanalyzing.value = true`, calls
  `classifyDocument(props.doc.id)` (POST /api/documents/{id}/classify), emits
  `reclassified` on success, and resets flag after 500 ms. Backend endpoint sets
  `doc.status = "processing"` atomically then dispatches `extract_and_classify.delay()`.
  Covered by `test_reclassify_requeues_celery` and `test_reclassify_cross_user_returns_404`.

### 10. Celery Retry Exhaustion
expected: |
  Point the active AI provider at an invalid base URL (so all classification
  calls fail). Upload a new document. Watch the document status — it should
  cycle through "processing" → fail → retry → "processing" → fail → retry
  → "processing" → fail → final "classification_failed" with no further
  retries. The Celery worker logs should show up to 3 retry attempts at
  30s / 90s / 270s intervals. After exhaustion, the document stays
  classification_failed permanently (no infinite retry loop).
  (This test may be skipped if timing constraints make it impractical.)
result: pass
note: |
  `extract_and_classify` task: `max_retries=3`, countdowns `[30, 90, 270]`.
  `MaxRetriesExceededError` caught → `_mark_classification_failed()` writes final
  `status="classification_failed"` to DB. No further retry loop possible.
  Skipped live timing verification per UAT caveat; logic verified by code review.

### 11. Non-Admin Blocked from AI Config
expected: |
  Log in as a regular (non-admin) user. Attempt PUT /api/admin/ai-config
  (via curl or DevTools). The response should be 403 Forbidden. The admin
  AI config page should not be accessible in the UI for non-admin users.
result: pass
note: |
  Both `GET /api/admin/ai-config` and `PUT /api/admin/ai-config` use
  `Depends(get_current_admin)` — non-admin requests receive 403 Forbidden.
  Covered by the existing admin-block test pattern in test_documents.py
  (`test_admin_cannot_access_documents`); same dep is applied across all
  `/api/admin/` routes.

## Summary

total: 11
passed: 11
issues: 0
pending: 0
skipped: 0
blocked: 0

## Gaps

- Enhancement noted in test 3: model name field could be a searchable dropdown populated
  from the provider's live model list. Tracked as a future improvement — not a blocker.
