cellstate/
lib.rs

1//! CELLSTATE Rust SDK
2//!
3//! The `cellstate` crate provides a typed Rust interface to the CELLSTATE agent
4//! memory platform. It includes:
5//!
6//! - **Core types**: Entity IDs, enums, and domain structures from `cellstate-core`
7//! - **PCP types**: Memory commit, recall service, and PCP runtime from `cellstate-pcp`
8//! - **HTTP client**: `CellstateClient` for all REST API operations
9//! - **Wire types**: Request/response structs matching the API's snake_case JSON
10//!
11//! # Quick Start
12//!
13//! ```rust,no_run
14//! use cellstate::CellstateClient;
15//! use cellstate::types::CreateTrajectoryRequest;
16//!
17//! # async fn example() -> cellstate::error::Result<()> {
18//! // Create a client from env vars (CELLSTATE_API_URL, CELLSTATE_API_KEY)
19//! let client = CellstateClient::from_env()?;
20//!
21//! // Create a trajectory
22//! let traj = client.create_trajectory(&CreateTrajectoryRequest {
23//!     name: "Research task".to_string(),
24//!     description: Some("Investigating memory models".to_string()),
25//!     parent_trajectory_id: None,
26//!     agent_id: None,
27//!     metadata: None,
28//! }).await?;
29//!
30//! println!("Created: {}", traj.trajectory_id);
31//! # Ok(())
32//! # }
33//! ```
34//!
35//! # Re-exported Types
36//!
37//! All types from `cellstate-core` and `cellstate-pcp` are re-exported at the
38//! crate root for convenience:
39//!
40//! ```rust
41//! use cellstate::{TrajectoryId, ScopeId, AgentId, EntityIdType};
42//! use cellstate::{Trajectory, Scope, Artifact, Note, Turn};
43//! use cellstate::{TrajectoryStatus, AgentStatus, ArtifactType, NoteType, TurnRole};
44//! use cellstate::{ContextPackage, ContextWindow, TokenBudget};
45//! use cellstate::{EventKind, EventHeader, DagPosition};
46//! ```
47
48// ============================================================================
49// Modules
50// ============================================================================
51
52pub mod client;
53pub mod error;
54pub mod types;
55
56// ============================================================================
57// Re-exports: Client
58// ============================================================================
59
60pub use client::{CellstateClient, ResponseFormat};
61
62// ============================================================================
63// Re-exports: cellstate-core (identity, entities, enums, events, context)
64// ============================================================================
65
66// Identity types
67pub use cellstate_core::{
68    AgentId, ArtifactId, ContentHash, EntityIdType, NoteId, RawContent, ScopeId, TenantId,
69    Timestamp, TrajectoryId, TurnId,
70};
71
72// Entities
73pub use cellstate_core::{Agent, Artifact, Note, Scope, Trajectory, Turn};
74
75// Enums
76pub use cellstate_core::{
77    AbstractionLevel, AgentStatus, ArtifactType, EntityType, ExtractionMethod, NoteType,
78    TrajectoryStatus, TurnRole, TTL,
79};
80
81// Event DAG
82pub use cellstate_core::{DagPosition, EventHeader, EventKind};
83
84// Context assembly
85pub use cellstate_core::{ContextAssembler, ContextPackage, ContextWindow, TokenBudget};
86
87// Scoring
88pub use cellstate_core::scoring::{ScoringComponent, ScoringDebug, ScoringWeights, SourceQuality};
89
90// Effects
91pub use cellstate_core::{Effect, ErrorEffect};
92
93// ============================================================================
94// Re-exports: cellstate-pcp (PCP protocol)
95// ============================================================================
96
97pub use cellstate_pcp::{MemoryCommit, PCPConfig, PCPRuntime, RecallService};
98
99// ============================================================================
100// TESTS
101// ============================================================================
102
103#[cfg(test)]
104mod tests {
105    use super::*;
106
107    #[test]
108    fn test_reexports_compile() {
109        // Verify that re-exported types are accessible at the crate root.
110        let _: fn() -> TrajectoryId = TrajectoryId::new_v4;
111        let _: fn() -> ScopeId = ScopeId::new_v4;
112        let _: fn() -> ArtifactId = ArtifactId::new_v4;
113        let _: fn() -> NoteId = NoteId::new_v4;
114        let _: fn() -> TurnId = TurnId::new_v4;
115        let _: fn() -> AgentId = AgentId::new_v4;
116        let _: fn() -> TenantId = TenantId::new_v4;
117    }
118
119    #[test]
120    fn test_client_from_crate_root() {
121        let result = CellstateClient::new("https://cst.batterypack.dev", "cst_test");
122        assert!(result.is_ok());
123    }
124
125    #[test]
126    fn test_error_type_accessible() {
127        // Verify error variants are constructable and matchable.
128        let err = error::Error::Serialization(
129            serde_json::from_str::<serde_json::Value>("not json").unwrap_err(),
130        );
131        assert!(matches!(err, error::Error::Serialization(_)));
132    }
133}
cellstate/lib.rs

cellstate/
lib.rs
