@providerprotocol/ai 0.0.16 → 0.0.17

package/README.md

@@ -57,16 +57,119 @@ const turn = await llm({
 console.log(turn.data); // { name: 'John', age: 30 }
 ```
 
+## Embeddings
+
+Generate vector embeddings from text using the unified `embedding()` interface.
+
+```typescript
+import { embedding } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
+import { google } from '@providerprotocol/ai/google';
+import { ollama } from '@providerprotocol/ai/ollama';
+import { openrouter } from '@providerprotocol/ai/openrouter';
+
+// Single text embedding
+const embedder = embedding({ model: openai('text-embedding-3-small') });
+const result = await embedder.embed('Hello world');
+console.log(result.embeddings[0].vector); // [0.123, -0.456, ...]
+console.log(result.embeddings[0].dimensions); // 1536
+
+// Batch embedding
+const batch = await embedder.embed(['doc1', 'doc2', 'doc3']);
+console.log(batch.embeddings.length); // 3
+
+// Custom dimensions (OpenAI text-embedding-3 models)
+const smallEmbed = embedding({
+  model: openai('text-embedding-3-small'),
+  params: { dimensions: 256 },
+});
+
+// Google with task type optimization
+const googleEmbed = embedding({
+  model: google('text-embedding-004'),
+  params: {
+    taskType: 'RETRIEVAL_DOCUMENT',
+    title: 'Important Document',
+  },
+});
+
+// Ollama local embeddings
+const localEmbed = embedding({
+  model: ollama('qwen3-embedding:4b'),
+});
+
+// OpenRouter (access multiple providers)
+const routerEmbed = embedding({
+  model: openrouter('openai/text-embedding-3-small'),
+});
+```
+
+### Chunked Streaming
+
+For large document sets, use chunked mode for progress tracking:
+
+```typescript
+const embedder = embedding({ model: openai('text-embedding-3-small') });
+const documents = Array.from({ length: 1000 }, (_, i) => `Document ${i}`);
+
+const stream = embedder.embed(documents, {
+  chunked: true,
+  batchSize: 100,
+  concurrency: 2,
+});
+
+for await (const progress of stream) {
+  console.log(`${progress.percent.toFixed(1)}% complete`);
+  console.log(`Processed ${progress.completed} of ${progress.total}`);
+}
+
+const finalResult = await stream.result;
+console.log(`Total embeddings: ${finalResult.embeddings.length}`);
+```
+
+### Provider-Specific Parameters
+
+Each provider supports its native parameters passed through unchanged:
+
+```typescript
+// OpenAI: dimensions, encoding_format, user
+embedding({
+  model: openai('text-embedding-3-large'),
+  params: { dimensions: 1024, encoding_format: 'float' },
+});
+
+// Google: taskType, title, outputDimensionality
+embedding({
+  model: google('text-embedding-004'),
+  params: {
+    taskType: 'SEMANTIC_SIMILARITY',
+    outputDimensionality: 256,
+  },
+});
+
+// Ollama: truncate, keep_alive, options
+embedding({
+  model: ollama('nomic-embed-text'),
+  params: { truncate: true, keep_alive: '5m' },
+});
+
+// OpenRouter: dimensions, encoding_format, input_type
+embedding({
+  model: openrouter('openai/text-embedding-3-small'),
+  params: { dimensions: 512 },
+});
+```
+
 ## Providers
 
-| Provider | Import |
-|----------|--------|
-| Anthropic | `@providerprotocol/ai/anthropic` |
-| OpenAI | `@providerprotocol/ai/openai` |
-| Google | `@providerprotocol/ai/google` |
-| Ollama | `@providerprotocol/ai/ollama` |
-| OpenRouter | `@providerprotocol/ai/openrouter` |
-| xAI (Grok) | `@providerprotocol/ai/xai` |
+| Provider | Import | LLM | Embedding |
+|----------|--------|-----|-----------|
+| Anthropic | `@providerprotocol/ai/anthropic` | Yes | - |
+| OpenAI | `@providerprotocol/ai/openai` | Yes | Yes |
+| Google | `@providerprotocol/ai/google` | Yes | Yes |
+| Ollama | `@providerprotocol/ai/ollama` | Yes | Yes |
+| OpenRouter | `@providerprotocol/ai/openrouter` | Yes | Yes |
+| xAI (Grok) | `@providerprotocol/ai/xai` | Yes | - |
 
 ### xAI API Modes
 

package/dist/anthropic/index.d.ts

@@ -1,4 +1,4 @@
-import { b as Provider } from '../provider-vTZ74u-w.js';
+import { d as Provider } from '../provider-D5MO3-pS.js';
 
 /**
  * @fileoverview Anthropic API type definitions.

package/dist/google/index.d.ts

@@ -1,4 +1,4 @@
-import { b as Provider } from '../provider-vTZ74u-w.js';
+import { d as Provider } from '../provider-D5MO3-pS.js';
 
 /**
  * Provider-specific parameters for Google Gemini API requests.
@@ -839,6 +839,33 @@ declare const cache: {
     delete: typeof deleteCache;
 };
 
+/**
+ * @fileoverview Google Gemini Embeddings API Handler
+ *
+ * This module implements the embedding handler for Google's Gemini embeddings API.
+ * Supports gemini-embedding-001 and text-embedding-004 models.
+ *
+ * @see {@link https://ai.google.dev/gemini-api/docs/embeddings Google Embeddings API Reference}
+ * @module providers/google/embed
+ */
+
+/**
+ * Google task types for embedding optimization.
+ */
+type GoogleTaskType = 'RETRIEVAL_QUERY' | 'RETRIEVAL_DOCUMENT' | 'SEMANTIC_SIMILARITY' | 'CLASSIFICATION' | 'CLUSTERING' | 'QUESTION_ANSWERING' | 'FACT_VERIFICATION' | 'CODE_RETRIEVAL_QUERY' | 'TASK_TYPE_UNSPECIFIED';
+/**
+ * Google embedding parameters.
+ * Passed through unchanged to the API.
+ */
+interface GoogleEmbedParams {
+    /** Task type for optimization */
+    taskType?: GoogleTaskType;
+    /** Document title (for RETRIEVAL_DOCUMENT taskType) */
+    title?: string;
+    /** Output dimensionality */
+    outputDimensionality?: number;
+}
+
 /**
  * Google Gemini provider for the Unified Provider Protocol (UPP).
  *
@@ -908,4 +935,4 @@ declare const google: Provider<unknown> & {
     };
 };
 
-export { type CacheCreateOptions, type CacheListOptions, type GoogleBuiltInTool, type GoogleCacheCreateRequest, type GoogleCacheListResponse, type GoogleCacheResponse, type GoogleCacheUpdateRequest, type GoogleCodeExecutionResult, type GoogleCodeExecutionTool, type GoogleFileSearchTool, type GoogleGroundingMetadata, type GoogleHeaders, type GoogleLLMParams, type GoogleMapsTool, type GoogleSearchTool, type GoogleToolConfig, type GoogleUrlContextTool, cache, google, tools };
+export { type CacheCreateOptions, type CacheListOptions, type GoogleBuiltInTool, type GoogleCacheCreateRequest, type GoogleCacheListResponse, type GoogleCacheResponse, type GoogleCacheUpdateRequest, type GoogleCodeExecutionResult, type GoogleCodeExecutionTool, type GoogleEmbedParams, type GoogleFileSearchTool, type GoogleGroundingMetadata, type GoogleHeaders, type GoogleLLMParams, type GoogleMapsTool, type GoogleSearchTool, type GoogleTaskType, type GoogleToolConfig, type GoogleUrlContextTool, cache, google, tools };

package/dist/google/index.js

@@ -520,6 +520,106 @@ function createLLMHandler() {
   };
 }
 
+// src/providers/google/embed.ts
+var GOOGLE_API_URL = "https://generativelanguage.googleapis.com/v1beta";
+function createEmbeddingHandler() {
+  let providerRef = null;
+  return {
+    supportedInputs: ["text"],
+    _setProvider(provider) {
+      providerRef = provider;
+    },
+    bind(modelId) {
+      if (!providerRef) {
+        throw new UPPError(
+          "Provider reference not set. Handler must be used with createProvider().",
+          "INVALID_REQUEST",
+          "google",
+          "embedding"
+        );
+      }
+      const model = {
+        modelId,
+        maxBatchSize: 100,
+        maxInputLength: 2048,
+        dimensions: 3072,
+        get provider() {
+          return providerRef;
+        },
+        async embed(request) {
+          const apiKey = await resolveApiKey(
+            request.config,
+            "GOOGLE_API_KEY",
+            "google",
+            "embedding"
+          );
+          const baseUrl = request.config.baseUrl ?? GOOGLE_API_URL;
+          const requests = request.inputs.map((input) => {
+            const text = typeof input === "string" ? input : "text" in input ? input.text : "";
+            if (!text) {
+              throw new UPPError(
+                "Google embeddings only support text input",
+                "INVALID_REQUEST",
+                "google",
+                "embedding"
+              );
+            }
+            const embedRequest = {
+              model: `models/${modelId}`,
+              content: { parts: [{ text }] }
+            };
+            if (request.params?.taskType !== void 0) {
+              embedRequest.taskType = request.params.taskType;
+            }
+            if (request.params?.title !== void 0) {
+              embedRequest.title = request.params.title;
+            }
+            if (request.params?.outputDimensionality !== void 0) {
+              embedRequest.outputDimensionality = request.params.outputDimensionality;
+            }
+            return embedRequest;
+          });
+          const url = `${baseUrl}/models/${modelId}:batchEmbedContents?key=${apiKey}`;
+          const headers = {
+            "Content-Type": "application/json"
+          };
+          if (request.config.headers) {
+            for (const [key, value] of Object.entries(request.config.headers)) {
+              if (value !== void 0) {
+                headers[key] = value;
+              }
+            }
+          }
+          const response = await doFetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ requests }),
+            signal: request.signal
+          }, request.config, "google", "embedding");
+          const data = await response.json();
+          let totalTokens = 0;
+          for (const emb of data.embeddings) {
+            totalTokens += emb.statistics?.tokenCount ?? 0;
+          }
+          return {
+            embeddings: data.embeddings.map((e, index) => ({
+              vector: e.values,
+              index,
+              tokens: e.statistics?.tokenCount,
+              // Per-embedding metadata (NOT redacted)
+              metadata: e.statistics ? {
+                truncated: e.statistics.truncated
+              } : void 0
+            })),
+            usage: { totalTokens }
+          };
+        }
+      };
+      return model;
+    }
+  };
+}
+
 // src/providers/google/cache.ts
 var CACHE_API_BASE = "https://generativelanguage.googleapis.com/v1beta/cachedContents";
 async function create(options) {
@@ -654,7 +754,8 @@ var baseProvider = createProvider({
   name: "google",
   version: "1.0.0",
   modalities: {
-    llm: createLLMHandler()
+    llm: createLLMHandler(),
+    embedding: createEmbeddingHandler()
   }
 });
 var google = Object.assign(baseProvider, { cache });