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
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.Service 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
Servicefor the service shape returned by this constructorProviderOptionsfor the input passed to the provider implementationProviderResponsefor the provider response contract consumed by this constructor
Signature
declare const make: (params: {
readonly embedMany: (
options: ProviderOptions,
) => Effect.Effect<ProviderResponse, AiError.AiError>;
}) => Effect.Effect<Service>;Models
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
EmbedResponsefor individual embedding responsesEmbeddingUsagefor 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;
};
}Defines the service interface for embedding operations.
Signature
interface Service {
readonly embed: (input: string) => Effect<EmbedResponse, AiError>;
readonly embedMany: (input: readonly Array<string>) => Effect<EmbedManyResponse, AiError>;
readonly resolver: RequestResolver<EmbeddingRequest>;
}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
EmbeddingModelfor the embedding service that uses these dimensions
Signature
declare class Dimensions extends Shape<
"effect/unstable/ai/EmbeddingModel/Dimensions",
number,
this
> {
constructor(_: never);
}EmbeddingModel
Service tag for embedding model operations.
When to use
Use to retrieve or provide the embedding model service for an Effect program that embeds text into vectors.
See
Servicefor the service contract provided by this tagmakefor constructing an embedding model service from a providerDimensionsfor the current embedding vector size service
Signature
declare class EmbeddingModel extends Shape<"effect/unstable/ai/EmbeddingModel", Service, this> {
constructor(_: never);
}
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
Servicefor the resolver-bearing service contractmakefor constructing the request resolver from a provider implementationEmbedResponsefor the response produced by this request