Kowalski Core

The core library for the Kowalski AI agent framework, providing foundational abstractions, types, and utilities for building modular, extensible, and robust AI agents.

Description

kowalski-core is the heart of the Kowalski agent ecosystem. It defines the essential building blocks for agent-based AI systems, including agent logic, conversation management, tool and toolchain orchestration, model management, roles/personas, configuration, error handling, and logging. All other Kowalski modules and agents build on top of these abstractions.

Dependencies

• serde (with derive) — Serialization/deserialization
• serde_json — JSON support
• async-trait — Async trait support
• tokio — Async runtime
• reqwest — HTTP client
• thiserror — Error handling
• uuid — Unique IDs for conversations, etc.
• chrono — Date/time utilities
• log — Logging facade
• config — Configuration file parsing
• dirs — Platform-specific directory helpers
• toml — TOML parsing
• env_logger — Logging backend
• url — URL parsing

Architecture

kowalski-core/
├── agent/         # Agent trait and base agent implementation
├── config.rs      # Configuration system
├── conversation/  # Conversation and message types
├── error.rs       # Unified error types
├── logging/       # Logging utilities
├── model/         # Model management and selection
├── role/          # Role, audience, preset, and style abstractions
├── tool_chain.rs  # Tool chain orchestration
├── tools.rs       # Tool trait and parameter types
├── utils/         # Utility helpers
└── lib.rs         # Main library entry point

• Trait-based design: All extensible components (agents, tools, task types) are defined as traits.
• Async-first: All major operations are async for scalability.
• Strong typing: Rich, serializable types for all core concepts.
• Extensible: Designed for easy extension with new tools, roles, and agent types.

Core Functionality & Examples

1. Agent Abstraction

Defines the Agent trait and a BaseAgent implementation for managing conversations, interacting with models, and handling messages.

use kowalski_core::{Agent, BaseAgent, Config};

let config = Config::default();
let mut agent = BaseAgent::new(config, "Demo Agent", "A test agent").await?;
let conv_id = agent.start_conversation("llama3.2");
agent.add_message(&conv_id, "user", "Hello, world!").await;

2. Conversation Management

Manages conversation history, messages, and tool calls.

use kowalski_core::conversation::Conversation;

let mut conv = Conversation::new("llama3.2");
conv.add_message("user", "What's the weather?");
for msg in conv.get_messages() {
    println!("{}: {}", msg.role, msg.content);
}

3. Tool & Tool Chain System

Defines the Tool trait for pluggable tools and the ToolChain for orchestrating tool execution.

use kowalski_core::{Tool, ToolInput, ToolOutput, ToolChain};
use serde_json::json;

struct EchoTool;
#[async_trait::async_trait]
impl Tool for EchoTool {
    async fn execute(&mut self, input: ToolInput) -> Result<ToolOutput, kowalski_core::KowalskiError> {
        Ok(ToolOutput::new(json!({"echo": input.content}), None))
    }
    fn name(&self) -> &str { "echo" }
    fn description(&self) -> &str { "Echoes input" }
    fn parameters(&self) -> Vec<kowalski_core::ToolParameter> { vec![] }
}

let mut chain = ToolChain::new();
chain.register_tool(Box::new(EchoTool));

4. Model Management

Handles model listing, existence checks, and pulling models from a server.

use kowalski_core::model::ModelManager;

let manager = ModelManager::new("http://localhost:11434".to_string())?;
let models = manager.list_models().await?;

5. Roles, Audiences, Presets, Styles

Allows agents to assume different personas and communication styles.

use kowalski_core::role::{Role, Audience, Preset, Style};

let role = Role::new("Teacher", "Explains concepts simply")
    .with_audience(Audience::new("Student", "Learning Rust"))
    .with_preset(Preset::new("Beginner", "No prior experience"))
    .with_style(Style::new("Friendly", "Conversational and encouraging"));

6. Configuration

Flexible, extensible configuration system for agents and tools.

use kowalski_core::Config;

let config = Config::default();
println!("Ollama host: {}", config.ollama.host);

7. Error Handling

Unified error type for all core operations.

use kowalski_core::KowalskiError;

fn do_something() -> Result<(), KowalskiError> {
    Err(KowalskiError::ToolExecution("Something went wrong".into()))
}

Future Enhancements

• Agent orchestration: Multi-agent collaboration and federation
• Advanced tool chaining: Conditional and parallel tool execution
• Persistent conversation storage: Database-backed conversation history
• Dynamic model selection: Automatic model switching based on context
• Role learning: Adaptive personas based on user feedback
• Plugin system: Hot-swappable tools and agent extensions
• Improved logging and tracing: Distributed tracing and analytics