@kenkaiiii/gg-ai 5.76.0 → 5.78.0

package/dist/index.d.cts

@@ -289,6 +289,60 @@ interface StreamOptions {
      *  `User-Agent: kimi-code-cli/...` and `X-Msh-*` device headers). Merged
      *  into the underlying SDK's default headers. */
     defaultHeaders?: Record<string, string>;
+    /** Provider-specific request-body fields, merged into the JSON body of every
+     *  model request (e.g. OpenRouter's routing object:
+     *  `{ provider: { zdr: true, data_collection: "deny" } }`). Fields gg-ai
+     *  sets itself — `model`, `messages`, `tools`, `stream`, sampling and
+     *  reasoning parameters, and so on — always win; see `ProviderOptions`. */
+    providerOptions?: ProviderOptions;
+}
+/**
+ * Provider-specific JSON body fields passed through to the provider unchanged
+ * by `stream()`, `embed()` and `rerank()`.
+ *
+ * Merge rules: a field is added only when gg-ai hasn't set it on the request.
+ * Core fields (`model`, `messages`, `input`, `query`, `documents`, `stream`,
+ * `tools`, `system`, `contents`, `requests`, `dimensions`, `encoding_format`,
+ * `top_n`) are never taken from here, even when gg-ai left them unset — use the
+ * dedicated option instead. Keys are applied in sorted order, so the merged body
+ * is deterministic.
+ *
+ * ```ts
+ * providerOptions: {
+ *   provider: { zdr: true, data_collection: "deny" } satisfies OpenRouterProviderPreferences,
+ * }
+ * ```
+ */
+type ProviderOptions = Readonly<Record<string, unknown>>;
+/**
+ * OpenRouter's provider-routing preferences (the `provider` body field on
+ * `/chat/completions`, `/embeddings` and `/rerank`). Pass it through
+ * `providerOptions: { provider: … }`. Only the commonly used fields are typed;
+ * anything else OpenRouter documents is passed through as-is.
+ * See https://openrouter.ai/docs/features/provider-routing.
+ */
+interface OpenRouterProviderPreferences {
+    /** Allow backup providers when the preferred ones are unavailable (default true). */
+    allow_fallbacks?: boolean;
+    /** Only route to providers that don't retain prompts. */
+    zdr?: boolean;
+    /** `"deny"` restricts routing to providers that don't collect user data. */
+    data_collection?: "allow" | "deny";
+    /** Only route to providers that support every parameter in the request. */
+    require_parameters?: boolean;
+    /** Provider slugs to try, in order. */
+    order?: string[];
+    /** Provider slugs to allow. */
+    only?: string[];
+    /** Provider slugs to skip. */
+    ignore?: string[];
+    /** Quantization levels to allow (e.g. `"fp8"`). */
+    quantizations?: string[];
+    /** Sort strategy (`"price"`, `"throughput"`, `"latency"`) or a sort config object. */
+    sort?: string | Readonly<Record<string, unknown>>;
+    /** Maximum price per million tokens, by usage kind. */
+    max_price?: Readonly<Record<string, number | string>>;
+    [key: string]: unknown;
 }
 
 /**
@@ -361,6 +415,10 @@ declare function localWireModelId(id: string): string;
  * Providers are resolved via the provider registry. Built-in providers
  * (anthropic, openai, glm, moonshot) are registered at module load.
  * Extensions can register custom providers via `providerRegistry.register()`.
+ * The same registry backs `embed()` and `rerank()`: a provider entry may also
+ * carry `embed` / `rerank` functions (check `providerRegistry.supports(name,
+ * "embed")`), and `providerOptions` passes provider-specific body fields to all
+ * three.
  *
  * ```ts
  * // Stream events
@@ -374,18 +432,170 @@ declare function localWireModelId(id: string): string;
  */
 declare function stream(options: StreamOptions): StreamResult;
 
+/** What the embedded text will be used for. See `EmbedOptions.inputType`. */
+type EmbedInputType = "query" | "document";
+/** Fields shared by every `embed()` / `rerank()` request. */
+interface RetrievalRequestOptions {
+    /** Registered provider name. Resolved through `providerRegistry`, like `stream()`. */
+    provider: Provider;
+    model: string;
+    /** API key. Sent as the provider expects (Bearer token, or `x-goog-api-key` for Gemini).
+     *  Not read from the environment — pass it explicitly. */
+    apiKey?: string;
+    /** Override the provider's default API base URL (required for `local`). */
+    baseUrl?: string;
+    /** Aborts the in-flight request and skips any remaining batches. */
+    signal?: AbortSignal;
+    /** Custom fetch implementation (tests, React Native, proxies). */
+    fetch?: typeof globalThis.fetch;
+    /** Provider-specific body fields (e.g. OpenRouter's `provider` routing object).
+     *  Never overrides fields gg-ai sets; see `ProviderOptions`. */
+    providerOptions?: ProviderOptions;
+}
+interface EmbedOptions extends RetrievalRequestOptions {
+    /** Texts to embed. Any length — gg-ai splits it into provider-sized batches. */
+    input: string[];
+    /** Requested vector size, for models that support shortened embeddings.
+     *  Every returned vector is checked against it; a mismatch throws. */
+    dimensions?: number;
+    /**
+     * Whether the texts are search queries or documents being indexed. Mapped to
+     * the provider's native task parameter where one exists (Gemini `taskType`,
+     * OpenRouter `input_type`); ignored where it doesn't (OpenAI, local servers,
+     * and `gemini-embedding-2`, which takes the task as a text prefix instead).
+     */
+    inputType?: EmbedInputType;
+    /** L2-normalize every vector after validation. Default false. */
+    normalize?: boolean;
+    /** Inputs per request. Defaults to the provider's documented maximum (see README). */
+    batchSize?: number;
+}
+interface EmbedUsage {
+    /** Input tokens, summed over every batch that reported usage. */
+    inputTokens: number;
+}
+interface EmbedResult {
+    /** One vector per input, in input order. */
+    embeddings: number[][];
+    /** Model the provider reports having used (falls back to the requested model). */
+    model: string;
+    /** Present when the provider reported usage for at least one batch. */
+    usage?: EmbedUsage;
+}
+interface RerankOptions extends RetrievalRequestOptions {
+    query: string;
+    documents: string[];
+    /** Return only the best `topN` results. Default: all documents. */
+    topN?: number;
+}
+interface RerankResult {
+    /** Index into the caller's `documents` array. */
+    index: number;
+    /** Relevance score; higher is more relevant. Scale depends on the model. */
+    score: number;
+}
+interface RerankUsage {
+    inputTokens?: number;
+    /** Billing units for search-unit priced rerankers (e.g. Cohere via OpenRouter). */
+    searchUnits?: number;
+}
+interface RerankResponse {
+    /** Sorted by score, highest first. */
+    results: RerankResult[];
+    model: string;
+    usage?: RerankUsage;
+}
+/** One embedding request as a provider sees it: a single batch. */
+type ProviderEmbedRequest = Omit<EmbedOptions, "normalize" | "batchSize">;
+/** A provider's answer to one batch. `embeddings` must be in input order. */
+interface ProviderEmbedResponse {
+    embeddings: number[][];
+    model?: string;
+    usage?: EmbedUsage;
+}
+/** Embed one batch. gg-ai handles batching, validation and normalization. */
+type ProviderEmbedFn = (request: ProviderEmbedRequest) => Promise<ProviderEmbedResponse>;
+/** A rerank request as a provider sees it. `documents` is never empty. */
+type ProviderRerankRequest = RerankOptions;
+/** A provider's rerank answer. Any order; gg-ai validates, sorts and applies `topN`. */
+interface ProviderRerankResponse {
+    results: RerankResult[];
+    model?: string;
+    usage?: RerankUsage;
+}
+type ProviderRerankFn = (request: ProviderRerankRequest) => Promise<ProviderRerankResponse>;
+
+/**
+ * Create embeddings through any registered provider that offers them (see
+ * `providerRegistry.supports(name, "embed")`).
+ *
+ * - `input` may be any length: it's split into provider-sized batches, sent in
+ *   order, one at a time. `signal` aborts the in-flight batch and skips the rest.
+ * - The result has exactly one vector per input, in input order. A provider
+ *   reply with the wrong count, a non-numeric value, mixed vector lengths, or a
+ *   length other than `dimensions` throws `ProviderError` — nothing is padded
+ *   or truncated.
+ * - `normalize: true` L2-normalizes each vector (all-zero vectors stay zero).
+ * - No retries: as with `stream()`, retry policy belongs to the caller. 429s
+ *   carry `resetsAt` when the provider sends `Retry-After`; auth and billing
+ *   failures (`isUsageLimitError`) should never be retried.
+ *
+ * ```ts
+ * const { embeddings } = await embed({
+ *   provider: "openai",
+ *   model: "text-embedding-3-small",
+ *   input: ["first chunk", "second chunk"],
+ *   apiKey,
+ * });
+ * ```
+ */
+declare function embed(options: EmbedOptions): Promise<EmbedResult>;
+/**
+ * Rerank `documents` against `query` through any registered provider that
+ * offers reranking (see `providerRegistry.supports(name, "rerank")`).
+ *
+ * Results are sorted by score, highest first (ties keep document order), and
+ * `index` points into the caller's `documents`. At most `topN` results are
+ * returned. A reply with an out-of-range or duplicate index throws
+ * `ProviderError`. No retries — see `embed()`.
+ *
+ * ```ts
+ * const { results } = await rerank({
+ *   provider: "openrouter",
+ *   model: "cohere/rerank-v3.5",
+ *   query: "capital of France",
+ *   documents,
+ *   topN: 5,
+ *   apiKey,
+ * });
+ * const best = documents[results[0].index];
+ * ```
+ */
+declare function rerank(options: RerankOptions): Promise<RerankResponse>;
+
 /**
  * A provider stream function. Takes StreamOptions and returns a StreamResult.
  * Each provider implements this to handle its specific API format.
  */
 type ProviderStreamFn = (options: StreamOptions) => StreamResult;
+/** Capabilities a registered provider can offer. */
+type ProviderCapability = "stream" | "embed" | "rerank";
 /**
  * Registry entry for a provider. A provider can have a simple stream function
- * or a more complex setup with custom routing logic.
+ * or a more complex setup with custom routing logic. `embed` and `rerank` are
+ * optional: leave them out when the provider has no such API, and `embed()` /
+ * `rerank()` fail with a capability error instead.
  */
 interface ProviderEntry {
     /** Main stream function for this provider */
     stream: ProviderStreamFn;
+    /** Embed one batch of texts. Batching, ordering checks and normalization are done by `embed()`. */
+    embed?: ProviderEmbedFn;
+    /** Default inputs per embedding request (the provider's documented maximum).
+     *  Omit to send every input in one request. Callers can override with `batchSize`. */
+    embedBatchSize?: number;
+    /** Rerank documents against a query. Sorting and `topN` are applied by `rerank()`. */
+    rerank?: ProviderRerankFn;
 }
 /**
  * Map-based provider registry. Built-in providers are registered at module load,
@@ -411,6 +621,8 @@ declare class ProviderRegistryImpl {
     get(name: string): ProviderEntry | undefined;
     /** Check if a provider is registered. */
     has(name: string): boolean;
+    /** Whether a registered provider offers a capability (`false` for unknown providers). */
+    supports(name: string, capability: ProviderCapability): boolean;
     /** List all registered provider names. */
     list(): string[];
 }
@@ -473,6 +685,8 @@ declare class ProviderError extends GGAIError {
         hint?: string;
         cause?: unknown;
         resetsAt?: number;
+        /** `"auth"` for credential rejections (HTTP 401/403). Default `"provider"`. */
+        source?: "provider" | "auth";
     });
 }
 /**
@@ -727,7 +941,12 @@ declare function prewarmAnthropicCache(options: {
 }): Promise<void>;
 
 interface PalsuProviderState {
+    /** `stream()` calls served. */
     callCount: number;
+    /** Embedding requests served (one per batch). */
+    embedCallCount: number;
+    /** Rerank requests served. */
+    rerankCallCount: number;
 }
 type PalsuResponseFactory = (messages: Message[], options: StreamOptions, state: PalsuProviderState) => AssistantMessage | Promise<AssistantMessage>;
 type PalsuResponse = AssistantMessage | PalsuResponseFactory;
@@ -778,6 +997,10 @@ interface PalsuProviderConfig {
     promptCache?: boolean;
     /** Model-specific configurations with per-model response queues. */
     models?: Record<string, PalsuModelConfig>;
+    /** Vector size of the fake embeddings when the caller doesn't pass `dimensions`. Default 64. */
+    embedDimensions?: number;
+    /** Inputs per fake embedding request, to exercise batching. Default: all in one request. */
+    embedBatchSize?: number;
 }
 /**
  * Register a palsu (mock) LLM provider for testing.
@@ -794,5 +1017,13 @@ interface PalsuProviderConfig {
  * ```
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
+/**
+ * Deterministic fake embedding: a signed, hashed bag of words, L2-normalized.
+ * Texts sharing words get a higher cosine similarity, so retrieval code behaves
+ * plausibly in tests. Text with no words maps to a fixed unit vector.
+ */
+declare function palsuEmbedding(text: string, dimensions?: number): number[];
+/** Deterministic fake relevance: the share of distinct query words found in the document (0–1). */
+declare function palsuRerankScore(query: string, document: string): number;
 
-export { type AssistantMessage, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type ErrorEvent, type ErrorSource, EventStream, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderDiagnosticFn, type ProviderEntry, ProviderError, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, dropInvalidToolCalls, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };
+export { type AssistantMessage, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type EmbedInputType, type EmbedOptions, type EmbedResult, type EmbedUsage, type ErrorEvent, type ErrorSource, EventStream, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type OpenRouterProviderPreferences, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderCapability, type ProviderDiagnosticFn, type ProviderEmbedFn, type ProviderEmbedRequest, type ProviderEmbedResponse, type ProviderEntry, ProviderError, type ProviderOptions, type ProviderRerankFn, type ProviderRerankRequest, type ProviderRerankResponse, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type RerankOptions, type RerankResponse, type RerankResult, type RerankUsage, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, dropInvalidToolCalls, embed, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, palsuAssistantMessage, palsuEmbedding, palsuRerankScore, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, rerank, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };

package/dist/index.d.ts

@@ -289,6 +289,60 @@ interface StreamOptions {
      *  `User-Agent: kimi-code-cli/...` and `X-Msh-*` device headers). Merged
      *  into the underlying SDK's default headers. */
     defaultHeaders?: Record<string, string>;
+    /** Provider-specific request-body fields, merged into the JSON body of every
+     *  model request (e.g. OpenRouter's routing object:
+     *  `{ provider: { zdr: true, data_collection: "deny" } }`). Fields gg-ai
+     *  sets itself — `model`, `messages`, `tools`, `stream`, sampling and
+     *  reasoning parameters, and so on — always win; see `ProviderOptions`. */
+    providerOptions?: ProviderOptions;
+}
+/**
+ * Provider-specific JSON body fields passed through to the provider unchanged
+ * by `stream()`, `embed()` and `rerank()`.
+ *
+ * Merge rules: a field is added only when gg-ai hasn't set it on the request.
+ * Core fields (`model`, `messages`, `input`, `query`, `documents`, `stream`,
+ * `tools`, `system`, `contents`, `requests`, `dimensions`, `encoding_format`,
+ * `top_n`) are never taken from here, even when gg-ai left them unset — use the
+ * dedicated option instead. Keys are applied in sorted order, so the merged body
+ * is deterministic.
+ *
+ * ```ts
+ * providerOptions: {
+ *   provider: { zdr: true, data_collection: "deny" } satisfies OpenRouterProviderPreferences,
+ * }
+ * ```
+ */
+type ProviderOptions = Readonly<Record<string, unknown>>;
+/**
+ * OpenRouter's provider-routing preferences (the `provider` body field on
+ * `/chat/completions`, `/embeddings` and `/rerank`). Pass it through
+ * `providerOptions: { provider: … }`. Only the commonly used fields are typed;
+ * anything else OpenRouter documents is passed through as-is.
+ * See https://openrouter.ai/docs/features/provider-routing.
+ */
+interface OpenRouterProviderPreferences {
+    /** Allow backup providers when the preferred ones are unavailable (default true). */
+    allow_fallbacks?: boolean;
+    /** Only route to providers that don't retain prompts. */
+    zdr?: boolean;
+    /** `"deny"` restricts routing to providers that don't collect user data. */
+    data_collection?: "allow" | "deny";
+    /** Only route to providers that support every parameter in the request. */
+    require_parameters?: boolean;
+    /** Provider slugs to try, in order. */
+    order?: string[];
+    /** Provider slugs to allow. */
+    only?: string[];
+    /** Provider slugs to skip. */
+    ignore?: string[];
+    /** Quantization levels to allow (e.g. `"fp8"`). */
+    quantizations?: string[];
+    /** Sort strategy (`"price"`, `"throughput"`, `"latency"`) or a sort config object. */
+    sort?: string | Readonly<Record<string, unknown>>;
+    /** Maximum price per million tokens, by usage kind. */
+    max_price?: Readonly<Record<string, number | string>>;
+    [key: string]: unknown;
 }
 
 /**
@@ -361,6 +415,10 @@ declare function localWireModelId(id: string): string;
  * Providers are resolved via the provider registry. Built-in providers
  * (anthropic, openai, glm, moonshot) are registered at module load.
  * Extensions can register custom providers via `providerRegistry.register()`.
+ * The same registry backs `embed()` and `rerank()`: a provider entry may also
+ * carry `embed` / `rerank` functions (check `providerRegistry.supports(name,
+ * "embed")`), and `providerOptions` passes provider-specific body fields to all
+ * three.
  *
  * ```ts
  * // Stream events
@@ -374,18 +432,170 @@ declare function localWireModelId(id: string): string;
  */
 declare function stream(options: StreamOptions): StreamResult;
 
+/** What the embedded text will be used for. See `EmbedOptions.inputType`. */
+type EmbedInputType = "query" | "document";
+/** Fields shared by every `embed()` / `rerank()` request. */
+interface RetrievalRequestOptions {
+    /** Registered provider name. Resolved through `providerRegistry`, like `stream()`. */
+    provider: Provider;
+    model: string;
+    /** API key. Sent as the provider expects (Bearer token, or `x-goog-api-key` for Gemini).
+     *  Not read from the environment — pass it explicitly. */
+    apiKey?: string;
+    /** Override the provider's default API base URL (required for `local`). */
+    baseUrl?: string;
+    /** Aborts the in-flight request and skips any remaining batches. */
+    signal?: AbortSignal;
+    /** Custom fetch implementation (tests, React Native, proxies). */
+    fetch?: typeof globalThis.fetch;
+    /** Provider-specific body fields (e.g. OpenRouter's `provider` routing object).
+     *  Never overrides fields gg-ai sets; see `ProviderOptions`. */
+    providerOptions?: ProviderOptions;
+}
+interface EmbedOptions extends RetrievalRequestOptions {
+    /** Texts to embed. Any length — gg-ai splits it into provider-sized batches. */
+    input: string[];
+    /** Requested vector size, for models that support shortened embeddings.
+     *  Every returned vector is checked against it; a mismatch throws. */
+    dimensions?: number;
+    /**
+     * Whether the texts are search queries or documents being indexed. Mapped to
+     * the provider's native task parameter where one exists (Gemini `taskType`,
+     * OpenRouter `input_type`); ignored where it doesn't (OpenAI, local servers,
+     * and `gemini-embedding-2`, which takes the task as a text prefix instead).
+     */
+    inputType?: EmbedInputType;
+    /** L2-normalize every vector after validation. Default false. */
+    normalize?: boolean;
+    /** Inputs per request. Defaults to the provider's documented maximum (see README). */
+    batchSize?: number;
+}
+interface EmbedUsage {
+    /** Input tokens, summed over every batch that reported usage. */
+    inputTokens: number;
+}
+interface EmbedResult {
+    /** One vector per input, in input order. */
+    embeddings: number[][];
+    /** Model the provider reports having used (falls back to the requested model). */
+    model: string;
+    /** Present when the provider reported usage for at least one batch. */
+    usage?: EmbedUsage;
+}
+interface RerankOptions extends RetrievalRequestOptions {
+    query: string;
+    documents: string[];
+    /** Return only the best `topN` results. Default: all documents. */
+    topN?: number;
+}
+interface RerankResult {
+    /** Index into the caller's `documents` array. */
+    index: number;
+    /** Relevance score; higher is more relevant. Scale depends on the model. */
+    score: number;
+}
+interface RerankUsage {
+    inputTokens?: number;
+    /** Billing units for search-unit priced rerankers (e.g. Cohere via OpenRouter). */
+    searchUnits?: number;
+}
+interface RerankResponse {
+    /** Sorted by score, highest first. */
+    results: RerankResult[];
+    model: string;
+    usage?: RerankUsage;
+}
+/** One embedding request as a provider sees it: a single batch. */
+type ProviderEmbedRequest = Omit<EmbedOptions, "normalize" | "batchSize">;
+/** A provider's answer to one batch. `embeddings` must be in input order. */
+interface ProviderEmbedResponse {
+    embeddings: number[][];
+    model?: string;
+    usage?: EmbedUsage;
+}
+/** Embed one batch. gg-ai handles batching, validation and normalization. */
+type ProviderEmbedFn = (request: ProviderEmbedRequest) => Promise<ProviderEmbedResponse>;
+/** A rerank request as a provider sees it. `documents` is never empty. */
+type ProviderRerankRequest = RerankOptions;
+/** A provider's rerank answer. Any order; gg-ai validates, sorts and applies `topN`. */
+interface ProviderRerankResponse {
+    results: RerankResult[];
+    model?: string;
+    usage?: RerankUsage;
+}
+type ProviderRerankFn = (request: ProviderRerankRequest) => Promise<ProviderRerankResponse>;
+
+/**
+ * Create embeddings through any registered provider that offers them (see
+ * `providerRegistry.supports(name, "embed")`).
+ *
+ * - `input` may be any length: it's split into provider-sized batches, sent in
+ *   order, one at a time. `signal` aborts the in-flight batch and skips the rest.
+ * - The result has exactly one vector per input, in input order. A provider
+ *   reply with the wrong count, a non-numeric value, mixed vector lengths, or a
+ *   length other than `dimensions` throws `ProviderError` — nothing is padded
+ *   or truncated.
+ * - `normalize: true` L2-normalizes each vector (all-zero vectors stay zero).
+ * - No retries: as with `stream()`, retry policy belongs to the caller. 429s
+ *   carry `resetsAt` when the provider sends `Retry-After`; auth and billing
+ *   failures (`isUsageLimitError`) should never be retried.
+ *
+ * ```ts
+ * const { embeddings } = await embed({
+ *   provider: "openai",
+ *   model: "text-embedding-3-small",
+ *   input: ["first chunk", "second chunk"],
+ *   apiKey,
+ * });
+ * ```
+ */
+declare function embed(options: EmbedOptions): Promise<EmbedResult>;
+/**
+ * Rerank `documents` against `query` through any registered provider that
+ * offers reranking (see `providerRegistry.supports(name, "rerank")`).
+ *
+ * Results are sorted by score, highest first (ties keep document order), and
+ * `index` points into the caller's `documents`. At most `topN` results are
+ * returned. A reply with an out-of-range or duplicate index throws
+ * `ProviderError`. No retries — see `embed()`.
+ *
+ * ```ts
+ * const { results } = await rerank({
+ *   provider: "openrouter",
+ *   model: "cohere/rerank-v3.5",
+ *   query: "capital of France",
+ *   documents,
+ *   topN: 5,
+ *   apiKey,
+ * });
+ * const best = documents[results[0].index];
+ * ```
+ */
+declare function rerank(options: RerankOptions): Promise<RerankResponse>;
+
 /**
  * A provider stream function. Takes StreamOptions and returns a StreamResult.
  * Each provider implements this to handle its specific API format.
  */
 type ProviderStreamFn = (options: StreamOptions) => StreamResult;
+/** Capabilities a registered provider can offer. */
+type ProviderCapability = "stream" | "embed" | "rerank";
 /**
  * Registry entry for a provider. A provider can have a simple stream function
- * or a more complex setup with custom routing logic.
+ * or a more complex setup with custom routing logic. `embed` and `rerank` are
+ * optional: leave them out when the provider has no such API, and `embed()` /
+ * `rerank()` fail with a capability error instead.
  */
 interface ProviderEntry {
     /** Main stream function for this provider */
     stream: ProviderStreamFn;
+    /** Embed one batch of texts. Batching, ordering checks and normalization are done by `embed()`. */
+    embed?: ProviderEmbedFn;
+    /** Default inputs per embedding request (the provider's documented maximum).
+     *  Omit to send every input in one request. Callers can override with `batchSize`. */
+    embedBatchSize?: number;
+    /** Rerank documents against a query. Sorting and `topN` are applied by `rerank()`. */
+    rerank?: ProviderRerankFn;
 }
 /**
  * Map-based provider registry. Built-in providers are registered at module load,
@@ -411,6 +621,8 @@ declare class ProviderRegistryImpl {
     get(name: string): ProviderEntry | undefined;
     /** Check if a provider is registered. */
     has(name: string): boolean;
+    /** Whether a registered provider offers a capability (`false` for unknown providers). */
+    supports(name: string, capability: ProviderCapability): boolean;
     /** List all registered provider names. */
     list(): string[];
 }
@@ -473,6 +685,8 @@ declare class ProviderError extends GGAIError {
         hint?: string;
         cause?: unknown;
         resetsAt?: number;
+        /** `"auth"` for credential rejections (HTTP 401/403). Default `"provider"`. */
+        source?: "provider" | "auth";
     });
 }
 /**
@@ -727,7 +941,12 @@ declare function prewarmAnthropicCache(options: {
 }): Promise<void>;
 
 interface PalsuProviderState {
+    /** `stream()` calls served. */
     callCount: number;
+    /** Embedding requests served (one per batch). */
+    embedCallCount: number;
+    /** Rerank requests served. */
+    rerankCallCount: number;
 }
 type PalsuResponseFactory = (messages: Message[], options: StreamOptions, state: PalsuProviderState) => AssistantMessage | Promise<AssistantMessage>;
 type PalsuResponse = AssistantMessage | PalsuResponseFactory;
@@ -778,6 +997,10 @@ interface PalsuProviderConfig {
     promptCache?: boolean;
     /** Model-specific configurations with per-model response queues. */
     models?: Record<string, PalsuModelConfig>;
+    /** Vector size of the fake embeddings when the caller doesn't pass `dimensions`. Default 64. */
+    embedDimensions?: number;
+    /** Inputs per fake embedding request, to exercise batching. Default: all in one request. */
+    embedBatchSize?: number;
 }
 /**
  * Register a palsu (mock) LLM provider for testing.
@@ -794,5 +1017,13 @@ interface PalsuProviderConfig {
  * ```
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
+/**
+ * Deterministic fake embedding: a signed, hashed bag of words, L2-normalized.
+ * Texts sharing words get a higher cosine similarity, so retrieval code behaves
+ * plausibly in tests. Text with no words maps to a fixed unit vector.
+ */
+declare function palsuEmbedding(text: string, dimensions?: number): number[];
+/** Deterministic fake relevance: the share of distinct query words found in the document (0–1). */
+declare function palsuRerankScore(query: string, document: string): number;
 
-export { type AssistantMessage, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type ErrorEvent, type ErrorSource, EventStream, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderDiagnosticFn, type ProviderEntry, ProviderError, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, dropInvalidToolCalls, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };
+export { type AssistantMessage, type CacheRetention, type ChatErrorReason, type ContentPart, type DoneEvent, type EmbedInputType, type EmbedOptions, type EmbedResult, type EmbedUsage, type ErrorEvent, type ErrorSource, EventStream, type FormattedChatError, type FormattedError, GGAIError, type ImageContent, type Message, type MessageProvenance, type MessageProvenanceKind, type MessageProvenanceSource, type MessageProvenanceVisibility, type OpenRouterProviderPreferences, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type PreparedContext, type Provider, type ProviderCapability, type ProviderDiagnosticFn, type ProviderEmbedFn, type ProviderEmbedRequest, type ProviderEmbedResponse, type ProviderEntry, ProviderError, type ProviderOptions, type ProviderRerankFn, type ProviderRerankRequest, type ProviderRerankResponse, type ProviderStreamFn, REDACTED as REDACTION_MARKER, type RawContent, type RedactionOptions, type RerankOptions, type RerankResponse, type RerankResult, type RerankUsage, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, TOOL_CALL_NAME_RULES, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolCallNameRule, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, type VideoContent, clampProviderContextImages, classifyProviderError, dropInvalidToolCalls, embed, environmentSecrets, formatChatError, formatError, formatErrorForDisplay, hasLoneSurrogate, isHardBillingMessage, isUsageLimitError, isValidToolCallName, localWireModelId, palsuAssistantMessage, palsuEmbedding, palsuRerankScore, palsuText, palsuThinking, palsuToolCall, prewarmAnthropicCache, providerRegistry, redactText, redactValue, registerPalsuProvider, rerank, resolveToolSchema, sanitizeMessagesForWire, setProviderDiagnostic, sliceHead, sliceTail, stream, toAnthropicMessages, toOpenAIMessages, toWellFormedText, toolCallNameRuleFor, usesResponsesLite };