@4djs/assistant 0.0.0

package/src/core/llm-config.ts

@@ -0,0 +1,101 @@
+export const DEFAULT_LLM_BASE_URL = "https://api.openai.com/v1";
+export const DEFAULT_LLM_MODEL = "gpt-4o-mini";
+export const DEFAULT_ASSISTANT_SYSTEM_PROMPT =
+	"You are a helpful assistant with access to tools. Use tools when they help answer the user.";
+
+const FALLBACK_MODEL_OPTIONS = [
+	DEFAULT_LLM_MODEL,
+	"gpt-4o",
+	"gpt-4.1",
+	"gpt-4.1-mini",
+	"gpt-4.1-nano",
+	"o3-mini",
+];
+
+export interface ResolvedLlmSettings {
+	enabled: boolean;
+	baseUrl: string;
+	apiKey: string | null;
+	model: string;
+	models?: string[];
+	systemPrompt?: string;
+}
+
+export function getFallbackModels(defaultModel: string): string[] {
+	return [...new Set([defaultModel, ...FALLBACK_MODEL_OPTIONS])];
+}
+
+export function resolveRequestModel(
+	requested: string | undefined,
+	config: Pick<ResolvedLlmSettings, "model">,
+): string {
+	const candidate = requested?.trim();
+	if (candidate) return candidate;
+	return config.model;
+}
+
+export function buildCompletionsUrl(baseUrl: string): string {
+	const base = baseUrl.replace(/\/+$/, "");
+	if (base.endsWith("/v1")) return `${base}/chat/completions`;
+	return `${base}/v1/chat/completions`;
+}
+
+export function buildModelsUrl(baseUrl: string): string {
+	const base = baseUrl.replace(/\/+$/, "");
+	if (base.endsWith("/v1")) return `${base}/models`;
+	return `${base}/v1/models`;
+}
+
+export function isLocalLlmBaseUrl(baseUrl: string): boolean {
+	try {
+		const normalized = baseUrl.includes("://") ? baseUrl : `http://${baseUrl}`;
+		const hostname = new URL(normalized).hostname.toLowerCase();
+		return (
+			hostname === "localhost" ||
+			hostname === "127.0.0.1" ||
+			hostname === "0.0.0.0" ||
+			hostname === "[::1]" ||
+			hostname.endsWith(".local")
+		);
+	} catch {
+		return false;
+	}
+}
+
+export function isLlmConfigured(
+	settings: Pick<
+		ResolvedLlmSettings,
+		"enabled" | "baseUrl" | "apiKey" | "model"
+	>,
+): boolean {
+	if (settings.enabled === false) return false;
+	if (!settings.baseUrl?.trim() || !settings.model?.trim()) return false;
+	if (settings.apiKey?.trim()) return true;
+	return isLocalLlmBaseUrl(settings.baseUrl);
+}
+
+export const LLM_UNAVAILABLE_MESSAGE =
+	"Chat requires an LLM. Open LLM settings to add your provider base URL, model, and API key (optional for local servers).";
+
+export function isLlmUnavailableMessage(message: {
+	content: string;
+	llmSetupRequired?: boolean;
+}): boolean {
+	return (
+		message.llmSetupRequired === true ||
+		message.content.trim() === LLM_UNAVAILABLE_MESSAGE
+	);
+}
+
+export function buildLlmRequestHeaders(
+	apiKey: string | null | undefined,
+): Record<string, string> {
+	const headers: Record<string, string> = {
+		"Content-Type": "application/json",
+	};
+	const token = apiKey?.trim();
+	if (token) {
+		headers.Authorization = `Bearer ${token}`;
+	}
+	return headers;
+}

package/src/core/llm-models.ts

@@ -0,0 +1,96 @@
+import {
+	buildLlmRequestHeaders,
+	buildModelsUrl,
+	getFallbackModels,
+	isLlmConfigured,
+	type ResolvedLlmSettings,
+} from "./llm-config.ts";
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+const EXCLUDED_MODEL_PATTERNS = [
+	/embed/i,
+	/whisper/i,
+	/tts/i,
+	/dall-e/i,
+	/moderation/i,
+	/transcribe/i,
+	/realtime/i,
+	/audio/i,
+	/speech/i,
+	/image/i,
+	/completion$/i,
+];
+
+interface ProviderModelEntry {
+	id?: string;
+}
+
+interface ProviderModelsResponse {
+	data?: ProviderModelEntry[];
+}
+
+let modelCache: { key: string; models: string[]; fetchedAt: number } | null =
+	null;
+
+export async function fetchProviderModels(
+	config: Pick<ResolvedLlmSettings, "baseUrl" | "apiKey" | "model">,
+): Promise<string[]> {
+	const cacheKey = `${config.baseUrl}:${config.apiKey?.slice(-6) ?? "local"}`;
+	if (
+		modelCache &&
+		modelCache.key === cacheKey &&
+		Date.now() - modelCache.fetchedAt < CACHE_TTL_MS
+	) {
+		return modelCache.models;
+	}
+
+	if (!config.apiKey?.trim()) {
+		if (!isLlmConfigured({ enabled: true, ...config })) {
+			return getFallbackModels(config.model);
+		}
+	}
+
+	try {
+		const response = await fetch(buildModelsUrl(config.baseUrl), {
+			headers: buildLlmRequestHeaders(config.apiKey),
+		});
+
+		if (!response.ok) {
+			return getFallbackModels(config.model);
+		}
+
+		const body = (await response.json()) as ProviderModelsResponse;
+		const models = normalizeProviderModels(body, config.model);
+		modelCache = { key: cacheKey, models, fetchedAt: Date.now() };
+		return models;
+	} catch {
+		return getFallbackModels(config.model);
+	}
+}
+
+export function normalizeProviderModels(
+	body: ProviderModelsResponse,
+	defaultModel: string,
+): string[] {
+	const ids = (body.data ?? [])
+		.map((entry) => entry.id?.trim())
+		.filter((id): id is string => Boolean(id))
+		.filter(isChatModel);
+
+	return mergeModels(defaultModel, ids);
+}
+
+export function isChatModel(modelId: string): boolean {
+	return !EXCLUDED_MODEL_PATTERNS.some((pattern) => pattern.test(modelId));
+}
+
+export function mergeModels(defaultModel: string, models: string[]): string[] {
+	return [...new Set([defaultModel, ...models])].sort((a, b) =>
+		a.localeCompare(b),
+	);
+}
+
+export function clearProviderModelCache() {
+	modelCache = null;
+}

package/src/core/llm-provider.ts

@@ -0,0 +1,99 @@
+import {
+	buildCompletionsUrl,
+	buildLlmRequestHeaders,
+	DEFAULT_LLM_BASE_URL,
+	DEFAULT_LLM_MODEL,
+	isLocalLlmBaseUrl,
+	type ResolvedLlmSettings,
+} from "./llm-config.ts";
+import type { AssistantLlmConfig, AssistantLlmSettings } from "./types.ts";
+
+const DISABLED_SETTINGS: ResolvedLlmSettings = {
+	enabled: false,
+	baseUrl: DEFAULT_LLM_BASE_URL,
+	apiKey: null,
+	model: DEFAULT_LLM_MODEL,
+};
+
+let resolveSettings: (() => Promise<ResolvedLlmSettings>) | null = null;
+
+function normalizeSettings(input: AssistantLlmSettings): ResolvedLlmSettings {
+	return {
+		enabled: input.enabled,
+		baseUrl: input.baseUrl?.trim() || DEFAULT_LLM_BASE_URL,
+		apiKey: input.apiKey?.trim() || null,
+		model: input.model?.trim() || DEFAULT_LLM_MODEL,
+		models: input.models?.length ? [...input.models] : undefined,
+		systemPrompt: input.systemPrompt?.trim() || undefined,
+	};
+}
+
+export function configureAssistantLlm(config: AssistantLlmConfig) {
+	if (typeof config === "function") {
+		resolveSettings = async () => normalizeSettings(await config());
+		return;
+	}
+
+	const settings = normalizeSettings(config);
+	resolveSettings = async () => settings;
+}
+
+export async function resolveAssistantLlmSettings(): Promise<ResolvedLlmSettings> {
+	if (!resolveSettings) return DISABLED_SETTINGS;
+	return resolveSettings();
+}
+
+export function resetAssistantLlm() {
+	resolveSettings = null;
+}
+
+export async function testLlmConnection(
+	settings: Pick<ResolvedLlmSettings, "baseUrl" | "apiKey" | "model">,
+): Promise<{ ok: true; model: string } | { ok: false; error: string }> {
+	if (!settings.apiKey?.trim() && !isLocalLlmBaseUrl(settings.baseUrl)) {
+		return {
+			ok: false,
+			error: "API key is required for remote LLM providers.",
+		};
+	}
+
+	try {
+		const response = await fetch(buildCompletionsUrl(settings.baseUrl), {
+			method: "POST",
+			headers: buildLlmRequestHeaders(settings.apiKey),
+			body: JSON.stringify({
+				model: settings.model,
+				messages: [{ role: "user", content: "ping" }],
+				max_tokens: 1,
+			}),
+		});
+
+		if (!response.ok) {
+			const raw = await response.text();
+			let message = `Connection failed (${response.status})`;
+			try {
+				const body = JSON.parse(raw) as {
+					error?: { message?: string } | string;
+					message?: string;
+				};
+				if (typeof body.error === "string") message = body.error;
+				else if (typeof body.error?.message === "string") {
+					message = body.error.message;
+				} else if (typeof body.message === "string") {
+					message = body.message;
+				}
+			} catch {
+				if (raw.trim()) message = raw.trim();
+			}
+			return { ok: false, error: message };
+		}
+
+		const body = (await response.json()) as { model?: string };
+		return { ok: true, model: body.model ?? settings.model };
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : "Connection failed",
+		};
+	}
+}

package/src/core/llm-settings-storage.ts

@@ -0,0 +1,331 @@
+import {
+	DEFAULT_ASSISTANT_SYSTEM_PROMPT,
+	DEFAULT_LLM_BASE_URL,
+	DEFAULT_LLM_MODEL,
+	isLlmConfigured,
+} from "./llm-config.ts";
+import type { AssistantLlmSettings } from "./types.ts";
+
+export const DEFAULT_LLM_SETTINGS_STORAGE_KEY = "assistant-llm-settings";
+
+/** Full LLM configuration persisted in localStorage */
+export interface StoredLlmUserSettings {
+	baseUrl: string;
+	apiKey: string | null;
+	model: string;
+	models: string[];
+	systemPrompt: string;
+}
+
+export interface LlmSettingsFormValues {
+	baseUrl: string;
+	apiKey: string;
+	model: string;
+	modelsText: string;
+	systemPrompt: string;
+}
+
+export type LlmSettingsFormState = LlmSettingsFormValues & {
+	hasStoredApiKey: boolean;
+	defaultSystemPrompt: string;
+};
+
+export function buildDefaultLlmSettings(): AssistantLlmSettings {
+	return {
+		enabled: false,
+		baseUrl: DEFAULT_LLM_BASE_URL,
+		apiKey: null,
+		model: DEFAULT_LLM_MODEL,
+	};
+}
+
+export function assistantToStored(
+	settings: AssistantLlmSettings,
+): StoredLlmUserSettings {
+	return {
+		baseUrl: settings.baseUrl?.trim() || DEFAULT_LLM_BASE_URL,
+		apiKey: settings.apiKey?.trim() || null,
+		model: settings.model?.trim() || DEFAULT_LLM_MODEL,
+		models: settings.models?.length ? [...settings.models] : [],
+		systemPrompt: settings.systemPrompt ?? "",
+	};
+}
+
+export function storedToAssistant(
+	stored: StoredLlmUserSettings,
+): AssistantLlmSettings {
+	const baseUrl = stored.baseUrl;
+	const apiKey = stored.apiKey;
+	const model = stored.model;
+	return {
+		enabled: isLlmConfigured({
+			enabled: true,
+			baseUrl,
+			apiKey,
+			model,
+		}),
+		baseUrl,
+		apiKey,
+		model,
+		models: stored.models.length > 0 ? stored.models : undefined,
+		systemPrompt: stored.systemPrompt || undefined,
+	};
+}
+
+/** Normalize legacy/partial stored payloads against env defaults */
+export function normalizeStoredSettings(
+	raw: unknown,
+	base: AssistantLlmSettings,
+): StoredLlmUserSettings | null {
+	if (!raw || typeof raw !== "object") return null;
+
+	const partial = raw as Partial<StoredLlmUserSettings>;
+	const baseStored = assistantToStored(base);
+
+	return {
+		baseUrl:
+			typeof partial.baseUrl === "string" && partial.baseUrl.trim()
+				? partial.baseUrl.trim()
+				: baseStored.baseUrl,
+		apiKey:
+			typeof partial.apiKey === "string"
+				? partial.apiKey.trim() || null
+				: partial.apiKey === null
+					? null
+					: baseStored.apiKey,
+		model:
+			typeof partial.model === "string" && partial.model.trim()
+				? partial.model.trim()
+				: baseStored.model,
+		models: Array.isArray(partial.models)
+			? partial.models
+					.filter((entry): entry is string => typeof entry === "string")
+					.map((entry) => entry.trim())
+					.filter(Boolean)
+			: baseStored.models,
+		systemPrompt:
+			typeof partial.systemPrompt === "string"
+				? partial.systemPrompt
+				: baseStored.systemPrompt,
+	};
+}
+
+export function normalizeStoredSystemPrompt(
+	storedPrompt: string,
+	base: AssistantLlmSettings,
+): string {
+	const trimmed = storedPrompt.trim();
+	if (!trimmed) return "";
+	const basePrompt = base.systemPrompt?.trim() ?? "";
+	return trimmed === basePrompt ? "" : trimmed;
+}
+
+export function createDefaultStoredSettings(
+	base: AssistantLlmSettings,
+): StoredLlmUserSettings {
+	return {
+		baseUrl: base.baseUrl?.trim() || DEFAULT_LLM_BASE_URL,
+		apiKey: base.apiKey?.trim() || null,
+		model: base.model?.trim() || DEFAULT_LLM_MODEL,
+		models: base.models?.length ? [...base.models] : [],
+		systemPrompt: "",
+	};
+}
+
+export function storedSettingsHaveOverrides(
+	stored: StoredLlmUserSettings,
+	base: AssistantLlmSettings,
+): boolean {
+	const normalized = {
+		...stored,
+		systemPrompt: normalizeStoredSystemPrompt(stored.systemPrompt, base),
+	};
+	return (
+		JSON.stringify(normalized) !==
+		JSON.stringify(createDefaultStoredSettings(base))
+	);
+}
+
+export function mergeLlmSettings(
+	base: AssistantLlmSettings,
+	stored: StoredLlmUserSettings | null,
+): AssistantLlmSettings {
+	if (!stored) return base;
+	const merged = storedToAssistant(stored);
+	return {
+		...merged,
+		systemPrompt: merged.systemPrompt?.trim() || base.systemPrompt,
+		models: merged.models?.length ? merged.models : base.models,
+	};
+}
+
+export function isLlmSettingsFormDirty(
+	current: LlmSettingsFormValues,
+	saved: LlmSettingsFormValues,
+): boolean {
+	return (
+		current.baseUrl !== saved.baseUrl ||
+		current.apiKey !== saved.apiKey ||
+		current.model !== saved.model ||
+		current.modelsText !== saved.modelsText ||
+		current.systemPrompt !== saved.systemPrompt
+	);
+}
+
+export function resolveSelectedModel(
+	storedModel: string,
+	defaultModel: string,
+	availableModels: string[],
+): string {
+	const preferred = storedModel.trim();
+	if (preferred) return preferred;
+	if (availableModels.includes(defaultModel)) return defaultModel;
+	return availableModels[0] ?? defaultModel;
+}
+
+export function peekStoredModel(storageKey: string): string | null {
+	try {
+		const raw = localStorage.getItem(storageKey);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw) as Partial<StoredLlmUserSettings>;
+		const model = typeof parsed.model === "string" ? parsed.model.trim() : "";
+		return model || null;
+	} catch {
+		return null;
+	}
+}
+
+export function persistStoredModelSelection(
+	storageKey: string,
+	model: string,
+): void {
+	const trimmed = model.trim();
+	if (!trimmed) return;
+
+	try {
+		const raw = localStorage.getItem(storageKey);
+		if (!raw) return;
+		const parsed = JSON.parse(raw) as Partial<StoredLlmUserSettings>;
+		if (!parsed || typeof parsed !== "object") return;
+		localStorage.setItem(
+			storageKey,
+			JSON.stringify({ ...parsed, model: trimmed }),
+		);
+	} catch {
+		// ignore corrupt storage payloads
+	}
+}
+
+const LEGACY_MODEL_STORAGE_KEYS = [
+	"assistant-llm-model",
+	"4d-llm-model",
+] as const;
+
+export function migrateLegacyModelStorage(
+	llmSettingsKey: string,
+	legacyModelKey: string | undefined,
+	base: AssistantLlmSettings,
+): void {
+	const legacyKeys = [
+		...(legacyModelKey ? [legacyModelKey] : []),
+		...LEGACY_MODEL_STORAGE_KEYS,
+	];
+
+	for (const key of legacyKeys) {
+		const legacyModel = localStorage.getItem(key)?.trim();
+		if (!legacyModel) continue;
+
+		const storage = createLlmSettingsStorage(llmSettingsKey);
+		const stored = storage.load(base) ?? createDefaultStoredSettings(base);
+		storage.save({ ...stored, model: legacyModel });
+		localStorage.removeItem(key);
+		break;
+	}
+}
+
+export function parseModelsText(text: string): string[] {
+	return [
+		...new Set(
+			text
+				.split(/[\n,]/)
+				.map((entry) => entry.trim())
+				.filter(Boolean),
+		),
+	];
+}
+
+export function formatModelsText(models: string[] | undefined): string {
+	return models?.join(", ") ?? "";
+}
+
+export function createLlmSettingsStorage(storageKey: string) {
+	return {
+		load(base: AssistantLlmSettings): StoredLlmUserSettings | null {
+			try {
+				const raw = localStorage.getItem(storageKey);
+				if (!raw) return null;
+				return normalizeStoredSettings(JSON.parse(raw) as unknown, base);
+			} catch {
+				return null;
+			}
+		},
+
+		save(settings: StoredLlmUserSettings) {
+			localStorage.setItem(storageKey, JSON.stringify(settings));
+		},
+
+		clear() {
+			localStorage.removeItem(storageKey);
+		},
+
+		hasStored(): boolean {
+			return localStorage.getItem(storageKey) !== null;
+		},
+	};
+}
+
+export function toStoredSettings(
+	values: LlmSettingsFormValues,
+	existingApiKey: string | null,
+): StoredLlmUserSettings {
+	const apiKeyInput = values.apiKey.trim();
+
+	return {
+		baseUrl: values.baseUrl.trim() || DEFAULT_LLM_BASE_URL,
+		apiKey: apiKeyInput.length > 0 ? apiKeyInput : existingApiKey,
+		model: values.model.trim() || DEFAULT_LLM_MODEL,
+		models: parseModelsText(values.modelsText),
+		systemPrompt: values.systemPrompt,
+	};
+}
+
+export function createLlmSettingsFormState(
+	settings: AssistantLlmSettings,
+	hasStoredApiKey: boolean,
+	defaultSystemPrompt = DEFAULT_ASSISTANT_SYSTEM_PROMPT,
+): LlmSettingsFormState {
+	return {
+		baseUrl: settings.baseUrl,
+		apiKey: "",
+		model: settings.model,
+		modelsText: formatModelsText(settings.models),
+		systemPrompt: settings.systemPrompt ?? "",
+		hasStoredApiKey,
+		defaultSystemPrompt,
+	};
+}
+
+export function createLlmSettingsFormStateFromStored(
+	stored: StoredLlmUserSettings,
+	defaultSystemPrompt = DEFAULT_ASSISTANT_SYSTEM_PROMPT,
+): LlmSettingsFormState {
+	return {
+		baseUrl: stored.baseUrl,
+		apiKey: "",
+		model: stored.model,
+		modelsText: formatModelsText(stored.models),
+		systemPrompt: stored.systemPrompt,
+		hasStoredApiKey: Boolean(stored.apiKey),
+		defaultSystemPrompt,
+	};
+}