# TRUEREF-0018 — Embedding Provider Configuration UI

**Priority:** P2
**Status:** Pending
**Depends On:** TRUEREF-0007, TRUEREF-0015
**Blocks:** —

---

## Overview

A settings page within the web UI that allows users to configure the embedding provider without editing environment variables or config files. Supports switching between "None" (FTS5-only), OpenAI-compatible API, and local model (if available). Includes a live connectivity test before saving.

---

## Acceptance Criteria

- [ ] Settings page at `/settings` with embedding provider section
- [ ] Provider selector: None / OpenAI-compatible / Local model
- [ ] OpenAI provider form: base URL, API key (masked), model name, dimensions
- [ ] "Test Connection" button that validates the API key and model before saving
- [ ] Success/error feedback from connection test
- [ ] Save configuration (calls `PUT /api/v1/settings/embedding`)
- [ ] Current configuration loaded from `GET /api/v1/settings/embedding`
- [ ] Warning shown when "None" is selected (search will be FTS5-only, lower quality)
- [ ] Local model option shows whether `@xenova/transformers` is installed
- [ ] Preset buttons for common providers (OpenAI, Ollama, Azure OpenAI)

---

## Provider Presets

```typescript
const PROVIDER_PRESETS = [
  {
    name: 'OpenAI',
    baseUrl: 'https://api.openai.com/v1',
    model: 'text-embedding-3-small',
    dimensions: 1536,
  },
  {
    name: 'Ollama (local)',
    baseUrl: 'http://localhost:11434/v1',
    model: 'nomic-embed-text',
    dimensions: 768,
  },
  {
    name: 'Azure OpenAI',
    baseUrl: 'https://{resource}.openai.azure.com/openai/deployments/{deployment}/v1',
    model: 'text-embedding-3-small',
    dimensions: 1536,
  },
];
```

---

## Settings Page Component

```svelte
<!-- src/routes/settings/+page.svelte -->
<script lang="ts">
  let provider = $state<'none' | 'openai' | 'local'>('none');
  let baseUrl = $state('https://api.openai.com/v1');
  let apiKey = $state('');
  let model = $state('text-embedding-3-small');
  let dimensions = $state<number | undefined>(1536);
  let testStatus = $state<'idle' | 'testing' | 'ok' | 'error'>('idle');
  let testError = $state<string | null>(null);
  let saving = $state(false);

  async function testConnection() {
    testStatus = 'testing';
    testError = null;
    try {
      const res = await fetch('/api/v1/settings/embedding/test', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ provider, openai: { baseUrl, apiKey, model, dimensions } }),
      });
      if (res.ok) {
        testStatus = 'ok';
      } else {
        const data = await res.json();
        testStatus = 'error';
        testError = data.error;
      }
    } catch (e) {
      testStatus = 'error';
      testError = (e as Error).message;
    }
  }

  async function save() {
    saving = true;
    await fetch('/api/v1/settings/embedding', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ provider, openai: { baseUrl, apiKey, model, dimensions } }),
    });
    saving = false;
  }
</script>

<div class="mx-auto max-w-2xl py-8">
  <h1 class="mb-6 text-2xl font-bold text-gray-900">Settings</h1>

  <section class="rounded-xl border border-gray-200 bg-white p-6">
    <h2 class="mb-1 text-lg font-semibold">Embedding Provider</h2>
    <p class="mb-4 text-sm text-gray-500">
      Embeddings enable semantic search. Without them, only keyword search (FTS5) is used.
    </p>

    <div class="mb-4 flex gap-2">
      {#each ['none', 'openai', 'local'] as p}
        <button
          onclick={() => provider = p}
          class="rounded-lg px-4 py-2 text-sm {provider === p
            ? 'bg-blue-600 text-white'
            : 'border border-gray-200 text-gray-700 hover:bg-gray-50'}"
        >
          {p === 'none' ? 'None (FTS5 only)' : p === 'openai' ? 'OpenAI-compatible' : 'Local Model'}
        </button>
      {/each}
    </div>

    {#if provider === 'none'}
      <div class="rounded-lg bg-amber-50 border border-amber-200 p-3 text-sm text-amber-700">
        Search will use keyword matching only. Results may be less relevant for complex questions.
      </div>
    {/if}

    {#if provider === 'openai'}
      <div class="space-y-3">
        <!-- Preset buttons -->
        <div class="flex gap-2 flex-wrap">
          {#each PROVIDER_PRESETS as preset}
            <button
              onclick={() => { baseUrl = preset.baseUrl; model = preset.model; dimensions = preset.dimensions; }}
              class="rounded border border-gray-200 px-2.5 py-1 text-xs text-gray-600 hover:bg-gray-50"
            >
              {preset.name}
            </button>
          {/each}
        </div>

        <label class="block">
          <span class="text-sm font-medium">Base URL</span>
          <input type="text" bind:value={baseUrl} class="mt-1 w-full rounded-lg border px-3 py-2 text-sm" />
        </label>

        <label class="block">
          <span class="text-sm font-medium">API Key</span>
          <input type="password" bind:value={apiKey} class="mt-1 w-full rounded-lg border px-3 py-2 text-sm" placeholder="sk-..." />
        </label>

        <label class="block">
          <span class="text-sm font-medium">Model</span>
          <input type="text" bind:value={model} class="mt-1 w-full rounded-lg border px-3 py-2 text-sm" />
        </label>

        <label class="block">
          <span class="text-sm font-medium">Dimensions (optional override)</span>
          <input type="number" bind:value={dimensions} class="mt-1 w-full rounded-lg border px-3 py-2 text-sm" />
        </label>

        <div class="flex items-center gap-3">
          <button onclick={testConnection} class="rounded-lg border border-gray-300 px-3 py-1.5 text-sm">
            {testStatus === 'testing' ? 'Testing...' : 'Test Connection'}
          </button>
          {#if testStatus === 'ok'}
            <span class="text-sm text-green-600">✓ Connection successful</span>
          {:else if testStatus === 'error'}
            <span class="text-sm text-red-600">✗ {testError}</span>
          {/if}
        </div>
      </div>
    {/if}

    <div class="mt-6 flex justify-end">
      <button
        onclick={save}
        disabled={saving}
        class="rounded-lg bg-blue-600 px-4 py-2 text-sm text-white disabled:opacity-50"
      >
        {saving ? 'Saving...' : 'Save Settings'}
      </button>
    </div>
  </section>
</div>
```

---

## Test Connection Endpoint

`POST /api/v1/settings/embedding/test`

Request body: same as `PUT /api/v1/settings/embedding`
Action: create a provider instance, call `embed(['test'])`, return success/failure
Response `200`: `{ "ok": true, "dimensions": 1536 }`
Response `400`: `{ "error": "API key is invalid" }`

---

## Files to Create

- `src/routes/settings/+page.svelte`
- `src/routes/api/v1/settings/embedding/test/+server.ts`

## Files to Modify

- `src/routes/api/v1/settings/embedding/+server.ts` — already defined in TRUEREF-0007
