Ceylon - AI Agent Framework

A powerful and flexible Rust framework for building AI agents with goal-oriented capabilities, memory management, and tool integration.

Features

• Goal-Oriented Agents: Create agents that can analyze tasks, break them into sub-goals, and track progress
• Memory Management: Built-in conversation history, context management, and vector memory support
• Tool Integration: Extensible tool system for adding custom capabilities to your agents
• Multiple LLM Support: Works with 13+ providers including OpenAI, Anthropic, Ollama, Google, Groq, and more
• Async-First: Built on Tokio for efficient async/await support
• Vector Memory: Optional support for semantic search with OpenAI, Ollama, HuggingFace embeddings
• Interactive Runner: Optional CLI runner for interactive agent sessions
• WASM Support: Can be compiled to WebAssembly for browser-based applications

Quick Start

Add Ceylon to your Cargo.toml:

[dependencies]
ceylon-next = "0.1.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Basic Usage

use ceylon_next::agent::Agent;
use ceylon_next::tasks::TaskRequest;

#[tokio::main]
async fn main() {
    // Create a new agent
    let mut agent = Agent::new("MyAssistant", "openai::gpt-4");

    // Create a task
    let task = TaskRequest::new("What is the capital of France?");

    // Run the agent
    let response = agent.run(task).await;
    println!("Response: {:?}", response.result());
}

Set your API key as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

Working with Tools

Extend your agent's capabilities with custom tools:

use ceylon_next::agent::Agent;
use ceylon_next::tools::ToolTrait;
use serde_json::json;

// Define a custom tool
struct CalculatorTool;

impl ToolTrait for CalculatorTool {
    fn name(&self) -> String {
        "calculator".to_string()
    }

    fn description(&self) -> String {
        "Performs basic arithmetic operations".to_string()
    }

    fn input_schema(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": {
                "operation": {"type": "string", "enum": ["add", "subtract", "multiply", "divide"]},
                "a": {"type": "number"},
                "b": {"type": "number"}
            },
            "required": ["operation", "a", "b"]
        })
    }

    fn execute(&self, input: serde_json::Value) -> serde_json::Value {
        let op = input["operation"].as_str().unwrap();
        let a = input["a"].as_f64().unwrap();
        let b = input["b"].as_f64().unwrap();

        let result = match op {
            "add" => a + b,
            "subtract" => a - b,
            "multiply" => a * b,
            "divide" => a / b,
            _ => 0.0,
        };

        json!({"result": result})
    }
}

#[tokio::main]
async fn main() {
    let mut agent = Agent::new("Calculator Agent", "openai::gpt-4");
    agent.add_tool(CalculatorTool);

    let task = TaskRequest::new("What is 15 multiplied by 7?");
    let response = agent.run(task).await;
    println!("{:?}", response.result());
}

Working with Memory

Agents automatically maintain conversation history:

use ceylon_next::agent::Agent;
use ceylon_next::tasks::TaskRequest;

#[tokio::main]
async fn main() {
    let mut agent = Agent::new("MemoryAgent", "openai::gpt-4");

    // First conversation
    let task1 = TaskRequest::new("My name is Alice");
    agent.run(task1).await;

    // Second conversation - agent remembers context
    let task2 = TaskRequest::new("What is my name?");
    let response = agent.run(task2).await;
    // Agent should respond with "Alice"

    // Search memory
    let memories = agent.search_memory("Alice").await;
    println!("Found {} relevant conversations", memories.len());
}

Supported LLM Providers

Ceylon supports 13+ LLM providers out of the box:

Features

Ceylon uses Cargo features to enable optional functionality:

[dependencies]
# Default: std features, vector memory, and CLI runner
ceylon-next = "0.1.0"

# Minimal installation (no tokio, no LLM, suitable for WASM)
ceylon-next = { version = "0.1.0", default-features = false }

# With specific vector providers
ceylon-next = { version = "0.1.0", features = ["vector-openai"] }
ceylon-next = { version = "0.1.0", features = ["vector-huggingface-local"] }

# All vector providers
ceylon-next = { version = "0.1.0", features = ["full-vector"] }

Available Features

• std (default): Standard features including tokio, LLM support, SQLite memory, and MessagePack serialization
• vector: Base vector memory functionality
• vector-openai: OpenAI embeddings for vector memory
• vector-ollama: Ollama embeddings for vector memory
• vector-huggingface: HuggingFace API embeddings
• vector-huggingface-local: Local HuggingFace embeddings using Candle
• full-vector: All vector providers
• runner: Interactive CLI runner
• wasm: WebAssembly support

Goal-Oriented Programming

Create agents that can break down complex tasks:

use ceylon_next::agent::Agent;
use ceylon_next::goal::Goal;
use ceylon_next::tasks::TaskRequest;

#[tokio::main]
async fn main() {
    let mut agent = Agent::new("ProjectManager", "openai::gpt-4");

    // Create a goal with success criteria
    let mut goal = Goal::new(
        "Launch Product",
        "Successfully launch the new product to market"
    );

    goal.add_criterion("Product is tested and bug-free");
    goal.add_criterion("Marketing materials are ready");
    goal.add_criterion("Launch event is scheduled");

    // Add sub-goals
    goal.add_sub_goal(Goal::new("Development", "Complete development"));
    goal.add_sub_goal(Goal::new("Marketing", "Create marketing campaign"));
    goal.add_sub_goal(Goal::new("Launch", "Execute launch"));

    // Track progress
    println!("Progress: {}%", goal.get_progress());
}

Examples

The repository includes numerous examples:

• 01_basic_agent: Simple agent creation and usage
• 02_with_tools: Custom tool implementation
• 03_with_memory: Working with conversation history
• 04_advanced_agent: Complex agent configurations
• 05_with_goals: Goal-oriented task management
• 08_llm_providers: Using different LLM providers
• 10_file_saving: Creating file-saving tools
• 11_persistent_memory: SQLite-backed memory
• 12_vector_memory: Semantic search with Ollama
• 13_vector_memory_openai: OpenAI embeddings
• 14_vector_memory_huggingface: HuggingFace API embeddings
• 15_vector_memory_huggingface_local: Local embeddings with Candle

Run examples from the repository:

# Clone the repository
git clone https://github.com/ceylonai/next.git
cd next

# Run an example
cargo run --example 01_basic_agent --manifest-path ceylon/Cargo.toml

Documentation

• API Documentation
• GitHub Repository
• Examples

Architecture

Ceylon is organized into several core modules:

• agent: Core agent implementation and lifecycle management
• tools: Tool system and built-in tools
• memory: Memory backends (in-memory, SQLite, vector)
• llm: LLM provider integrations and abstractions
• goal: Goal-oriented task management
• runner: Interactive CLI runner
• tasks: Task definitions and execution

Contributing

We welcome contributions! Please see our GitHub repository for more information.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.

Acknowledgments

Ceylon is built on top of the excellent llm crate for LLM provider integrations.