feagi_agent/
lib.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! FEAGI Agent SDK - Rust client library for building FEAGI agents
5//!
6//! This SDK provides a production-ready client for building agents that connect to FEAGI.
7//!
8//! # Features
9//! - Automatic registration with retry/backoff
10//! - Background heartbeat for keepalive
11//! - Reconnection logic
12//! - Sensory data sending (ZMQ PUSH)
13//! - Motor data receiving (ZMQ SUB)
14//! - Thread-safe operations
15//! - Graceful shutdown with deregistration
16//!
17//! # Quick Start
18//!
19//! ```ignore
20//! use feagi_agent::{AgentClient, AgentConfig, AgentType};
21//!
22//! // Create configuration
23//! let config = AgentConfig::new("my_camera", AgentType::Sensory)
24//!     .with_feagi_host("localhost")
25//!     .with_vision_capability("camera", (640, 480), 3, "i_vision")
26//!     .with_heartbeat_interval(5.0);
27//!
28//! // Create and connect client
29//! let mut client = AgentClient::new(config)?;
30//! client.connect()?;
31//!
32//! // Send sensory data
33//! client.send_sensory_data(vec![
34//!     (0, 50.0),   // neuron_id, potential
35//!     (1, 75.0),
36//!     (2, 30.0),
37//! ])?;
38//!
39//! // For motor agents - receive motor commands
40//! if let Some(motor_data) = client.receive_motor_data()? {
41//!     println!("Motor command: {:?}", motor_data);
42//! }
43//!
44//! // Client automatically deregisters on drop
45//! ```
46//!
47//! # Architecture
48//!
49//! The SDK uses ZMQ for communication with FEAGI:
50//! - **Registration**: ZMQ REQ/REP socket (also used for heartbeat)
51//! - **Sensory Data**: ZMQ PUSH socket (agent → FEAGI)
52//! - **Motor Data**: ZMQ SUB socket (FEAGI → agent)
53//!
54//! Heartbeat runs in a background thread and automatically keeps the agent alive.
55//!
56//! # Error Handling
57//!
58//! All operations return `Result<T, SdkError>`. The SDK distinguishes between:
59//! - **Retryable errors**: Network issues, timeouts (handled by retry logic)
60//! - **Non-retryable errors**: Configuration errors, invalid data
61//!
62//! # Thread Safety
63//!
64//! `AgentClient` uses `Arc<Mutex<>>` internally for socket sharing between
65//! the main thread and heartbeat thread. All public methods are safe to call
66//! from multiple threads.
67
68pub mod client;
69pub mod config;
70pub mod error;
71pub mod heartbeat;
72pub mod reconnect;
73pub mod transport;
74
75// Re-export main types for convenience
76pub use client::AgentClient;
77pub use config::AgentConfig;
78pub use error::{Result, SdkError};
79pub use transport::{RegistrationResponse, TransportConfig as TransportInfo};
80
81// Re-export types from feagi-io
82pub use feagi_io::{AgentCapabilities, AgentType, MotorCapability, VisionCapability};
83
84#[cfg(test)]
85mod tests {
86    use super::*;
87
88    #[test]
89    fn test_sdk_imports() {
90        // Verify all main types are accessible
91        let _config = AgentConfig::new("test", AgentType::Sensory);
92    }
93}
feagi_agent/lib.rs

feagi_agent/
lib.rs
