persistence_agent/lib.rs
1//! # persistence-agent
2//!
3//! Persistent homology for agent behavior profiling — topological fingerprints.
4//!
5//! This crate computes persistent homology from point clouds representing agent
6//! state trajectories and maps topological invariants to behavior archetypes.
7//!
8//! ## Quick Start
9//!
10//! ```
11//! use persistence_agent::agent_features::AgentProfiler;
12//!
13//! // Agent observations over time (e.g. 2D state vectors)
14//! let obs = vec![
15//! vec![0.0, 0.0],
16//! vec![0.1, 0.0],
17//! vec![0.0, 0.1],
18//! vec![1.0, 1.0],
19//! vec![1.1, 1.0],
20//! ];
21//!
22//! let profiler = AgentProfiler::new(1);
23//! let profile = profiler.profile(obs).unwrap();
24//! println!("Archetype: {}", profile.archetype);
25//! println!("Entropy: {:.3}", profile.persistence_entropy);
26//! ```
27//!
28//! ## Pipeline
29//!
30//! 1. **PointCloud** — embed observations, compute distances
31//! 2. **VietorisRipsComplex** — build filtration from pairwise distances
32//! 3. **BoundaryMatrix** — mod-2 boundary matrix + column reduction
33//! 4. **Barcode** — extract persistence pairs and Betti curves
34//! 5. **AgentProfiler** — classify behavior into archetypes
35//!
36//! ## Archetypes
37//!
38//! | Archetype | Topological Signature |
39//! |-----------|----------------------|
40//! | Steady | Single persistent cluster (β₀ = 1) |
41//! | Explorer | Many short-lived loops |
42//! | Volatile | Many disconnected components |
43//! | Deep | Long-lived higher-dimensional features |
44//! | Balanced | Mixed features, no dominant signature |
45
46pub mod agent_features;
47pub mod barcode;
48pub mod boundary;
49pub mod error;
50pub mod point_cloud;
51pub mod vietoris_rips;
52
53#[cfg(test)]
54mod tests;
55
56pub use agent_features::{AgentArchetype, AgentProfile, AgentProfiler};
57pub use barcode::{Barcode, PersistencePair};
58pub use boundary::BoundaryMatrix;
59pub use error::PersistenceError;
60pub use point_cloud::PointCloud;
61pub use vietoris_rips::VietorisRipsComplex;