@framers/agentos 0.1.55 → 0.1.57

package/dist/core/guardrails/guardrailDispatcher.js

@@ -31,12 +31,29 @@
  */
 import { uuidv4 } from '../../utils/uuid.js';
 import { AgentOSResponseChunkType, } from '../../api/types/AgentOSResponse.js';
-import { GuardrailAction, } from './IGuardrailService.js';
+import { ParallelGuardrailDispatcher } from './ParallelGuardrailDispatcher.js';
+/**
+ * Normalize a service input (single, array, or undefined) into a flat array.
+ *
+ * Filters out falsy entries so callers never need null-checks.
+ *
+ * @param service - Single guardrail, array of guardrails, or undefined
+ * @returns Non-empty array of valid guardrail services
+ */
+export function normalizeServices(service) {
+    return Array.isArray(service)
+        ? service.filter(Boolean)
+        : service
+            ? [service]
+            : [];
+}
 /**
  * Type guard to check if a guardrail service implements evaluateOutput.
- * @internal
+ *
+ * @param svc - The guardrail service to inspect
+ * @returns `true` when `svc.evaluateOutput` is a callable function
  */
-function hasEvaluateOutput(svc) {
+export function hasEvaluateOutput(svc) {
     return typeof svc.evaluateOutput === 'function';
 }
 /**
@@ -70,48 +87,9 @@ function hasEvaluateOutput(svc) {
  * ```
  */
 export async function evaluateInputGuardrails(service, input, context) {
-    const services = Array.isArray(service)
-        ? service.filter(Boolean)
-        : service
-            ? [service]
-            : [];
-    if (services.length === 0) {
-        return { sanitizedInput: input, evaluations: [] };
-    }
-    let sanitizedInput = input;
-    const evaluations = [];
-    for (const currentService of services) {
-        if (!currentService?.evaluateInput) {
-            continue;
-        }
-        let evaluation = null;
-        try {
-            evaluation = await currentService.evaluateInput({ context, input: sanitizedInput });
-        }
-        catch (error) {
-            console.warn('[AgentOS][Guardrails] evaluateInput failed.', error);
-            continue;
-        }
-        if (!evaluation) {
-            continue;
-        }
-        evaluations.push(evaluation);
-        if (evaluation.action === GuardrailAction.SANITIZE && evaluation.modifiedText !== undefined) {
-            sanitizedInput = {
-                ...sanitizedInput,
-                textInput: evaluation.modifiedText,
-            };
-            continue;
-        }
-        if (evaluation.action === GuardrailAction.BLOCK) {
-            return { sanitizedInput, evaluation, evaluations };
-        }
-    }
-    return {
-        sanitizedInput,
-        evaluation: evaluations.at(-1) ?? null,
-        evaluations,
-    };
+    // Delegate to the two-phase parallel dispatcher.
+    // normalizeServices handles single / array / undefined normalization.
+    return ParallelGuardrailDispatcher.evaluateInput(normalizeServices(service), input, context);
 }
 /**
  * Create a stream that emits a single error chunk for blocked content.
@@ -195,115 +173,21 @@ export async function* createGuardrailBlockedStream(context, evaluation, options
  * ```
  */
 export async function* wrapOutputGuardrails(service, context, stream, options) {
-    const services = Array.isArray(service)
-        ? service.filter(Boolean)
-        : service
-            ? [service]
-            : [];
-    // Separate guardrails by evaluation mode
-    const streamingGuardrails = services.filter((svc) => svc.config?.evaluateStreamingChunks === true && hasEvaluateOutput(svc));
-    const _finalOnlyGuardrails = services.filter((svc) => svc.config?.evaluateStreamingChunks !== true && typeof svc.evaluateOutput === 'function');
-    const guardrailEnabled = services.some((svc) => typeof svc.evaluateOutput === 'function');
-    const serializedInputEvaluations = (options.inputEvaluations ?? []).map(serializeEvaluation);
-    let inputMetadataApplied = serializedInputEvaluations.length === 0;
-    // Track streaming evaluations for rate limiting
-    const streamingEvaluationCounts = new Map();
-    for await (const chunk of stream) {
-        let currentChunk = chunk;
-        if (!inputMetadataApplied && serializedInputEvaluations.length > 0) {
-            currentChunk = withGuardrailMetadata(currentChunk, { input: serializedInputEvaluations });
-            inputMetadataApplied = true;
-        }
-        // Evaluate streaming chunks (TEXT_DELTA) if guardrails are configured for it
-        if (streamingGuardrails.length > 0 &&
-            chunk.type === AgentOSResponseChunkType.TEXT_DELTA &&
-            !chunk.isFinal) {
-            const outputEvaluations = [];
-            let workingChunk = currentChunk;
-            for (const svc of streamingGuardrails) {
-                const svcId = svc.id || 'unknown';
-                const currentCount = streamingEvaluationCounts.get(svcId) || 0;
-                const maxEvals = svc.config?.maxStreamingEvaluations;
-                // Skip if rate limit reached
-                if (maxEvals !== undefined && currentCount >= maxEvals) {
-                    continue;
-                }
-                let evaluation = null;
-                try {
-                    const evalRes = await svc.evaluateOutput({ context, chunk: workingChunk });
-                    streamingEvaluationCounts.set(svcId, currentCount + 1);
-                    evaluation = evalRes ?? null;
-                }
-                catch (error) {
-                    console.warn('[AgentOS][Guardrails] evaluateOutput (streaming) failed.', error);
-                }
-                if (!evaluation) {
-                    continue;
-                }
-                outputEvaluations.push(evaluation);
-                if (evaluation.action === GuardrailAction.BLOCK) {
-                    yield* createGuardrailBlockedStream(context, evaluation, options);
-                    return;
-                }
-                // For TEXT_DELTA chunks, sanitize modifies the textDelta field
-                if (evaluation.action === GuardrailAction.SANITIZE && evaluation.modifiedText !== undefined) {
-                    workingChunk = {
-                        ...workingChunk,
-                        textDelta: evaluation.modifiedText,
-                    };
-                }
-            }
-            if (outputEvaluations.length > 0) {
-                workingChunk = withGuardrailMetadata(workingChunk, {
-                    output: outputEvaluations.map(serializeEvaluation),
-                });
-            }
-            currentChunk = workingChunk;
-        }
-        // Evaluate final chunks (all guardrails)
-        if (guardrailEnabled && chunk.isFinal) {
-            const outputEvaluations = [];
-            let workingChunk = currentChunk;
-            for (const svc of services) {
-                if (!svc?.evaluateOutput) {
-                    continue;
-                }
-                let evaluation = null;
-                try {
-                    evaluation = await svc.evaluateOutput({ context, chunk: workingChunk });
-                }
-                catch (error) {
-                    console.warn('[AgentOS][Guardrails] evaluateOutput (final) failed.', error);
-                }
-                if (!evaluation) {
-                    continue;
-                }
-                outputEvaluations.push(evaluation);
-                if (evaluation.action === GuardrailAction.BLOCK) {
-                    yield* createGuardrailBlockedStream(context, evaluation, options);
-                    return;
-                }
-                if (evaluation.action === GuardrailAction.SANITIZE &&
-                    workingChunk.type === AgentOSResponseChunkType.FINAL_RESPONSE) {
-                    workingChunk = {
-                        ...workingChunk,
-                        finalResponseText: evaluation.modifiedText !== undefined
-                            ? evaluation.modifiedText
-                            : workingChunk.finalResponseText,
-                    };
-                }
-            }
-            if (outputEvaluations.length > 0) {
-                workingChunk = withGuardrailMetadata(workingChunk, {
-                    output: outputEvaluations.map(serializeEvaluation),
-                });
-            }
-            currentChunk = workingChunk;
-        }
-        yield currentChunk;
-    }
+    // Delegate to the two-phase parallel dispatcher.
+    // normalizeServices handles single / array / undefined normalization.
+    yield* ParallelGuardrailDispatcher.wrapOutput(normalizeServices(service), context, stream, options);
 }
-function serializeEvaluation(evaluation) {
+/**
+ * Convert a full {@link GuardrailEvaluationResult} into the compact
+ * {@link GuardrailMetadataEntry} shape that gets embedded in chunk metadata.
+ *
+ * Strips heavy fields (`details`, `modifiedText`) that are not needed
+ * for downstream telemetry / observability.
+ *
+ * @param evaluation - The evaluation to serialize
+ * @returns A lightweight metadata entry suitable for chunk embedding
+ */
+export function serializeEvaluation(evaluation) {
     return {
         action: evaluation.action,
         reason: evaluation.reason,
@@ -311,7 +195,18 @@ function serializeEvaluation(evaluation) {
         metadata: evaluation.metadata,
     };
 }
-function withGuardrailMetadata(chunk, entry) {
+/**
+ * Attach guardrail evaluation metadata to a response chunk.
+ *
+ * Merges new input/output evaluation entries into any existing
+ * `metadata.guardrail` structure on the chunk. The result is a
+ * shallow-cloned chunk — the original is never mutated.
+ *
+ * @param chunk   - The response chunk to annotate
+ * @param entry   - Input and/or output metadata entries to merge
+ * @returns A new chunk with guardrail metadata merged in
+ */
+export function withGuardrailMetadata(chunk, entry) {
     const existingMetadata = chunk.metadata ?? {};
     const existingGuardrail = existingMetadata.guardrail ?? {};
     const existingInput = Array.isArray(existingGuardrail.input)

package/dist/core/guardrails/guardrailDispatcher.js.map

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

package/dist/core/guardrails/index.d.ts

@@ -47,6 +47,7 @@
  */
 export { GuardrailAction, type GuardrailConfig, type GuardrailContext, type GuardrailEvaluationResult, type GuardrailInputPayload, type GuardrailOutputPayload, type IGuardrailService, } from './IGuardrailService';
 export { createGuardrailBlockedStream, evaluateInputGuardrails, type GuardrailInputOutcome, type GuardrailOutputOptions, wrapOutputGuardrails, } from './guardrailDispatcher';
+export { ParallelGuardrailDispatcher } from './ParallelGuardrailDispatcher';
 export { type CrossAgentOutputPayload, type ICrossAgentGuardrailService, isCrossAgentGuardrail, shouldObserveAgent, } from './ICrossAgentGuardrailService';
 export { type CrossAgentEvaluationResult, type CrossAgentGuardrailContext, evaluateCrossAgentGuardrails, filterCrossAgentGuardrails, wrapWithCrossAgentGuardrails, } from './crossAgentGuardrailDispatcher';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/guardrails/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/guardrails/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/guardrails/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAG5E,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,iCAAiC,CAAC"}

package/dist/core/guardrails/index.js

@@ -49,6 +49,8 @@
 export { GuardrailAction, } from './IGuardrailService.js';
 // Guardrail dispatcher functions
 export { createGuardrailBlockedStream, evaluateInputGuardrails, wrapOutputGuardrails, } from './guardrailDispatcher.js';
+// Two-phase parallel guardrail dispatcher
+export { ParallelGuardrailDispatcher } from './ParallelGuardrailDispatcher.js';
 // Cross-agent guardrail interface and types
 export { isCrossAgentGuardrail, shouldObserveAgent, } from './ICrossAgentGuardrailService.js';
 // Cross-agent guardrail dispatcher

package/dist/core/guardrails/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/guardrails/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,qCAAqC;AACrC,OAAO,EACL,eAAe,GAOhB,MAAM,qBAAqB,CAAC;AAE7B,iCAAiC;AACjC,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EAGvB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,4CAA4C;AAC5C,OAAO,EAGL,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAEvC,mCAAmC;AACnC,OAAO,EAGL,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/guardrails/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,qCAAqC;AACrC,OAAO,EACL,eAAe,GAOhB,MAAM,qBAAqB,CAAC;AAE7B,iCAAiC;AACjC,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EAGvB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,0CAA0C;AAC1C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,4CAA4C;AAC5C,OAAO,EAGL,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAEvC,mCAAmC;AACnC,OAAO,EAGL,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,iCAAiC,CAAC"}

package/dist/core/utils/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Barrel export for the `core/utils` module.
+ *
+ * Re-exports all public utilities so consumers can import from the directory
+ * root:
+ * ```typescript
+ * import { clamp, tokenize, estimateTokens } from '../core/utils';
+ * ```
+ *
+ * @module agentos/core/utils
+ */
+export * from './text-utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,cAAc,CAAC"}

package/dist/core/utils/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Barrel export for the `core/utils` module.
+ *
+ * Re-exports all public utilities so consumers can import from the directory
+ * root:
+ * ```typescript
+ * import { clamp, tokenize, estimateTokens } from '../core/utils';
+ * ```
+ *
+ * @module agentos/core/utils
+ */
+export * from './text-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/core/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,cAAc,CAAC"}

package/dist/core/utils/text-utils.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Shared text utility functions used across AgentOS modules.
+ *
+ * These utilities cover common text-processing operations: numeric clamping,
+ * safe JSON parsing (including markdown code-fence stripping), tokenisation,
+ * text normalisation, and a lightweight token-count estimator used wherever
+ * the exact subword count is not critical.
+ *
+ * All functions are pure (no side-effects) and operate synchronously so they
+ * can be called from any context — including hot paths and web workers.
+ *
+ * @module agentos/core/utils/text-utils
+ */
+/**
+ * Clamps a numeric `value` to the closed interval [`min`, `max`].
+ *
+ * @example
+ * ```typescript
+ * clamp(5, 0, 10);  // → 5
+ * clamp(-3, 0, 10); // → 0
+ * clamp(15, 0, 10); // → 10
+ * ```
+ *
+ * @param value - The number to clamp.
+ * @param min   - The inclusive lower bound.
+ * @param max   - The inclusive upper bound.
+ * @returns The clamped value, guaranteed to satisfy `min <= result <= max`.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Safely parses a JSON string, stripping markdown code fences if present.
+ *
+ * LLMs frequently wrap JSON in triple-backtick blocks (e.g. ` ```json … ``` `
+ * or ` ``` … ``` `).  This function strips those fences before attempting
+ * `JSON.parse`, so callers do not need to pre-process LLM output.
+ *
+ * @example
+ * ```typescript
+ * // Plain JSON
+ * parseJsonResponse<{ ok: boolean }>('{"ok":true}'); // → { ok: true }
+ *
+ * // Markdown-fenced JSON
+ * parseJsonResponse('```json\n{"ok":true}\n```'); // → { ok: true }
+ *
+ * // Invalid input
+ * parseJsonResponse('not json'); // → null
+ * ```
+ *
+ * @typeParam T - Expected shape of the parsed value.
+ * @param response - Raw string that may contain JSON, optionally wrapped in
+ *   markdown code fences.
+ * @returns The parsed value cast to `T`, or `null` if parsing fails for any
+ *   reason (syntax error, empty input, etc.).
+ */
+export declare function parseJsonResponse<T = unknown>(response: string): T | null;
+/**
+ * Splits text into lowercase word tokens, stripping punctuation.
+ *
+ * This is an intentionally simple, dependency-free tokeniser suited for tasks
+ * like keyword matching, vocabulary analysis, and lightweight NLP pipelines.
+ * It is *not* a subword tokeniser and does not respect language-specific rules.
+ *
+ * Steps performed:
+ * 1. Convert to lowercase.
+ * 2. Replace non-alphanumeric characters (except spaces) with spaces.
+ * 3. Split on whitespace.
+ * 4. Drop empty strings that can arise from consecutive separators.
+ *
+ * @example
+ * ```typescript
+ * tokenize('Hello, World!');    // → ['hello', 'world']
+ * tokenize('foo  bar\tbaz');    // → ['foo', 'bar', 'baz']
+ * tokenize('');                 // → []
+ * ```
+ *
+ * @param text - The string to tokenise.
+ * @returns An array of lowercase word tokens with punctuation removed.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Normalises text by lowercasing, stripping punctuation, and collapsing
+ * internal whitespace runs to a single space.
+ *
+ * This produces a canonical form useful for fuzzy comparisons, deduplication,
+ * and pre-processing before embedding or classification.
+ *
+ * Steps performed:
+ * 1. Convert to lowercase.
+ * 2. Replace non-alphanumeric characters (except spaces) with spaces.
+ * 3. Collapse consecutive whitespace to a single space.
+ * 4. Trim leading and trailing whitespace.
+ *
+ * @example
+ * ```typescript
+ * normalizeText('Hello, World!');       // → 'hello world'
+ * normalizeText('  foo   bar  ');       // → 'foo bar'
+ * normalizeText("it's a test!");        // → 'it s a test'
+ * ```
+ *
+ * @param text - The string to normalise.
+ * @returns A normalised string.
+ */
+export declare function normalizeText(text: string): string;
+/**
+ * Estimates the number of LLM tokens in a string using the rough heuristic
+ * of **1 token ≈ 4 characters** (the widely-cited GPT-family average).
+ *
+ * This is intentionally approximate. It is suitable for budget checks,
+ * sliding-window sizing, and other cost-control logic where precision is not
+ * required.  For exact subword counts, use the model's native tokeniser.
+ *
+ * @example
+ * ```typescript
+ * estimateTokens('Hello!');     // → 2  (6 chars / 4 → ceil(1.5) = 2)
+ * estimateTokens('');           // → 0
+ * estimateTokens('a'.repeat(8)); // → 2
+ * ```
+ *
+ * @param text - The string whose token count should be estimated.
+ * @returns A non-negative integer estimate of the token count.
+ *   Returns `0` for empty or non-string input.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Computes the cosine similarity between two numeric vectors.
+ *
+ * Cosine similarity measures the cosine of the angle between two vectors in
+ * an inner-product space.  It ranges from **-1.0** (perfectly opposite
+ * directions) to **1.0** (perfectly identical directions), with **0** meaning
+ * the vectors are orthogonal (no linear similarity).
+ *
+ * This single implementation consolidates 6+ duplicate `cosineSimilarity`
+ * helpers that previously existed across the AgentOS codebase (discovery,
+ * social-posting, rag, etc.), providing a single well-tested source of truth.
+ *
+ * ### Edge-case behaviour
+ * | Condition | Return value | Reason |
+ * |---|---|---|
+ * | Empty arrays | `0` | Division by zero is undefined; 0 is the safe neutral value. |
+ * | Mismatched dimensions | `0` | Meaningless to compare vectors in different spaces. |
+ * | Either vector is the zero vector | `0` | Magnitude is 0, denominator would be 0. |
+ *
+ * @example
+ * ```typescript
+ * // Identical unit vectors → 1
+ * cosineSimilarity([1, 0], [1, 0]);  // → 1.0
+ *
+ * // Orthogonal vectors → 0
+ * cosineSimilarity([1, 0], [0, 1]);  // → 0
+ *
+ * // Opposite unit vectors → -1
+ * cosineSimilarity([1, 0], [-1, 0]); // → -1.0
+ *
+ * // Non-unit but parallel vectors → 1
+ * cosineSimilarity([2, 4], [1, 2]);  // → 1.0
+ * ```
+ *
+ * @param a - First numeric vector (any dimension ≥ 1).
+ * @param b - Second numeric vector — must have the same length as `a`.
+ * @returns Cosine similarity in the range `[-1, 1]`.
+ *   Returns `0` for mismatched dimensions, empty arrays, or zero-magnitude vectors.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=text-utils.d.ts.map

package/dist/core/utils/text-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/text-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMrE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAwBzE;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB/C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAclD;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBjE"}