EmbeddingBatch

Models & Types · AiDotNet.Agentic.Embeddings

The outcome of one embedding request: either every vector, or an explicit bounded failure.

For Beginners

When you ask a provider to turn text into vectors, the call can fail. This type says clearly which happened: Succeeded true with one vector per input, or false with a short reason. Because the failure is explicit you can decide what a failure means for your run instead of silently getting back something that looks like a valid but meaningless answer.

How It Works

A batch is a discriminated outcome rather than a possibly-empty list. The reference implementation returns an empty vector (in fact a (list, float) tuple, which does not match its own declared return type) when a request fails, stores that value on the program record, and lets every later cosine comparison against it return zero — so one transient network error both fails open for the current decision and permanently poisons that record’s similarity for the rest of the run. Here a failure is a value the caller must look at: nothing is cached, nothing is stored, and the caller decides whether to fail open or closed.

FailureReason is bounded and carries only a status code or an exception type name. A provider’s response body can echo request content or an authorization header, so it never reaches this string, a log, or a prompt.

Properties

Property Summary
IReadOnlyList<EmbeddingVector> Vectors { get; } Gets the vectors, in the order the inputs were supplied; empty when the request failed.
bool Succeeded { get; } Gets whether the request produced a vector for every input.
string FailureReason { get; } Gets the bounded failure reason, or an empty string when the request succeeded.

Methods

Method Summary
EmbeddingBatch Failure(string reason) Creates a failed batch carrying a bounded reason.
EmbeddingBatch Success(IEnumerable<EmbeddingVector> vectors) Creates a successful batch.
string ToString() Returns the outcome and vector count, never the components.

Fields

Field Summary
int MaxFailureReasonLength The longest failure reason retained, in characters.