# ABK (Agent Builder Kit)
**Modular utilities for building LLM agents**
ABK is a feature-gated Rust crate providing essential utilities for building LLM-based agents. Choose only the components you need via Cargo features.
# ABK (Agent Builder Kit)
**Complete modular agent building blocks with feature-gated modules**
ABK is a comprehensive Rust crate providing feature-gated modules for building LLM-based agents. Choose only the components you need via Cargo features to keep your builds lean and focused.
## Features
ABK provides feature-gated modules organized by functionality:
### Core Features
- **`config`** - TOML configuration loading and environment variable resolution
- **`observability`** - Structured logging with file/console output
- **`checkpoint`** - Session persistence and resume capabilities
### Execution Features
- **`executor`** - Command execution with timeout and validation
- **`orchestration`** - Workflow coordination and session management
- **`lifecycle`** - WASM lifecycle plugin integration
### High-Level Features
- **`cli`** - Command-line interface utilities and formatting with convenience functions
- **`provider`** - LLM provider abstraction with WASM support
- **`agent`** - Complete agent implementation with all dependencies
### Composite Features
- **`all`** - Enables all features for complete functionality
## Installation
Add to your `Cargo.toml`:
```toml
[dependencies]
# Enable only the features you need:
abk = { version = "0.1.24", features = ["config"] }
# Or enable multiple features:
abk = { version = "0.1.24", features = ["config", "observability", "executor"] }
# Or enable everything:
abk = { version = "0.1.24", features = ["all"] }
```
## Usage
### Configuration Feature
```rust
use abk::config::{ConfigurationLoader, EnvironmentLoader};
use std::path::Path;
// Load environment variables
let env = EnvironmentLoader::new(None);
// Load configuration from TOML
let config_loader = ConfigurationLoader::new(
Some(Path::new("config/simpaticoder.toml"))
).unwrap();
let config = &config_loader.config;
// Access configuration
println!("Max iterations: {}", config.execution.max_iterations);
println!("LLM provider: {:?}", env.llm_provider());
```
### Observability Feature
```rust
use abk::observability::Logger;
use std::collections::HashMap;
// Create a logger with custom path and log level
let logger = Logger::new(
Some(Path::new("logs/agent.md")),
Some("DEBUG")
).unwrap();
// Log session lifecycle
let config = HashMap::new();
logger.log_session_start("auto", &config).unwrap();
// Log LLM interactions
let messages = vec![];
logger.log_llm_interaction(&messages, "Response text", "gpt-4").unwrap();
// Log completion
logger.log_completion("Task completed successfully").unwrap();
```
### CLI Feature
```rust
use abk::cli::{run_from_config_path, CommandContext};
// Option 1: One-liner convenience function (recommended for simple apps)
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
run_from_config_path("config/agent.toml", None).await
}
// Option 2: Full customization with CommandContext trait
struct MyContext { /* custom implementation */ }
impl CommandContext for MyContext { /* implement all methods */ }
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let context = MyContext::new();
let cli_config = CliConfig::from_simpaticoder_config(&context.config);
run_configured_cli(&context, &cli_config).await
}
```
### Provider Feature
```rust
use abk::checkpoint::{get_storage_manager, CheckpointResult};
// Initialize checkpoint storage
let manager = get_storage_manager()?;
let project_path = Path::new(".");
let project_storage = manager.get_project_storage(project_path).await?;
// Create a new session
let session_storage = project_storage.create_session("my-task").await?;
```
### Provider Feature
```rust
use abk::provider::ProviderFactory;
// Create LLM provider from environment
let provider = ProviderFactory::create(&env)?;
// Generate text
let config = GenerateConfig {
max_tokens: 100,
temperature: 0.7,
..Default::default()
};
let response = provider.generate(&messages, &config).await?;
```
### Agent Feature
```rust
use abk::agent::Agent;
// Create a complete agent
let mut agent = Agent::new(
Some(Path::new("config.toml")),
Some(Path::new(".env")),
Some(AgentMode::Confirm)
)?;
// Agent has access to all features:
// - Configuration via agent.config
// - Executor via agent.executor
// - Logger via agent.logger
// - Provider via agent.provider
// - Checkpoint manager via agent.session_manager
```
## Roadmap
ABK has evolved from a simple configuration utility to a comprehensive **Agent Builder Kit**:
- ✅ **Phase 1**: `config` feature (v0.1.0 - configuration management)
- ✅ **Phase 2**: `observability` feature (v0.1.1 - logging and metrics)
- ✅ **Phase 3**: `checkpoint` feature (v0.1.2 - session persistence)
- ✅ **Phase 4**: `provider` feature (v0.1.3+ - LLM provider abstraction)
- ✅ **Phase 5**: `executor` feature (v0.1.23 - command execution)
- ✅ **Phase 6**: `orchestration` feature (v0.1.23 - workflow management)
- ✅ **Phase 7**: `lifecycle` feature (v0.1.23 - WASM plugin integration)
- ✅ **Phase 8**: `cli` feature (v0.1.23 - command-line utilities)
- ✅ **Phase 9**: `agent` feature (v0.1.23 - complete agent implementation)
## Why ABK?
ABK provides a **unified, modular foundation** for building LLM agents:
### 🏗️ **Modular Architecture**
- **Feature-gated modules**: Only compile what you need
- **Clean separation**: Each feature has focused responsibilities
- **Composable design**: Mix and match components as needed
### 📦 **Unified Package**
Instead of maintaining separate crates for each component, ABK unifies them under one package with feature flags:
- **Unified versioning** - One version number for all infrastructure utilities
- **Simplified dependencies** - Import one crate instead of nine
- **Coordinated releases** - Breaking changes managed together
### 🚀 **Production Ready**
- **Comprehensive testing** - Extensive test coverage for all features
- **Error handling** - Robust error types and recovery mechanisms
- **Performance optimized** - Efficient implementations with async support
- **Well documented** - Complete API documentation and examples
### 🔧 **Developer Experience**
- **Type safety** - Strongly typed APIs with compile-time guarantees
- **Intuitive APIs** - Easy-to-use interfaces following Rust conventions
- **Extensible design** - Easy to add new features and providers
## License
Dual-licensed under MIT OR Apache-2.0