agtrace_sdk/
lib.rs

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

agtrace_sdk/
lib.rs
