feat: extract IEmbedder protocol, add @objectstack/embedder-openai

Author: os-zhuang

.changeset/config.json

@@ -61,6 +61,7 @@
       "@objectstack/knowledge-memory",
       "@objectstack/knowledge-ragflow",
       "@objectstack/knowledge-turso",
+      "@objectstack/embedder-openai",
       "@objectstack/account",
       "create-objectstack",
       "objectstack-vscode"

.changeset/embedder-openai-protocol.md

@@ -0,0 +1,39 @@
+---
+'@objectstack/spec': minor
+'@objectstack/embedder-openai': minor
+'@objectstack/knowledge-turso': minor
+---
+
+Introduce `IEmbedder` protocol and extract `@objectstack/embedder-openai` plugin.
+
+**What's new**
+
+- **`IEmbedder` contract** (`@objectstack/spec/contracts/embedder.ts`) — protocol-level interface for text → vector providers. One contract covers cloud APIs (OpenAI / 阿里通义 / 智谱 / 硅基流动 / 火山 Doubao / MiniMax), local Ollama daemons, and in-process embedders.
+- **`@objectstack/embedder-openai`** — new package. Drop-in for any OpenAI-shape endpoint via `baseUrl`. Ships preset constants for 8 mainstream providers (`createOpenAIEmbedder({ preset: 'siliconflow', ... })`) and pre-baked dimensions for 16+ popular models.
+
+**Breaking changes (`@objectstack/knowledge-turso`)**
+
+- `OpenAIEmbeddingProvider` is **removed** — install `@objectstack/embedder-openai` and use `OpenAIEmbedder` instead (identical option shape).
+- `EmbeddingProvider` type alias kept as a deprecated re-export of `IEmbedder` for smoother migration; will be removed in a future major.
+- `HashEmbeddingProvider` is now an alias for the renamed `HashEmbedder` class — no functional change.
+
+**Migration**
+
+```diff
+- import { OpenAIEmbeddingProvider } from '@objectstack/knowledge-turso';
++ import { OpenAIEmbedder } from '@objectstack/embedder-openai';
+
+- const embedding = new OpenAIEmbeddingProvider({ apiKey });
++ const embedding = new OpenAIEmbedder({ apiKey });
+```
+
+For 国内 providers, use presets:
+
+```ts
+import { createOpenAIEmbedder } from '@objectstack/embedder-openai';
+const embedding = createOpenAIEmbedder({
+  preset: 'siliconflow',                 // or 'dashscope', 'zhipu', 'doubao', 'ollama', …
+  apiKey: process.env.SILICONFLOW_API_KEY!,
+  model: 'BAAI/bge-m3',
+});
+```

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — `IEmbedder` protocol + `@objectstack/embedder-openai` plugin
+
+Extracted text-→-vector providers into a dedicated, plugin-shaped layer:
+
+- **`IEmbedder`** contract added to `@objectstack/spec/contracts` —
+  protocol-level interface (`id`, `dimensions`, `embed(texts[])`).
+  One contract covers cloud APIs, local Ollama, and in-process embedders.
+- **`@objectstack/embedder-openai`** — new plugin package. Drop-in for
+  any OpenAI-shape endpoint via `baseUrl`. Ships preset constants for
+  8 mainstream providers (OpenAI, Azure, 阿里通义 DashScope, 智谱
+  BigModel, 硅基流动 SiliconFlow, 火山引擎 Doubao, MiniMax, Ollama)
+  and pre-baked default `dimensions` for 16+ popular models including
+  `text-embedding-v3`, `embedding-3`, `BAAI/bge-m3`, `nomic-embed-text`.
+
+```ts
+import { createOpenAIEmbedder } from '@objectstack/embedder-openai';
+const embedding = createOpenAIEmbedder({
+  preset: 'siliconflow',
+  apiKey: process.env.SILICONFLOW_API_KEY!,
+  model: 'BAAI/bge-m3',
+});
+```
+
+### Changed — `@objectstack/knowledge-turso` consumes `IEmbedder`
+
+`KnowledgeTursoPluginOptions.embedding` is now typed as `IEmbedder`
+(`@objectstack/spec/contracts`). The package no longer ships an
+OpenAI provider of its own — install `@objectstack/embedder-openai`.
+
+**Breaking:**
+- `OpenAIEmbeddingProvider` removed from `@objectstack/knowledge-turso`
+  exports. Replace with `OpenAIEmbedder` from `@objectstack/embedder-openai`.
+- `HashEmbeddingProvider` renamed to `HashEmbedder` (old name kept as a
+  deprecated alias).
+- `EmbeddingProvider` type kept as a deprecated alias for `IEmbedder`.
+
 ### Added — Runtime `services.*` API reference chapter
 
 Documentation now includes a dedicated `Runtime Services` guides chapter