# 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 border border-amber-200 bg-amber-50 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 flex-wrap gap-2">
					{#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