refactor: move embedding interface to spec contracts, add settings tests

Author: os-zhuang

packages/plugins/knowledge-turso/src/embedding.ts

@@ -1,112 +1,47 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Pluggable embedding provider for the Turso knowledge adapter.
+ * Embedding helpers for the Turso knowledge adapter.
  *
- * Adapters call `embed()` once with the full batch of chunk texts at
- * upsert time, and once per query at search time. Implementations are
- * responsible for batching / rate-limiting against their upstream API.
+ * The interface itself now lives in `@objectstack/spec/contracts` as
+ * `IEmbedder` — see that file for the protocol-level contract.
+ *
+ * This module ships ONLY the deterministic `HashEmbedder` used for
+ * tests and offline dev. For real models, install a dedicated
+ * embedder plugin:
+ *
+ *   - `@objectstack/embedder-openai`      (OpenAI / 阿里通义 / 智谱 /
+ *                                          硅基流动 / 火山 Doubao /
+ *                                          MiniMax / Ollama / 任何
+ *                                          OpenAI-shape 兼容端点)
+ *
+ * Migrating from `@objectstack/knowledge-turso` ≤ 6.6:
+ *   - `EmbeddingProvider`         → `IEmbedder` (`@objectstack/spec/contracts`)
+ *   - `OpenAIEmbeddingProvider`   → `OpenAIEmbedder` (`@objectstack/embedder-openai`)
+ *   - `HashEmbeddingProvider`     → `HashEmbedder` (this file, unchanged behaviour)
  */
-export interface EmbeddingProvider {
-  /** Stable id (mostly for logs). */
-  readonly id: string;
-  /** Output vector dimensionality — used to size the `F32_BLOB(N)` column. */
-  readonly dimensions: number;
-  /** Embed a batch of strings. Output order matches input order. */
-  embed(texts: string[]): Promise<number[][]>;
-}
 
-export interface OpenAIEmbeddingOptions {
-  apiKey: string;
-  /** @default 'text-embedding-3-small' */
-  model?: string;
-  /** Override dimensions (only some models support this). */
-  dimensions?: number;
-  /** Override base URL (Azure / proxy / Ollama-compatible servers). */
-  baseUrl?: string;
-  /** Inject for tests. Defaults to global fetch. */
-  fetch?: typeof fetch;
-}
+import type { IEmbedder } from '@objectstack/spec/contracts';
 
 /**
- * Known dimensions for OpenAI's first-party embedding models. Used as
- * the default when the caller doesn't pass `dimensions` explicitly.
+ * @deprecated Use `IEmbedder` from `@objectstack/spec/contracts`.
+ * Re-exported here as an alias to ease migration; will be removed in
+ * a future major.
  */
-const OPENAI_DEFAULT_DIMS: Record<string, number> = {
-  'text-embedding-3-small': 1536,
-  'text-embedding-3-large': 3072,
-  'text-embedding-ada-002': 1536,
-};
-
-/**
- * OpenAI-compatible embedding provider. Works against the real OpenAI
- * API, Azure OpenAI deployments, and any drop-in compatible server
- * (LiteLLM, vLLM, Ollama with the openai shim).
- */
-export class OpenAIEmbeddingProvider implements EmbeddingProvider {
-  readonly id = 'openai';
-  readonly dimensions: number;
-  private readonly model: string;
-  private readonly baseUrl: string;
-  private readonly apiKey: string;
-  private readonly fetchImpl: typeof fetch;
-  private readonly requestedDims?: number;
-
-  constructor(opts: OpenAIEmbeddingOptions) {
-    if (!opts.apiKey) throw new Error('OpenAIEmbeddingProvider: apiKey required');
-    this.apiKey = opts.apiKey;
-    this.model = opts.model ?? 'text-embedding-3-small';
-    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\/+$/, '');
-    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);
-    this.requestedDims = opts.dimensions;
-    this.dimensions =
-      opts.dimensions ?? OPENAI_DEFAULT_DIMS[this.model] ?? 1536;
-    if (!this.fetchImpl) {
-      throw new Error('OpenAIEmbeddingProvider: no fetch available; pass options.fetch');
-    }
-  }
-
-  async embed(texts: string[]): Promise<number[][]> {
-    if (texts.length === 0) return [];
-    const body: Record<string, unknown> = { model: this.model, input: texts };
-    if (this.requestedDims) body.dimensions = this.requestedDims;
-    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      throw new Error(
-        `OpenAI embeddings → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,
-      );
-    }
-    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };
-    const data = json.data ?? [];
-    if (data.length !== texts.length) {
-      throw new Error(
-        `OpenAI embeddings: expected ${texts.length} vectors, got ${data.length}`,
-      );
-    }
-    return data.map((d) => d.embedding);
-  }
-}
+export type EmbeddingProvider = IEmbedder;
 
 /**
- * Deterministic, dependency-free embedding provider for unit tests
- * and offline development. Hashes tokens into a fixed-width vector —
- * not semantically meaningful, but cosine-distance preserves token
+ * Deterministic, dependency-free embedder for unit tests and offline
+ * development. Hashes tokens into a fixed-width vector — not
+ * semantically meaningful, but cosine-distance preserves token
  * overlap, which is enough to validate adapter plumbing.
  */
-export class HashEmbeddingProvider implements EmbeddingProvider {
+export class HashEmbedder implements IEmbedder {
   readonly id = 'hash';
   readonly dimensions: number;
 
   constructor(dimensions = 64) {
-    if (dimensions < 4) throw new Error('HashEmbeddingProvider: dimensions must be >= 4');
+    if (dimensions < 4) throw new Error('HashEmbedder: dimensions must be >= 4');
     this.dimensions = dimensions;
   }
 
@@ -136,6 +71,9 @@ export class HashEmbeddingProvider implements EmbeddingProvider {
   }
 }
 
+/** @deprecated Renamed to {@link HashEmbedder}. */
+export const HashEmbeddingProvider = HashEmbedder;
+
 function fnv1a(s: string): number {
   let h = 0x811c9dc5;
   for (let i = 0; i < s.length; i++) {

packages/plugins/knowledge-turso/src/index.ts

@@ -10,20 +10,18 @@
  */
 
 import type { Plugin, PluginContext } from '@objectstack/core';
-import type { IKnowledgeService } from '@objectstack/spec/contracts';
+import type { IKnowledgeService, IEmbedder } from '@objectstack/spec/contracts';
 import { KNOWLEDGE_SERVICE } from '@objectstack/spec/contracts';
 import { createClient, type Client } from '@libsql/client';
 
 import { TursoKnowledgeAdapter, type TursoAdapterOptions } from './turso-adapter';
-import type { EmbeddingProvider } from './embedding';
 
 export { TursoKnowledgeAdapter } from './turso-adapter';
 export type { TursoAdapterOptions } from './turso-adapter';
 export {
+  HashEmbedder,
   HashEmbeddingProvider,
-  OpenAIEmbeddingProvider,
   type EmbeddingProvider,
-  type OpenAIEmbeddingOptions,
 } from './embedding';
 
 export interface KnowledgeTursoPluginOptions {
@@ -38,8 +36,16 @@ export interface KnowledgeTursoPluginOptions {
   url?: string;
   authToken?: string;
   client?: Client;
-  /** Embedding provider — required. */
-  embedding: EmbeddingProvider;
+  /**
+   * Embedder used for both upsert and search.
+   *
+   * For real models, install a dedicated plugin and pass its instance:
+   *   - `@objectstack/embedder-openai` (OpenAI / 阿里通义 / 智谱 /
+   *     硅基流动 / 火山 Doubao / Ollama / 任何 OpenAI-shape 兼容端点)
+   *
+   * For tests / smoke runs, use the bundled `HashEmbedder`.
+   */
+  embedding: IEmbedder;
   /** Forwarded to the adapter. */
   chunkTarget?: TursoAdapterOptions['chunkTarget'];
   /** Forwarded to the adapter. */

packages/plugins/knowledge-turso/src/turso-adapter.ts

@@ -5,21 +5,21 @@ import type {
   IKnowledgeAdapter,
   AdapterContext,
   AdapterSearchOptions,
+  IEmbedder,
 } from '@objectstack/spec/contracts';
 import type {
   KnowledgeDocument,
   KnowledgeHit,
   KnowledgeSource,
 } from '@objectstack/spec/ai';
-import type { EmbeddingProvider } from './embedding';
 
 export interface TursoAdapterOptions {
   /** Stable adapter id used in `KnowledgeSource.adapter`. @default 'turso' */
   id?: string;
   /** libsql client (Turso cloud, embedded replica, file, or `:memory:`). */
   client: Client;
   /** Embedding provider used for both upsert and search. */
-  embedder: EmbeddingProvider;
+  embedder: IEmbedder;
   /** Soft cap on chunk size, in characters. @default 800 */
   chunkTarget?: number;
   /**
@@ -67,7 +67,7 @@ const DEFAULT_OVER_FETCH = 4;
 export class TursoKnowledgeAdapter implements IKnowledgeAdapter {
   readonly id: string;
   private readonly client: Client;
-  private readonly embedder: EmbeddingProvider;
+  private readonly embedder: IEmbedder;
   private readonly chunkTarget: number;
   private readonly overFetch: number;
   private readonly ready = new Map<string, Promise<{ table: string; dimensions: number }>>();

packages/services/service-ai/src/__tests__/ai-service.test.ts

@@ -1093,4 +1093,107 @@ describe('AIServicePlugin', () => {
       process.env = oldEnv;
     }
   });
+
+  // ── settings binding ─────────────────────────────────────────────
+  describe('settings binding', () => {
+    function createCtxWithSettings(settings: any) {
+      const ctx = createMockContext();
+      // expose settings via the same getService mock
+      (ctx as any).getServices().set('settings', settings);
+      return ctx;
+    }
+
+    it('AIService.setAdapter swaps the active adapter', () => {
+      const a: LLMAdapter = { name: 'a', chat: async () => ({ content: 'a' }), complete: async () => ({ content: '' }) };
+      const b: LLMAdapter = { name: 'b', chat: async () => ({ content: 'b' }), complete: async () => ({ content: '' }) };
+      const svc = new AIService({ adapter: a, logger: silentLogger });
+      expect(svc.adapterName).toBe('a');
+      svc.setAdapter(b);
+      expect(svc.adapterName).toBe('b');
+    });
+
+    it('does not bind to settings when bindToSettings=false', async () => {
+      const settings = {
+        getNamespace: vi.fn(),
+        subscribe: vi.fn(),
+        registerAction: vi.fn(),
+      };
+      const plugin = new AIServicePlugin({ bindToSettings: false });
+      const ctx = createCtxWithSettings(settings);
+      await plugin.init(ctx);
+      await plugin.start!(ctx);
+      // No kernel:ready hook registered for settings binding
+      const kernelReadyHooks = (ctx.hook as any).mock.calls.filter(([n]: any[]) => n === 'kernel:ready');
+      expect(kernelReadyHooks.length).toBe(0);
+    });
+
+    it('binds to settings, applies values, subscribes, and registers live test action', async () => {
+      const customAdapter: LLMAdapter = {
+        name: 'preset', chat: async () => ({ content: 'preset' }), complete: async () => ({ content: '' }),
+      };
+      const settings = {
+        getNamespace: vi.fn(async () => ({
+          manifest: { namespace: 'ai' },
+          values: { provider: { value: 'memory' } },
+        })),
+        subscribe: vi.fn(),
+        registerAction: vi.fn(),
+      };
+      const plugin = new AIServicePlugin({ adapter: customAdapter });
+      const ctx = createCtxWithSettings(settings);
+      await plugin.init(ctx);
+      await plugin.start!(ctx);
+
+      // Find and invoke the kernel:ready hook that does settings binding
+      const kernelReady = (ctx.hook as any).mock.calls.find(([n]: any[]) => n === 'kernel:ready');
+      expect(kernelReady).toBeDefined();
+      await kernelReady[1]();
+
+      expect(settings.getNamespace).toHaveBeenCalledWith('ai');
+      expect(settings.subscribe).toHaveBeenCalledWith('ai', expect.any(Function));
+      expect(settings.registerAction).toHaveBeenCalledWith('ai', 'test', expect.any(Function));
+
+      // memory provider is no-op overlay → original adapter retained
+      const svc = ctx.getService<AIService>('ai');
+      expect(svc.adapterName).toBe('preset');
+    });
+
+    it('live test action returns warning for memory provider', async () => {
+      const settings: any = {
+        getNamespace: vi.fn(async () => ({ manifest: { namespace: 'ai' }, values: {} })),
+        subscribe: vi.fn(),
+        registerAction: vi.fn(),
+      };
+      const plugin = new AIServicePlugin();
+      const ctx = createCtxWithSettings(settings);
+      await plugin.init(ctx);
+      await plugin.start!(ctx);
+      const kernelReady = (ctx.hook as any).mock.calls.find(([n]: any[]) => n === 'kernel:ready');
+      await kernelReady[1]();
+
+      const handler = settings.registerAction.mock.calls.find((c: any[]) => c[0] === 'ai' && c[1] === 'test')[2];
+      const result = await handler({ values: {}, payload: { values: { provider: 'memory' } } });
+      expect(result.ok).toBe(true);
+      expect(result.severity).toBe('warning');
+      expect(result.message).toContain('echo stub');
+    });
+
+    it('live test action reports missing api key for openai', async () => {
+      const settings: any = {
+        getNamespace: vi.fn(async () => ({ manifest: { namespace: 'ai' }, values: {} })),
+        subscribe: vi.fn(),
+        registerAction: vi.fn(),
+      };
+      const plugin = new AIServicePlugin();
+      const ctx = createCtxWithSettings(settings);
+      await plugin.init(ctx);
+      await plugin.start!(ctx);
+      const kernelReady = (ctx.hook as any).mock.calls.find(([n]: any[]) => n === 'kernel:ready');
+      await kernelReady[1]();
+      const handler = settings.registerAction.mock.calls.find((c: any[]) => c[0] === 'ai' && c[1] === 'test')[2];
+      const result = await handler({ values: {}, payload: { values: { provider: 'openai' } } });
+      expect(result.ok).toBe(false);
+      expect(result.severity).toBe('error');
+    });
+  });
 });