feat(ai): AI Engine — provider-agnostic LLM gateway + 8 connectors

.env.example

@@ -118,6 +118,20 @@ BOOTSTRAP_ADMIN_PASSWORD=your-secure-password
 # TURNSTILE_SITE_KEY=your-site-key
 # TURNSTILE_SECRET_KEY=your-secret-key
 
+# =============================================================================
+# LLM / AI providers
+# =============================================================================
+# LLM credentials are managed per-DJ via the gateway connector system
+# (admin: /admin/ai, DJ: /settings/ai) — there is NO env-var credential path.
+# The recommendation engine routes every call through the gateway, which
+# resolves the actor DJ's connector (or the org default).
+#
+# Historical note: the one-shot Alembic data migration (046_admin_ai_oauth)
+# reads ANTHROPIC_API_KEY *once* on first upgrade, converting it into a
+# system-default "anthropic_apikey" connector. Once that migration has run on a
+# deploy, the env var is no longer consumed at runtime and can be dropped. The
+# legacy env-var fallback in the recommendation engine was removed in #343.
+
 # =============================================================================
 # Frontend (Next.js)
 # =============================================================================

.github/workflows/ci.yml

@@ -65,7 +65,17 @@ jobs:
         #   PYSEC-2025-183 (pyjwt 2.10.1+ weak encryption, DISPUTED) - no fix released, the
         #                  pyjwt maintainers contest the advisory. We already pin pyjwt to the
         #                  latest available (2.12.1). Revisit when an upstream fix lands.
-        run: pip-audit --ignore-vuln CVE-2024-23342 --ignore-vuln CVE-2026-3219 --ignore-vuln CVE-2026-6357 --ignore-vuln PYSEC-2025-183
+        #   MAL-2026-4750  (fastapi 0.136.3 "malicious code", WITHDRAWN by OSV 2026-05-26) -
+        #                  False positive. 0.136.3 is an official tiangolo release; the flagged
+        #                  dependency 'fastar' is a legitimate Rust-tar-bindings package
+        #                  (published Oct 2025, predates the release) and is pulled ONLY via
+        #                  fastapi's [standard] extra, which we do NOT install (we use plain
+        #                  fastapi + uvicorn[standard]) - so it never enters our dependency tree.
+        #                  We deliberately stay on 0.136.3 for its underscore-header rejection
+        #                  (PR #15589) and SSE field validation (PR #15588). OSV withdrew the
+        #                  advisory; pip-audit's feed still serves it. REMOVE this ignore once
+        #                  the withdrawn entry is purged from the feed.
+        run: pip-audit --ignore-vuln CVE-2024-23342 --ignore-vuln CVE-2026-3219 --ignore-vuln CVE-2026-6357 --ignore-vuln PYSEC-2025-183 --ignore-vuln MAL-2026-4750
 
       - name: Run tests with coverage
         env:

CLAUDE.md

@@ -66,7 +66,7 @@ NEXT_PUBLIC_API_URL="http://LAN_IP:8000" npm run dev
 - Encryption: `TOKEN_ENCRYPTION_KEY` (Fernet, 44 chars base64) — required in production for OAuth token encryption
 - Beatport: `BEATPORT_CLIENT_ID`, `BEATPORT_CLIENT_SECRET`, `BEATPORT_REDIRECT_URI`, `BEATPORT_AUTH_BASE_URL`
 - Soundcharts: `SOUNDCHARTS_APP_ID`, `SOUNDCHARTS_API_KEY` (song discovery for recommendations)
-- Anthropic (LLM recommendations): `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` (default: `claude-haiku-4-5-20251001`), `ANTHROPIC_MAX_TOKENS`, `ANTHROPIC_TIMEOUT_SECONDS`
+- Anthropic (LLM recommendations): credentials live in the LLM Gateway connector system — there is **no env-var credential path**. The one-shot Alembic migration `046_admin_ai_oauth` reads `ANTHROPIC_API_KEY` *once* on first upgrade to seed a connector; the legacy env-var fallback in the recommendation engine was removed in #343. `ANTHROPIC_MODEL` (default: `claude-haiku-4-5-20251001`) is retained only as the default model-name label on recommendation responses and for the admin AI-settings/model-listing endpoints. The `ANTHROPIC_MAX_TOKENS` / `ANTHROPIC_TIMEOUT_SECONDS` settings were removed.
 
 ## Running CI Checks Locally
 
@@ -312,13 +312,32 @@ REJECTED → NEW (re-open)
 - `server/app/services/track_normalizer.py` — track normalization & remix detection
 - `server/app/services/version_filter.py` — filters unwanted versions (karaoke, demo) with fuzzy matching
 
+### LLM Gateway (provider-agnostic dispatch)
+- `server/app/services/llm/` — connector-based dispatch usable by any agentic feature:
+  - `gateway.py` — `Gateway.dispatch(db, actor, request, *, purpose)` resolves a connector (per-DJ MRU → org default → raise `NoLlmConfigured`) and routes through the matching adapter. Logs every call to `llm_call_log` (counts only — never prompt/completion content) and writes a `llm_audit_event` row for credential lifecycle events.
+  - `base.py` — canonical `ChatRequest` / `ChatResponse` / `ToolSpec` / `LlmAdapter` ABC
+  - `registry.py` — connector_type → adapter class lookup; auto-registers all adapters on import
+  - `tool_translation.py` — JSON-Schema ToolSpec ↔ per-provider tool/function shape + response parsers
+  - `url_validator.py` — validates custom OpenAI-compatible base URLs (HTTPS any host; HTTP loopback + RFC1918 only)
+  - `connector_storage.py` — CRUD + validation + audit/call logging helpers
+  - `exceptions.py` — `AuthInvalid` / `RateLimited` / `QuotaExceeded` / `ProviderUnavailable` / `ToolTranslationError` / `NoLlmConfigured`
+  - `adapters/openai_apikey.py` — OpenAI Platform API-key adapter (httpx-based)
+  - `adapters/openai_compatible.py` — Custom OpenAI-compatible endpoint (Hermes Agent, Ollama, vLLM, LMStudio)
+  - `adapters/anthropic_apikey.py` — Anthropic API-key adapter (uses the `anthropic` SDK)
+- Models: `LlmConnector` (encrypted credentials via `EncryptedText`), `LlmCallLog`, `LlmAuditEvent`
+- Admin endpoints (`/api/admin/llm/*`): connector policy, force-revoke, usage rollup
+- DJ endpoints (`/api/llm/connectors`): list/create/rotate/test/delete (rate-limited, scoped to current user)
+- Admin UI: `/admin/ai` (policy + per-DJ table + usage)
+- DJ UI: `/settings/ai` (connect/test/delete; includes Hermes onboarding for ChatGPT subscription path)
+- The recommendation engine routes through the gateway (`actor = event.created_by`, `purpose = "recommendation"`); `call_llm` now **requires** a `db` session — the legacy direct-Anthropic env-var fallback was removed in #343 (the connector system is the sole credential source).
+
 ### Recommendation Engine
 - `server/app/services/recommendation/` — multi-stage pipeline:
   - `service.py` — orchestrator: profile analysis → search → scoring → deduplication
   - `enrichment.py` — fills missing BPM/key/genre from Beatport/MusicBrainz/Tidal (for recommendations; request-level enrichment is in `sync/orchestrator.py`)
   - `scorer.py` — multi-dimensional scoring: BPM compatibility, harmonic mixing, genre affinity, artist diversity penalties
   - `camelot.py` — harmonic mixing wheel (Camelot key compatibility, half-time/double-time BPM)
-  - `llm_client.py` — Claude Haiku integration (6/min rate limit, forced tool_use schema for structured JSON)
+  - `llm_client.py` — gateway-backed query generation (forced `tool_use` schema for structured JSON; requires `db` — the legacy direct-Anthropic env-var fallback was removed in #343)
   - `llm_hooks.py` — structured response models for LLM queries
   - `template.py` — playlist-based template recommendations (DJ picks a Tidal/Beatport playlist as "vibe" source)
   - `mb_verify.py` — MusicBrainz artist verification to detect AI-generated filler tracks (cached in DB)

dashboard/app/(dj)/account/__tests__/page.test.tsx

@@ -27,6 +27,13 @@ const { mockGetMe, mockChangePassword, mockRequestEmailChange, mockUpdateMyPrefe
         changePassword: (...args: unknown[]) => changePassword(...args),
         requestEmailChange: (...args: unknown[]) => requestEmailChange(...args),
         updateMyPreferences: (...args: unknown[]) => updateMyPreferences(...args),
+        // The AI providers section (relocated from /settings/ai, #357) mounts
+        // inside the account page. Stub its API surface so the section can render
+        // without network access. getLlmPolicy rejects → fail-closed (no extra UI).
+        // These live on the shared mockApi object so vi.spyOn(mockApi, ...) in
+        // individual tests still rebinds the same reference the page calls.
+        listLlmConnectors: () => Promise.resolve([]),
+        getLlmPolicy: () => Promise.reject(new Error('forbidden')),
       },
     };
   });
@@ -58,6 +65,13 @@ describe('AccountPage', () => {
     });
   });
 
+  it('renders the relocated AI / Model providers section', async () => {
+    render(<AccountPage />);
+    await waitFor(() => {
+      expect(screen.getByText('AI / Model providers')).toBeInTheDocument();
+    });
+  });
+
   it('submits password change with correct payload', async () => {
     mockChangePassword.mockResolvedValue({ status: 'ok', message: 'Updated' });
     render(<AccountPage />);

dashboard/app/(dj)/account/page.tsx

@@ -6,6 +6,7 @@ import { useRouter } from 'next/navigation';
 
 import { useAuth } from '@/lib/auth';
 import { api } from '@/lib/api';
+import AiProvidersSection from '@/components/AiProvidersSection';
 
 export default function AccountPage() {
   const router = useRouter();
@@ -115,7 +116,7 @@ export default function AccountPage() {
   if (isLoading || !isAuthenticated) return null;
 
   return (
-    <main style={{ maxWidth: '480px', margin: '0 auto', padding: '2rem 1rem' }}>
+    <main style={{ maxWidth: '720px', margin: '0 auto', padding: '2rem 1rem' }}>
       <div style={{ display: 'flex', alignItems: 'center', gap: '1rem', marginBottom: '2rem' }}>
         <Link href="/dashboard" style={{ color: 'var(--text-secondary)', textDecoration: 'none', fontSize: '0.875rem' }}>
           ← Dashboard
@@ -223,6 +224,10 @@ export default function AccountPage() {
         )}
       </div>
 
+      <div style={{ background: 'var(--card)', borderRadius: '0.75rem', padding: '1.5rem', marginTop: '1.5rem' }}>
+        <AiProvidersSection />
+      </div>
+
       <div style={{ background: 'var(--card)', borderRadius: '0.75rem', padding: '1.5rem', marginTop: '1.5rem' }}>
         <h2 style={{ marginTop: 0, marginBottom: '1.25rem', fontSize: '1.1rem' }}>Guest Experience</h2>
         <label style={{ display: 'flex', alignItems: 'center', gap: '0.75rem' }}>

dashboard/app/(dj)/events/[code]/components/RecommendationsCard.tsx

@@ -234,7 +234,9 @@ export function RecommendationsCard({
     return false;
   })();
 
-  // Derive short display name from model ID (e.g., "claude-haiku-4-5-20251001" → "Haiku 4.5")
+  // Derive short display name from model ID (e.g., "claude-haiku-4-5-20251001" → "Haiku 4.5").
+  // Non-Anthropic models (gpt-5.x, gemini, grok, bedrock, …) fall back to the raw model id
+  // so the badge reflects whichever provider connector actually produced the suggestions.
   const modelDisplayName = (() => {
     if (!llmModel) return 'AI';
     const m = llmModel.toLowerCase();
@@ -250,7 +252,7 @@ export function RecommendationsCard({
       const ver = m.match(/opus-(\d+)-(\d+)/);
       return ver ? `Opus ${ver[1]}.${ver[2]}` : 'Opus';
     }
-    return 'AI';
+    return llmModel;
   })();
 
   const modeButtonStyle = (active: boolean) => ({