1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
//! A trait-based framework for building agent loops with pluggable LLM
//! clients, tools, and memory.
//!
//! # Module Overview
//!
//! ## Foundational Types
//!
//! - **[`message`]** — Core conversation types: messages, parts, tool results.
//! - **[`error`]** — Central error enum ([`LoopError`](error::LoopError)) for all framework operations.
//! - **[`config`]** — Session configuration ([`LoopConfig`](config::LoopConfig)).
//! - **[`cancel`]** — Cooperative cancellation signal (`CancelSignal`).
//!
//! ## Subsystems
//!
//! - **[`observer`]** — Lifecycle event observation ([`LoopObserver`](observer::LoopObserver), [`ObserverHost`](observer::ObserverHost)).
//! - **[`memory`]** — Agent memory trait ([`LoopMemory`](memory::LoopMemory)) and entry types.
//! - **[`reflection`]** — Failure reflection and recovery strategies.
//! - **[`detection`]** — Loop and convergence detection ([`DetectionManager`](detection::DetectionManager)).
//! - **[`fallback`]** — Circuit breaker pattern for automatic API model fallback.
//! - **[`compact`]** — Context management and compaction (threshold detection, pluggable strategies).
//! - **[`stream`]** — Streaming event types for LLM API responses.
//! - **[`middleware`]** — Tool dispatch middleware pipeline (timeouts, permissions, output limits).
//! - **[`tool`]** — Tool trait, registry, and supporting types.
//! - **[`tool::health`]** — Per-tool health monitoring, circuit breakers, and self-healing routing. *Requires `tool_health` feature.*
//!
//! ## API Layer
//!
//! - **[`api`]** — LLM API client trait ([`ApiClient`](api::ApiClient)) and error types.
//!
//! ## Runtime & Capabilities
//!
//! - **[`capabilities`]** — Capability traits ([`Observable`](capabilities::Observable), [`Detectable`](capabilities::Detectable), etc.).
//! - **[`runtime`]** — [`LoopRuntime`](runtime::LoopRuntime) — the default infrastructure bundle.
//!
//! ## Engine
//!
//! - **[`engine`]** — The core agentic loop ([`BareLoop`](engine::BareLoop)) that orchestrates the full agent lifecycle.
//!
//! ## Support
//!
//! - **[`memory::builtin`]** — Reference [`InMemoryStore`](memory::builtin::InMemoryStore) implementation.
//! - **[`hooks`]** — Bidirectional lifecycle control (allow/block/ask before tool use, compaction). *Requires `hooks` feature.*
//! - **[`testing`]** — Test utilities and fixtures. *Requires `testing` feature.*
// Relax strict lints in test code. The crate enforces a strict no-panic /
// no-unwrap policy in production code, but test code legitimately uses
// assertions, unwrap, indexing, etc. for readability.