agtrace_sdk/
lib.rs

1//! agtrace-sdk: The Observability Platform for AI Agents.
2//!
3//! # Overview
4//!
5//! `agtrace-sdk` provides a high-level, stable API for building observability
6//! tools on top of agtrace. It abstracts away the internal complexity of
7//! providers, indexing, and runtime orchestration, exposing only the essential
8//! primitives for monitoring and analyzing AI agent behavior.
9//!
10//! # Architecture
11//!
12//! This SDK acts as a facade over:
13//! - `agtrace-types`: Core domain models (AgentEvent, etc.)
14//! - `agtrace-providers`: Multi-provider log normalization
15//! - `agtrace-engine`: Session analysis and diagnostics
16//! - `agtrace-index`: Metadata storage and querying
17//! - `agtrace-runtime`: Internal orchestration layer
18//!
19//! # Usage
20//!
21//! ## Client-based API (Recommended)
22//!
23//! ```no_run
24//! use agtrace_sdk::{Client, Lens};
25//!
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! // 1. Connect to the workspace
28//! let client = Client::connect("~/.agtrace")?;
29//!
30//! // 2. Watch for live events (Real-time monitoring)
31//! let stream = client.watch().all_providers().start()?;
32//! for event in stream.take(10) {
33//!     println!("New event: {:?}", event);
34//! }
35//!
36//! // 3. Analyze a specific session (Diagnosis)
37//! let handle = client.sessions().get("session_id_123")?;
38//! let report = handle.analyze()?
39//!     .through(Lens::Failures)
40//!     .through(Lens::Loops)
41//!     .report()?;
42//!
43//! println!("Health score: {}", report.score);
44//! for insight in &report.insights {
45//!     println!("Turn {}: {:?} - {}",
46//!         insight.turn_index + 1,
47//!         insight.severity,
48//!         insight.message);
49//! }
50//! # Ok(())
51//! # }
52//! ```
53//!
54//! ## Standalone API (for testing/simulations)
55//!
56//! ```no_run
57//! use agtrace_sdk::{SessionHandle, types::AgentEvent};
58//!
59//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
60//! // When you have raw events without Client (e.g., testing, simulations)
61//! let events: Vec<AgentEvent> = vec![/* ... */];
62//! let handle = SessionHandle::from_events(events);
63//!
64//! let session = handle.assemble()?;
65//! println!("Session has {} turns", session.turns.len());
66//! # Ok(())
67//! # }
68//! ```
69
70pub mod analysis;
71pub mod client;
72pub mod error;
73pub mod types;
74pub mod watch;
75
76// Re-export core domain types for convenience
77pub use agtrace_engine::AgentSession;
78
79// Public facade
80pub use analysis::{AnalysisReport, Insight, Lens, Severity};
81pub use client::{
82    Client, InsightClient, ProjectClient, SessionClient, SessionHandle, SystemClient, WatchClient,
83};
84pub use error::{Error, Result};
85pub use types::{
86    AgentEvent, EventPayload, ExportStrategy, SessionFilter, SessionSummary, StreamId, ToolKind,
87};
88pub use watch::{LiveStream, WatchBuilder};
89
90// ============================================================================
91// Low-level Utilities (Power User API)
92// ============================================================================
93
94/// Utility functions for building custom observability tools.
95///
96/// These are stateless, pure functions that power the CLI and can be used
97/// by external tool developers to replicate or extend agtrace functionality.
98///
99/// # When to use this module
100///
101/// - Building custom TUIs or dashboards that need event stream processing
102/// - Writing tests that need to compute project hashes
103/// - Implementing custom project detection logic
104///
105/// # Examples
106///
107/// ## Event Processing
108///
109/// ```no_run
110/// use agtrace_sdk::{Client, utils};
111/// use agtrace_sdk::watch::{StreamEvent, WorkspaceEvent};
112///
113/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
114/// let client = Client::connect("~/.agtrace")?;
115/// let stream = client.watch().all_providers().start()?;
116///
117/// for workspace_event in stream.take(10) {
118///     if let WorkspaceEvent::Stream(StreamEvent::Events { events, .. }) = workspace_event {
119///         for event in events {
120///             let updates = utils::extract_state_updates(&event);
121///             if updates.is_new_turn {
122///                 println!("New turn started!");
123///             }
124///             if let Some(usage) = updates.usage {
125///                 println!("Token usage: {:?}", usage);
126///             }
127///         }
128///     }
129/// }
130/// # Ok(())
131/// # }
132/// ```
133///
134/// ## Project Hash Computation
135///
136/// ```no_run
137/// use agtrace_sdk::utils;
138///
139/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
140/// let project_root = utils::discover_project_root(None)?;
141/// let hash = utils::project_hash_from_root(&project_root.to_string_lossy());
142/// println!("Project hash: {}", hash);
143/// # Ok(())
144/// # }
145/// ```
146pub mod utils {
147    // Event processing utilities
148    pub use agtrace_engine::extract_state_updates;
149
150    // Project management utilities
151    pub use agtrace_types::{
152        discover_project_root, project_hash_from_root, resolve_effective_project_hash,
153    };
154}
agtrace_sdk/lib.rs

agtrace_sdk/
lib.rs
