EmbeddingModel unstable
Defines the provider-neutral service for text embeddings.
An EmbeddingModel turns text into numeric vectors. It supports single-input
embedding and ordered batch embedding, and represents provider failures as
AiError values. This module also includes the embedding dimensions service,
request and response models, usage metadata, provider contracts, and a
constructor that adapts a provider batch implementation into the service.
Single embed calls can be batched together internally.
Constructors
EmbeddingRequest
unstableRepresents a tagged request used by request resolvers for embedding operations.
When to use
Use when you need a typed request for one embedding input while building or calling a low-level embedding request resolver.
See
- EmbeddingModel for the resolver-bearing service contract
- make for constructing the request resolver from a provider implementation
- EmbedResponse for the response produced by this request
Signature
declare class EmbeddingRequest extends Request<EmbedResponse, AiError, never, this> & Readonly<{ readonly input: string;}> & { readonly _tag: "EmbeddingRequest";} { constructor(args: { readonly input: string; });}Creates an EmbeddingModel service from a provider embedMany implementation.
When to use
Use to adapt a provider's batch embedding implementation into an
EmbeddingModel that offers single-input and batch embedding
operations.
Details
The returned service builds single-input embed calls through a request
resolver, so concurrent embed requests can be batched into one provider
embedMany call. Direct embedMany calls pass the input array to the
provider, while embedMany([]) returns an empty response without calling the
provider.
Concurrent embed calls share one embedMany call when batchKey returns
equal keys under Equal.equals. The batch runs with the first caller's
context, so return every value embedMany reads from that context. Without
batchKey, all callers share one batch.
Gotchas
Context that batchKey does not return is not isolated. Per-call
FetchHttpClient.RequestInit, or any service read by an injected HTTP
client, takes the first caller's value for the whole batch.
Provider responses are interpreted positionally and must contain exactly one
result for each requested input. If the provider returns a different number
of results, embed and embedMany fail with AiError.InvalidOutputError.
See
- EmbeddingModel for the service shape returned by this constructor
- ProviderOptions for the input passed to the provider implementation
- ProviderResponse for the provider response contract consumed by this constructor
Signature
declare const make: (params: { readonly batchKey?: (context: Context.Context<never>) => unknown; readonly embedMany: (options: ProviderOptions) => Effect.Effect<ProviderResponse, AiError.AiError>;}) => Effect.Effect<EmbeddingModel>Models
Single-input and batch embedding operations.
Signature
interface EmbeddingModel { readonly "~effect/ai/EmbeddingModel": "~effect/ai/EmbeddingModel"; readonly embed: (input: string) => Effect<EmbedResponse, AiError>; readonly embedMany: (input: readonly Array<string>) => Effect<EmbedManyResponse, AiError>; readonly resolver: RequestResolver<EmbeddingRequest>;}EmbeddingUsage
unstableRepresents token usage metadata for embedding operations.
Details
Contains optional provider-reported inputTokens. The value may be
undefined when the provider does not report usage or when embedMany([])
bypasses the provider.
Signature
declare class EmbeddingUsage extends { readonly inputTokens?: number;} { constructor(...args: [props?: { readonly inputTokens?: number; }, options?: MakeOptions]);}EmbedManyResponse
unstableResponse for batch embedding requests containing per-input embeddings and usage metadata.
Details
embeddings preserves batch order, and usage carries token metadata for
the operation.
See
- EmbedResponse for individual embedding responses
- EmbeddingUsage for token usage metadata
Signature
declare class EmbedManyResponse extends { readonly embeddings: readonly Array<EmbedResponse>; readonly usage: EmbeddingUsage;} { constructor(...args: [props: { readonly embeddings: readonly Array<EmbedResponse>; readonly usage: EmbeddingUsage; }, options?: MakeOptions]);}EmbedResponse
unstableResponse for a single embedding request.
Signature
declare class EmbedResponse extends { readonly vector: readonly Array<number>;} { constructor(...args: [props: { readonly vector: readonly Array<number>; }, options?: MakeOptions]);}Provider response for batch embedding requests.
Signature
interface ProviderResponse { readonly results: Array<Array<number>>; readonly usage: { readonly inputTokens: number | undefined; };}Options
Provider input options for embedding requests.
Signature
interface ProviderOptions { readonly inputs: readonly Array<string>;}Services
Dimensions
unstableService tag that provides the current embedding dimensions.
When to use
Use to retrieve or provide the configured embedding vector size through context.
See
- EmbeddingModel for the embedding service that uses these dimensions
Signature
declare class Dimensions extends Shape<"effect/ai/EmbeddingModel/Dimensions", number, this> { constructor(_: never);}EmbeddingModel
unstableService key for embedding text into vectors.
See
- make for constructing an embedding model service from a provider
- Dimensions for the current embedding vector size service
Signature
declare const EmbeddingModel: Context.Service<EmbeddingModel, EmbeddingModel>