zoey-core 0.1.1

ZoeyAI core runtime and types — privacy-first AI agent framework optimized for local models
Documentation 
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

//! Agent API module
//!
//! Provides a secure REST API for agent interaction, enabling frontend
//! applications to communicate with agents through authenticated endpoints.
//!
//! # Features
//!
//! - **Authentication**: Token-based authentication with SHA-256 hashing
//! - **Authorization**: Permission-based access control (Read, Write, Execute, Admin)
//! - **Rate Limiting**: Configurable rate limits per token/user
//! - **Input Validation**: Automatic validation and sanitization
//! - **Streaming**: Server-Sent Events (SSE) for real-time responses
//! - **CORS**: Configurable CORS for frontend integration
//!
//! # Endpoints
//!
//! - `GET /health` - Health check (no auth required)
//! - `POST /agent/chat` - Send messages to agent (requires Write permission)
//! - `POST /agent/action` - Execute agent actions (requires Execute permission)
//! - `POST /agent/state` - Get agent state (requires Read permission)
//!
//! # Example
//!
//! ```no_run
//! use zoey_core::{AgentRuntime, RuntimeOpts, agent_api::{AgentApiServer, AgentApiConfig}};
//!
//! #[tokio::main]
//! async fn main() -> zoey_core::Result<()> {
//!     // Create agent runtime
//!     let runtime = AgentRuntime::new(RuntimeOpts::default()).await?;
//!
//!     // Configure API server
//!     let config = AgentApiConfig {
//!         host: "127.0.0.1".to_string(),
//!         port: 3000,
//!         require_auth: false,  // Disable for testing
//!         ..Default::default()
//!     };
//!
//!     // Start server
//!     let mut server = AgentApiServer::new(config, runtime);
//!     server.start().await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! # Security Best Practices
//!
//! 1. **Always enable authentication in production** (`require_auth: true`)
//! 2. **Use HTTPS/TLS** for production deployments
//! 3. **Configure rate limiting** to prevent abuse
//! 4. **Validate CORS origins** - avoid using "*" in production
//! 5. **Rotate tokens regularly** and set expiration times
//! 6. **Monitor API usage** and set up alerts for suspicious activity
//!
//! # Authentication
//!
//! Requests to protected endpoints must include an Authorization header:
//!
//! ```text
//! Authorization: Bearer <your-token>
//! ```
//!
//! Tokens are SHA-256 hashed and validated against configured permissions.

pub mod auth;
pub mod handlers;
pub mod server;
pub mod state;
pub mod task;
pub mod types;

#[cfg(test)]
mod tests;

// Re-export main types
pub use auth::ApiAuthManager;
pub use handlers::ApiError;
pub use server::{AgentApiConfig, AgentApiServer};
pub use state::{ApiState, ServerState};
pub use task::{Task, TaskManager, TaskResult, TaskStatus};
pub use types::{
    ActionRequest, ActionResponse, ApiPermission, ApiResponse, ApiToken, ChatRequest, ChatResponse,
    HealthResponse, StateRequest, StateResponse, StreamEvent,
};