Expand description
A small, provider-neutral AI SDK designed for learning.
The important idea in this crate is the split between:
- an internal message model that can represent messy agent histories;
- a normalization layer that turns that model into a clean, strict provider-facing conversation;
- provider adapters that only serialize the normalized form.
This keeps role conversion and tool-call repair in one place.
The crate intentionally stops at the model request/response boundary.
Conversation loops, tool execution, permissions, and agent scheduling belong
to the downstream application. See examples/minimal_agent.rs for a small
runtime built only from the public API.
Structs§
- Anthropic
- Entry point for Anthropic adapters.
- Anthropic
Messages - Adapter for
POST /v1/messages. - Audit
Config - Controls which structured transport events are emitted.
- Audit
Stats - Runtime counters for a bounded audit channel.
- Audit
Stats Snapshot - A point-in-time copy of
AuditStatscounters. - Byte
Counts - Content-free request and response byte counts.
- Cancellation
Token - A cloneable cooperative cancellation handle.
- Capabilities
- Capability switches used to reject requests before they reach a provider.
- Chat
Request - A request sent to a model adapter.
- Chat
Response - A normalized model response.
- Client
Info - Product identity attached to requests.
- Completion
Report - A stable summary of transformations applied while preparing or decoding a model request.
- Custom
Tool Accumulator - Accumulates a single custom call; deltas are fragments and done inputs are authoritative snapshots. Identical completion snapshots are idempotent.
- Effort
Mapping - Provider-specific translation for neutral reasoning effort values.
- Endpoint
Adapter - A protocol-dispatching adapter for explicitly configured endpoints.
- Endpoint
Spec - Explicit description of one HTTP endpoint.
- Gemini
- Entry point for Gemini adapters.
- Gemini
Generate Content - Adapter for
POST /v1beta/models/{model}:generateContent. - Header
Policy - Header names that an application must explicitly opt into overriding.
- Image
Part - A multimodal image input.
- Image
Url - Image input used by multimodal messages.
- Message
- A message in the internal conversation model.
- Model
Profile - Model-level policy selected after the endpoint protocol is known.
- Native
Tool Call - Original call identity and input, independent of a canonical tool call.
- Native
Tool Identity - Identity fields as they become available across streamed frames.
- Normalize
Options - Rules used by the normalization layer.
- Normalize
Profile - Normalization behavior attached to a provider profile.
- Normalize
Report - Details about normalization. Callers can log this while learning.
- Normalize
Stats - Context-free aggregate of normalization repairs.
- Normalized
Chat - A provider-facing conversation.
- Normalized
Message - A provider-facing message after role downgrade and tool-pair repair.
- OpenAI
- Entry point for OpenAI-compatible adapters.
- OpenAI
Chat - Adapter for
POST /v1/chat/completions. - OpenAI
Responses - Adapter for
POST /v1/responses. - Profile
Audit Snapshot - Non-content configuration snapshot for diagnostics.
- Profile
Id - Stable identifier for a provider profile.
- Profile
Registry - Explicit registry for built-in behavior profiles.
- Provider
Error Info - Safe, provider-neutral summary of a structured error response.
- Provider
Profile - Provider-level defaults and behavior switches.
- Provider
Request Options - Typed provider request switches that are common across compatible APIs.
- Provider
State - Opaque state needed to replay provider-specific content.
- Reasoning
- Provider-neutral reasoning content.
- Reasoning
Aliases - Names observed in provider responses for each neutral reasoning category.
- Reasoning
Capabilities - Reasoning feature switches for a provider.
- Reasoning
Config - Provider-neutral reasoning request configuration.
- Reasoning
Profile - Reasoning-related defaults for a provider.
- Request
Context - Per-request context. It is intentionally not automatically mapped to
provider-specific headers such as
x-sessionid. - Request
Options - Per-request transport options.
- Request
Profile - Request fields that are applied before per-call
extra_*values. - Request
Timing - Timing measured from the start of one logical request.
- Response
Limits - Bounds decoded provider data across all attempts of a logical request.
- Response
Metadata - HTTP metadata associated with a model response.
- Retry
Directive - A parsed server-directed retry instruction.
- Retry
Policy - Controls how transient errors are retried.
- Server
Tool Item - Opaque provider-hosted tool item returned by a provider.
- SseMessage
- A parsed SSE message.
- SseParser
- Incremental, zero-I/O SSE parser.
- Stream
Capabilities - Streaming feature switches for a provider.
- Stream
Error - Stable, content-free metadata for a recoverable stream error.
- Stream
Profile - Streaming behavior for a provider.
- Stream
Reconnect Policy - Opt-in transport reconnect policy for an already-started SSE stream.
- Tool
Call - A tool call requested by the model.
- Tool
Capabilities - Tool-call feature switches for a provider.
- Tool
Profile - Tool-call encoding behavior for a provider.
- Tool
Result - A tool result that will be sent back to the model.
- Tool
Spec - A provider-neutral tool definition.
- Transport
Config - Shared transport defaults for an adapter.
- Usage
- Token usage reported by a provider.
- Usage
Profile - Usage reporting behavior for a provider.
- Wire
Report - Provider-wire transformations that could not be represented losslessly.
Enums§
- Audit
Event - A structured, context-free audit event.
- Audit
Outcome - The final outcome of an attempt or request.
- Auth
Style - How the generic adapter authenticates a request.
- Custom
Tool Format - Input accepted by a client-executed custom tool.
- Error
- The error type returned by this crate’s public API.
- Error
Kind - Stable high-level classification for SDK errors.
- External
Role - Roles that are safe to send to a provider adapter.
- First
Token Kind - Which model output started the stream.
- Image
Detail - Processing-detail hint for image inputs.
- Image
Source - A provider-neutral image source.
- MaxTokens
Semantics - Which request field carries the maximum output token limit.
- Missing
Tool Result Policy - What to do when an assistant tool call has no result.
- Model
Matcher - Selects which model names a
ModelProfileapplies to. - Native
Tool Completion - Whether the protocol has reliably finished delivering a call.
- Native
Tool Kind - The original wire representation of a client-executed tool call.
- Native
Tool Payload - Raw input, kept separate from application-specific canonical arguments.
- Normalize
Action - A human-readable trace of every repair made at the boundary.
- Orphan
Tool Result Policy - What to do with a tool result that has no matching assistant tool call.
- Part
- A piece of a message.
- Profile
Selector - Which profile implementation should be used for an endpoint.
- Protocol
- The provider-facing protocol we are preparing a request for.
- Protocol
Surface - Protocol surface of an endpoint, re-exported from the normalize module.
- Provider
State Format - The wire format that owns an opaque provider state.
- Reasoning
Effort - A provider-neutral reasoning-effort level.
- Reasoning
Kind - The main display category of a reasoning item.
- Reasoning
Mode - High-level mode for providers that expose enable/disable controls.
- Reasoning
Replay Policy - Whether and how reasoning state captured from a response is replayed on follow-up requests.
- Reasoning
Summary - How much reasoning detail the provider should expose.
- Response
Format - Provider-neutral output format for one request.
- Retry
Provider - Provider family used to decide which vendor-specific reset headers to read.
- Retry
Source - Where a retry delay came from. This is useful for logs and debugging.
- Role
- The role used inside your application.
- Scoped
Tool Declaration - A client-executed tool within a declaration scope.
- Server
Tool - A provider-hosted tool declaration.
- Server
Tool State - Generic state of a provider-hosted tool.
- SseError
- Errors that can occur while parsing an SSE stream.
- SseEvent
- An event emitted by
SseParser. - SseUtf8
Policy - How invalid UTF-8 in field values is handled.
- Stream
Event - A provider-neutral streaming event.
- Stream
Terminal - The event that marks the end of a provider’s response stream.
- System
Placement - How
System/Developermessages are placed by normalization. - Tail
Policy - How an incomplete trailing event is handled by
SseParser::finish. - Thinking
Request Profile - How a neutral thinking configuration is encoded into a provider request.
- Tool
Call Content Mode - How an assistant tool-call message should encode empty content.
- Tool
Call IdPolicy - How tool-call identifiers are handled when translating between protocols.
- Tool
Choice - Provider-neutral tool selection for one request.
- Tool
Declaration - A flat client tool or a single-level namespace of client tools.
- Tool
Result Part - A structured tool-result payload.
- Usage
Placement - Where usage (token counts) appears in a streamed response.
- Wire
Action - Wire
Feature
Constants§
- SDK_
USER_ AGENT - Default
User-Agentvalue, e.g.mutil-ai/0.1.0.
Traits§
- Audit
Sink - Receives context-free audit events.
- Header
Injector - Dynamic header provider for authentication refresh and request-specific routing.
- Model
Adapter - A provider adapter.
- Request
Transform - A synchronous, provider-neutral request transform.
Functions§
- apply_
headers - Merges one header layer into
target, enforcing theHeaderPolicy. - bounded_
audit_ channel - Create a non-blocking, bounded audit channel.
- collect_
stream - Collect a stream into the final response while preserving all events.
- next_
event - Await the next stream event without requiring the caller to import
futures_util::StreamExt. - normalize
- Normalize a request using the default rules for a protocol.
- normalize_
with_ options - Normalize a request with explicit rules.
- parse_
retry_ after - Parse the HTTP
Retry-Afterheader. - parse_
retry_ after_ at - Deterministic version of
parse_retry_afterfor tests and custom clocks. - parse_
retry_ headers - Read all supported retry headers using the current time.
- parse_
retry_ headers_ at - Deterministic version of
parse_retry_headers. - retry_
async - Retry an async operation according to a
RetryPolicy. - validate_
tool_ declarations - Reject duplicate names within each declaration scope, regardless of kind.
Type Aliases§
- Model
Stream - A boxed provider-neutral stream of model events.
- OpenAI
Compatible - Backwards-compatible name for the OpenAI Chat-focused first iteration.
- Result
- Convenience alias for results returned by this crate.