concevent-ai-agent-sdk 3.2.1 → 3.2.2

package/README.md

@@ -22,6 +22,7 @@ A framework-agnostic AI Agent SDK for building intelligent conversational agents
 - 📋 **Structured Output** - JSON schema validation with Zod for type-safe responses
 - 🎭 **Multi-Agent Orchestration** - Route tasks to specialized sub-agents based on their capabilities
 - 📊 **Flow Visualization** - Automatic Mermaid sequence diagrams showing orchestration flow
+- 🔢 **Embeddings** - Generate text embeddings for semantic search and RAG applications
 
 ## Installation
 
@@ -106,6 +107,7 @@ console.log(result.message);
   - [Middleware](#middleware)
   - [Multi-Agent Orchestration](#multi-agent-orchestration)
   - [Orchestration Flow Diagrams](#orchestration-flow-diagrams)
+  - [Embeddings](#embeddings)
 
 ---
 
@@ -2206,6 +2208,148 @@ await writeFile("orchestration-flow.md", `\`\`\`mermaid\n${result.diagram}\n\`\`
 - **Special Character Escaping**: Characters that could break Mermaid syntax are safely escaped
 - **Activation Boxes**: Sub-agent calls show activation (`+`/`-`) to indicate processing time
 
+### Embeddings
+
+The SDK provides embedding generation support for semantic search and RAG (Retrieval Augmented Generation) use cases. This uses OpenRouter's OpenAI-compatible embedding endpoint.
+
+#### Single Embedding
+
+Generate an embedding vector for a single text input:
+
+```typescript
+import { createEmbedding } from "concevent-ai-agent-sdk";
+
+const result = await createEmbedding({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/text-embedding-3-large",
+  input: "Text to embed",
+  dimensions: 3072, // Optional: reduce dimensions
+});
+
+console.log(result.embedding); // number[] - the embedding vector
+console.log(result.model);     // Model used
+console.log(result.usage);     // { prompt_tokens, total_tokens }
+```
+
+#### Batch Embeddings
+
+Generate embeddings for multiple texts in a single request (more efficient):
+
+```typescript
+import { createEmbeddings } from "concevent-ai-agent-sdk";
+
+const result = await createEmbeddings({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/text-embedding-3-large",
+  inputs: ["Text 1", "Text 2", "Text 3"],
+  dimensions: 3072, // Optional
+});
+
+// Access embeddings by index
+result.embeddings.forEach(({ index, embedding }) => {
+  console.log(`Embedding ${index}:`, embedding.length, "dimensions");
+});
+```
+
+#### Configuration
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `apiKey` | `string` | ✅ | - | API key for authentication |
+| `model` | `string` | ✅ | - | Embedding model to use |
+| `input` | `string` | ✅ | - | Text to embed (single) |
+| `inputs` | `string[]` | ✅ | - | Texts to embed (batch) |
+| `baseURL` | `string` | ❌ | OpenRouter | API base URL |
+| `dimensions` | `number` | ❌ | Model default | Reduce embedding dimensions |
+
+#### Recommended Models
+
+| Model | Dimensions | Best For |
+|-------|-----------|----------|
+| `openai/text-embedding-3-large` | 3072 | Highest accuracy, multilingual |
+| `openai/text-embedding-3-small` | 1536 | Good balance of speed/accuracy |
+| `openai/text-embedding-ada-002` | 1536 | Legacy, widely compatible |
+
+#### Semantic Search Example
+
+```typescript
+import { createEmbedding, createEmbeddings } from "concevent-ai-agent-sdk";
+
+// 1. Build an index from your documents
+const chunks = ["Document chunk 1...", "Document chunk 2...", "Document chunk 3..."];
+const { embeddings } = await createEmbeddings({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/text-embedding-3-large",
+  inputs: chunks,
+});
+
+// Store embeddings with your chunks (in a vector database, etc.)
+const index = chunks.map((text, i) => ({
+  text,
+  embedding: embeddings.find((e) => e.index === i)!.embedding,
+}));
+
+// 2. Query with semantic search
+const { embedding: queryEmbedding } = await createEmbedding({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/text-embedding-3-large",
+  input: "User's search query",
+});
+
+// 3. Find most similar chunks (cosine similarity)
+function cosineSimilarity(a: number[], b: number[]): number {
+  const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
+  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
+  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
+  return dot / (magA * magB);
+}
+
+const results = index
+  .map((item) => ({
+    text: item.text,
+    score: cosineSimilarity(queryEmbedding, item.embedding),
+  }))
+  .sort((a, b) => b.score - a.score);
+
+console.log("Most relevant:", results[0]);
+```
+
+#### Types
+
+```typescript
+interface EmbeddingConfig {
+  apiKey: string;
+  model: string;
+  baseURL?: string;
+  dimensions?: number;
+}
+
+interface CreateEmbeddingParams extends EmbeddingConfig {
+  input: string;
+}
+
+interface CreateEmbeddingsParams extends EmbeddingConfig {
+  inputs: string[];
+}
+
+interface EmbeddingResult {
+  embedding: number[];
+  model: string;
+  usage: EmbeddingUsage;
+}
+
+interface EmbeddingsResult {
+  embeddings: Array<{ index: number; embedding: number[] }>;
+  model: string;
+  usage: EmbeddingUsage;
+}
+
+interface EmbeddingUsage {
+  prompt_tokens: number;
+  total_tokens: number;
+}
+```
+
 ---
 
 ## Exports Summary
@@ -2359,6 +2503,17 @@ export type {
   TodoWriteParams,
   ReadResultParams,
 } from "./tools";
+
+// Embeddings
+export { createEmbedding, createEmbeddings } from "./core/embedding";
+export type {
+  EmbeddingConfig,
+  CreateEmbeddingParams,
+  CreateEmbeddingsParams,
+  EmbeddingResult,
+  EmbeddingsResult,
+  EmbeddingUsage,
+} from "./types/embedding";
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concevent-ai-agent-sdk",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Framework-agnostic AI Agent SDK with tool calling, conversation management, and automatic summarization",
   "type": "module",
   "main": "./dist/index.js",