@framers/agentos 0.1.113 → 0.1.114

package/dist/api/agentExport.js.map

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

package/dist/api/editImage.d.ts

@@ -0,0 +1,119 @@
+import type { GeneratedImage, ImageEditMode, ImageProviderOptionBag } from '../core/images/IImageProvider.js';
+import { type AgentOSUsageLedgerOptions } from './usageLedger.js';
+/**
+ * Options for an {@link editImage} call.
+ *
+ * @example
+ * ```ts
+ * const result = await editImage({
+ *   provider: 'openai',
+ *   image: 'data:image/png;base64,...',
+ *   prompt: 'Add a rainbow in the sky.',
+ *   mode: 'img2img',
+ *   strength: 0.6,
+ * });
+ * ```
+ */
+export interface EditImageOptions {
+    /**
+     * Provider name (e.g. `"openai"`, `"stability"`, `"stable-diffusion-local"`).
+     * When omitted, auto-detection via env vars is attempted.
+     */
+    provider?: string;
+    /**
+     * Model in `provider:model` format (legacy) or plain model name when `provider` is set.
+     * @example `"openai:gpt-image-1"`, `"stability:sd3-medium"`
+     */
+    model?: string;
+    /**
+     * Source image as a base64 data URL, raw base64 string, `Buffer`,
+     * local file path, or HTTP/HTTPS URL.
+     */
+    image: string | Buffer;
+    /** Text prompt describing the desired changes. */
+    prompt: string;
+    /**
+     * Optional mask for inpainting.  White pixels mark regions to be edited;
+     * black pixels mark regions to keep.  Accepts the same formats as `image`.
+     */
+    mask?: string | Buffer;
+    /**
+     * Edit mode.
+     * - `'img2img'` (default) — prompt-guided transformation.
+     * - `'inpaint'` — mask-guided regional editing.
+     * - `'outpaint'` — extend image borders.
+     */
+    mode?: ImageEditMode;
+    /**
+     * How much to deviate from the source image.
+     * `0` = identical, `1` = completely new.  Default `0.75`.
+     */
+    strength?: number;
+    /** Negative prompt describing content to avoid. */
+    negativePrompt?: string;
+    /** Output size (e.g. `"1024x1024"`). */
+    size?: string;
+    /** Seed for reproducibility (provider-dependent support). */
+    seed?: number;
+    /** Number of output images. */
+    n?: number;
+    /** Override the provider API key instead of reading from env vars. */
+    apiKey?: string;
+    /** Override the provider base URL. */
+    baseUrl?: string;
+    /** Arbitrary provider-specific options. */
+    providerOptions?: ImageProviderOptionBag | Record<string, unknown>;
+    /** Optional usage ledger configuration. */
+    usageLedger?: AgentOSUsageLedgerOptions;
+}
+/**
+ * Result returned by {@link editImage}.
+ */
+export interface EditImageResult {
+    /** Array of edited image objects containing URLs or base64 data. */
+    images: GeneratedImage[];
+    /** Provider identifier. */
+    provider: string;
+    /** Model identifier. */
+    model: string;
+    /** Token/credit usage reported by the provider, when available. */
+    usage: {
+        costUSD?: number;
+    };
+}
+/**
+ * Edits an image using a provider-agnostic interface.
+ *
+ * Resolves credentials via `resolveMediaProvider()`, initialises the
+ * matching image provider, converts the input image to a `Buffer`, and
+ * dispatches to the provider's `editImage` method.
+ *
+ * @param opts - Image editing options.
+ * @returns A promise resolving to the edit result with image data and metadata.
+ *
+ * @throws {ImageEditNotSupportedError} When the resolved provider does not
+ *   implement image editing.
+ * @throws {Error} When no provider can be determined or credentials are missing.
+ *
+ * @example
+ * ```ts
+ * // Img2img transformation
+ * const result = await editImage({
+ *   provider: 'stability',
+ *   image: fs.readFileSync('landscape.png'),
+ *   prompt: 'Convert the daytime scene to a starry night.',
+ *   strength: 0.7,
+ * });
+ *
+ * // Inpainting with mask
+ * const inpainted = await editImage({
+ *   provider: 'openai',
+ *   image: 'data:image/png;base64,...',
+ *   mask: 'data:image/png;base64,...',
+ *   prompt: 'Replace the sky with aurora borealis.',
+ *   mode: 'inpaint',
+ * });
+ * ```
+ */
+export declare function editImage(opts: EditImageOptions): Promise<EditImageResult>;
+//# sourceMappingURL=editImage.d.ts.map

package/dist/api/editImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editImage.d.ts","sourceRoot":"","sources":["../../src/api/editImage.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,sBAAsB,EACvB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAOtF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnE,2CAA2C;IAC3C,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,KAAK,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiGhF"}

package/dist/api/editImage.js

@@ -0,0 +1,150 @@
+/**
+ * @file editImage.ts
+ * Provider-agnostic image editing for the AgentOS high-level API.
+ *
+ * Supports three editing modes:
+ * - **img2img** — Prompt-guided transformation of a source image, controlled by a
+ *   `strength` parameter (0 = keep original, 1 = completely redrawn).
+ * - **inpaint** — Mask-guided regional editing where white mask regions are
+ *   repainted according to the prompt while black regions are preserved.
+ * - **outpaint** — Extends an image beyond its original borders (provider support varies).
+ *
+ * Routing and credential resolution follow the same `provider:model` pattern
+ * established by {@link generateImage}.
+ */
+import { createImageProvider } from '../core/images/index.js';
+import { ImageEditNotSupportedError } from '../core/images/ImageOperationError.js';
+import { imageToBuffer } from '../core/images/imageToBuffer.js';
+import { resolveModelOption, resolveMediaProvider } from './model.js';
+import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { recordAgentOSUsage } from './usageLedger.js';
+import { recordAgentOSTurnMetrics, withAgentOSSpan } from '../core/observability/otel.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Edits an image using a provider-agnostic interface.
+ *
+ * Resolves credentials via `resolveMediaProvider()`, initialises the
+ * matching image provider, converts the input image to a `Buffer`, and
+ * dispatches to the provider's `editImage` method.
+ *
+ * @param opts - Image editing options.
+ * @returns A promise resolving to the edit result with image data and metadata.
+ *
+ * @throws {ImageEditNotSupportedError} When the resolved provider does not
+ *   implement image editing.
+ * @throws {Error} When no provider can be determined or credentials are missing.
+ *
+ * @example
+ * ```ts
+ * // Img2img transformation
+ * const result = await editImage({
+ *   provider: 'stability',
+ *   image: fs.readFileSync('landscape.png'),
+ *   prompt: 'Convert the daytime scene to a starry night.',
+ *   strength: 0.7,
+ * });
+ *
+ * // Inpainting with mask
+ * const inpainted = await editImage({
+ *   provider: 'openai',
+ *   image: 'data:image/png;base64,...',
+ *   mask: 'data:image/png;base64,...',
+ *   prompt: 'Replace the sky with aurora borealis.',
+ *   mode: 'inpaint',
+ * });
+ * ```
+ */
+export async function editImage(opts) {
+    const startedAt = Date.now();
+    let metricStatus = 'ok';
+    let metricUsage;
+    let metricProviderId;
+    let metricModelId;
+    try {
+        return await withAgentOSSpan('agentos.api.edit_image', async (span) => {
+            const { providerId, modelId } = resolveModelOption(opts, 'image');
+            const resolved = resolveMediaProvider(providerId, modelId, {
+                apiKey: opts.apiKey,
+                baseUrl: opts.baseUrl,
+            });
+            metricProviderId = resolved.providerId;
+            metricModelId = resolved.modelId;
+            span?.setAttribute('llm.provider', resolved.providerId);
+            span?.setAttribute('llm.model', resolved.modelId);
+            span?.setAttribute('agentos.api.edit_mode', opts.mode ?? 'img2img');
+            const provider = createImageProvider(resolved.providerId);
+            await provider.initialize({
+                apiKey: resolved.apiKey,
+                baseURL: resolved.baseUrl,
+                defaultModelId: resolved.modelId,
+            });
+            // Guard: the provider must implement editImage.
+            if (typeof provider.editImage !== 'function') {
+                throw new ImageEditNotSupportedError(resolved.providerId);
+            }
+            // Normalise heterogeneous image input into Buffers.
+            const imageBuffer = await imageToBuffer(opts.image);
+            const maskBuffer = opts.mask ? await imageToBuffer(opts.mask) : undefined;
+            const result = await provider.editImage({
+                modelId: resolved.modelId,
+                image: imageBuffer,
+                prompt: opts.prompt,
+                mask: maskBuffer,
+                mode: opts.mode,
+                strength: opts.strength,
+                negativePrompt: opts.negativePrompt,
+                size: opts.size,
+                seed: opts.seed,
+                n: opts.n,
+                providerOptions: opts.providerOptions,
+            });
+            metricUsage = result.usage;
+            span?.setAttribute('agentos.api.images_count', result.images.length);
+            attachUsageAttributes(span, {
+                totalCostUSD: result.usage?.totalCostUSD,
+            });
+            return {
+                images: result.images,
+                provider: result.providerId,
+                model: result.modelId,
+                usage: { costUSD: result.usage?.totalCostUSD },
+            };
+        });
+    }
+    catch (error) {
+        metricStatus = 'error';
+        throw error;
+    }
+    finally {
+        try {
+            await recordAgentOSUsage({
+                providerId: metricProviderId,
+                modelId: metricModelId,
+                usage: metricUsage
+                    ? {
+                        costUSD: metricUsage.totalCostUSD,
+                    }
+                    : undefined,
+                options: {
+                    ...opts.usageLedger,
+                    source: opts.usageLedger?.source ?? 'editImage',
+                },
+            });
+        }
+        catch {
+            // Best-effort — usage persistence must not break the edit operation.
+        }
+        recordAgentOSTurnMetrics({
+            durationMs: Date.now() - startedAt,
+            status: metricStatus,
+            usage: toTurnMetricUsage(metricUsage
+                ? {
+                    totalCostUSD: metricUsage.totalCostUSD,
+                }
+                : undefined),
+        });
+    }
+}
+//# sourceMappingURL=editImage.js.map

package/dist/api/editImage.js.map

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

package/dist/api/embedText.d.ts

@@ -0,0 +1,137 @@
+import { type AgentOSUsageLedgerOptions } from './usageLedger.js';
+/**
+ * Options for an {@link embedText} call.
+ *
+ * At minimum, `input` must be provided. Provider/model resolution follows
+ * the same rules as {@link generateText}: supply `provider`, `model`
+ * (optionally in `provider:model` format), or rely on env-var auto-detection.
+ *
+ * @example
+ * ```ts
+ * const opts: EmbedTextOptions = {
+ *   model: 'openai:text-embedding-3-small',
+ *   input: ['Hello world', 'Goodbye world'],
+ *   dimensions: 256,
+ * };
+ * ```
+ */
+export interface EmbedTextOptions {
+    /**
+     * Provider name. When supplied without `model`, the default embedding model
+     * for the provider is resolved automatically from the built-in defaults.
+     *
+     * @example `"openai"`, `"ollama"`, `"openrouter"`
+     */
+    provider?: string;
+    /**
+     * Model identifier. Accepts `"provider:model"` or plain model name with `provider`.
+     *
+     * @example `"openai:text-embedding-3-small"`, `"nomic-embed-text"`
+     */
+    model?: string;
+    /**
+     * Text(s) to embed. Pass a single string for one embedding or an array
+     * for batch processing.
+     *
+     * @example
+     * ```ts
+     * // Single input
+     * input: 'Hello world'
+     * // Batch input
+     * input: ['Hello world', 'Goodbye world']
+     * ```
+     */
+    input: string | string[];
+    /**
+     * Desired output dimensionality. Only honoured by models that support
+     * dimension reduction (e.g. OpenAI `text-embedding-3-*` with `dimensions`).
+     * Ignored when the model has a fixed output size.
+     */
+    dimensions?: number;
+    /** Override the API key instead of reading from environment variables. */
+    apiKey?: string;
+    /** Override the provider base URL (useful for local proxies or Ollama). */
+    baseUrl?: string;
+    /** Optional durable usage ledger configuration for helper-level accounting. */
+    usageLedger?: AgentOSUsageLedgerOptions;
+}
+/**
+ * The result returned by {@link embedText}.
+ *
+ * @example
+ * ```ts
+ * const { embeddings, usage } = await embedText({
+ *   model: 'openai:text-embedding-3-small',
+ *   input: ['Hello', 'World'],
+ * });
+ * console.log(embeddings.length); // 2
+ * console.log(embeddings[0].length); // e.g. 1536
+ * ```
+ */
+export interface EmbedTextResult {
+    /**
+     * One embedding vector per input string. Each vector is a plain `number[]`
+     * of floats whose dimensionality depends on the model (and the optional
+     * `dimensions` parameter).
+     */
+    embeddings: number[][];
+    /** Model identifier reported by the provider (may differ from the requested model). */
+    model: string;
+    /** Provider identifier used for the run. */
+    provider: string;
+    /**
+     * Token usage for the embedding request.
+     * Most embedding APIs only report prompt tokens (the input); completion
+     * tokens are typically zero.
+     */
+    usage: {
+        /** Number of tokens consumed by the input text(s). */
+        promptTokens: number;
+        /** Sum of prompt and any other tokens (usually equal to `promptTokens`). */
+        totalTokens: number;
+    };
+}
+/**
+ * Generates embedding vectors for one or more text inputs using a
+ * provider-agnostic `provider:model` string.
+ *
+ * Resolves credentials via the standard AgentOS provider pipeline, then
+ * dispatches to the appropriate embedding endpoint (OpenAI, Ollama, or
+ * OpenRouter). Returns raw float arrays suitable for vector similarity
+ * search, clustering, or any downstream ML pipeline.
+ *
+ * @param opts - Embedding options including model, input text(s), and
+ *   optional provider/key overrides.
+ * @returns A promise resolving to the embedding vectors, provider metadata,
+ *   and token usage.
+ *
+ * @throws {Error} When provider resolution fails (missing API key, unknown
+ *   provider, etc.).
+ * @throws {Error} When the embedding API returns a non-2xx status.
+ *
+ * @example
+ * ```ts
+ * import { embedText } from '@framers/agentos';
+ *
+ * // Single input
+ * const { embeddings } = await embedText({
+ *   model: 'openai:text-embedding-3-small',
+ *   input: 'Hello world',
+ * });
+ * console.log(embeddings[0].length); // 1536
+ *
+ * // Batch with reduced dimensions
+ * const batch = await embedText({
+ *   model: 'openai:text-embedding-3-small',
+ *   input: ['Hello', 'World'],
+ *   dimensions: 256,
+ * });
+ * console.log(batch.embeddings.length); // 2
+ * console.log(batch.embeddings[0].length); // 256
+ * ```
+ *
+ * @see {@link generateText} for text generation.
+ * @see {@link resolveModelOption} for provider auto-detection behaviour.
+ */
+export declare function embedText(opts: EmbedTextOptions): Promise<EmbedTextResult>;
+//# sourceMappingURL=embedText.d.ts.map

package/dist/api/embedText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedText.d.ts","sourceRoot":"","sources":["../../src/api/embedText.ts"],"names":[],"mappings":"AAcA,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAOtF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IAEvB,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IAEd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,KAAK,EAAE;QACL,sDAAsD;QACtD,YAAY,EAAE,MAAM,CAAC;QACrB,4EAA4E;QAC5E,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAsID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwHhF"}

package/dist/api/embedText.js

@@ -0,0 +1,229 @@
+/**
+ * @file embedText.ts
+ * Provider-agnostic text embedding generation for the AgentOS high-level API.
+ *
+ * Dispatches embedding requests to OpenAI-compatible, Ollama, or OpenRouter
+ * endpoints using the same provider resolution pipeline as {@link generateText}.
+ * Supports single and batch text inputs, optional dimensionality reduction,
+ * and returns raw float vectors.
+ *
+ * @see {@link generateText} for the text generation primitive.
+ * @see {@link resolveModelOption} for model resolution with `TaskType = 'embedding'`.
+ */
+import { resolveModelOption, resolveProvider } from './model.js';
+import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { recordAgentOSUsage } from './usageLedger.js';
+import { recordAgentOSTurnMetrics, withAgentOSSpan } from '../core/observability/otel.js';
+// ---------------------------------------------------------------------------
+// Provider dispatch helpers
+// ---------------------------------------------------------------------------
+/**
+ * Calls the OpenAI-compatible `/v1/embeddings` endpoint.
+ *
+ * Works for OpenAI native, OpenRouter, and any API that follows the
+ * same request/response contract.
+ *
+ * @param baseUrl - The API base URL (e.g. `https://api.openai.com/v1`).
+ * @param apiKey - Bearer token for the Authorization header.
+ * @param modelId - The embedding model identifier.
+ * @param input - Array of strings to embed.
+ * @param dimensions - Optional dimensionality reduction hint.
+ * @returns Parsed {@link OpenAIEmbeddingResponse}.
+ * @throws {Error} On non-2xx HTTP status or network failure.
+ */
+async function callOpenAIEmbedding(baseUrl, apiKey, modelId, input, dimensions) {
+    // Construct the request body, omitting `dimensions` when not specified
+    // to avoid confusing models that don't support it.
+    const body = { model: modelId, input };
+    if (dimensions !== undefined) {
+        body.dimensions = dimensions;
+    }
+    const url = `${baseUrl.replace(/\/+$/, '')}/embeddings`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '(no body)');
+        throw new Error(`Embedding request failed (${response.status}): ${text}`);
+    }
+    return response.json();
+}
+/**
+ * Calls the Ollama `/api/embed` endpoint.
+ *
+ * Ollama uses a different request shape than OpenAI: input is passed as a
+ * top-level `input` field (string or string[]), and the response has
+ * `embeddings` at the top level.
+ *
+ * @param baseUrl - The Ollama API base URL (e.g. `http://localhost:11434`).
+ * @param modelId - The Ollama model name (e.g. `nomic-embed-text`).
+ * @param input - Array of strings to embed.
+ * @returns Parsed {@link OllamaEmbedResponse}.
+ * @throws {Error} On non-2xx HTTP status or network failure.
+ */
+async function callOllamaEmbed(baseUrl, modelId, input) {
+    const url = `${baseUrl.replace(/\/+$/, '')}/api/embed`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: modelId, input }),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '(no body)');
+        throw new Error(`Ollama embed request failed (${response.status}): ${text}`);
+    }
+    return response.json();
+}
+// ---------------------------------------------------------------------------
+// Main function
+// ---------------------------------------------------------------------------
+/**
+ * Generates embedding vectors for one or more text inputs using a
+ * provider-agnostic `provider:model` string.
+ *
+ * Resolves credentials via the standard AgentOS provider pipeline, then
+ * dispatches to the appropriate embedding endpoint (OpenAI, Ollama, or
+ * OpenRouter). Returns raw float arrays suitable for vector similarity
+ * search, clustering, or any downstream ML pipeline.
+ *
+ * @param opts - Embedding options including model, input text(s), and
+ *   optional provider/key overrides.
+ * @returns A promise resolving to the embedding vectors, provider metadata,
+ *   and token usage.
+ *
+ * @throws {Error} When provider resolution fails (missing API key, unknown
+ *   provider, etc.).
+ * @throws {Error} When the embedding API returns a non-2xx status.
+ *
+ * @example
+ * ```ts
+ * import { embedText } from '@framers/agentos';
+ *
+ * // Single input
+ * const { embeddings } = await embedText({
+ *   model: 'openai:text-embedding-3-small',
+ *   input: 'Hello world',
+ * });
+ * console.log(embeddings[0].length); // 1536
+ *
+ * // Batch with reduced dimensions
+ * const batch = await embedText({
+ *   model: 'openai:text-embedding-3-small',
+ *   input: ['Hello', 'World'],
+ *   dimensions: 256,
+ * });
+ * console.log(batch.embeddings.length); // 2
+ * console.log(batch.embeddings[0].length); // 256
+ * ```
+ *
+ * @see {@link generateText} for text generation.
+ * @see {@link resolveModelOption} for provider auto-detection behaviour.
+ */
+export async function embedText(opts) {
+    const startedAt = Date.now();
+    let metricStatus = 'ok';
+    let metricProviderId;
+    let metricModelId;
+    let metricUsage;
+    try {
+        return await withAgentOSSpan('agentos.api.embed_text', async (span) => {
+            // Resolve provider/model using the 'embedding' task type so the
+            // correct default model is selected (e.g. text-embedding-3-small).
+            const { providerId, modelId } = resolveModelOption(opts, 'embedding');
+            const resolved = resolveProvider(providerId, modelId, {
+                apiKey: opts.apiKey,
+                baseUrl: opts.baseUrl,
+            });
+            metricProviderId = resolved.providerId;
+            metricModelId = resolved.modelId;
+            span?.setAttribute('llm.provider', resolved.providerId);
+            span?.setAttribute('llm.model', resolved.modelId);
+            // Normalise input to an array for uniform handling downstream
+            const inputArray = Array.isArray(opts.input) ? opts.input : [opts.input];
+            span?.setAttribute('agentos.api.embed_input_count', inputArray.length);
+            let embeddings;
+            let reportedModel;
+            let usage;
+            if (resolved.providerId === 'ollama') {
+                // Ollama uses its own /api/embed endpoint format
+                const baseUrl = resolved.baseUrl ?? 'http://localhost:11434';
+                const result = await callOllamaEmbed(baseUrl, resolved.modelId, inputArray);
+                embeddings = result.embeddings;
+                reportedModel = result.model;
+                // Ollama doesn't report token usage for embeddings
+                usage = { promptTokens: 0, totalTokens: 0 };
+            }
+            else {
+                // OpenAI, OpenRouter, and any OpenAI-compatible provider
+                const baseUrl = resolved.baseUrl ?? (resolved.providerId === 'openrouter'
+                    ? 'https://openrouter.ai/api/v1'
+                    : 'https://api.openai.com/v1');
+                if (!resolved.apiKey) {
+                    throw new Error(`No API key available for embedding provider "${resolved.providerId}".`);
+                }
+                const result = await callOpenAIEmbedding(baseUrl, resolved.apiKey, resolved.modelId, inputArray, opts.dimensions);
+                // Sort by index to guarantee order matches input order
+                // (the API contract already guarantees this, but defensive coding)
+                const sorted = [...result.data].sort((a, b) => a.index - b.index);
+                embeddings = sorted.map((d) => d.embedding);
+                reportedModel = result.model;
+                usage = {
+                    promptTokens: result.usage.prompt_tokens,
+                    totalTokens: result.usage.total_tokens,
+                };
+            }
+            metricUsage = usage;
+            span?.setAttribute('agentos.api.embed_dimensions', embeddings[0]?.length ?? 0);
+            attachUsageAttributes(span, {
+                promptTokens: usage.promptTokens,
+                totalTokens: usage.totalTokens,
+            });
+            return {
+                embeddings,
+                model: reportedModel,
+                provider: resolved.providerId,
+                usage,
+            };
+        });
+    }
+    catch (error) {
+        metricStatus = 'error';
+        throw error;
+    }
+    finally {
+        // Best-effort usage persistence and metrics recording
+        try {
+            await recordAgentOSUsage({
+                providerId: metricProviderId,
+                modelId: metricModelId,
+                usage: metricUsage ? {
+                    promptTokens: metricUsage.promptTokens,
+                    completionTokens: 0,
+                    totalTokens: metricUsage.totalTokens,
+                } : undefined,
+                options: {
+                    ...opts.usageLedger,
+                    source: opts.usageLedger?.source ?? 'embedText',
+                },
+            });
+        }
+        catch {
+            // Helper-level usage persistence is best-effort and should not break embedding.
+        }
+        recordAgentOSTurnMetrics({
+            durationMs: Date.now() - startedAt,
+            status: metricStatus,
+            usage: toTurnMetricUsage(metricUsage ? {
+                promptTokens: metricUsage.promptTokens,
+                completionTokens: 0,
+                totalTokens: metricUsage.totalTokens,
+            } : undefined),
+        });
+    }
+}
+//# sourceMappingURL=embedText.js.map