Crate ailoop

Expand description

High-level façade for building an LLM agent loop. Most application code only depends on this crate — it re-exports the vocabulary from ailoop_core (messages, stream chunks, hooks) and from the side crates (ailoop-history, ailoop-tools, ailoop-prompts) you need to wire a Conversation together.

§Happy path

let mut chat = ailoop::Conversation::builder(model)
    .system_prompt("You are a helpful assistant.")
    .build()?;

let outcome = chat.run("What is the speed of light?").await?;
println!("{}", outcome.final_text.unwrap_or_default());

Conversation::run is the one-shot helper for CLI flows and notebooks; Conversation::stream yields one StreamChunk at a time when you want to render tokens, observe tool calls, or thread events through middleware as they happen.

§Mini-index

Conversation — the agent loop. Construct via Conversation::builder.
ConversationBuilder — builder pattern. Register tools with tool / tool_dyn, gate them with with_capabilities / with_approval, and layer per-request defaults with temperature, max_tokens, and friends.
RunOutcome — what Conversation::run returns. Aborts surface here as FinishReason::Aborted, not as Err.
Built-in middlewares: AntiLoop (loop-detection abort), Sanitize (caller-supplied text rewrites at the model boundary), ApprovalMiddleware (human-in-the-loop gating), JsonTracer (NDJSON event sink). With the tracing feature, TracingMiddleware routes the same events through the tracing crate.
SubAgentTool — wrap a Conversation as a ToolDyn so a parent agent can delegate to it.
advanced::run_chat — escape hatch for engine-level access without a History in the loop.

Modules§

advanced: Lower-level entry points outside the Conversation happy path.

Structs§

AntiLoop: Middleware that aborts a run when the model gets stuck repeating itself. Two independent detectors run side by side:
ApprovalMiddleware: Middleware that asks a user-supplied async callback whether each tool call should proceed, returning the callback’s ToolDecision to the engine.
CancellationToken: A token which can be used to signal a cancellation request to one or more tasks.
CharTokenizer: Fallback Tokenizer that approximates tokens as text.len() / 4.
ChatRequest: Per-turn request the engine assembles and the adapter lowers to the provider’s wire format.
Conversation: An agent loop bound to a single CompletionModel, with history, tool registry, and middleware chain configured up front. Construct via Conversation::builder.
ConversationBuilder: Configuration builder for a Conversation. Returned by Conversation::builder.
ConversationSnapshot: Persistable image of a conversation’s logical state.
History: Owns the message vector backing a single conversation, plus the budget and pin mask that govern how compaction reduces it.
HistoryBuilder: Configuration for a History.
InMemoryHistoryStore: Volatile HistoryStore kept entirely in process memory. Intended for tests and short-lived sessions where durable persistence is not required.
JsonFileHistoryStore: JSON-backed HistoryStore that writes the full snapshot to a single file. save pretty-prints; load returns Ok(None) when the file does not exist (first run) so callers can seed an empty conversation without branching on the missing-file case.
JsonTracer: Append-only NDJSON sink. Holds the open file behind a tokio Mutex so concurrent runs sharing the same Arc<JsonTracer> cannot interleave bytes within a line. The inner handle is std::fs::File: the writes are small (one JSON object) and tokio::fs::File buffers internally, which would silently swallow events on drop without an explicit flush().await between every emit.
Prompt: Composable system prompt: an ordered list of PromptSections.
PromptBuilder: Fluent builder for Prompt. Each section call appends to the running list; build finalizes it.
PromptSection: One section of a Prompt.
RetryConfig: Backoff settings for RetryingModel.
RetryingModel: Decorator that retries setup-time failures of an inner CompletionModel using exponential backoff with optional jitter, honouring Retry-After when the inner error provides it.
RunConfig: Per-run configuration consumed by the engine entry point.
RunId: Unique identifier for a single run of the engine.
RunOutcome: Summary of a completed (or aborted) run, returned by Conversation::run.
RunStream: Stream of StreamChunks for a single in-flight run, returned by Conversation::stream.
Sanitize: Middleware that runs caller-supplied transformations at the points where text crosses the model boundary: user-message text and tool args on the way out, tool results on the way back in.
StepId: Unique identifier for one provider turn (one model call) within a run.
SubAgentTool: Wraps a Conversation so a parent agent can delegate to it as a regular tool. Pure composition: nothing in the engine or registry changes — the child runs on its own CompletionModel, history, and middleware chain.
SummarizeStrategy: Compaction strategy that calls a CompletionModel to summarize the dropped portion of the history into a single text message, instead of dropping it outright.
ToolActivation: Per-run handle to the active tool set.
ToolContext: Context delivered to a tool handler on every dispatch.
ToolDefinition: Tool description sent to the provider so the model can decide when and how to call it.
ToolRegistry: Owns every tool a Conversation can dispatch to and tracks which of them are currently active.
ToolResultContent: Body of a tool reply sent back to the model in a UserBlock::ToolResult.
TruncateStrategy: Default CompactionStrategy: drop the oldest unpinned messages until the preserved tail starts at a safe User-without- ToolResult boundary. Pinned messages from the dropped prefix survive verbatim at their relative position; the cut never strands a ToolResult from its ToolCall. Reports under CompactionStrategy::name as "truncate".
Usage: Token counters reported by the provider for a turn.

Enums§

AssistantBlock: One block inside a Message::Assistant turn.
BuildError: Errors accumulated by ConversationBuilder and surfaced when build is called. Distinct from EngineError: these fire during setup, not during a run.
CompactionError: Failure surface of CompactionStrategy::compact (and therefore of History::compact_if_needed).
EngineError: Failure surface of Conversation::run / Conversation::stream and the underlying run_chat engine.
FinishReason: Reason a provider turn (or an entire run) ended.
FromMessagesError: Returned by ConversationSnapshot::new and History::from_messages when the supplied parallel vectors are inconsistent. Surfaces at restore time so a malformed snapshot fails loudly instead of corrupting state silently.
HookAction: Decision returned from ChatMiddleware::on_run_started to optionally short-circuit a run before any provider call.
JsonFileHistoryStoreError: HistoryStore::Error variant for JsonFileHistoryStore.
Message: One turn in the conversation history exchanged with a provider.
RetryClassification: Outcome of Retryable::retry_classification: whether the decorator should attempt the call again, and after how long.
StreamChunk: Event the engine emits as a run progresses.
ToolActivationError: Failures from ToolActivation mutations.
ToolChoice: Constraint placed on the model’s tool selection for a single request. Variant naming follows Anthropic’s wire vocabulary; the Chat Completions adapter translates Any → "required" and None_ → "none".
ToolDecision: Decision returned from ChatMiddleware::on_before_tool_call to optionally bypass or abort a tool invocation.
ToolRegistryError: Errors surfaced by ToolRegistry operations.
ToolTag: Capability tag attached to a ToolDefinition.
UserBlock: One block inside a Message::User turn.

Constants§

DEFAULT_HISTORY_MAX_TOKENS: Default token budget the internal History is configured with when ConversationBuilder::with_history is not called.

Traits§

ChatMiddleware: Extension point invoked by the engine at every lifecycle event of a run.
CompactionStrategy: User-implementable strategy for shrinking a History’s history when History::compact_if_needed runs.
CompletionClient: Factory for CompletionModel handles bound to a provider account / endpoint.
CompletionModel: Provider-agnostic streaming completion contract.
HistoryStore: Persistence backend for conversation snapshots.
Retryable: Adapter-side classification of an error as retryable or not.
Tokenizer: Counts tokens in text and full messages.
Tool: Typed tool entry point. Implement (or derive via #[ailoop_tool]) to expose a function to the model with deserialized Args in and a serializable Output out.
ToolDyn: Object-safe sibling of Tool used wherever the registry needs Arc<dyn ToolDyn> — runtime tool discovery (MCP, plugin loaders, config-driven catalogs). The blanket impl<T: Tool> ToolDyn for T promotes every static tool to a dynamic one for free.
ToolJsonType: Per-type JSON Schema fragment supplier for the #[ailoop_tool] macro.

Type Aliases§

TextPredicate: Predicate used to compare two assistant text turns. Receives (previous, current) and returns true when the texts should count as a repeated turn for the loop detector. Default trims both sides and compares for equality, which absorbs the trailing newline that some providers emit at the end of a turn.
TextRewriter: Rewriter applied to a piece of text. Receives the current value and returns either Cow::Borrowed(input) (no change, zero allocation) or Cow::Owned(new) (replace). The HRTB on the function signature lets callers return a borrow whose lifetime is tied to the input slice without naming it explicitly.
ToolArgsRewriter: Rewriter applied to a tool’s args value. Receives the tool name so the callback can dispatch on it (match name { "fetch" => ..., _ => ()}) instead of forcing a per-tool registry.
ToolResultRewriter: Rewriter applied to a tool’s result before the model sees it. Receives the tool name; mutate result in place to redact / scrub / truncate.

Attribute Macros§

ailoop_tool

Derive Macros§

ToolJsonType

Crate ailoop

Crate ailoop Copy item path

§Happy path

§Mini-index

Modules§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate ailoop