ai library

AI extension library.

This library provides abstractions for chat completion, embeddings, image generation, speech-to-text, and tool pipelines. You supply provider-specific clients and then layer cross-cutting concerns like logging, caching, or message reduction via builders.

Example: build a simple chat pipeline and send a message.

import 'package:extensions/ai.dart';

class EchoChatClient implements ChatClient {
  @override
  Future<ChatResponse> getResponse({
    required Iterable<ChatMessage> messages,
    ChatOptions? options,
    CancellationToken? cancellationToken,
  }) async {
    final last = messages.last.text;
    return ChatResponse.fromMessage(
      ChatMessage.fromText(ChatRole.assistant, 'Echo: $last'),
    );
  }

  @override
  Stream<ChatResponseUpdate> getStreamingResponse({
    required Iterable<ChatMessage> messages,
    ChatOptions? options,
    CancellationToken? cancellationToken,
  }) async* {}

  @override
  void dispose() {}
}

Future<void> main() async {
  final client = ChatClientBuilder(EchoChatClient()).build();
  final response = await client.getResponse(
    messages: [ChatMessage.fromText(ChatRole.user, 'Hello')],
  );
  print(response.text);
}

Classes

AIAnnotation: Base class for annotations on AI content.
AIContent: Base class for all AI content types.
AIFunction: Represents a function that can be described to and invoked by an AI model.
AIFunctionArguments: Represents the arguments passed to an AI function invocation.
AIFunctionDeclaration: Represents a function that can be described to an AI service.
AIFunctionFactory: A factory for creating AIFunction instances from simple callbacks.
AIFunctionFactoryOptions: Options for controlling how AIFunctionFactory creates an AIFunction.
AITool: Base class for tools that can be provided to an AI model.
AnnotatedRegion: Base class for annotated regions.
AnonymousDelegatingChatClient: A DelegatingChatClient that uses anonymous delegates to implement its functionality.
ApprovalRequiredAIFunction: An AIFunction that is marked as requiring user approval before invocation.
AutoChatToolMode: Indicates that a chat client is free to select any of the available tools, or none at all.
BLEUAlgorithm: Static helpers for computing BLEU scores.
BLEUEvaluator: Evaluates response quality using the BLEU (Bilingual Evaluation Understudy) algorithm.
BLEUEvaluatorContext: Contextual information for BLEUEvaluator: one or more reference responses to compare against.
BooleanMetric: An EvaluationMetric with a boolean value (pass/fail or yes/no).
CachingChatClient: An abstract DelegatingChatClient that caches chat responses.
ChatClient: Represents a chat client.
ChatClientBuilder: Builds a pipeline of chat client middleware.
ChatClientMetadata: Provides metadata about a chat client.
ChatConfiguration: Specifies the ChatClient to use when evaluation is performed by an AI model.
ChatDetails: Records details for all LLM chat turns in a ScenarioRun execution.
ChatFinishReason: Represents the reason a chat response finished being generated.
ChatMessage: Represents a chat message used by a chat client.
ChatOptions: Represents the options for a chat request.
ChatReducer: Reduces a list of chat messages (e.g. for context window management).
ChatResponse: Represents the response to a chat request.
ChatResponseFormat: Represents the desired format of a chat response.
ChatResponseFormatJson: Requests structured JSON output without a specific schema.
ChatResponseFormatJsonSchema: Requests structured JSON output conforming to a specific schema.
ChatResponseFormatText: Requests unstructured text output.
ChatResponseUpdate: Represents a single streaming update to a chat response.
ChatRole: Represents the role of a chat message author.
ChatToolMode: Represents the mode in which tools are used by the chat client.
ChatTurnDetails: Details for a single LLM chat conversation turn in a ScenarioRun.
CitationAnnotation: An annotation citing a source.
CodeInterpreterToolCallContent: Represents a code interpreter tool call invoked by a hosted service.
CodeInterpreterToolResultContent: Represents the result of a code interpreter tool invocation by a hosted service.
CodeVulnerabilityEvaluator: Evaluates AI responses for code vulnerabilities (e.g. injection flaws).
CoherenceEvaluator: Evaluates the coherence of an AI response — logical organization, flow, and readability.
CompletenessEvaluator: Evaluates how completely an AI response covers the key information in a ground truth reference.
CompletenessEvaluatorContext: Context for CompletenessEvaluator: the ground truth response against which completeness is measured.
CompositeEvaluator: An Evaluator that composes multiple Evaluators and runs them concurrently.
ConfigureOptionsChatClient: A delegating chat client that applies configuration to ChatOptions before each request.
ConfigureOptionsEmbeddingGenerator: A delegating embedding generator that applies configuration to EmbeddingGenerationOptions before each request.
ConfigureOptionsImageGenerator: A delegating image generator that applies configuration to ImageGenerationOptions before each request.
ConfigureOptionsSpeechToTextClient: A delegating speech-to-text client that applies configuration to SpeechToTextOptions before each request.
ConfigureOptionsTextToSpeechClient: A DelegatingTextToSpeechClient that applies a configuration callback to TextToSpeechOptions before each request.
ContentHarmEvaluator: Evaluates AI responses for all supported content harm categories: hate/unfairness, violence, self-harm, and sexual content.
ContentSafetyEvaluator: Base class for evaluators that call the Azure AI Foundry Evaluation service to detect unsafe content.
ContentSafetyServiceConfiguration: Configuration for connecting to the Azure AI Foundry Evaluation service.
DataContent: Represents binary data content, such as an image or audio.
DelegatingAIFunction: An AIFunction that delegates all calls to an inner function.
DelegatingAIFunctionDeclaration: An AIFunctionDeclaration that delegates its properties to an inner declaration.
DelegatingChatClient: Provides an optional base class for an ChatClient that passes through calls to another instance.
DelegatingEmbeddingGenerator: An EmbeddingGenerator that delegates all calls to an inner generator.
DelegatingHostedFileClient: A HostedFileClient that delegates all calls to an inner client.
DelegatingImageGenerator: An ImageGenerator that delegates all calls to an inner generator.
DelegatingSpeechToTextClient: A SpeechToTextClient that delegates all calls to an inner client.
DelegatingTextToSpeechClient: A TextToSpeechClient that delegates all calls to an inner client.
DiskBasedReportingConfiguration: Factory for a fully disk-backed ReportingConfiguration.
DiskBasedResponseCache: A ResponseCache that persists ChatResponses as JSON files on disk.
DiskBasedResponseCacheProvider: An EvaluationResponseCacheProvider that stores response caches on disk.
DiskBasedResultStore: Stores ScenarioRunResults as JSON files under storageRootPath.
Embedding: Represents a generated embedding vector.
EmbeddingGenerationOptions: Options for embedding generation requests.
EmbeddingGenerator: Represents an embedding generator.
EmbeddingGeneratorBuilder: Builds a pipeline of embedding generator middleware.
EmbeddingGeneratorMetadata: Provides metadata about an embedding generator.
EquivalenceEvaluator: Evaluates whether an AI response is semantically equivalent to a ground truth reference.
EquivalenceEvaluatorContext: Context for EquivalenceEvaluator: the expected ground-truth response.
ErrorContent: Represents error content in a chat response.
EvaluationContext: Base class for contextual information beyond the conversation history that an Evaluator may need to accurately evaluate a response.
EvaluationDiagnostic: A diagnostic message associated with an EvaluationMetric.
EvaluationMetric: Base class for all evaluation metric results.
EvaluationMetricInterpretation: Specifies how an EvaluationMetric's result should be interpreted.
EvaluationResponseCacheProvider: Provides ResponseCache instances scoped to a particular scenario run.
EvaluationResult: A collection of EvaluationMetrics representing the result of an evaluation run.
EvaluationResultStore: Stores and retrieves ScenarioRunResults from a backing store.
Evaluator: Evaluates AI model responses and returns EvaluationResults.
F1Algorithm: Computes word-overlap F1 scores.
F1Evaluator: Evaluates response quality using F1 scoring (shared word ratio).
F1EvaluatorContext: Contextual information for F1Evaluator: a single ground-truth reference response.
FluencyEvaluator: Evaluates the fluency of an AI response — grammar, vocabulary, and clarity of written communication.
FunctionCallContent: Represents a request from the model to invoke a function.
FunctionInvocationContext: Provides context for a function invocation within a chat client pipeline.
FunctionInvocationResult: The result of a function invocation.
FunctionInvokingChatClient: A delegating chat client that automatically invokes functions requested by the model.
FunctionResultContent: Represents the result of a function call.
GeneratedEmbeddings: Represents a collection of generated embeddings.
GLEUAlgorithm: Computes Google-BLEU (GLEU) scores.
GLEUEvaluator: Evaluates response quality using Google-BLEU (GLEU) n-gram overlap.
GLEUEvaluatorContext: Contextual information for GLEUEvaluator: one or more reference responses to compare against.
GroundednessEvaluator: Evaluates how well an AI response is grounded in provided context, without introducing unsupported information.
GroundednessEvaluatorContext: Context for GroundednessEvaluator: the grounding information against which fidelity is measured.
GroundednessProEvaluator: Enterprise-grade groundedness evaluator using the Azure AI Foundry service.
GroundednessProEvaluatorContext: Context for GroundednessProEvaluator: the grounding information against which response fidelity is assessed.
HateAndUnfairnessEvaluator: Evaluates AI responses for hate speech and unfairness.
HostedCodeInterpreterTool: A tool representing a hosted code interpreter capability.
HostedFileClient: A client for uploading, downloading, and managing files hosted by an AI service.
HostedFileClientBuilder: Builds a pipeline of HostedFileClient middleware.
HostedFileClientMetadata: Provides metadata about a HostedFileClient.
HostedFileClientOptions: Options for HostedFileClient requests.
HostedFileContent: Represents a reference to a file hosted by the AI service.
HostedFileSearchTool: A tool representing a hosted file search capability.
HostedImageGenerationTool: A tool representing a hosted image generation capability.
HostedMcpServerTool: A tool representing a hosted MCP server.
HostedMcpServerToolAlwaysRequireApprovalMode: Always require approval for MCP server tool calls.
HostedMcpServerToolApprovalMode: Approval mode for hosted MCP server tools.
HostedMcpServerToolNeverRequireApprovalMode: Never require approval for MCP server tool calls.
HostedMcpServerToolRequireSpecificApprovalMode: Require approval for specific MCP server tool calls.
HostedToolSearchTool: A marker tool that enables on-demand tool discovery from a hosted service.
HostedVectorStoreContent: Represents a reference to a vector store hosted by the AI service.
HostedWebSearchTool: A tool representing a hosted web search capability.
ImageGeneratingChatClient: A DelegatingChatClient that handles image generation tool calls by delegating to an ImageGenerator.
ImageGenerationOptions: Options for image generation requests.
ImageGenerationRequest: Represents an image generation request.
ImageGenerationResponse: Represents an image generation response.
ImageGenerationToolCallContent: Represents an image generation tool call invoked by a hosted service.
ImageGenerationToolResultContent: Represents the result of an image generation tool invocation by a hosted service.
ImageGenerator: Represents an image generator.
ImageGeneratorBuilder: Builds a pipeline of image generator middleware.
ImageGeneratorMetadata: Provides metadata about an image generator.
IndirectAttackEvaluator: Evaluates AI responses for indirect prompt injection attacks.
InputRequestContent: Represents a request for input from the user or application.
InputResponseContent: Represents the response to an InputRequestContent.
IntentResolutionEvaluator: Evaluates how effectively an AI system identifies and resolves user intent.
IntentResolutionEvaluatorContext: Context for IntentResolutionEvaluator: the tool definitions used when generating the response.
LoggingChatClient: A delegating chat client that logs chat operations to an Logger.
LoggingEmbeddingGenerator: A delegating embedding generator that logs operations to a Logger.
LoggingHostedFileClient: A DelegatingHostedFileClient that logs file operations.
LoggingImageGenerator: A delegating image generator that logs operations to a Logger.
LoggingSpeechToTextClient: A delegating speech-to-text client that logs operations to a Logger.
LoggingTextToSpeechClient: A DelegatingTextToSpeechClient that logs requests and responses.
McpServerToolCallContent: Represents a tool call request to an MCP server by a hosted service.
MCPServerToolResultContent: Represents the result of an MCP server tool call by a hosted service.
MessageCountingChatReducer: A chat reducer that keeps the most recent messages up to a target count.
NGram<T>: An n-gram: a contiguous sequence of n tokens.
NoneChatToolMode: No tools should be used by the model.
NumericMetric: An EvaluationMetric with a numeric value.
OpenTelemetryChatClient: A DelegatingChatClient that records OpenTelemetry spans for each request.
OpenTelemetryConsts: Semantic convention constants for AI telemetry spans and attributes.
OpenTelemetryEmbeddingGenerator: A DelegatingEmbeddingGenerator that records OpenTelemetry spans.
OpenTelemetryImageGenerator: A DelegatingImageGenerator that records OpenTelemetry spans.
OpenTelemetryTextToSpeechClient: A DelegatingTextToSpeechClient that records OpenTelemetry spans.
ProtectedMaterialEvaluator: Evaluates AI responses for copyrighted or otherwise protected material.
QualityEvaluatorBase: Shared evaluation loop for AI-based quality evaluators (1–5 scale).
ReasoningOptions: Options for configuring reasoning behavior in chat requests.
ReducingChatClient: A DelegatingChatClient that reduces chat messages before forwarding requests to the inner client.
RelevanceEvaluator: Evaluates how well an AI response addresses the user's question.
RelevanceTruthAndCompletenessEvaluator: Evaluates an AI response on three dimensions — Relevance, Truth, and Completeness — in a single model call, returning one NumericMetric per dimension (each scored 1–5).
RelevanceTruthAndCompletenessRating: The structured JSON response from RelevanceTruthAndCompletenessEvaluator.
ReportingConfiguration: Bundles all configuration needed to create ScenarioRun instances for an evaluation batch.
RequiredChatToolMode: The model must call at least one tool.
ResponseCache: A key-value cache for ChatResponses used during evaluation.
ResponseCachingChatClient: A CachingChatClient that persists responses to a ResponseCache and records per-turn latency and usage in a ChatDetails object.
ResponseContinuationToken: Represents a token that can be used to resume an interrupted response.
RetrievalEvaluator: Evaluates how well the retrieved context chunks are relevant to the user request and ranked appropriately.
RetrievalEvaluatorContext: Context for RetrievalEvaluator: the retrieved context chunks to assess.
ScenarioRun: Orchestrates the evaluation of a single iteration of a scenario.
ScenarioRunResult: The persisted result of a single ScenarioRun evaluation.
SelfHarmEvaluator: Evaluates AI responses for self-harm advocacy.
SexualEvaluator: Evaluates AI responses for sexual content.
SimpleWordTokenizer: Tokenizes text using rules inspired by the NLTK word tokenizer.
SpeechToTextClient: Represents a speech-to-text client.
SpeechToTextClientBuilder: Builds a pipeline of speech-to-text client middleware.
SpeechToTextClientMetadata: Provides metadata about a speech-to-text client.
SpeechToTextOptions: Options for speech-to-text requests.
SpeechToTextResponse: Represents a speech-to-text response.
SpeechToTextResponseUpdate: Represents a streaming update from a speech-to-text operation.
SpeechToTextResponseUpdateKind: The kind of a speech-to-text response update.
StringMetric: An EvaluationMetric with a string value.
SummarizingChatReducer: A ChatReducer that summarizes older messages using a ChatClient.
TaskAdherenceEvaluator: Evaluates how accurately an AI system adhered to its assigned task, instructions, and any tool use.
TaskAdherenceEvaluatorContext: Context for TaskAdherenceEvaluator: the tool definitions used when generating the response.
TextContent: Represents text content in a chat message.
TextReasoningContent: Represents reasoning or "thinking" content from an AI model.
TextSpanAnnotatedRegion: An annotated region defined by character span indices.
TextToSpeechClient: Represents a text-to-speech client.
TextToSpeechClientBuilder: Builds a pipeline of text-to-speech client middleware.
TextToSpeechClientMetadata: Provides metadata about a TextToSpeechClient.
TextToSpeechOptions: Options for text-to-speech requests.
TextToSpeechResponse: The result of a text-to-speech request.
TextToSpeechResponseUpdate: A single streaming response chunk from a TextToSpeechClient.
ToolApprovalRequestContent: Represents a request for approval before a tool call is executed.
ToolApprovalResponseContent: Represents a response to a ToolApprovalRequestContent, indicating whether the tool call was approved.
ToolCallAccuracyEvaluator: Evaluates how accurately an AI system used the tools available to it, examining relevance, parameter correctness, and value extraction accuracy.
ToolCallAccuracyEvaluatorContext: Context for ToolCallAccuracyEvaluator: the tool definitions used when generating the response.
ToolCallContent: Base class for content types that represent a tool call request.
ToolReductionStrategy: Represents a strategy capable of selecting a reduced set of tools for a chat request.
ToolResultContent: Base class for content types that represent the result of a tool call.
UngroundedAttributesEvaluator: Evaluates AI responses for ungrounded protected-class attributes or emotional state inferences.
UngroundedAttributesEvaluatorContext: Context for UngroundedAttributesEvaluator: the grounding information used to assess whether the response contains ungrounded attributes.
UriContent: Represents content referenced by a URI.
UsageContent: Content representing usage information.
UsageDetails: Provides usage details about a request/response.
ViolenceEvaluator: Evaluates AI responses for violent content.
WebSearchToolCallContent: Represents a web search tool call invoked by a hosted service.
WebSearchToolResultContent: Represents the result of a web search tool invocation by a hosted service.

Enums

EvaluationDiagnosticSeverity: Severity of an EvaluationDiagnostic.
EvaluationRating: Identifies how the result of an evaluation should be interpreted.
FunctionInvocationStatus: The status of a function invocation.
ReasoningEffort: Specifies the level of reasoning effort to apply when generating responses.
ReasoningOutput: Specifies how reasoning content should be included in the response.

Extensions

AIContentExtensions on Iterable<AIContent>: Extensions for working with collections of AIContent.
ChatClientBuilderServiceCollectionExtensions on ServiceCollection: Provides extension methods for working with ChatClient in the context of ChatClientBuilder.
ChatClientExtensions on ChatClient: Convenience extension methods on ChatClient.
EvaluationMetricExtensions on EvaluationMetric: Extension methods for EvaluationMetric.
FunctionInvokingChatClientBuilderExtensions on ChatClientBuilder: Extension methods for adding FunctionInvokingChatClient to a pipeline.
NGramListExtensions on List<T>: Extension methods for creating n-grams from token lists.
NumericMetricInterpretationExtensions on NumericMetric: Score interpretation helpers for NumericMetric.
OpenTelemetryChatClientBuilderExtensions on ChatClientBuilder: Extension methods for adding OpenTelemetryChatClient to a pipeline.
OpenTelemetryEmbeddingGeneratorBuilderExtensions on EmbeddingGeneratorBuilder: Extension methods for adding OpenTelemetryEmbeddingGenerator to a pipeline.
OpenTelemetryImageGeneratorBuilderExtensions on ImageGeneratorBuilder: Extension methods for adding OpenTelemetryImageGenerator to a pipeline.
OpenTelemetryTextToSpeechClientBuilderExtensions on TextToSpeechClientBuilder: Extension methods for adding OpenTelemetryTextToSpeechClient to a pipeline.
QualityMessageListExtensions on List<ChatMessage>: Finds the last user message in a list.

Typedefs

AdditionalPropertiesDictionary = Map<String, Object?>: A dictionary of additional properties.
ChatClientFactory = ChatClient Function(ChatClient innerClient): A factory that creates middleware by wrapping an inner ChatClient.
ChatClientFactoryWithServices = ChatClient Function(ChatClient innerClient, ServiceProvider services): A factory that creates middleware by wrapping an inner ChatClient and receiving the active ServiceProvider.
ChatClientResponseHandler = Future<ChatResponse> Function(Iterable<ChatMessage> messages, ChatOptions? options, ChatClient innerClient, CancellationToken? cancellationToken): A function that handles a chat response request.
ChatClientSharedDelegate = Future<void> Function(Iterable<ChatMessage> messages, ChatOptions? options, Future<void> next(Iterable<ChatMessage> messages, ChatOptions? options, CancellationToken? cancellationToken), CancellationToken? cancellationToken): Delegate used to wrap both non-streaming and streaming operations.
ChatClientStreamingResponseHandler = Stream<ChatResponseUpdate> Function(Iterable<ChatMessage> messages, ChatOptions? options, ChatClient innerClient, CancellationToken? cancellationToken): A function that handles a streaming chat response request.
ConfigureFunctionInvokingChatClient = void Function(FunctionInvokingChatClient client)
InnerClientFactory = ChatClient Function(ServiceProvider services)
InnerEmbeddingGeneratorFactory = EmbeddingGenerator Function(ServiceProvider services): A factory that creates an EmbeddingGenerator from a ServiceProvider.
InnerHostedFileClientFactory = HostedFileClient Function(ServiceProvider services): A factory that creates a HostedFileClient from a ServiceProvider.
InnerImageGeneratorFactory = ImageGenerator Function(ServiceProvider services): A factory that creates an ImageGenerator from a ServiceProvider.
InnerSpeechToTextClientFactory = SpeechToTextClient Function(ServiceProvider services): A factory that creates a SpeechToTextClient from a ServiceProvider.
InnerTextToSpeechClientFactory = TextToSpeechClient Function(ServiceProvider services): A factory that creates a TextToSpeechClient from a ServiceProvider.

ai library

Classes

Enums

Extensions

Typedefs

extensions package

ai library