feat(sdk): add embed() and embedMany() support across providers and s…

CLAUDE.md

@@ -369,6 +369,29 @@ When changing how messages are constructed:
 4. Add tests for new message types
 5. Update type definitions in `src/lib/types/conversation.ts`
 
+### Embeddings
+
+Providers expose `embed()` and `embedMany()` methods for generating vector embeddings. The `AIProvider` type interface includes both methods; unsupported providers throw descriptive errors.
+
+**Supported providers and defaults:**
+
+| Provider         | Default Model                  | Env Override                |
+| ---------------- | ------------------------------ | --------------------------- |
+| OpenAI           | `text-embedding-3-small`       | —                           |
+| Google AI Studio | `gemini-embedding-001`         | `GOOGLE_AI_EMBEDDING_MODEL` |
+| Google Vertex    | `text-embedding-004`           | `VERTEX_EMBEDDING_MODEL`    |
+| Amazon Bedrock   | `amazon.titan-embed-text-v2:0` | —                           |
+
+**Server routes:** `POST /api/agent/embed` (single) and `POST /api/agent/embed-many` (batch) in `src/lib/server/routes/agentRoutes.ts`.
+
+**Key files:**
+
+- `src/lib/core/baseProvider.ts` — Base `embed()` / `embedMany()` stubs
+- `src/lib/types/providers.ts` — `AIProvider` type with embedding methods
+- `src/lib/server/routes/agentRoutes.ts` — Server embedding endpoints
+- `src/lib/server/utils/validation.ts` — `EmbedRequestSchema` / `EmbedManyRequestSchema`
+- `src/lib/server/types.ts` — `EmbedRequest`, `EmbedResponse`, `EmbedManyRequest`, `EmbedManyResponse`
+
 ### Working with Multimodal Content
 
 **For images:**

docs/advanced/api-reference.md

@@ -22,6 +22,63 @@ POST /api/stream
 GET /api/status
 ```
 
+## Embeddings
+
+### Generate Embedding
+
+```http
+POST /api/agent/embed
+```
+
+**Request body:**
+
+```json
+{
+  "text": "Hello world",
+  "provider": "googleAiStudio",
+  "model": "gemini-embedding-001"
+}
+```
+
+**Response:**
+
+```json
+{
+  "embedding": [0.123, -0.456, ...],
+  "provider": "googleAiStudio",
+  "model": "gemini-embedding-001",
+  "dimension": 768
+}
+```
+
+### Generate Batch Embeddings
+
+```http
+POST /api/agent/embed-many
+```
+
+**Request body:**
+
+```json
+{
+  "texts": ["First document", "Second document", "Third document"],
+  "provider": "openai",
+  "model": "text-embedding-3-small"
+}
+```
+
+**Response:**
+
+```json
+{
+  "embeddings": [[0.123, -0.456, ...], [0.789, -0.012, ...], [0.345, -0.678, ...]],
+  "provider": "openai",
+  "model": "text-embedding-3-small",
+  "count": 3,
+  "dimension": 1536
+}
+```
+
 ## MCP Integration
 
 ### List MCP Tools

docs/api/type-aliases/AIProvider.md

@@ -80,6 +80,50 @@ Defined in: [types/providers.ts:308](https://github.com/juspay/neurolink/blob/1b
 
 ---
 
+### embed()
+
+> **embed**(`text`, `modelName?`): `Promise`\<`number[]`\>
+
+Generate an embedding vector for a single text. Throws if the provider does not support embeddings.
+
+#### Parameters
+
+##### text
+
+`string`
+
+##### modelName?
+
+`string`
+
+#### Returns
+
+`Promise`\<`number[]`\>
+
+---
+
+### embedMany()
+
+> **embedMany**(`texts`, `modelName?`): `Promise`\<`number[][]`\>
+
+Generate embedding vectors for multiple texts in a single batch. The AI SDK automatically handles chunking for models with batch limits.
+
+#### Parameters
+
+##### texts
+
+`string[]`
+
+##### modelName?
+
+`string`
+
+#### Returns
+
+`Promise`\<`number[][]`\>
+
+---
+
 ### setupToolExecutor()
 
 > **setupToolExecutor**(`sdk`, `functionTag`): `void`

docs/guides/server-adapters/index.md

@@ -147,11 +147,13 @@ All server adapters expose the same REST API endpoints:
 
 ### Agent Operations
 
-| Endpoint               | Method | Description                            |
-| ---------------------- | ------ | -------------------------------------- |
-| `/api/agent/execute`   | POST   | Execute agent and return full response |
-| `/api/agent/stream`    | POST   | Stream agent response via SSE          |
-| `/api/agent/providers` | GET    | List available AI providers            |
+| Endpoint                | Method | Description                                  |
+| ----------------------- | ------ | -------------------------------------------- |
+| `/api/agent/execute`    | POST   | Execute agent and return full response       |
+| `/api/agent/stream`     | POST   | Stream agent response via SSE                |
+| `/api/agent/providers`  | GET    | List available AI providers                  |
+| `/api/agent/embed`      | POST   | Generate embedding for a single text         |
+| `/api/agent/embed-many` | POST   | Generate embeddings for multiple texts batch |
 
 ### Tool Operations
 
@@ -433,6 +435,59 @@ data: {"type":"text-end","timestamp":1706745600100}
 data: {"type":"finish","usage":{"inputTokens":5,"outputTokens":50,"totalTokens":55}}
 ```
 
+### Generate Embedding
+
+**Request:**
+
+```json
+POST /api/agent/embed
+Content-Type: application/json
+
+{
+  "text": "What is the meaning of life?",
+  "provider": "openai",
+  "model": "text-embedding-3-small"
+}
+```
+
+**Response:**
+
+```json
+{
+  "embedding": [0.123, -0.456, 0.789, ...],
+  "provider": "openai",
+  "model": "text-embedding-3-small",
+  "dimension": 1536
+}
+```
+
+### Generate Batch Embeddings
+
+**Request:**
+
+```json
+POST /api/agent/embed-many
+Content-Type: application/json
+
+{
+  "texts": ["First document", "Second document"],
+  "provider": "googleAiStudio",
+  "model": "gemini-embedding-001"
+}
+```
+
+**Response:**
+
+```json
+{
+  "embeddings": [[0.123, -0.456, ...], [0.789, -0.012, ...]],
+  "provider": "googleAiStudio",
+  "model": "gemini-embedding-001",
+  "count": 2,
+  "dimension": 768
+}
+```
+
 ---
 
 ## Production Deployment

docs/sdk/api-reference.md

@@ -454,6 +454,47 @@ const result = await neurolink.gen({
 
 ---
 
+### Embeddings
+
+Generate embeddings directly via the provider's `embed()` and `embedMany()` methods.
+
+#### `provider.embed(text, modelName?)`
+
+Generate an embedding vector for a single text.
+
+```typescript
+import { ProviderFactory } from "@juspay/neurolink";
+
+const provider = await ProviderFactory.createProvider("googleAiStudio");
+const embedding = await provider.embed("Hello world");
+// embedding: number[] (e.g., 768 dimensions)
+```
+
+#### `provider.embedMany(texts, modelName?)`
+
+Generate embedding vectors for multiple texts in a single batch. The AI SDK automatically handles chunking for models with batch limits.
+
+```typescript
+const provider = await ProviderFactory.createProvider("openai");
+const embeddings = await provider.embedMany([
+  "First document",
+  "Second document",
+  "Third document",
+]);
+// embeddings: number[][] (e.g., 3 × 1536 dimensions)
+```
+
+**Supported providers and default models:**
+
+| Provider         | Default Embedding Model        | Env Override                |
+| ---------------- | ------------------------------ | --------------------------- |
+| OpenAI           | `text-embedding-3-small`       | —                           |
+| Google AI Studio | `gemini-embedding-001`         | `GOOGLE_AI_EMBEDDING_MODEL` |
+| Google Vertex    | `text-embedding-004`           | `VERTEX_EMBEDDING_MODEL`    |
+| Amazon Bedrock   | `amazon.titan-embed-text-v2:0` | —                           |
+
+---
+
 ### RAG Integration
 
 Pass `rag: { files: [...] }` to `generate()` or `stream()` for automatic RAG pipeline setup:

src/lib/core/baseProvider.ts

@@ -674,14 +674,14 @@
    * IMPLEMENTATION NOTE: Uses streamText() under the hood and accumulates results
    * for consistency and better performance
    */
   async generate(
     optionsOrPrompt: TextGenerationOptions | string,
     _analysisSchema?: ValidationSchema,
   ): Promise<EnhancedGenerateResult | null> {
     return providerTracer.startActiveSpan(
       "neurolink.provider.generate",
       { kind: SpanKind.INTERNAL },
       async (span) => {
         const options = this.normalizeTextOptions(optionsOrPrompt);
         this.validateOptions(options);
         const startTime = Date.now();
@@ -1081,6 +1081,33 @@
     );
   }
 
+  /**
+   * Generate embeddings for multiple texts in a single batch
+   *
+   * This is a default implementation that throws an error.
+   * Providers that support embeddings should override this method.
+   * The AI SDK's embedMany automatically handles chunking for models with batch limits.
+   *
+   * @param texts - The texts to embed
+   * @param _modelName - Optional embedding model name (provider-specific)
+   * @returns Promise resolving to an array of embedding vectors
+   * @throws Error if the provider does not support embeddings
+   */
+  async embedMany(texts: string[], _modelName?: string): Promise<number[][]> {
+    logger.warn(
+      `embedMany() called on ${this.providerName} which does not have a native implementation`,
+      {
+        count: texts.length,
+      },
+    );
+    throw new Error(
+      `Batch embedding generation is not supported by the ${this.providerName} provider. ` +
+        `Supported providers: openai, googleAiStudio, vertex/google, bedrock. ` +
+        `Use an embedding model like text-embedding-3-small (OpenAI), gemini-embedding-001 (Google AI), ` +
+        `text-embedding-004 (Vertex), or amazon.titan-embed-text-v2:0 (Bedrock).`,
+    );
+  }
+
   /**
    * Get the default embedding model for this provider
    *

src/lib/providers/amazonBedrock.ts

@@ -2099,4 +2099,43 @@ export class AmazonBedrockProvider extends BaseProvider {
       throw this.handleProviderError(error);
     }
   }
+
+  /**
+   * Generate embeddings for multiple texts in a single batch
+   * @param texts - The texts to embed
+   * @param modelName - The embedding model to use (default: amazon.titan-embed-text-v2:0)
+   * @returns Promise resolving to an array of embedding vectors
+   */
+  async embedMany(texts: string[], modelName?: string): Promise<number[][]> {
+    const embeddingModelName = modelName || "amazon.titan-embed-text-v2:0";
+
+    logger.debug("Generating batch embeddings", {
+      provider: this.providerName,
+      model: embeddingModelName,
+      count: texts.length,
+    });
+
+    try {
+      const embeddings = await Promise.all(
+        texts.map((text) => this.embed(text, embeddingModelName)),
+      );
+
+      logger.debug("Batch embeddings generated successfully", {
+        provider: this.providerName,
+        model: embeddingModelName,
+        count: embeddings.length,
+        embeddingDimension: embeddings[0]?.length,
+      });
+
+      return embeddings;
+    } catch (error) {
+      logger.error("Batch embedding generation failed", {
+        error: error instanceof Error ? error.message : String(error),
+        model: embeddingModelName,
+        count: texts.length,
+      });
+
+      throw this.handleProviderError(error);
+    }
+  }
 }