EmbeddingModel
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
Represents 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.
Gotchas
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 embedMany: (options: ProviderOptions) => Effect.Effect<ProviderResponse, AiError.AiError>;}) => Effect.Effect<EmbeddingModel>Models
EmbeddingModel interface
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
Represents 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
Response 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
Response 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]);}ProviderResponse interface
Provider response for batch embedding requests.
Signature
interface ProviderResponse { readonly results: Array<Array<number>>; readonly usage: { readonly inputTokens: number | undefined; };}Options
ProviderOptions interface
Provider input options for embedding requests.
Signature
interface ProviderOptions { readonly inputs: readonly Array<string>;}Services
Dimensions
Service 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/unstable/ai/EmbeddingModel/Dimensions", number, this> { constructor(_: never);}EmbeddingModel
Service 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>