ai.matey.utils 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# ai.matey.utils
+
+## 0.4.0
+
+### Minor Changes
+
+- d9e1489: July 2026 provider refresh. DeepSeek: V4 generation (`deepseek-v4-flash`/`deepseek-v4-pro`, 1M
+  context, 384K output) with image input enabled — the adapter now advertises `multiModal` and
+  defaults to `deepseek-v4-flash`; `deepseek-chat`/`deepseek-reasoner` marked deprecated (provider
+  retires them 2026-07-24). Registry adds `claude-sonnet-5` (1M context), `gemini-3.5-flash`,
+  `gemini-3.1-pro-preview`, `grok-4.3`, `grok-4.20` variants, and `grok-build-0.1`; capability
+  inference recognizes the claude-5 and deepseek-v4 families; xAI default model updated off the
+  retired `grok-beta`.
+
+## 0.3.0
+
+### Minor Changes
+
+- dae4d01: Embeddings support: `bridge.embed()` / `router.embed()` with batch chunking, dimension
+  normalization, and an embed middleware chain; provider implementations for OpenAI, Mistral,
+  Gemini, Cohere, Ollama, Together, Fireworks, DeepInfra, NVIDIA, and LM Studio; caching and
+  cost-tracking embedding middleware.
+- 2912b7d: Introduce a shared, data-driven model registry in `ai.matey.utils` as the single source of truth
+  for model metadata (pricing, context windows, capabilities, quality/latency). The registry ships
+  with a mid-2026 seed (GPT-5.x/o-series, Claude 4.x, Gemini 2.5/3, Grok, current Mistral/DeepSeek,
+  plus embedding models) and is runtime-extensible via `registerModels()` / `overrideModelPricing()`,
+  with alias and longest-prefix fallback so new dated snapshots of known families still resolve.
+
+  `ai.matey.core`'s model-pricing API is now a thin delegate over the registry (no API break; legacy
+  models keep their prices, marked `deprecated`). Capability inference recognizes current families.
+  Cost-tracking middleware consults the registry before provider-level defaults. `useTokenCount`
+  consults the registry for context windows. Backend default models updated:
+  `claude-3-haiku-20240307` → `claude-sonnet-4-5-20250929` (Anthropic), `gpt-3.5-turbo` →
+  `gpt-5-mini` (OpenAI) — note this changes behavior for requests that omit a model. `estimateCost()`
+  on both backends now prices the actual requested model. Refreshed `deepseek-chat` pricing.
+
+- b7e2312: Tool-calling helpers (`extractToolCalls`, `createToolResultMessage`, `validateToolArgs`, ...)
+  and an agentic loop: `bridge.runTools({ prompt, tools })` executes model-requested tools and
+  feeds results back until completion. `bridge.executeIR()` exposes the IR pipeline directly.
+- 58ebc03: Streaming tool-call support end-to-end. OpenAI and Anthropic backends now emit `tool_use` IR chunks
+  for streamed tool-call deltas (previously dropped with a console warning) and assemble complete
+  `ToolUseContent` blocks on the final `done` chunk. The Anthropic backend reports the real
+  provider stop reason (previously fabricated, e.g. `max_tokens` streams reported `stop`) and
+  captures usage from every `message_delta`. The OpenAI backend folds the trailing
+  `stream_options.include_usage` chunk into the done chunk. Frontend adapters re-emit tool deltas in
+  native formats (OpenAI index-based `tool_calls` deltas; Anthropic `content_block_start`/
+  `input_json_delta` events — the leading text block is now opened lazily so tool-only streams do not
+  fabricate an empty text block). `StreamAccumulator` assembles streamed tool calls.
+
+  Note: when tools are streamed, the done chunk's `message.content` is now a structured
+  `MessageContent[]` (text + tool_use blocks) rather than a plain string, and finish reasons are now
+  truthful (`tool_calls`/`length` where `stop` was previously reported).
+
+### Patch Changes
+
+- Updated dependencies [dae4d01]
+- Updated dependencies [e7df1d0]
+- Updated dependencies [2912b7d]
+- Updated dependencies [78731bb]
+- Updated dependencies [b7e2312]
+  - ai.matey.types@0.3.0

package/dist/cjs/embeddings.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Embedding Utilities
+ *
+ * Shared helpers for embedding support: batch chunking, dimension
+ * normalization, similarity, capability detection, and OpenAI wire-format
+ * conversion (used by the HTTP layer's /v1/embeddings route).
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsEmbeddings = supportsEmbeddings;
+exports.chunkEmbedInputs = chunkEmbedInputs;
+exports.normalizeDimensions = normalizeDimensions;
+exports.cosineSimilarity = cosineSimilarity;
+exports.openaiEmbedRequestToIR = openaiEmbedRequestToIR;
+exports.irToOpenAIEmbedResponse = irToOpenAIEmbedResponse;
+// ============================================================================
+// Capability Detection
+// ============================================================================
+/**
+ * Type guard: does this backend implement embeddings?
+ */
+function supportsEmbeddings(adapter) {
+    // An inherited embed() can be explicitly opted out of via the capability
+    // flag (e.g. providers subclassing the OpenAI adapter without an
+    // embeddings endpoint set `capabilities.embeddings: false`)
+    return typeof adapter.embed === 'function' && adapter.metadata.capabilities.embeddings !== false;
+}
+// ============================================================================
+// Batch Chunking
+// ============================================================================
+/**
+ * Split embedding inputs into provider-sized batches.
+ *
+ * @param inputs - Input strings
+ * @param options - maxBatchSize: max inputs per request; maxTokensPerBatch:
+ *   optional token budget per batch using estimateTokens (default ~4 chars
+ *   per token)
+ * @returns Batches in original order
+ */
+function chunkEmbedInputs(inputs, options) {
+    const { maxBatchSize, maxTokensPerBatch, estimateTokens } = options;
+    const tokensOf = estimateTokens ?? ((text) => Math.ceil(text.length / 4));
+    const batches = [];
+    let current = [];
+    let currentTokens = 0;
+    for (const input of inputs) {
+        const inputTokens = maxTokensPerBatch ? tokensOf(input) : 0;
+        const wouldOverflow = current.length >= maxBatchSize ||
+            (maxTokensPerBatch !== undefined &&
+                current.length > 0 &&
+                currentTokens + inputTokens > maxTokensPerBatch);
+        if (wouldOverflow) {
+            batches.push(current);
+            current = [];
+            currentTokens = 0;
+        }
+        current.push(input);
+        currentTokens += inputTokens;
+    }
+    if (current.length > 0) {
+        batches.push(current);
+    }
+    return batches;
+}
+// ============================================================================
+// Dimension Normalization
+// ============================================================================
+/**
+ * Normalize a vector to a target dimensionality.
+ *
+ * - `truncate` (default): drop trailing components and re-normalize to unit
+ *   length (valid for Matryoshka-trained models; approximate otherwise)
+ * - `pad`: zero-pad to the target length
+ *
+ * @param vector - Source vector
+ * @param dimensions - Target dimensionality
+ * @param strategy - 'truncate' | 'pad'
+ */
+function normalizeDimensions(vector, dimensions, strategy = 'truncate') {
+    if (vector.length === dimensions) {
+        return [...vector];
+    }
+    if (vector.length > dimensions) {
+        const truncated = vector.slice(0, dimensions);
+        const norm = Math.sqrt(truncated.reduce((sum, value) => sum + value * value, 0));
+        return norm === 0 ? truncated : truncated.map((value) => value / norm);
+    }
+    if (strategy === 'pad') {
+        return [...vector, ...new Array(dimensions - vector.length).fill(0)];
+    }
+    // Truncate strategy with a shorter source: return as-is (cannot invent data)
+    return [...vector];
+}
+/**
+ * Cosine similarity between two vectors (also the seed primitive for
+ * semantic caching).
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        normA += x * x;
+        normB += y * y;
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dot / denominator;
+}
+/**
+ * Convert an OpenAI-format embeddings request body to IR.
+ */
+function openaiEmbedRequestToIR(body) {
+    return {
+        input: body.input,
+        parameters: {
+            model: body.model,
+            dimensions: body.dimensions,
+            user: body.user,
+        },
+        metadata: {
+            requestId: crypto.randomUUID(),
+            timestamp: Date.now(),
+            provenance: { frontend: 'openai-embed' },
+        },
+    };
+}
+/**
+ * Convert an IR embedding response to the OpenAI wire format.
+ */
+function irToOpenAIEmbedResponse(response) {
+    return {
+        object: 'list',
+        data: response.embeddings.map((embedding) => ({
+            object: 'embedding',
+            index: embedding.index,
+            embedding: [...embedding.vector],
+        })),
+        model: response.model,
+        usage: {
+            prompt_tokens: response.usage?.promptTokens ?? 0,
+            total_tokens: response.usage?.totalTokens ?? 0,
+        },
+    };
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/cjs/embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/embeddings.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.js

@@ -21,6 +21,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_REGISTRY_SEED = void 0;
 // Validation utilities
 __exportStar(require("./validation.js"), exports);
 // System message utilities
@@ -37,6 +38,14 @@ __exportStar(require("./warnings.js"), exports);
 __exportStar(require("./conversation-history.js"), exports);
 // Model cache utilities
 __exportStar(require("./model-cache.js"), exports);
+// Embedding utilities
+__exportStar(require("./embeddings.js"), exports);
+// Tool-calling helpers
+__exportStar(require("./tools.js"), exports);
+// Model registry (pricing, context windows, capabilities)
+__exportStar(require("./model-registry.js"), exports);
+var model_registry_data_js_1 = require("./model-registry-data.js");
+Object.defineProperty(exports, "MODEL_REGISTRY_SEED", { enumerable: true, get: function () { return model_registry_data_js_1.MODEL_REGISTRY_SEED; } });
 // Structured output utilities (Zod integration)
 __exportStar(require("./structured-output.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;AAEH,uBAAuB;AACvB,kDAAgC;AAEhC,2BAA2B;AAC3B,sDAAoC;AAEpC,oCAAoC;AACpC,4DAA0C;AAE1C,sBAAsB;AACtB,iDAA+B;AAE/B,sCAAsC;AACtC,uDAAqC;AAErC,oBAAoB;AACpB,gDAA8B;AAE9B,iCAAiC;AACjC,4DAA0C;AAE1C,wBAAwB;AACxB,mDAAiC;AAEjC,gDAAgD;AAChD,yDAAuC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;AAEH,uBAAuB;AACvB,kDAAgC;AAEhC,2BAA2B;AAC3B,sDAAoC;AAEpC,oCAAoC;AACpC,4DAA0C;AAE1C,sBAAsB;AACtB,iDAA+B;AAE/B,sCAAsC;AACtC,uDAAqC;AAErC,oBAAoB;AACpB,gDAA8B;AAE9B,iCAAiC;AACjC,4DAA0C;AAE1C,wBAAwB;AACxB,mDAAiC;AAEjC,sBAAsB;AACtB,kDAAgC;AAEhC,uBAAuB;AACvB,6CAA2B;AAE3B,0DAA0D;AAC1D,sDAAoC;AACpC,mEAA+D;AAAtD,6HAAA,mBAAmB,OAAA;AAE5B,gDAAgD;AAChD,yDAAuC"}