Struct Agent 

pub struct Agent { /* private fields */ }

An AI Agent with goal-oriented capabilities, memory, and tool integration.

Agent is the core component of the Ceylon framework. It manages:

• LLM interactions for generating responses
• Goal analysis and tracking
• Conversation history and memory
• Tool execution and management

Examples

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

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

    let task = TaskRequest::new("Hello, how are you?");
    let response = agent.run(task).await;

    println!("{:?}", response.result());
}

Implementations

impl Agent

pub fn new(name: &str, model: &str) -> Self

Creates a new Agent with the specified name and LLM model.

Arguments

• name - The name of the agent (used in system prompts)
• model - The LLM model to use (e.g., “openai::gpt-4”, “claude-3-opus”, “llama2”)

Examples

use ceylon_next::agent::Agent;

let agent = Agent::new("MyAssistant", "openai::gpt-4");

Supported Models

• OpenAI: “openai::gpt-4”, “gpt-3.5-turbo”
• Anthropic: “claude-3-opus”, “claude-3-sonnet”
• Ollama: “llama2”, “mistral”

Panics

Panics if the model format is invalid or if an API key is required but not found in environment variables. Use Agent::new_with_config to provide API keys explicitly.

Examples found in repository

examples/02_with_tools.rs (line 141)

async fn main() {
    println!("🤖 Ceylon Agent - Tools Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MathAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful math and text assistant. \
         Use the available tools to help the user. \
         Be clear about what tools you're using and why."
    );

    // Step 2: Register custom tools with the agent
    println!("🔧 Registering tools...");
    agent.add_tool(CalculatorTool);
    agent.add_tool(StringToolTool);
    println!("✓ Tools registered\n");

    // Step 3: Create a task that requires tool usage
    let mut task = TaskRequest::new(
        "Please calculate 25 + 15 + 10, and then tell me the uppercase version of the word 'hello'"
    );
    task.with_name("Complex Task")
        .with_description("A task requiring multiple tools")
        .with_priority(8);

    // Step 4: Run the agent
    println!("📋 Task: {}\n", task.id());
    let response = agent.run(task).await;

    // Step 5: Display the result
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/01_basic_agent.rs (line 17)

async fn main() {
    println!("🤖 Ceylon Agent - Basic Example\n");

    // Step 1: Create a new agent with a name and model
    // The model should be one supported by the LLM library (openai, anthropic, ollama, etc.)
    let mut agent = Agent::new("Assistant", "ollama::gemma3:latest");

    // Step 2: (Optional) Configure the agent with custom settings
    let config = AgentConfig::new(
        3,   // max_retries
        60,  // timeout in seconds
    );
    agent.with_config(config);

    // Step 3: (Optional) Customize the system prompt
    agent.with_system_prompt(
        "You are a helpful assistant that answers questions accurately and concisely. \
         Always provide well-structured responses."
    );

    // Step 4: Create a task request
    let mut task = TaskRequest::new("What is the capital of France?");
    task.with_name("Geography Question")
        .with_description("A simple geography question")
        .with_priority(5);

    // Step 5: Run the agent with the task
    println!("📋 Task: {}\n", "What is the capital of France?");
    let response = agent.run(task).await;

    // Step 6: Handle the response
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/08_llm_providers.rs (line 130)

async fn basic_provider_usage() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Using different providers with simple syntax:\n");

    // OpenAI
    println!("📘 OpenAI GPT-4:");
    let mut openai_agent = Agent::new("OpenAI Assistant", "openai::gpt-4");
    let task1 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = openai_agent.run(task1).await;
    println!("   Response: {:?}\n", response.result());

    // Anthropic Claude
    println!("📗 Anthropic Claude:");
    let mut anthropic_agent = Agent::new("Claude Assistant", "anthropic::claude-3-sonnet-20240229");
    let task2 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = anthropic_agent.run(task2).await;
    println!("   Response: {:?}\n", response.result());

    // Ollama (local)
    println!("📙 Ollama (Local):");
    let mut ollama_agent = Agent::new("Ollama Assistant", "ollama::llama3.2");
    let task3 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = ollama_agent.run(task3).await;
    println!("   Response: {:?}\n", response.result());

    // Google Gemini
    println!("📕 Google Gemini:");
    let mut gemini_agent = Agent::new("Gemini Assistant", "google::gemini-pro");
    let task4 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = gemini_agent.run(task4).await;
    println!("   Response: {:?}\n", response.result());

    // Groq
    println!("📔 Groq:");
    let mut groq_agent = Agent::new("Groq Assistant", "groq::mixtral-8x7b-32768");
    let task5 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = groq_agent.run(task5).await;
    println!("   Response: {:?}\n", response.result());

    Ok(())
}

/// Example 2: Advanced configuration with LLMConfig
async fn advanced_configuration() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Using LLMConfig for advanced configuration:\n");

    // Method 1: Using Agent::new_with_config() (Recommended for explicit API keys)
    println!("📘 Using Agent::new_with_config() with explicit API key:");
    if let Ok(api_key) = std::env::var("OPENAI_API_KEY") {
        let config = LLMConfig::new("openai::gpt-4")
            .with_api_key(api_key)
            .with_temperature(0.7)
            .with_max_tokens(150)
            .with_top_p(0.9);

        if let Ok(mut agent) = Agent::new_with_config("Configured Assistant", config) {
            let task1 = TaskRequest::new("Explain quantum computing in one sentence.");
            let response = agent.run(task1).await;
            println!("   Response: {:?}\n", response.result());
        }
    } else {
        println!("   Skipped (OPENAI_API_KEY not set)\n");
    }

    // Method 2: Using Agent::new() then with_llm_config() (Alternative approach)
    println!("📗 Using Agent::new() then with_llm_config():");
    let mut agent = Agent::new("Configured Assistant", "openai::gpt-4");

    let config = LLMConfig::new("openai::gpt-4")
        .with_temperature(0.8)
        .with_max_tokens(200);

    if let Ok(_) = agent.with_llm_config(config) {
        let task2 = TaskRequest::new("What is machine learning in one sentence?");
        let response = agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Anthropic with reasoning
    println!("📗 Anthropic with extended thinking:");
    let mut claude_agent = Agent::new("Thinking Claude", "anthropic::claude-3-opus-20240229");

    let claude_config = LLMConfig::new("anthropic::claude-3-opus-20240229")
        .with_api_key(std::env::var("ANTHROPIC_API_KEY").unwrap_or_default())
        .with_temperature(0.5)
        .with_max_tokens(200)
        .with_reasoning(true);

    if let Ok(_) = claude_agent.with_llm_config(claude_config) {
        let task2 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = claude_agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Ollama with custom system prompt
    println!("📙 Ollama with custom system prompt:");
    let mut ollama_agent = Agent::new("Custom Ollama", "ollama::llama3.2");

    let ollama_config = LLMConfig::new("ollama::llama3.2")
        .with_system("You are a concise and technical AI assistant.")
        .with_max_tokens(100)
        .with_temperature(0.3);

    if let Ok(_) = ollama_agent.with_llm_config(ollama_config) {
        let task3 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = ollama_agent.run(task3).await;
        println!("   Response: {:?}\n", response.result());
    }

    Ok(())
}

/// Example 3: Provider-specific features
async fn provider_specific_features() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Provider-specific features:\n");

    // Azure OpenAI
    println!("☁️  Azure OpenAI with deployment configuration:");
    let mut azure_agent = Agent::new("Azure Assistant", "azure::gpt-4");

    let azure_config = LLMConfig::new("azure::gpt-4")
        .with_api_key(std::env::var("AZURE_OPENAI_API_KEY").unwrap_or_default())
        .with_deployment_id("your-deployment-id")
        .with_api_version("2024-02-01")
        .with_base_url("https://your-resource.openai.azure.com");

    if let Ok(_) = azure_agent.with_llm_config(azure_config) {
        println!("   ✓ Azure agent configured with deployment settings");
    }

    // OpenAI with web search
    println!("\n🌐 OpenAI with web search enabled:");
    let mut search_agent = Agent::new("Search Assistant", "openai::gpt-4");

    let search_config = LLMConfig::new("openai::gpt-4")
        .with_api_key(std::env::var("OPENAI_API_KEY").unwrap_or_default())
        .with_openai_web_search(true);

    if let Ok(_) = search_agent.with_llm_config(search_config) {
        let task1 = TaskRequest::new("What are the latest developments in AI?");
        let response = search_agent.run(task1).await;
        println!("   Response (with web search): {:?}\n", response.result());
    }

    // DeepSeek
    println!("🔍 DeepSeek for code-focused tasks:");
    let mut deepseek_agent = Agent::new("DeepSeek Assistant", "deepseek::deepseek-coder");

    let deepseek_config = LLMConfig::new("deepseek::deepseek-coder")
        .with_api_key(std::env::var("DEEPSEEK_API_KEY").unwrap_or_default())
        .with_temperature(0.2);

    if let Ok(_) = deepseek_agent.with_llm_config(deepseek_config) {
        let code_task = TaskRequest::new("Write a Rust function to calculate fibonacci numbers");
        let response = deepseek_agent.run(code_task).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Mistral
    println!("🌟 Mistral for European AI:");
    let mut mistral_agent = Agent::new("Mistral Assistant", "mistral::mistral-large-latest");

    let mistral_config = LLMConfig::new("mistral::mistral-large-latest")
        .with_api_key(std::env::var("MISTRAL_API_KEY").unwrap_or_default())
        .with_temperature(0.7)
        .with_max_tokens(500);

    if let Ok(_) = mistral_agent.with_llm_config(mistral_config) {
        println!("   ✓ Mistral agent configured");
    }

    Ok(())
}

/// Example 4: Compare providers
async fn compare_providers() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Comparing responses across providers:\n");

    let providers = vec![
        ("OpenAI GPT-4", "openai::gpt-4", std::env::var("OPENAI_API_KEY").ok()),
        ("Anthropic Claude", "anthropic::claude-3-sonnet-20240229", std::env::var("ANTHROPIC_API_KEY").ok()),
        ("Ollama Llama", "ollama::llama3.2", None),
        ("Google Gemini", "google::gemini-pro", std::env::var("GOOGLE_API_KEY").ok()),
        ("Groq Mixtral", "groq::mixtral-8x7b-32768", std::env::var("GROQ_API_KEY").ok()),
    ];

    for (name, model, api_key) in providers {
        println!("🤖 {}:", name);

        let mut agent = Agent::new(name, model);

        // Configure with LLMConfig if API key is available
        if let Some(key) = api_key {
            let config = LLMConfig::new(model)
                .with_api_key(key)
                .with_temperature(0.7)
                .with_max_tokens(100);

            if let Ok(_) = agent.with_llm_config(config) {
                let task = TaskRequest::new("Explain the concept of 'ownership' in Rust in one sentence.");
                let response = agent.run(task).await;
                println!("   ✓ {:?}", response.result());
            }
        } else {
            // Try without explicit API key (for Ollama or env vars)
            let task = TaskRequest::new("Explain the concept of 'ownership' in Rust in one sentence.");
            let response = agent.run(task).await;
            println!("   ✓ {:?}", response.result());
        }

        println!();
    }

    Ok(())
}

examples/05_with_goals.rs (line 26)

async fn example_1_manual_goal() {
    println!("=== Example 1: Manual Goal Creation ===\n");

    // Create an agent
    let mut agent = Agent::new("MealPlanner", "ollama::gemma3:latest");

    // Create a goal manually for a complex task
    let mut goal = Goal::new(
        "Plan a healthy meal prep for the week".to_string()
    );

    // Define what success looks like
    println!("📋 Setting success criteria...");
    goal.add_criterion("7 breakfast recipes selected".to_string());
    goal.add_criterion("7 lunch recipes selected".to_string());
    goal.add_criterion("7 dinner recipes selected".to_string());
    goal.add_criterion("Shopping list created".to_string());
    goal.add_criterion("Prep schedule created".to_string());

    // Break down into steps (sub-goals)
    println!("🎯 Breaking down into sub-goals...\n");
    goal.add_sub_goal("Ask user about dietary preferences".to_string(), 0);
    goal.add_sub_goal("Ask about time available for prep".to_string(), 1);
    goal.add_sub_goal("Suggest breakfast options".to_string(), 2);
    goal.add_sub_goal("Suggest lunch options".to_string(), 3);
    goal.add_sub_goal("Suggest dinner options".to_string(), 4);
    goal.add_sub_goal("Create shopping list".to_string(), 5);
    goal.add_sub_goal("Create prep schedule".to_string(), 6);

    // Start working on the goal
    goal.status = GoalStatus::InProgress;

    // Set the goal on the agent
    agent.set_goal(goal.clone());

    // Create a task aligned with the goal
    let task = TaskRequest::new("I need help with meal planning");

    // Run the agent
    println!("⏳ Agent is working on the meal planning task...\n");
    let _response = agent.run(task).await;

    // Show the goal summary
    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: Goal Progress Tracking
// ============================================

async fn example_2_goal_progress_tracking() {
    println!("\n=== Example 2: Goal Progress Tracking ===\n");

    // Create a goal for a project
    let mut goal = Goal::new(
        "Create a project plan for building a mobile app".to_string()
    );

    // Add success criteria
    goal.add_criterion("Project requirements documented".to_string());
    goal.add_criterion("Timeline created with milestones".to_string());
    goal.add_criterion("Resource allocation plan completed".to_string());
    goal.add_criterion("Risk assessment performed".to_string());

    // Add sub-goals
    goal.add_sub_goal("Gather stakeholder requirements".to_string(), 0);
    goal.add_sub_goal("Define project scope".to_string(), 1);
    goal.add_sub_goal("Create development timeline".to_string(), 2);
    goal.add_sub_goal("Allocate resources".to_string(), 3);
    goal.add_sub_goal("Identify risks and mitigation strategies".to_string(), 4);

    goal.status = GoalStatus::InProgress;

    // Simulate progress through the goal
    println!("📈 Tracking goal progress...\n");

    // Complete first sub-goal
    println!("Step 1: Gathering requirements");
    goal.complete_sub_goal(0, Some("Interviewed 5 stakeholders".to_string()));
    goal.mark_criterion_met(0, "Requirements documented".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete second sub-goal
    println!("Step 2: Defining scope");
    goal.complete_sub_goal(1, Some("Scope document created".to_string()));
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete third sub-goal
    println!("Step 3: Creating timeline");
    goal.complete_sub_goal(2, Some("12-month timeline with milestones".to_string()));
    goal.mark_criterion_met(1, "Timeline created".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fourth sub-goal
    println!("Step 4: Allocating resources");
    goal.complete_sub_goal(3, Some("Resource allocation table created".to_string()));
    goal.mark_criterion_met(2, "Resources allocated".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fifth sub-goal
    println!("Step 5: Assessing risks");
    goal.complete_sub_goal(4, Some("Risk register created with 8 identified risks".to_string()));
    goal.mark_criterion_met(3, "Risks identified".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Show final status
    println!("\n📊 Final Goal Status:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: Job Interview Preparation Goal
// ============================================

async fn example_3_interview_preparation() {
    println!("\n=== Example 3: Job Interview Preparation Goal ===\n");

    let mut agent = Agent::new("InterviewCoach", "ollama::gemma3:latest");

    // Create a structured goal for interview prep
    let mut goal = Goal::new(
        "Prepare for a senior software engineer interview at a tech company".to_string()
    );

    // Define success criteria
    println!("🎯 Success criteria:");
    goal.add_criterion("Technical topics reviewed (algorithms, data structures, system design)".to_string());
    goal.add_criterion("Behavioral questions prepared with STAR method examples".to_string());
    goal.add_criterion("Company research completed".to_string());
    goal.add_criterion("Practice mock interview conducted".to_string());
    goal.add_criterion("Questions to ask the interviewer prepared".to_string());

    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    // Define steps
    println!("\n📋 Steps to take:");
    goal.add_sub_goal("Review core algorithms and data structures".to_string(), 0);
    goal.add_sub_goal("Study system design patterns".to_string(), 1);
    goal.add_sub_goal("Prepare STAR method stories from past projects".to_string(), 2);
    goal.add_sub_goal("Research company background and culture".to_string(), 3);
    goal.add_sub_goal("Practice mock interview with a friend".to_string(), 4);
    goal.add_sub_goal("Prepare thoughtful questions about the role".to_string(), 5);

    for sub_goal in &goal.sub_goals {
        println!("  {}. {}", sub_goal.priority + 1, sub_goal.description);
    }

    goal.status = GoalStatus::InProgress;

    // Set goal on agent
    agent.set_goal(goal.clone());

    // Create related task
    let task = TaskRequest::new("Help me prepare for my senior engineer interview");

    println!("\n⏳ Agent is creating interview preparation plan...\n");
    let _response = agent.run(task).await;

    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 3 completed!\n");
}

examples/06_nextjs_app_generator.rs (line 42)

async fn example_1_basic_nextjs_app() {
    println!("=== Example 1: Generate a Basic Next.js App ===\n");

    // Create an agent that will generate the app
    let mut agent = Agent::new("NextJsGenerator", "ollama::gemma3:latest");

    // Create a goal for generating a Next.js app
    let mut goal = Goal::new(
        "Generate a Next.js web application with essential structure".to_string()
    );

    // Define success criteria
    goal.add_criterion("package.json created with dependencies".to_string());
    goal.add_criterion("next.config.js configuration file generated".to_string());
    goal.add_criterion("pages directory with index and api route created".to_string());
    goal.add_criterion("styles directory with global CSS".to_string());
    goal.add_criterion("README.md with setup instructions".to_string());

    // Define sub-goals (steps to generate the app)
    goal.add_sub_goal("Analyze Next.js requirements and best practices".to_string(), 0);
    goal.add_sub_goal("Generate package.json with required dependencies".to_string(), 1);
    goal.add_sub_goal("Create next.config.js configuration".to_string(), 2);
    goal.add_sub_goal("Generate pages (index.tsx, _app.tsx, _document.tsx)".to_string(), 3);
    goal.add_sub_goal("Create API route examples".to_string(), 4);
    goal.add_sub_goal("Generate styling setup (global.css, utilities)".to_string(), 5);
    goal.add_sub_goal("Create components directory with example components".to_string(), 6);
    goal.add_sub_goal("Generate README with setup and usage instructions".to_string(), 7);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    // Create a task to generate a Next.js app
    let task = TaskRequest::new(
        "Generate a modern Next.js 14 application with TypeScript, Tailwind CSS, and best practices. \
         Include package.json, next.config.js, sample pages, API routes, and components. \
         The app should be production-ready and follow Next.js conventions."
    );

    println!("📝 Task: Generate a Next.js application\n");
    println!("🎯 Success Criteria:");
    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    println!("\n⏳ Agent is generating the Next.js app...\n");
    let response = agent.run(task).await;

    // Extract and display the output
    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    // Show progress
    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("Status: {:?}", goal.status);

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: E-Commerce Next.js App
// ============================================

async fn example_2_ecommerce_app() {
    println!("\n=== Example 2: Generate E-Commerce Next.js App ===\n");

    let mut agent = Agent::new("EcommerceGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a complete e-commerce Next.js application".to_string()
    );

    // Success criteria for e-commerce
    goal.add_criterion("Product listing page with filtering and sorting".to_string());
    goal.add_criterion("Product detail pages with dynamic routes".to_string());
    goal.add_criterion("Shopping cart functionality".to_string());
    goal.add_criterion("User authentication setup".to_string());
    goal.add_criterion("Payment integration structure".to_string());
    goal.add_criterion("Database models and API endpoints".to_string());
    goal.add_criterion("Admin dashboard layout".to_string());

    // Sub-goals
    goal.add_sub_goal("Design database schema for products and orders".to_string(), 0);
    goal.add_sub_goal("Create product API endpoints".to_string(), 1);
    goal.add_sub_goal("Build product listing and search components".to_string(), 2);
    goal.add_sub_goal("Implement product detail pages".to_string(), 3);
    goal.add_sub_goal("Create shopping cart context and management".to_string(), 4);
    goal.add_sub_goal("Build checkout flow pages".to_string(), 5);
    goal.add_sub_goal("Integrate payment gateway API".to_string(), 6);
    goal.add_sub_goal("Create admin dashboard pages".to_string(), 7);
    goal.add_sub_goal("Add authentication middleware".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a complete e-commerce Next.js application with: \
         1. Product management system (listing, search, filters)\n\
         2. Shopping cart with add/remove/update functionality\n\
         3. User authentication and profile pages\n\
         4. Payment integration endpoints\n\
         5. Order history and tracking\n\
         6. Admin dashboard for managing products and orders\n\
         7. Database models for PostgreSQL or MongoDB\n\
         8. RESTful API endpoints\n\
         Use TypeScript, Tailwind CSS, and modern React patterns."
    );

    println!("📝 Task: Generate E-Commerce Next.js Application\n");
    println!("🎯 Features to Generate:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating e-commerce app...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: SaaS Dashboard App
// ============================================

async fn example_3_saas_dashboard() {
    println!("\n=== Example 3: Generate SaaS Dashboard Next.js App ===\n");

    let mut agent = Agent::new("SaasDashboardGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a SaaS dashboard application with user management".to_string()
    );

    goal.add_criterion("User authentication and authorization".to_string());
    goal.add_criterion("Multi-tenant database structure".to_string());
    goal.add_criterion("Dashboard with analytics and metrics".to_string());
    goal.add_criterion("User and team management pages".to_string());
    goal.add_criterion("Settings and preferences pages".to_string());
    goal.add_criterion("Billing and subscription management".to_string());
    goal.add_criterion("API for data collection and reporting".to_string());

    goal.add_sub_goal("Design multi-tenant database schema".to_string(), 0);
    goal.add_sub_goal("Implement OAuth authentication".to_string(), 1);
    goal.add_sub_goal("Create dashboard with charts and metrics".to_string(), 2);
    goal.add_sub_goal("Build team and user management interfaces".to_string(), 3);
    goal.add_sub_goal("Create settings pages for users and organization".to_string(), 4);
    goal.add_sub_goal("Implement billing API integration".to_string(), 5);
    goal.add_sub_goal("Create analytics and reporting system".to_string(), 6);
    goal.add_sub_goal("Add email notification templates".to_string(), 7);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a complete SaaS dashboard Next.js application with:\n\
         1. Multi-tenant authentication (OAuth + JWT)\n\
         2. Organization and team management\n\
         3. Comprehensive dashboard with charts and analytics\n\
         4. User permission and role management\n\
         5. Billing integration with Stripe\n\
         6. Settings pages for users and teams\n\
         7. Email notifications system\n\
         8. API logging and activity tracking\n\
         9. Dark mode support\n\
         10. Mobile responsive design\n\
         Include TypeScript, Tailwind CSS, Recharts for visualizations, \
         and PostgreSQL database models."
    );

    println!("📝 Task: Generate SaaS Dashboard Application\n");
    println!("🎯 Dashboard Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating SaaS dashboard...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 3 completed!\n");
}

// ============================================
// Example 4: Blog Platform with CMS
// ============================================

async fn example_4_blog_platform() {
    println!("\n=== Example 4: Generate Blog Platform with CMS ===\n");

    let mut agent = Agent::new("BlogCMSGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a comprehensive blog platform with CMS".to_string()
    );

    goal.add_criterion("Blog post management system".to_string());
    goal.add_criterion("Rich text editor with markdown support".to_string());
    goal.add_criterion("Category and tag system".to_string());
    goal.add_criterion("Search and filtering functionality".to_string());
    goal.add_criterion("Comments system with moderation".to_string());
    goal.add_criterion("SEO optimization (meta tags, sitemap)".to_string());
    goal.add_criterion("Author management and permissions".to_string());
    goal.add_criterion("Analytics and engagement tracking".to_string());

    goal.add_sub_goal("Design blog database schema".to_string(), 0);
    goal.add_sub_goal("Create CMS backend API".to_string(), 1);
    goal.add_sub_goal("Build post editor with markdown".to_string(), 2);
    goal.add_sub_goal("Create blog listing and search pages".to_string(), 3);
    goal.add_sub_goal("Build individual post pages with SEO".to_string(), 4);
    goal.add_sub_goal("Implement comments system".to_string(), 5);
    goal.add_sub_goal("Create author profiles and bio".to_string(), 6);
    goal.add_sub_goal("Build admin dashboard for content management".to_string(), 7);
    goal.add_sub_goal("Add analytics tracking and reporting".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a full-featured blog platform with CMS:\n\
         1. Post creation and editing with rich text editor\n\
         2. Markdown support with preview\n\
         3. Category and tag system\n\
         4. Advanced search with filters\n\
         5. Comments system with nested replies\n\
         6. Author profiles with biography\n\
         7. SEO optimization (sitemaps, meta tags, structured data)\n\
         8. Social sharing integration\n\
         9. Email newsletter subscription\n\
         10. Analytics dashboard for authors\n\
         11. Reading time estimates\n\
         12. Related posts suggestions\n\
         Include TypeScript, Tailwind CSS, next-mdx-remote for markdown, \
         and MongoDB/PostgreSQL models."
    );

    println!("📝 Task: Generate Blog Platform with CMS\n");
    println!("🎯 Blog Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating blog platform...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 4 completed!\n");
}

// ============================================
// Example 5: Extracting and Processing Output
// ============================================

async fn example_5_output_extraction() {
    println!("\n=== Example 5: Output Extraction and Processing ===\n");

    let mut agent = Agent::new("OutputProcessor", "ollama::gemma3:latest");

    // Create a simple task to generate specific file outputs
    let task = TaskRequest::new(
        "Generate ONLY the following files in proper format:\n\
         1. A complete package.json file for a Next.js project\n\
         2. A next.config.js configuration\n\
         3. A TypeScript types file for common types\n\
         Format each file with proper headers like:\n\
         === FILE: package.json ===\n\
         [file content]\n\
         === FILE: next.config.js ===\n\
         [file content]"
    );

    println!("📝 Task: Generate Specific Configuration Files\n");
    println!("⏳ Processing...\n");

    let response = agent.run(task).await;
    let output = extract_output_text(&response.result());

    // Parse output by file
    let files: HashMap<String, String> = parse_output_by_file(&output);

    println!("📦 Generated Files:\n");
    for (filename, content) in &files {
        println!("📄 File: {}", filename);
        println!("   Lines: {}", content.lines().count());
        println!("   Size: {} bytes\n", content.len());
    }

    println!("✅ Example 5 completed!\n");
}

examples/04_advanced_agent.rs (line 117)

async fn main() {
    println!("🤖 Ceylon Agent - Advanced Example\n");

    // Step 1: Create an agent with custom configuration
    let mut agent = Agent::new("AdvancedAssistant", "ollama::gemma3:latest");

    // Configure with custom settings
    let config = AgentConfig::new(
        5,   // Allow more retries for complex tasks
        120, // Longer timeout
    );
    agent.with_config(config);

    // Custom system prompt for the advanced agent
    agent.with_system_prompt(
        "You are an advanced AI assistant with access to specialized tools. \
         You can fetch weather data and analyze text. \
         Always explain your reasoning and use tools appropriately. \
         Provide detailed and accurate responses.",
    );

    // Step 2: Register multiple tools
    println!("🔧 Registering tools...");
    agent.add_tool(WeatherTool);
    agent.add_tool(TextAnalyzerTool);
    println!("✓ Tools registered: get_weather, analyze_text\n");

    // Step 3: Create and run multiple tasks with different priorities
    let tasks_data = vec![
        (
            "What's the weather in Paris and London? Compare them.",
            "Weather Comparison",
            "Compare weather in two cities",
            9, // High priority
        ),
        (
            "Analyze this text for readability: 'The quick brown fox jumps over the lazy dog. \
             This sentence demonstrates all letters of the English alphabet.'",
            "Text Analysis",
            "Analyze readability",
            5, // Medium priority
        ),
    ];

    for (prompt, name, description, priority) in tasks_data {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", name);
        println!("⭐ Priority: {}/10", priority);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(name)
            .with_description(description)
            .with_priority(priority);

        // Run the agent
        println!("⏳ Running agent...\n");
        let response = agent.run(task).await;

        // Handle response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✅ Task completed\n");
            }
            _ => {
                println!("⚠️ Unexpected response type\n");
            }
        }
    }

    // Step 4: Demonstrate memory capabilities
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Agent Status Summary:");
    println!("• System Prompt: Custom advanced prompt");
    println!("• Tools Available: 2 (weather, text analyzer)");
    println!("• Memory Enabled: Yes");
    println!("• Max Retries: 5");
    println!("• Timeout: 120 seconds");
    println!("• Tasks Completed: 2\n");

    println!("✅ Advanced example completed successfully!");
}

Additional examples can be found in:

• examples/09_test_groq.rs
• examples/07_python_project_generator.rs
• examples/03_with_memory.rs
• examples/10_file_saving.rs
• examples/11_persistent_memory.rs

pub fn new_with_config( name: &str, llm_config: LLMConfig, ) -> Result<Self, String>

Creates a new Agent with the specified name and LLM configuration.

This method allows you to provide comprehensive LLM configuration including API keys, temperature, max tokens, and other provider-specific settings.

Arguments

• name - The name of the agent (used in system prompts)
• llm_config - LLM configuration with model, API key, and other settings

Examples

use ceylon_next::agent::Agent;
use ceylon_next::llm::LLMConfig;

// Create agent with explicit API key
let config = LLMConfig::new("openai::gpt-4")
    .with_api_key("your-api-key")
    .with_temperature(0.7)
    .with_max_tokens(2048);

let agent = Agent::new_with_config("Assistant", config).unwrap();

Errors

Returns an error if:

• The model format is invalid (should be “provider::model-name”)
• An API key is required but not provided or found in environment variables
• The LLM provider fails to initialize

Examples found in repository

examples/08_llm_providers.rs (line 179)

async fn advanced_configuration() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Using LLMConfig for advanced configuration:\n");

    // Method 1: Using Agent::new_with_config() (Recommended for explicit API keys)
    println!("📘 Using Agent::new_with_config() with explicit API key:");
    if let Ok(api_key) = std::env::var("OPENAI_API_KEY") {
        let config = LLMConfig::new("openai::gpt-4")
            .with_api_key(api_key)
            .with_temperature(0.7)
            .with_max_tokens(150)
            .with_top_p(0.9);

        if let Ok(mut agent) = Agent::new_with_config("Configured Assistant", config) {
            let task1 = TaskRequest::new("Explain quantum computing in one sentence.");
            let response = agent.run(task1).await;
            println!("   Response: {:?}\n", response.result());
        }
    } else {
        println!("   Skipped (OPENAI_API_KEY not set)\n");
    }

    // Method 2: Using Agent::new() then with_llm_config() (Alternative approach)
    println!("📗 Using Agent::new() then with_llm_config():");
    let mut agent = Agent::new("Configured Assistant", "openai::gpt-4");

    let config = LLMConfig::new("openai::gpt-4")
        .with_temperature(0.8)
        .with_max_tokens(200);

    if let Ok(_) = agent.with_llm_config(config) {
        let task2 = TaskRequest::new("What is machine learning in one sentence?");
        let response = agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Anthropic with reasoning
    println!("📗 Anthropic with extended thinking:");
    let mut claude_agent = Agent::new("Thinking Claude", "anthropic::claude-3-opus-20240229");

    let claude_config = LLMConfig::new("anthropic::claude-3-opus-20240229")
        .with_api_key(std::env::var("ANTHROPIC_API_KEY").unwrap_or_default())
        .with_temperature(0.5)
        .with_max_tokens(200)
        .with_reasoning(true);

    if let Ok(_) = claude_agent.with_llm_config(claude_config) {
        let task2 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = claude_agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Ollama with custom system prompt
    println!("📙 Ollama with custom system prompt:");
    let mut ollama_agent = Agent::new("Custom Ollama", "ollama::llama3.2");

    let ollama_config = LLMConfig::new("ollama::llama3.2")
        .with_system("You are a concise and technical AI assistant.")
        .with_max_tokens(100)
        .with_temperature(0.3);

    if let Ok(_) = ollama_agent.with_llm_config(ollama_config) {
        let task3 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = ollama_agent.run(task3).await;
        println!("   Response: {:?}\n", response.result());
    }

    Ok(())
}

examples/09_test_groq.rs (line 23)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🧪 Testing Groq LLM Provider with API Key\n");

    // Test 1: Using Agent::new_with_config() - Recommended approach
    println!("{}", "=".repeat(60));
    println!("Test 1: Using Agent::new_with_config() with explicit API key");
    println!("{}", "=".repeat(60));

    match std::env::var("GROQ_API_KEY") {
        Ok(api_key) => {
            println!("✓ GROQ_API_KEY found in environment\n");

            let groq_config = LLMConfig::new("groq::llama-3.3-70b-versatile")
                .with_api_key(api_key)
                .with_temperature(0.7)
                .with_max_tokens(100);

            match Agent::new_with_config("Groq Agent", groq_config) {
                Ok(mut agent) => {
                    println!("✓ Groq agent created successfully!\n");

                    println!("Running task: 'What is 2 + 2?'");
                    let task = TaskRequest::new("What is 2 + 2? Answer in one short sentence.");
                    println!("Sending request to Groq API...\n");

                    let response = agent.run(task).await;

                    println!("Response received:");
                    println!("================");
                    println!("{:?}", response.result());
                    println!("================\n");

                    println!("🎉 Test 1 completed successfully!");
                }
                Err(e) => {
                    println!("✗ Failed to create Groq agent: {}\n", e);
                }
            }
        }
        Err(_) => {
            println!("✗ GROQ_API_KEY not found in environment");
            println!("  Please set GROQ_API_KEY to run this test\n");
        }
    }

    // Test 2: Using Agent::new() with environment variable - Simpler approach
    println!("\n{}", "=".repeat(60));
    println!("Test 2: Using Agent::new() with environment variable");
    println!("{}", "=".repeat(60));

    if std::env::var("GROQ_API_KEY").is_ok() {
        println!("✓ GROQ_API_KEY is set, agent will use it automatically\n");

        match std::panic::catch_unwind(|| {
            Agent::new("Simple Groq Agent", "groq::llama-3.3-70b-versatile")
        }) {
            Ok(mut agent) => {
                println!("✓ Groq agent created successfully with auto API key!\n");

                println!("Running task: 'What is the capital of France?'");
                let task = TaskRequest::new("What is the capital of France? Answer in one word.");

                let response = agent.run(task).await;

                println!("Response received:");
                println!("================");
                println!("{:?}", response.result());
                println!("================\n");

                println!("🎉 Test 2 completed successfully!");
            }
            Err(_) => {
                println!("✗ Failed to create agent (unexpected panic)\n");
            }
        }
    } else {
        println!("✗ GROQ_API_KEY not set, skipping this test\n");
    }

    println!("\n{}", "=".repeat(60));
    println!("All tests completed!");
    println!("{}", "=".repeat(60));

    Ok(())
}

pub fn with_memory(&mut self, memory: Arc<dyn Memory>) -> &mut Self

Sets a custom memory implementation for the agent.

By default, agents use InMemoryStore. You can provide a custom implementation of the Memory trait for persistent storage.

Arguments

• memory - An Arc-wrapped implementation of the Memory trait

Examples

use ceylon_next::agent::Agent;
use std::sync::Arc;
// Assuming you have a custom RedisMemory implementation
// let redis_memory = Arc::new(RedisMemory::new());
// let mut agent = Agent::new("Assistant", "openai::gpt-4");
// agent.with_memory(redis_memory);

Examples found in repository

examples/11_persistent_memory.rs (line 31)

async fn main() {
    println!("🤖 Ceylon Agent - Persistent Memory Example\n");

    // ============================================
    // Part 1: SQLite Backend
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📦 Part 1: SQLite Backend");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let sqlite_path = "agent_memory.db";
    let sqlite_store = SqliteStore::new(sqlite_path).await
        .expect("Failed to create SQLite store");

    let mut agent = Agent::new("PersistentAssistant", "ollama::gemma3:latest");
    agent.with_memory(Arc::new(sqlite_store))
         .with_system_prompt("You are a helpful assistant with persistent memory across sessions.");

    println!("✅ Created agent with SQLite backend at {}\n", sqlite_path);

    // Run some tasks to populate memory
    let tasks = vec![
        "My name is Alice and I love programming in Rust",
        "What programming language do I like?",
    ];

    for prompt in tasks {
        println!("📋 Task: {}", prompt);
        let mut task = TaskRequest::new(prompt);
        task.with_priority(5);

        let response = agent.run(task).await;
        if let OutputData::Text(_) = response.result() {
            println!("✓ Task completed\n");
        }
    }

    println!("📊 SQLite database now contains conversation history");
    println!("   This data persists even after the program exits!\n");

    // ============================================
    // Part 2: File-based Backend (JSON)
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📄 Part 2: File-based Backend (JSON)");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let json_path = "agent_memory.json";
    let file_store = FileStore::new(json_path, StorageFormat::Json).await
        .expect("Failed to create File store");

    let mut agent2 = Agent::new("FileAssistant", "ollama::gemma3:latest");
    agent2.with_memory(Arc::new(file_store))
          .with_system_prompt("You are a helpful assistant storing memories in JSON files.");

    println!("✅ Created agent with JSON file backend at {}\n", json_path);

    let task = TaskRequest::new("Remember: My favorite color is blue");
    let response = agent2.run(task).await;

    if let OutputData::Text(_) = response.result() {
        println!("✓ Memory saved to JSON file");
        println!("   You can open {} to view the human-readable data!\n", json_path);
    }

    // ============================================
    // Part 3: MessagePack Backend
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📦 Part 3: MessagePack Backend (Compact Binary)");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let msgpack_path = "agent_memory.msgpack";
    let msgpack_store = FileStore::new(msgpack_path, StorageFormat::MessagePack).await
        .expect("Failed to create MessagePack store");

    let mut agent3 = Agent::new("BinaryAssistant", "ollama::gemma3:latest");
    agent3.with_memory(Arc::new(msgpack_store))
          .with_system_prompt("You are a helpful assistant using compact binary storage.");

    println!("✅ Created agent with MessagePack backend at {}\n", msgpack_path);

    let task = TaskRequest::new("Store this efficiently: The quick brown fox jumps over the lazy dog");
    let response = agent3.run(task).await;

    if let OutputData::Text(_) = response.result() {
        println!("✓ Memory saved to MessagePack file");
        println!("   Binary format is more compact than JSON!\n");
    }

    // ============================================
    // Part 4: Memory Migration
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🔄 Part 4: Memory Migration Between Backends");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Create source and destination stores
    let source_db = SqliteStore::new("source.db").await.unwrap();

    // Create an agent with source backend and add some data
    let mut temp_agent = Agent::new("MigrationAgent", "ollama::gemma3:latest");
    temp_agent.with_memory(Arc::new(source_db));

    let task = TaskRequest::new("Migration test: This data will be migrated!");
    temp_agent.run(task).await;

    // Note: You would normally track your agent IDs. For this demo, we'll use
    // a known pattern - the agent creates entries with its own ID
    println!("💡 Tip: To migrate data, you need to know the agent's ID");
    println!("   In production, track agent IDs when creating agents\n");

    println!("✓ Migration between backends is available via migrate_memory()\n");
    println!("   Example: migrate_memory(&source, &target, \"agent-id\").await\n");

    // ============================================
    // Part 5: Export/Import Utilities
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("💾 Part 5: Export/Import Utilities");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Demonstrate export/import with the existing SQLite database
    println!("💡 Export and import utilities are available:\n");
    println!("   • export_to_json(store, agent_id, path)");
    println!("   • export_to_msgpack(store, agent_id, path)");
    println!("   • import_from_json(store, path)");
    println!("   • import_from_msgpack(store, path)\n");

    println!("✓ These functions allow you to backup and restore agent memories\n");

    // ============================================
    // Summary
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📊 Summary: Available Backends");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    println!("1. InMemoryStore (default)");
    println!("   • Fast, but data lost on restart");
    println!("   • Best for: Development, testing\n");

    println!("2. SqliteStore");
    println!("   • Persistent, efficient queries");
    println!("   • Best for: Production apps, large datasets\n");

    println!("3. FileStore (JSON)");
    println!("   • Human-readable, easy to inspect");
    println!("   • Best for: Debugging, data sharing\n");

    println!("4. FileStore (MessagePack)");
    println!("   • Compact binary format");
    println!("   • Best for: Large datasets, bandwidth constraints\n");

    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📝 Files Created:");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    println!("• agent_memory.db         - SQLite database");
    println!("• agent_memory.json       - JSON storage");
    println!("• agent_memory.msgpack    - MessagePack storage");
    println!("• backup.json             - Migrated data");
    println!("• exported_memory.json    - Exported snapshot");
    println!("• exported_memory.msgpack - Exported snapshot (binary)\n");

    println!("✅ Example completed successfully!");
    println!("\n💡 Tip: Check the created files to see your persisted data!");
    println!("   Try running this example again - your SQLite data will persist!");
}

pub async fn get_history(&self, limit: Option<usize>) -> Vec<MemoryEntry>

Retrieves conversation history from memory.

Arguments

• limit - Optional limit on number of conversations to retrieve. If None, returns all history.

Returns

A vector of MemoryEntry objects sorted by recency (newest first).

Examples

use ceylon_next::agent::Agent;

let agent = Agent::new("Assistant", "openai::gpt-4");

// Get last 5 conversations
let recent = agent.get_history(Some(5)).await;

// Get all history
let all = agent.get_history(None).await;

Examples found in repository

examples/03_with_memory.rs (line 59)

async fn main() {
    println!("🤖 Ceylon Agent - Memory Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MemoryAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful assistant with persistent memory. \
         Remember important details from our previous conversations \
         and refer back to them when relevant."
    );

    // Step 2: Run multiple tasks to build conversation history
    let tasks_and_prompts = vec![
        ("Tell me about your favorite color", "Learn about preferences"),
        ("What color did I mention?", "Test memory recall"),
        ("Can you suggest a hobby based on what you know about me?", "Use memory for suggestions"),
    ];

    for (prompt, description) in tasks_and_prompts {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", prompt);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(description)
            .with_priority(5);

        // Run the agent
        let response = agent.run(task).await;

        // Display response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✓ Response received\n");
            }
            _ => {
                println!("❌ Unexpected response type\n");
            }
        }
    }

    // Step 3: Retrieve conversation history
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Retrieving conversation history...\n");

    let history = agent.get_history(Some(5)).await;
    println!("Found {} recent conversations\n", history.len());

    if !history.is_empty() {
        println!("📖 Conversation Summary:");
        for (i, entry) in history.iter().enumerate() {
            println!("\n--- Conversation {} ---", i + 1);
            println!("Messages: {}", entry.messages.len());

            // Show first and last message
            if let Some(first) = entry.messages.first() {
                println!("First: {} - {}", first.role,
                    if first.content.len() > 50 {
                        format!("{}...", &first.content[..50])
                    } else {
                        first.content.clone()
                    });
            }

            if let Some(last) = entry.messages.last() {
                println!("Last: {} - {}", last.role,
                    if last.content.len() > 50 {
                        format!("{}...", &last.content[..50])
                    } else {
                        last.content.clone()
                    });
            }
        }
    }

    // Step 4: Search memory
    println!("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🔍 Searching memory for 'color'...\n");

    let search_results = agent.search_memory("color").await;
    println!("Found {} conversations mentioning 'color'\n", search_results.len());

    // Step 5: Clear memory (optional)
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🧹 Memory management options:");
    println!("- Use agent.get_history() to retrieve conversation history");
    println!("- Use agent.search_memory(query) to search conversations");
    println!("- Use agent.clear_memory() to clear all agent memory\n");

    println!("✅ Example completed successfully!");
}

pub async fn search_memory(&self, query: &str) -> Vec<MemoryEntry>

Searches conversation history for messages containing the query string.

Performs a case-insensitive text search across all stored messages.

Arguments

• query - The search query string

Returns

A vector of MemoryEntry objects containing the query.

Examples

use ceylon_next::agent::Agent;

let agent = Agent::new("Assistant", "openai::gpt-4");

let results = agent.search_memory("Python").await;
println!("Found {} conversations about Python", results.len());

Examples found in repository

examples/03_with_memory.rs (line 93)

async fn main() {
    println!("🤖 Ceylon Agent - Memory Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MemoryAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful assistant with persistent memory. \
         Remember important details from our previous conversations \
         and refer back to them when relevant."
    );

    // Step 2: Run multiple tasks to build conversation history
    let tasks_and_prompts = vec![
        ("Tell me about your favorite color", "Learn about preferences"),
        ("What color did I mention?", "Test memory recall"),
        ("Can you suggest a hobby based on what you know about me?", "Use memory for suggestions"),
    ];

    for (prompt, description) in tasks_and_prompts {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", prompt);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(description)
            .with_priority(5);

        // Run the agent
        let response = agent.run(task).await;

        // Display response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✓ Response received\n");
            }
            _ => {
                println!("❌ Unexpected response type\n");
            }
        }
    }

    // Step 3: Retrieve conversation history
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Retrieving conversation history...\n");

    let history = agent.get_history(Some(5)).await;
    println!("Found {} recent conversations\n", history.len());

    if !history.is_empty() {
        println!("📖 Conversation Summary:");
        for (i, entry) in history.iter().enumerate() {
            println!("\n--- Conversation {} ---", i + 1);
            println!("Messages: {}", entry.messages.len());

            // Show first and last message
            if let Some(first) = entry.messages.first() {
                println!("First: {} - {}", first.role,
                    if first.content.len() > 50 {
                        format!("{}...", &first.content[..50])
                    } else {
                        first.content.clone()
                    });
            }

            if let Some(last) = entry.messages.last() {
                println!("Last: {} - {}", last.role,
                    if last.content.len() > 50 {
                        format!("{}...", &last.content[..50])
                    } else {
                        last.content.clone()
                    });
            }
        }
    }

    // Step 4: Search memory
    println!("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🔍 Searching memory for 'color'...\n");

    let search_results = agent.search_memory("color").await;
    println!("Found {} conversations mentioning 'color'\n", search_results.len());

    // Step 5: Clear memory (optional)
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🧹 Memory management options:");
    println!("- Use agent.get_history() to retrieve conversation history");
    println!("- Use agent.search_memory(query) to search conversations");
    println!("- Use agent.clear_memory() to clear all agent memory\n");

    println!("✅ Example completed successfully!");
}

pub async fn clear_memory(&self) -> Result<(), String>

Clears all conversation history for this agent.

Returns

Ok(()) if successful, Err(String) with error message if failed.

Examples

use ceylon_next::agent::Agent;

let agent = Agent::new("Assistant", "openai::gpt-4");

if let Err(e) = agent.clear_memory().await {
    eprintln!("Failed to clear memory: {}", e);
}

pub fn get_current_goal(&self) -> Option<&Goal>

Returns the current goal the agent is working on, if any.

Examples

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

let mut agent = Agent::new("Assistant", "openai::gpt-4");

let task = TaskRequest::new("Build a web server");
agent.run(task).await;

if let Some(goal) = agent.get_current_goal() {
    println!("Current goal: {}", goal.description);
}

pub fn set_goal(&mut self, goal: Goal)

Manually sets a goal for the agent to work on.

This is useful when you want to provide a pre-structured goal instead of having the agent analyze the task automatically.

Arguments

• goal - The goal to set

Examples

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

let mut agent = Agent::new("Assistant", "openai::gpt-4");

let mut goal = Goal::new("Create a REST API".to_string());
goal.add_sub_goal("Design endpoints".to_string(), 1);
goal.add_sub_goal("Implement handlers".to_string(), 2);

agent.set_goal(goal);

Examples found in repository

examples/05_with_goals.rs (line 55)

async fn example_1_manual_goal() {
    println!("=== Example 1: Manual Goal Creation ===\n");

    // Create an agent
    let mut agent = Agent::new("MealPlanner", "ollama::gemma3:latest");

    // Create a goal manually for a complex task
    let mut goal = Goal::new(
        "Plan a healthy meal prep for the week".to_string()
    );

    // Define what success looks like
    println!("📋 Setting success criteria...");
    goal.add_criterion("7 breakfast recipes selected".to_string());
    goal.add_criterion("7 lunch recipes selected".to_string());
    goal.add_criterion("7 dinner recipes selected".to_string());
    goal.add_criterion("Shopping list created".to_string());
    goal.add_criterion("Prep schedule created".to_string());

    // Break down into steps (sub-goals)
    println!("🎯 Breaking down into sub-goals...\n");
    goal.add_sub_goal("Ask user about dietary preferences".to_string(), 0);
    goal.add_sub_goal("Ask about time available for prep".to_string(), 1);
    goal.add_sub_goal("Suggest breakfast options".to_string(), 2);
    goal.add_sub_goal("Suggest lunch options".to_string(), 3);
    goal.add_sub_goal("Suggest dinner options".to_string(), 4);
    goal.add_sub_goal("Create shopping list".to_string(), 5);
    goal.add_sub_goal("Create prep schedule".to_string(), 6);

    // Start working on the goal
    goal.status = GoalStatus::InProgress;

    // Set the goal on the agent
    agent.set_goal(goal.clone());

    // Create a task aligned with the goal
    let task = TaskRequest::new("I need help with meal planning");

    // Run the agent
    println!("⏳ Agent is working on the meal planning task...\n");
    let _response = agent.run(task).await;

    // Show the goal summary
    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: Goal Progress Tracking
// ============================================

async fn example_2_goal_progress_tracking() {
    println!("\n=== Example 2: Goal Progress Tracking ===\n");

    // Create a goal for a project
    let mut goal = Goal::new(
        "Create a project plan for building a mobile app".to_string()
    );

    // Add success criteria
    goal.add_criterion("Project requirements documented".to_string());
    goal.add_criterion("Timeline created with milestones".to_string());
    goal.add_criterion("Resource allocation plan completed".to_string());
    goal.add_criterion("Risk assessment performed".to_string());

    // Add sub-goals
    goal.add_sub_goal("Gather stakeholder requirements".to_string(), 0);
    goal.add_sub_goal("Define project scope".to_string(), 1);
    goal.add_sub_goal("Create development timeline".to_string(), 2);
    goal.add_sub_goal("Allocate resources".to_string(), 3);
    goal.add_sub_goal("Identify risks and mitigation strategies".to_string(), 4);

    goal.status = GoalStatus::InProgress;

    // Simulate progress through the goal
    println!("📈 Tracking goal progress...\n");

    // Complete first sub-goal
    println!("Step 1: Gathering requirements");
    goal.complete_sub_goal(0, Some("Interviewed 5 stakeholders".to_string()));
    goal.mark_criterion_met(0, "Requirements documented".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete second sub-goal
    println!("Step 2: Defining scope");
    goal.complete_sub_goal(1, Some("Scope document created".to_string()));
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete third sub-goal
    println!("Step 3: Creating timeline");
    goal.complete_sub_goal(2, Some("12-month timeline with milestones".to_string()));
    goal.mark_criterion_met(1, "Timeline created".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fourth sub-goal
    println!("Step 4: Allocating resources");
    goal.complete_sub_goal(3, Some("Resource allocation table created".to_string()));
    goal.mark_criterion_met(2, "Resources allocated".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fifth sub-goal
    println!("Step 5: Assessing risks");
    goal.complete_sub_goal(4, Some("Risk register created with 8 identified risks".to_string()));
    goal.mark_criterion_met(3, "Risks identified".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Show final status
    println!("\n📊 Final Goal Status:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: Job Interview Preparation Goal
// ============================================

async fn example_3_interview_preparation() {
    println!("\n=== Example 3: Job Interview Preparation Goal ===\n");

    let mut agent = Agent::new("InterviewCoach", "ollama::gemma3:latest");

    // Create a structured goal for interview prep
    let mut goal = Goal::new(
        "Prepare for a senior software engineer interview at a tech company".to_string()
    );

    // Define success criteria
    println!("🎯 Success criteria:");
    goal.add_criterion("Technical topics reviewed (algorithms, data structures, system design)".to_string());
    goal.add_criterion("Behavioral questions prepared with STAR method examples".to_string());
    goal.add_criterion("Company research completed".to_string());
    goal.add_criterion("Practice mock interview conducted".to_string());
    goal.add_criterion("Questions to ask the interviewer prepared".to_string());

    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    // Define steps
    println!("\n📋 Steps to take:");
    goal.add_sub_goal("Review core algorithms and data structures".to_string(), 0);
    goal.add_sub_goal("Study system design patterns".to_string(), 1);
    goal.add_sub_goal("Prepare STAR method stories from past projects".to_string(), 2);
    goal.add_sub_goal("Research company background and culture".to_string(), 3);
    goal.add_sub_goal("Practice mock interview with a friend".to_string(), 4);
    goal.add_sub_goal("Prepare thoughtful questions about the role".to_string(), 5);

    for sub_goal in &goal.sub_goals {
        println!("  {}. {}", sub_goal.priority + 1, sub_goal.description);
    }

    goal.status = GoalStatus::InProgress;

    // Set goal on agent
    agent.set_goal(goal.clone());

    // Create related task
    let task = TaskRequest::new("Help me prepare for my senior engineer interview");

    println!("\n⏳ Agent is creating interview preparation plan...\n");
    let _response = agent.run(task).await;

    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 3 completed!\n");
}

examples/06_nextjs_app_generator.rs (line 67)

async fn example_1_basic_nextjs_app() {
    println!("=== Example 1: Generate a Basic Next.js App ===\n");

    // Create an agent that will generate the app
    let mut agent = Agent::new("NextJsGenerator", "ollama::gemma3:latest");

    // Create a goal for generating a Next.js app
    let mut goal = Goal::new(
        "Generate a Next.js web application with essential structure".to_string()
    );

    // Define success criteria
    goal.add_criterion("package.json created with dependencies".to_string());
    goal.add_criterion("next.config.js configuration file generated".to_string());
    goal.add_criterion("pages directory with index and api route created".to_string());
    goal.add_criterion("styles directory with global CSS".to_string());
    goal.add_criterion("README.md with setup instructions".to_string());

    // Define sub-goals (steps to generate the app)
    goal.add_sub_goal("Analyze Next.js requirements and best practices".to_string(), 0);
    goal.add_sub_goal("Generate package.json with required dependencies".to_string(), 1);
    goal.add_sub_goal("Create next.config.js configuration".to_string(), 2);
    goal.add_sub_goal("Generate pages (index.tsx, _app.tsx, _document.tsx)".to_string(), 3);
    goal.add_sub_goal("Create API route examples".to_string(), 4);
    goal.add_sub_goal("Generate styling setup (global.css, utilities)".to_string(), 5);
    goal.add_sub_goal("Create components directory with example components".to_string(), 6);
    goal.add_sub_goal("Generate README with setup and usage instructions".to_string(), 7);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    // Create a task to generate a Next.js app
    let task = TaskRequest::new(
        "Generate a modern Next.js 14 application with TypeScript, Tailwind CSS, and best practices. \
         Include package.json, next.config.js, sample pages, API routes, and components. \
         The app should be production-ready and follow Next.js conventions."
    );

    println!("📝 Task: Generate a Next.js application\n");
    println!("🎯 Success Criteria:");
    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    println!("\n⏳ Agent is generating the Next.js app...\n");
    let response = agent.run(task).await;

    // Extract and display the output
    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    // Show progress
    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("Status: {:?}", goal.status);

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: E-Commerce Next.js App
// ============================================

async fn example_2_ecommerce_app() {
    println!("\n=== Example 2: Generate E-Commerce Next.js App ===\n");

    let mut agent = Agent::new("EcommerceGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a complete e-commerce Next.js application".to_string()
    );

    // Success criteria for e-commerce
    goal.add_criterion("Product listing page with filtering and sorting".to_string());
    goal.add_criterion("Product detail pages with dynamic routes".to_string());
    goal.add_criterion("Shopping cart functionality".to_string());
    goal.add_criterion("User authentication setup".to_string());
    goal.add_criterion("Payment integration structure".to_string());
    goal.add_criterion("Database models and API endpoints".to_string());
    goal.add_criterion("Admin dashboard layout".to_string());

    // Sub-goals
    goal.add_sub_goal("Design database schema for products and orders".to_string(), 0);
    goal.add_sub_goal("Create product API endpoints".to_string(), 1);
    goal.add_sub_goal("Build product listing and search components".to_string(), 2);
    goal.add_sub_goal("Implement product detail pages".to_string(), 3);
    goal.add_sub_goal("Create shopping cart context and management".to_string(), 4);
    goal.add_sub_goal("Build checkout flow pages".to_string(), 5);
    goal.add_sub_goal("Integrate payment gateway API".to_string(), 6);
    goal.add_sub_goal("Create admin dashboard pages".to_string(), 7);
    goal.add_sub_goal("Add authentication middleware".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a complete e-commerce Next.js application with: \
         1. Product management system (listing, search, filters)\n\
         2. Shopping cart with add/remove/update functionality\n\
         3. User authentication and profile pages\n\
         4. Payment integration endpoints\n\
         5. Order history and tracking\n\
         6. Admin dashboard for managing products and orders\n\
         7. Database models for PostgreSQL or MongoDB\n\
         8. RESTful API endpoints\n\
         Use TypeScript, Tailwind CSS, and modern React patterns."
    );

    println!("📝 Task: Generate E-Commerce Next.js Application\n");
    println!("🎯 Features to Generate:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating e-commerce app...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: SaaS Dashboard App
// ============================================

async fn example_3_saas_dashboard() {
    println!("\n=== Example 3: Generate SaaS Dashboard Next.js App ===\n");

    let mut agent = Agent::new("SaasDashboardGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a SaaS dashboard application with user management".to_string()
    );

    goal.add_criterion("User authentication and authorization".to_string());
    goal.add_criterion("Multi-tenant database structure".to_string());
    goal.add_criterion("Dashboard with analytics and metrics".to_string());
    goal.add_criterion("User and team management pages".to_string());
    goal.add_criterion("Settings and preferences pages".to_string());
    goal.add_criterion("Billing and subscription management".to_string());
    goal.add_criterion("API for data collection and reporting".to_string());

    goal.add_sub_goal("Design multi-tenant database schema".to_string(), 0);
    goal.add_sub_goal("Implement OAuth authentication".to_string(), 1);
    goal.add_sub_goal("Create dashboard with charts and metrics".to_string(), 2);
    goal.add_sub_goal("Build team and user management interfaces".to_string(), 3);
    goal.add_sub_goal("Create settings pages for users and organization".to_string(), 4);
    goal.add_sub_goal("Implement billing API integration".to_string(), 5);
    goal.add_sub_goal("Create analytics and reporting system".to_string(), 6);
    goal.add_sub_goal("Add email notification templates".to_string(), 7);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a complete SaaS dashboard Next.js application with:\n\
         1. Multi-tenant authentication (OAuth + JWT)\n\
         2. Organization and team management\n\
         3. Comprehensive dashboard with charts and analytics\n\
         4. User permission and role management\n\
         5. Billing integration with Stripe\n\
         6. Settings pages for users and teams\n\
         7. Email notifications system\n\
         8. API logging and activity tracking\n\
         9. Dark mode support\n\
         10. Mobile responsive design\n\
         Include TypeScript, Tailwind CSS, Recharts for visualizations, \
         and PostgreSQL database models."
    );

    println!("📝 Task: Generate SaaS Dashboard Application\n");
    println!("🎯 Dashboard Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating SaaS dashboard...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 3 completed!\n");
}

// ============================================
// Example 4: Blog Platform with CMS
// ============================================

async fn example_4_blog_platform() {
    println!("\n=== Example 4: Generate Blog Platform with CMS ===\n");

    let mut agent = Agent::new("BlogCMSGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a comprehensive blog platform with CMS".to_string()
    );

    goal.add_criterion("Blog post management system".to_string());
    goal.add_criterion("Rich text editor with markdown support".to_string());
    goal.add_criterion("Category and tag system".to_string());
    goal.add_criterion("Search and filtering functionality".to_string());
    goal.add_criterion("Comments system with moderation".to_string());
    goal.add_criterion("SEO optimization (meta tags, sitemap)".to_string());
    goal.add_criterion("Author management and permissions".to_string());
    goal.add_criterion("Analytics and engagement tracking".to_string());

    goal.add_sub_goal("Design blog database schema".to_string(), 0);
    goal.add_sub_goal("Create CMS backend API".to_string(), 1);
    goal.add_sub_goal("Build post editor with markdown".to_string(), 2);
    goal.add_sub_goal("Create blog listing and search pages".to_string(), 3);
    goal.add_sub_goal("Build individual post pages with SEO".to_string(), 4);
    goal.add_sub_goal("Implement comments system".to_string(), 5);
    goal.add_sub_goal("Create author profiles and bio".to_string(), 6);
    goal.add_sub_goal("Build admin dashboard for content management".to_string(), 7);
    goal.add_sub_goal("Add analytics tracking and reporting".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a full-featured blog platform with CMS:\n\
         1. Post creation and editing with rich text editor\n\
         2. Markdown support with preview\n\
         3. Category and tag system\n\
         4. Advanced search with filters\n\
         5. Comments system with nested replies\n\
         6. Author profiles with biography\n\
         7. SEO optimization (sitemaps, meta tags, structured data)\n\
         8. Social sharing integration\n\
         9. Email newsletter subscription\n\
         10. Analytics dashboard for authors\n\
         11. Reading time estimates\n\
         12. Related posts suggestions\n\
         Include TypeScript, Tailwind CSS, next-mdx-remote for markdown, \
         and MongoDB/PostgreSQL models."
    );

    println!("📝 Task: Generate Blog Platform with CMS\n");
    println!("🎯 Blog Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating blog platform...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 4 completed!\n");
}

examples/07_python_project_generator.rs (line 140)

async fn example_1_basic_cli_app() {
    println!("=== Example 1: Generate a Basic Python CLI Application ===\n");

    let mut agent = Agent::new("PythonCliGenerator", "ollama::gemma3:latest");

    // Create a goal for generating a Python CLI app
    let mut goal = Goal::new(
        "Generate a Python command-line application with core structure".to_string()
    );

    // Define success criteria
    goal.add_criterion("requirements.txt with dependencies listed".to_string());
    goal.add_criterion("setup.py or pyproject.toml for packaging".to_string());
    goal.add_criterion("Main CLI entry point with argument parsing".to_string());
    goal.add_criterion("Command structure with subcommands".to_string());
    goal.add_criterion("Basic error handling and logging".to_string());
    goal.add_criterion("README.md with usage instructions".to_string());
    goal.add_criterion(".gitignore for Python projects".to_string());

    // Define sub-goals (steps to generate the app)
    goal.add_sub_goal("Analyze Python CLI best practices".to_string(), 0);
    goal.add_sub_goal("Generate project structure and directories".to_string(), 1);
    goal.add_sub_goal("Create requirements.txt with dependencies (Click, Typer, etc)".to_string(), 2);
    goal.add_sub_goal("Generate pyproject.toml or setup.py".to_string(), 3);
    goal.add_sub_goal("Create main CLI module with argument parser".to_string(), 4);
    goal.add_sub_goal("Generate subcommands and command handlers".to_string(), 5);
    goal.add_sub_goal("Create utility modules and helpers".to_string(), 6);
    goal.add_sub_goal("Add logging and error handling".to_string(), 7);
    goal.add_sub_goal("Generate README with installation and usage".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    // Create a task to generate a Python CLI app
    let task = TaskRequest::new(
        "Generate a professional Python command-line application with the following structure:\n\
         1. Modern argument parsing using Click or Typer\n\
         2. Multiple subcommands (e.g., init, run, config, help)\n\
         3. Configuration file support (YAML or JSON)\n\
         4. Logging with different verbosity levels\n\
         5. Error handling and graceful failure messages\n\
         6. Proper project structure with src/ and tests/ directories\n\
         7. pyproject.toml or setup.py for packaging\n\
         8. requirements.txt with dev dependencies\n\
         9. .gitignore for Python\n\
         10. Comprehensive README with examples\n\
         The app should be production-ready and follow Python best practices (PEP 8)."
    );

    println!("📝 Task: Generate a Python CLI Application\n");
    println!("🎯 Success Criteria:");
    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    println!("\n⏳ Agent is generating the Python CLI app...\n");
    let response = agent.run(task).await;

    // Extract and display the output
    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    // Show progress
    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("Status: {:?}", goal.status);

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: Python Web API with FastAPI
// ============================================

async fn example_2_fastapi_web_app() {
    println!("\n=== Example 2: Generate Python FastAPI Web Application ===\n");

    let mut agent = Agent::new("FastApiGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a complete FastAPI web application with database integration".to_string()
    );

    // Success criteria for FastAPI app
    goal.add_criterion("FastAPI application structure with routers".to_string());
    goal.add_criterion("Database models using SQLAlchemy".to_string());
    goal.add_criterion("RESTful API endpoints with CRUD operations".to_string());
    goal.add_criterion("Request/response schemas using Pydantic".to_string());
    goal.add_criterion("Authentication and authorization middleware".to_string());
    goal.add_criterion("Database migrations with Alembic".to_string());
    goal.add_criterion("Configuration management with environment variables".to_string());
    goal.add_criterion("Unit and integration test examples".to_string());
    goal.add_criterion("Docker setup for containerization".to_string());

    // Sub-goals
    goal.add_sub_goal("Design REST API endpoints structure".to_string(), 0);
    goal.add_sub_goal("Create Pydantic models for request/response validation".to_string(), 1);
    goal.add_sub_goal("Set up SQLAlchemy ORM with database models".to_string(), 2);
    goal.add_sub_goal("Implement CRUD routers for resources".to_string(), 3);
    goal.add_sub_goal("Add authentication and JWT tokens".to_string(), 4);
    goal.add_sub_goal("Create Alembic migrations setup".to_string(), 5);
    goal.add_sub_goal("Set up configuration with environment variables".to_string(), 6);
    goal.add_sub_goal("Create test fixtures and example tests".to_string(), 7);
    goal.add_sub_goal("Generate Docker and docker-compose files".to_string(), 8);
    goal.add_sub_goal("Create comprehensive API documentation".to_string(), 9);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a production-ready FastAPI web application with:\n\
         1. Modular project structure with routers for different resources\n\
         2. Pydantic models for request/response validation\n\
         3. SQLAlchemy ORM setup with database models\n\
         4. CRUD operations for users, products, and orders\n\
         5. JWT authentication and authorization middleware\n\
         6. Role-based access control (RBAC)\n\
         7. Alembic database migrations\n\
         8. Environment configuration (.env support)\n\
         9. Error handling with proper HTTP status codes\n\
         10. Logging configuration\n\
         11. Unit tests with pytest\n\
         12. Integration tests with test database\n\
         13. Docker and docker-compose for local development\n\
         14. requirements.txt with all dependencies\n\
         15. Comprehensive API documentation\n\
         Use async/await patterns, follow REST conventions, and include examples."
    );

    println!("📝 Task: Generate FastAPI Web Application\n");
    println!("🎯 FastAPI Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating FastAPI app...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: Python Data Science Project
// ============================================

async fn example_3_data_science_project() {
    println!("\n=== Example 3: Generate Python Data Science Project ===\n");

    let mut agent = Agent::new("DataScienceGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a data science project with ML pipeline and analysis".to_string()
    );

    goal.add_criterion("Project structure following cookiecutter-data-science".to_string());
    goal.add_criterion("Data loading and preprocessing modules".to_string());
    goal.add_criterion("Exploratory data analysis (EDA) notebooks".to_string());
    goal.add_criterion("Feature engineering pipeline".to_string());
    goal.add_criterion("Model training and evaluation".to_string());
    goal.add_criterion("Hyperparameter tuning setup".to_string());
    goal.add_criterion("Model persistence and versioning".to_string());
    goal.add_criterion("Visualization utilities".to_string());
    goal.add_criterion("Unit tests for data pipeline".to_string());

    goal.add_sub_goal("Create cookiecutter-style directory structure".to_string(), 0);
    goal.add_sub_goal("Set up Jupyter notebook for EDA".to_string(), 1);
    goal.add_sub_goal("Create data loading and preprocessing modules".to_string(), 2);
    goal.add_sub_goal("Implement feature engineering pipeline".to_string(), 3);
    goal.add_sub_goal("Set up scikit-learn model training".to_string(), 4);
    goal.add_sub_goal("Create model evaluation and metrics".to_string(), 5);
    goal.add_sub_goal("Implement hyperparameter tuning with GridSearchCV".to_string(), 6);
    goal.add_sub_goal("Add model persistence with joblib/pickle".to_string(), 7);
    goal.add_sub_goal("Create visualization utilities with matplotlib/seaborn".to_string(), 8);
    goal.add_sub_goal("Write tests for data pipeline".to_string(), 9);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a comprehensive Python data science project with:\n\
         1. Proper project structure for data science work\n\
         2. Data loading module supporting CSV, JSON, Parquet\n\
         3. Data preprocessing and validation pipeline\n\
         4. Exploratory Data Analysis (EDA) notebook template\n\
         5. Feature engineering module\n\
         6. Model training with scikit-learn or XGBoost\n\
         7. Cross-validation and evaluation metrics\n\
         8. Hyperparameter tuning with GridSearchCV/RandomSearch\n\
         9. Model persistence and loading utilities\n\
         10. Visualization utilities (matplotlib, seaborn, plotly)\n\
         11. Unit tests for data loading and preprocessing\n\
         12. Configuration management for experiments\n\
         13. Logging for training pipeline\n\
         14. Requirements.txt with ML libraries (pandas, numpy, scikit-learn)\n\
         15. Makefile for common tasks\n\
         16. README with dataset description and results\n\
         Include example workflows and best practices for reproducibility."
    );

    println!("📝 Task: Generate Data Science Project\n");
    println!("🎯 Data Science Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating data science project...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 3 completed!\n");
}

// ============================================
// Example 4: Python Package/Library
// ============================================

async fn example_4_python_library() {
    println!("\n=== Example 4: Generate Python Library/Package ===\n");

    let mut agent = Agent::new("PythonLibraryGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a well-structured Python package ready for distribution".to_string()
    );

    goal.add_criterion("Proper package structure with namespace".to_string());
    goal.add_criterion("setup.py and pyproject.toml for distribution".to_string());
    goal.add_criterion("Comprehensive docstrings and type hints".to_string());
    goal.add_criterion("Unit tests with pytest".to_string());
    goal.add_criterion("Documentation with Sphinx".to_string());
    goal.add_criterion("CI/CD configuration (GitHub Actions)".to_string());
    goal.add_criterion("Version management strategy".to_string());
    goal.add_criterion("Contributing guidelines".to_string());

    goal.add_sub_goal("Create package structure with __init__.py files".to_string(), 0);
    goal.add_sub_goal("Write setup.py and pyproject.toml".to_string(), 1);
    goal.add_sub_goal("Create core modules with type hints".to_string(), 2);
    goal.add_sub_goal("Add comprehensive docstrings".to_string(), 3);
    goal.add_sub_goal("Create test structure with pytest".to_string(), 4);
    goal.add_sub_goal("Set up documentation with Sphinx".to_string(), 5);
    goal.add_sub_goal("Create GitHub Actions workflows".to_string(), 6);
    goal.add_sub_goal("Add CONTRIBUTING.md and CODE_OF_CONDUCT.md".to_string(), 7);
    goal.add_sub_goal("Create MANIFEST.in and manifest files".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a professional Python library/package with:\n\
         1. Standard package structure (src layout)\n\
         2. __init__.py with version and exports\n\
         3. Core modules with complete implementations\n\
         4. Type hints throughout (PEP 484)\n\
         5. Comprehensive docstrings (Google style)\n\
         6. setup.py with metadata\n\
         7. pyproject.toml with build system\n\
         8. MANIFEST.in for package data\n\
         9. Pytest test structure with fixtures\n\
         10. pytest.ini configuration\n\
         11. Sphinx documentation setup\n\
         12. GitHub Actions workflow for CI/CD\n\
         13. Pre-commit hooks configuration\n\
         14. LICENSE (MIT or Apache 2.0)\n\
         15. .gitignore for Python\n\
         16. README.md with installation and usage\n\
         17. CONTRIBUTING.md for contributors\n\
         18. CODE_OF_CONDUCT.md\n\
         19. Changelog/HISTORY.md template\n\
         20. Version management with __version__\n\
         Include examples for public API and best practices for library development."
    );

    println!("📝 Task: Generate Python Library Package\n");
    println!("🎯 Library Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating Python library...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 4 completed!\n");
}

// ============================================
// Example 5: Django Web Application
// ============================================

async fn example_5_django_web_app() {
    println!("\n=== Example 5: Generate Django Web Application ===\n");

    let mut agent = Agent::new("DjangoGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a complete Django web application with admin and authentication".to_string()
    );

    goal.add_criterion("Django project structure with multiple apps".to_string());
    goal.add_criterion("Custom user model implementation".to_string());
    goal.add_criterion("Database models for core features".to_string());
    goal.add_criterion("Admin interface customization".to_string());
    goal.add_criterion("Views and URL routing".to_string());
    goal.add_criterion("Templates with Bootstrap styling".to_string());
    goal.add_criterion("Authentication and permissions".to_string());
    goal.add_criterion("Database migrations".to_string());
    goal.add_criterion("Django REST Framework API".to_string());

    goal.add_sub_goal("Create Django project and app structure".to_string(), 0);
    goal.add_sub_goal("Design and implement custom user model".to_string(), 1);
    goal.add_sub_goal("Create models for core features".to_string(), 2);
    goal.add_sub_goal("Configure admin interface".to_string(), 3);
    goal.add_sub_goal("Create views and templates".to_string(), 4);
    goal.add_sub_goal("Set up URL routing".to_string(), 5);
    goal.add_sub_goal("Implement authentication views".to_string(), 6);
    goal.add_sub_goal("Create Django REST Framework serializers".to_string(), 7);
    goal.add_sub_goal("Set up static files and media handling".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a full-featured Django web application with:\n\
         1. Django project structure with multiple apps\n\
         2. Custom user model extending AbstractBaseUser\n\
         3. Models for main features (e.g., Blog posts, Comments, Categories)\n\
         4. Django ORM relationships (ForeignKey, ManyToMany)\n\
         5. Admin interface with custom actions\n\
         6. Class-based views (ListView, DetailView, CreateView)\n\
         7. Django templates with template inheritance\n\
         8. Bootstrap styling integration\n\
         9. Authentication and login required decorators\n\
         10. Permission-based access control\n\
         11. Database migrations\n\
         12. Forms with validation\n\
         13. Django REST Framework setup\n\
         14. API serializers and viewsets\n\
         15. Pagination and filtering\n\
         16. Settings for dev and production\n\
         17. Environment variable configuration\n\
         18. Logging configuration\n\
         19. Tests with Django TestCase\n\
         20. Static files and media management\n\
         21. Docker setup\n\
         22. Requirements.txt\n\
         Include examples and docstrings following Django conventions."
    );

    println!("📝 Task: Generate Django Web Application\n");
    println!("🎯 Django Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating Django app...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 5 completed!\n");
}

pub fn with_system_prompt(&mut self, prompt: &str) -> &mut Self

Sets a custom system prompt for the agent.

The system prompt defines the agent’s behavior, personality, and instructions. By default, a goal-oriented system prompt is used.

Arguments

• prompt - The system prompt text

Examples

use ceylon_next::agent::Agent;

let mut agent = Agent::new("Assistant", "openai::gpt-4");
agent.with_system_prompt("You are a helpful coding assistant specializing in Rust.");

Examples found in repository

examples/02_with_tools.rs (lines 143-147)

async fn main() {
    println!("🤖 Ceylon Agent - Tools Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MathAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful math and text assistant. \
         Use the available tools to help the user. \
         Be clear about what tools you're using and why."
    );

    // Step 2: Register custom tools with the agent
    println!("🔧 Registering tools...");
    agent.add_tool(CalculatorTool);
    agent.add_tool(StringToolTool);
    println!("✓ Tools registered\n");

    // Step 3: Create a task that requires tool usage
    let mut task = TaskRequest::new(
        "Please calculate 25 + 15 + 10, and then tell me the uppercase version of the word 'hello'"
    );
    task.with_name("Complex Task")
        .with_description("A task requiring multiple tools")
        .with_priority(8);

    // Step 4: Run the agent
    println!("📋 Task: {}\n", task.id());
    let response = agent.run(task).await;

    // Step 5: Display the result
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/01_basic_agent.rs (lines 27-30)

async fn main() {
    println!("🤖 Ceylon Agent - Basic Example\n");

    // Step 1: Create a new agent with a name and model
    // The model should be one supported by the LLM library (openai, anthropic, ollama, etc.)
    let mut agent = Agent::new("Assistant", "ollama::gemma3:latest");

    // Step 2: (Optional) Configure the agent with custom settings
    let config = AgentConfig::new(
        3,   // max_retries
        60,  // timeout in seconds
    );
    agent.with_config(config);

    // Step 3: (Optional) Customize the system prompt
    agent.with_system_prompt(
        "You are a helpful assistant that answers questions accurately and concisely. \
         Always provide well-structured responses."
    );

    // Step 4: Create a task request
    let mut task = TaskRequest::new("What is the capital of France?");
    task.with_name("Geography Question")
        .with_description("A simple geography question")
        .with_priority(5);

    // Step 5: Run the agent with the task
    println!("📋 Task: {}\n", "What is the capital of France?");
    let response = agent.run(task).await;

    // Step 6: Handle the response
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/04_advanced_agent.rs (lines 127-132)

async fn main() {
    println!("🤖 Ceylon Agent - Advanced Example\n");

    // Step 1: Create an agent with custom configuration
    let mut agent = Agent::new("AdvancedAssistant", "ollama::gemma3:latest");

    // Configure with custom settings
    let config = AgentConfig::new(
        5,   // Allow more retries for complex tasks
        120, // Longer timeout
    );
    agent.with_config(config);

    // Custom system prompt for the advanced agent
    agent.with_system_prompt(
        "You are an advanced AI assistant with access to specialized tools. \
         You can fetch weather data and analyze text. \
         Always explain your reasoning and use tools appropriately. \
         Provide detailed and accurate responses.",
    );

    // Step 2: Register multiple tools
    println!("🔧 Registering tools...");
    agent.add_tool(WeatherTool);
    agent.add_tool(TextAnalyzerTool);
    println!("✓ Tools registered: get_weather, analyze_text\n");

    // Step 3: Create and run multiple tasks with different priorities
    let tasks_data = vec![
        (
            "What's the weather in Paris and London? Compare them.",
            "Weather Comparison",
            "Compare weather in two cities",
            9, // High priority
        ),
        (
            "Analyze this text for readability: 'The quick brown fox jumps over the lazy dog. \
             This sentence demonstrates all letters of the English alphabet.'",
            "Text Analysis",
            "Analyze readability",
            5, // Medium priority
        ),
    ];

    for (prompt, name, description, priority) in tasks_data {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", name);
        println!("⭐ Priority: {}/10", priority);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(name)
            .with_description(description)
            .with_priority(priority);

        // Run the agent
        println!("⏳ Running agent...\n");
        let response = agent.run(task).await;

        // Handle response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✅ Task completed\n");
            }
            _ => {
                println!("⚠️ Unexpected response type\n");
            }
        }
    }

    // Step 4: Demonstrate memory capabilities
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Agent Status Summary:");
    println!("• System Prompt: Custom advanced prompt");
    println!("• Tools Available: 2 (weather, text analyzer)");
    println!("• Memory Enabled: Yes");
    println!("• Max Retries: 5");
    println!("• Timeout: 120 seconds");
    println!("• Tasks Completed: 2\n");

    println!("✅ Advanced example completed successfully!");
}

examples/03_with_memory.rs (lines 18-22)

async fn main() {
    println!("🤖 Ceylon Agent - Memory Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MemoryAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful assistant with persistent memory. \
         Remember important details from our previous conversations \
         and refer back to them when relevant."
    );

    // Step 2: Run multiple tasks to build conversation history
    let tasks_and_prompts = vec![
        ("Tell me about your favorite color", "Learn about preferences"),
        ("What color did I mention?", "Test memory recall"),
        ("Can you suggest a hobby based on what you know about me?", "Use memory for suggestions"),
    ];

    for (prompt, description) in tasks_and_prompts {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", prompt);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(description)
            .with_priority(5);

        // Run the agent
        let response = agent.run(task).await;

        // Display response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✓ Response received\n");
            }
            _ => {
                println!("❌ Unexpected response type\n");
            }
        }
    }

    // Step 3: Retrieve conversation history
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Retrieving conversation history...\n");

    let history = agent.get_history(Some(5)).await;
    println!("Found {} recent conversations\n", history.len());

    if !history.is_empty() {
        println!("📖 Conversation Summary:");
        for (i, entry) in history.iter().enumerate() {
            println!("\n--- Conversation {} ---", i + 1);
            println!("Messages: {}", entry.messages.len());

            // Show first and last message
            if let Some(first) = entry.messages.first() {
                println!("First: {} - {}", first.role,
                    if first.content.len() > 50 {
                        format!("{}...", &first.content[..50])
                    } else {
                        first.content.clone()
                    });
            }

            if let Some(last) = entry.messages.last() {
                println!("Last: {} - {}", last.role,
                    if last.content.len() > 50 {
                        format!("{}...", &last.content[..50])
                    } else {
                        last.content.clone()
                    });
            }
        }
    }

    // Step 4: Search memory
    println!("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🔍 Searching memory for 'color'...\n");

    let search_results = agent.search_memory("color").await;
    println!("Found {} conversations mentioning 'color'\n", search_results.len());

    // Step 5: Clear memory (optional)
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🧹 Memory management options:");
    println!("- Use agent.get_history() to retrieve conversation history");
    println!("- Use agent.search_memory(query) to search conversations");
    println!("- Use agent.clear_memory() to clear all agent memory\n");

    println!("✅ Example completed successfully!");
}

examples/10_file_saving.rs (lines 99-111)

async fn main() {
    println!("🤖 Ceylon Agent - File Saving Example\n");

    // Define the output directory
    let output_dir = "test/web_project_output";

    // Create the output directory if it doesn't exist
    if let Err(e) = fs::create_dir_all(output_dir) {
        eprintln!("❌ Failed to create output directory: {}", e);
        return;
    }
    println!("📁 Output directory: {}/\n", output_dir);

    // Step 1: Create an agent
    let mut agent = Agent::new("ContentGenerator", "ollama::gemma3:latest");

    agent.with_system_prompt(
        &format!(
            "You are a helpful assistant that can generate content and save it to files. \
             When asked to create content, generate it and use the file_saver tool to save it. \
             \
             IMPORTANT: All files MUST be saved inside the '{}' directory. \
             For example, to save 'server.js', use '{}/server.js' as the filename. \
             For files in subdirectories, use '{}/src/app.js' format. \
             \
             Be clear about what you're creating and where you're saving it.",
            output_dir, output_dir, output_dir
        )
    );

    // Step 2: Register the file saver tool
    println!("🔧 Registering file saver tool...");
    agent.add_tool(FileSaverTool);
    println!("✓ Tool registered\n");

    // Step 3: Create a task that generates content and saves it
    let mut task = TaskRequest::new(
        &format!(
            "Create a simple web project with a file upload API. Save all files in the '{}' directory:\
             \n1. server.js - A Node.js Express server with POST /upload endpoint\
             \n2. package.json - Package configuration with dependencies\
             \n3. test.http - HTTP test file to test the upload endpoint\
             \n4. README.md - Instructions on how to install and run the server\
             \n\nMake sure ALL files are saved in the '{}' directory!",
            output_dir, output_dir
        )
    );
    task.with_name("Generate and Save Web Project")
        .with_description("Generate a complete web project with file upload API")
        .with_priority(7);

    // Step 4: Run the agent
    println!("📋 Task: {}\n", task.id());
    println!("🔄 Running agent...\n");

    let response = agent.run(task).await;

    // Step 5: Display the result
    match response.result() {
        OutputData::Text(answer) => {
            println!("\n📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    // Step 6: Verify files were created
    println!("🔍 Checking created files in '{}/'\n", output_dir);

    let expected_files = vec![
        "server.js",
        "package.json",
        "test.http",
        "README.md"
    ];

    let mut created_count = 0;

    for file in &expected_files {
        let file_path = format!("{}/{}", output_dir, file);
        if Path::new(&file_path).exists() {
            created_count += 1;
            println!("✓ {} created successfully", file);

            if let Ok(content) = fs::read_to_string(&file_path) {
                let preview: String = content.chars().take(100).collect();
                println!("  Preview: {}", preview.replace('\n', " "));
            }
        } else {
            println!("⚠ {} not found", file);
        }
    }

    println!("\n📊 Summary: {}/{} expected files created", created_count, expected_files.len());

    // Show directory structure
    println!("\n📂 Directory structure:");
    if let Ok(entries) = fs::read_dir(output_dir) {
        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_file() {
                if let Some(filename) = path.file_name() {
                    if let Ok(metadata) = entry.metadata() {
                        println!("  - {} ({} bytes)",
                                 filename.to_string_lossy(),
                                 metadata.len());
                    }
                }
            }
        }
    }

    println!("\n✅ Example completed successfully!");
    println!("📁 All files are in: {}/", output_dir);
}

examples/11_persistent_memory.rs (line 32)

async fn main() {
    println!("🤖 Ceylon Agent - Persistent Memory Example\n");

    // ============================================
    // Part 1: SQLite Backend
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📦 Part 1: SQLite Backend");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let sqlite_path = "agent_memory.db";
    let sqlite_store = SqliteStore::new(sqlite_path).await
        .expect("Failed to create SQLite store");

    let mut agent = Agent::new("PersistentAssistant", "ollama::gemma3:latest");
    agent.with_memory(Arc::new(sqlite_store))
         .with_system_prompt("You are a helpful assistant with persistent memory across sessions.");

    println!("✅ Created agent with SQLite backend at {}\n", sqlite_path);

    // Run some tasks to populate memory
    let tasks = vec![
        "My name is Alice and I love programming in Rust",
        "What programming language do I like?",
    ];

    for prompt in tasks {
        println!("📋 Task: {}", prompt);
        let mut task = TaskRequest::new(prompt);
        task.with_priority(5);

        let response = agent.run(task).await;
        if let OutputData::Text(_) = response.result() {
            println!("✓ Task completed\n");
        }
    }

    println!("📊 SQLite database now contains conversation history");
    println!("   This data persists even after the program exits!\n");

    // ============================================
    // Part 2: File-based Backend (JSON)
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📄 Part 2: File-based Backend (JSON)");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let json_path = "agent_memory.json";
    let file_store = FileStore::new(json_path, StorageFormat::Json).await
        .expect("Failed to create File store");

    let mut agent2 = Agent::new("FileAssistant", "ollama::gemma3:latest");
    agent2.with_memory(Arc::new(file_store))
          .with_system_prompt("You are a helpful assistant storing memories in JSON files.");

    println!("✅ Created agent with JSON file backend at {}\n", json_path);

    let task = TaskRequest::new("Remember: My favorite color is blue");
    let response = agent2.run(task).await;

    if let OutputData::Text(_) = response.result() {
        println!("✓ Memory saved to JSON file");
        println!("   You can open {} to view the human-readable data!\n", json_path);
    }

    // ============================================
    // Part 3: MessagePack Backend
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📦 Part 3: MessagePack Backend (Compact Binary)");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let msgpack_path = "agent_memory.msgpack";
    let msgpack_store = FileStore::new(msgpack_path, StorageFormat::MessagePack).await
        .expect("Failed to create MessagePack store");

    let mut agent3 = Agent::new("BinaryAssistant", "ollama::gemma3:latest");
    agent3.with_memory(Arc::new(msgpack_store))
          .with_system_prompt("You are a helpful assistant using compact binary storage.");

    println!("✅ Created agent with MessagePack backend at {}\n", msgpack_path);

    let task = TaskRequest::new("Store this efficiently: The quick brown fox jumps over the lazy dog");
    let response = agent3.run(task).await;

    if let OutputData::Text(_) = response.result() {
        println!("✓ Memory saved to MessagePack file");
        println!("   Binary format is more compact than JSON!\n");
    }

    // ============================================
    // Part 4: Memory Migration
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🔄 Part 4: Memory Migration Between Backends");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Create source and destination stores
    let source_db = SqliteStore::new("source.db").await.unwrap();

    // Create an agent with source backend and add some data
    let mut temp_agent = Agent::new("MigrationAgent", "ollama::gemma3:latest");
    temp_agent.with_memory(Arc::new(source_db));

    let task = TaskRequest::new("Migration test: This data will be migrated!");
    temp_agent.run(task).await;

    // Note: You would normally track your agent IDs. For this demo, we'll use
    // a known pattern - the agent creates entries with its own ID
    println!("💡 Tip: To migrate data, you need to know the agent's ID");
    println!("   In production, track agent IDs when creating agents\n");

    println!("✓ Migration between backends is available via migrate_memory()\n");
    println!("   Example: migrate_memory(&source, &target, \"agent-id\").await\n");

    // ============================================
    // Part 5: Export/Import Utilities
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("💾 Part 5: Export/Import Utilities");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Demonstrate export/import with the existing SQLite database
    println!("💡 Export and import utilities are available:\n");
    println!("   • export_to_json(store, agent_id, path)");
    println!("   • export_to_msgpack(store, agent_id, path)");
    println!("   • import_from_json(store, path)");
    println!("   • import_from_msgpack(store, path)\n");

    println!("✓ These functions allow you to backup and restore agent memories\n");

    // ============================================
    // Summary
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📊 Summary: Available Backends");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    println!("1. InMemoryStore (default)");
    println!("   • Fast, but data lost on restart");
    println!("   • Best for: Development, testing\n");

    println!("2. SqliteStore");
    println!("   • Persistent, efficient queries");
    println!("   • Best for: Production apps, large datasets\n");

    println!("3. FileStore (JSON)");
    println!("   • Human-readable, easy to inspect");
    println!("   • Best for: Debugging, data sharing\n");

    println!("4. FileStore (MessagePack)");
    println!("   • Compact binary format");
    println!("   • Best for: Large datasets, bandwidth constraints\n");

    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📝 Files Created:");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    println!("• agent_memory.db         - SQLite database");
    println!("• agent_memory.json       - JSON storage");
    println!("• agent_memory.msgpack    - MessagePack storage");
    println!("• backup.json             - Migrated data");
    println!("• exported_memory.json    - Exported snapshot");
    println!("• exported_memory.msgpack - Exported snapshot (binary)\n");

    println!("✅ Example completed successfully!");
    println!("\n💡 Tip: Check the created files to see your persisted data!");
    println!("   Try running this example again - your SQLite data will persist!");
}

pub fn get_system_prompt(&self) -> &str

Returns the current system prompt.

Examples

use ceylon_next::agent::Agent;

let agent = Agent::new("Assistant", "openai::gpt-4");
println!("System prompt: {}", agent.get_system_prompt());

pub fn with_config(&mut self, config: AgentConfig) -> &mut Self

Sets the agent configuration.

Arguments

• config - The AgentConfig to use

Examples

use ceylon_next::agent::{Agent, AgentConfig};

let mut agent = Agent::new("Assistant", "openai::gpt-4");

let mut config = AgentConfig::new(5, 120);
config.with_goal_analysis(true);

agent.with_config(config);

Examples found in repository

examples/01_basic_agent.rs (line 24)

async fn main() {
    println!("🤖 Ceylon Agent - Basic Example\n");

    // Step 1: Create a new agent with a name and model
    // The model should be one supported by the LLM library (openai, anthropic, ollama, etc.)
    let mut agent = Agent::new("Assistant", "ollama::gemma3:latest");

    // Step 2: (Optional) Configure the agent with custom settings
    let config = AgentConfig::new(
        3,   // max_retries
        60,  // timeout in seconds
    );
    agent.with_config(config);

    // Step 3: (Optional) Customize the system prompt
    agent.with_system_prompt(
        "You are a helpful assistant that answers questions accurately and concisely. \
         Always provide well-structured responses."
    );

    // Step 4: Create a task request
    let mut task = TaskRequest::new("What is the capital of France?");
    task.with_name("Geography Question")
        .with_description("A simple geography question")
        .with_priority(5);

    // Step 5: Run the agent with the task
    println!("📋 Task: {}\n", "What is the capital of France?");
    let response = agent.run(task).await;

    // Step 6: Handle the response
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/04_advanced_agent.rs (line 124)

async fn main() {
    println!("🤖 Ceylon Agent - Advanced Example\n");

    // Step 1: Create an agent with custom configuration
    let mut agent = Agent::new("AdvancedAssistant", "ollama::gemma3:latest");

    // Configure with custom settings
    let config = AgentConfig::new(
        5,   // Allow more retries for complex tasks
        120, // Longer timeout
    );
    agent.with_config(config);

    // Custom system prompt for the advanced agent
    agent.with_system_prompt(
        "You are an advanced AI assistant with access to specialized tools. \
         You can fetch weather data and analyze text. \
         Always explain your reasoning and use tools appropriately. \
         Provide detailed and accurate responses.",
    );

    // Step 2: Register multiple tools
    println!("🔧 Registering tools...");
    agent.add_tool(WeatherTool);
    agent.add_tool(TextAnalyzerTool);
    println!("✓ Tools registered: get_weather, analyze_text\n");

    // Step 3: Create and run multiple tasks with different priorities
    let tasks_data = vec![
        (
            "What's the weather in Paris and London? Compare them.",
            "Weather Comparison",
            "Compare weather in two cities",
            9, // High priority
        ),
        (
            "Analyze this text for readability: 'The quick brown fox jumps over the lazy dog. \
             This sentence demonstrates all letters of the English alphabet.'",
            "Text Analysis",
            "Analyze readability",
            5, // Medium priority
        ),
    ];

    for (prompt, name, description, priority) in tasks_data {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", name);
        println!("⭐ Priority: {}/10", priority);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(name)
            .with_description(description)
            .with_priority(priority);

        // Run the agent
        println!("⏳ Running agent...\n");
        let response = agent.run(task).await;

        // Handle response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✅ Task completed\n");
            }
            _ => {
                println!("⚠️ Unexpected response type\n");
            }
        }
    }

    // Step 4: Demonstrate memory capabilities
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Agent Status Summary:");
    println!("• System Prompt: Custom advanced prompt");
    println!("• Tools Available: 2 (weather, text analyzer)");
    println!("• Memory Enabled: Yes");
    println!("• Max Retries: 5");
    println!("• Timeout: 120 seconds");
    println!("• Tasks Completed: 2\n");

    println!("✅ Advanced example completed successfully!");
}

pub fn with_llm_config( &mut self, llm_config: LLMConfig, ) -> Result<&mut Self, String>

Configures the agent with comprehensive LLM settings using LLMConfig.

This allows you to set advanced LLM parameters like temperature, top_p, reasoning, provider-specific options, and more.

Arguments

• llm_config - The LLMConfig containing comprehensive LLM settings

Examples

use ceylon_next::agent::Agent;
use ceylon_next::llm::LLMConfig;

let mut agent = Agent::new("Assistant", "openai::gpt-4");

// Configure with advanced settings
let llm_config = LLMConfig::new("openai::gpt-4")
    .with_api_key("your-api-key")
    .with_temperature(0.7)
    .with_max_tokens(2048)
    .with_top_p(0.9);

agent.with_llm_config(llm_config);

Provider-Specific Examples

Azure OpenAI

use ceylon_next::agent::Agent;
use ceylon_next::llm::LLMConfig;

let mut agent = Agent::new("Assistant", "azure::gpt-4");

let config = LLMConfig::new("azure::gpt-4")
    .with_api_key("your-azure-key")
    .with_deployment_id("your-deployment-id")
    .with_api_version("2024-02-01");

agent.with_llm_config(config);

OpenAI with Web Search

use ceylon_next::agent::Agent;
use ceylon_next::llm::LLMConfig;

let mut agent = Agent::new("Assistant", "openai::gpt-4");

let config = LLMConfig::new("openai::gpt-4")
    .with_api_key("your-api-key")
    .with_openai_web_search(true);

agent.with_llm_config(config);

Anthropic with Reasoning

use ceylon_next::agent::Agent;
use ceylon_next::llm::LLMConfig;

let mut agent = Agent::new("Assistant", "anthropic::claude-3-opus");

let config = LLMConfig::new("anthropic::claude-3-opus")
    .with_api_key("your-api-key")
    .with_reasoning(true)
    .with_reasoning_effort("high");

agent.with_llm_config(config);

Examples found in repository

examples/08_llm_providers.rs (line 196)

async fn advanced_configuration() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Using LLMConfig for advanced configuration:\n");

    // Method 1: Using Agent::new_with_config() (Recommended for explicit API keys)
    println!("📘 Using Agent::new_with_config() with explicit API key:");
    if let Ok(api_key) = std::env::var("OPENAI_API_KEY") {
        let config = LLMConfig::new("openai::gpt-4")
            .with_api_key(api_key)
            .with_temperature(0.7)
            .with_max_tokens(150)
            .with_top_p(0.9);

        if let Ok(mut agent) = Agent::new_with_config("Configured Assistant", config) {
            let task1 = TaskRequest::new("Explain quantum computing in one sentence.");
            let response = agent.run(task1).await;
            println!("   Response: {:?}\n", response.result());
        }
    } else {
        println!("   Skipped (OPENAI_API_KEY not set)\n");
    }

    // Method 2: Using Agent::new() then with_llm_config() (Alternative approach)
    println!("📗 Using Agent::new() then with_llm_config():");
    let mut agent = Agent::new("Configured Assistant", "openai::gpt-4");

    let config = LLMConfig::new("openai::gpt-4")
        .with_temperature(0.8)
        .with_max_tokens(200);

    if let Ok(_) = agent.with_llm_config(config) {
        let task2 = TaskRequest::new("What is machine learning in one sentence?");
        let response = agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Anthropic with reasoning
    println!("📗 Anthropic with extended thinking:");
    let mut claude_agent = Agent::new("Thinking Claude", "anthropic::claude-3-opus-20240229");

    let claude_config = LLMConfig::new("anthropic::claude-3-opus-20240229")
        .with_api_key(std::env::var("ANTHROPIC_API_KEY").unwrap_or_default())
        .with_temperature(0.5)
        .with_max_tokens(200)
        .with_reasoning(true);

    if let Ok(_) = claude_agent.with_llm_config(claude_config) {
        let task2 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = claude_agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Ollama with custom system prompt
    println!("📙 Ollama with custom system prompt:");
    let mut ollama_agent = Agent::new("Custom Ollama", "ollama::llama3.2");

    let ollama_config = LLMConfig::new("ollama::llama3.2")
        .with_system("You are a concise and technical AI assistant.")
        .with_max_tokens(100)
        .with_temperature(0.3);

    if let Ok(_) = ollama_agent.with_llm_config(ollama_config) {
        let task3 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = ollama_agent.run(task3).await;
        println!("   Response: {:?}\n", response.result());
    }

    Ok(())
}

/// Example 3: Provider-specific features
async fn provider_specific_features() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Provider-specific features:\n");

    // Azure OpenAI
    println!("☁️  Azure OpenAI with deployment configuration:");
    let mut azure_agent = Agent::new("Azure Assistant", "azure::gpt-4");

    let azure_config = LLMConfig::new("azure::gpt-4")
        .with_api_key(std::env::var("AZURE_OPENAI_API_KEY").unwrap_or_default())
        .with_deployment_id("your-deployment-id")
        .with_api_version("2024-02-01")
        .with_base_url("https://your-resource.openai.azure.com");

    if let Ok(_) = azure_agent.with_llm_config(azure_config) {
        println!("   ✓ Azure agent configured with deployment settings");
    }

    // OpenAI with web search
    println!("\n🌐 OpenAI with web search enabled:");
    let mut search_agent = Agent::new("Search Assistant", "openai::gpt-4");

    let search_config = LLMConfig::new("openai::gpt-4")
        .with_api_key(std::env::var("OPENAI_API_KEY").unwrap_or_default())
        .with_openai_web_search(true);

    if let Ok(_) = search_agent.with_llm_config(search_config) {
        let task1 = TaskRequest::new("What are the latest developments in AI?");
        let response = search_agent.run(task1).await;
        println!("   Response (with web search): {:?}\n", response.result());
    }

    // DeepSeek
    println!("🔍 DeepSeek for code-focused tasks:");
    let mut deepseek_agent = Agent::new("DeepSeek Assistant", "deepseek::deepseek-coder");

    let deepseek_config = LLMConfig::new("deepseek::deepseek-coder")
        .with_api_key(std::env::var("DEEPSEEK_API_KEY").unwrap_or_default())
        .with_temperature(0.2);

    if let Ok(_) = deepseek_agent.with_llm_config(deepseek_config) {
        let code_task = TaskRequest::new("Write a Rust function to calculate fibonacci numbers");
        let response = deepseek_agent.run(code_task).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Mistral
    println!("🌟 Mistral for European AI:");
    let mut mistral_agent = Agent::new("Mistral Assistant", "mistral::mistral-large-latest");

    let mistral_config = LLMConfig::new("mistral::mistral-large-latest")
        .with_api_key(std::env::var("MISTRAL_API_KEY").unwrap_or_default())
        .with_temperature(0.7)
        .with_max_tokens(500);

    if let Ok(_) = mistral_agent.with_llm_config(mistral_config) {
        println!("   ✓ Mistral agent configured");
    }

    Ok(())
}

/// Example 4: Compare providers
async fn compare_providers() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Comparing responses across providers:\n");

    let providers = vec![
        ("OpenAI GPT-4", "openai::gpt-4", std::env::var("OPENAI_API_KEY").ok()),
        ("Anthropic Claude", "anthropic::claude-3-sonnet-20240229", std::env::var("ANTHROPIC_API_KEY").ok()),
        ("Ollama Llama", "ollama::llama3.2", None),
        ("Google Gemini", "google::gemini-pro", std::env::var("GOOGLE_API_KEY").ok()),
        ("Groq Mixtral", "groq::mixtral-8x7b-32768", std::env::var("GROQ_API_KEY").ok()),
    ];

    for (name, model, api_key) in providers {
        println!("🤖 {}:", name);

        let mut agent = Agent::new(name, model);

        // Configure with LLMConfig if API key is available
        if let Some(key) = api_key {
            let config = LLMConfig::new(model)
                .with_api_key(key)
                .with_temperature(0.7)
                .with_max_tokens(100);

            if let Ok(_) = agent.with_llm_config(config) {
                let task = TaskRequest::new("Explain the concept of 'ownership' in Rust in one sentence.");
                let response = agent.run(task).await;
                println!("   ✓ {:?}", response.result());
            }
        } else {
            // Try without explicit API key (for Ollama or env vars)
            let task = TaskRequest::new("Explain the concept of 'ownership' in Rust in one sentence.");
            let response = agent.run(task).await;
            println!("   ✓ {:?}", response.result());
        }

        println!();
    }

    Ok(())
}

pub fn add_tool<T>(&mut self, tool: T) -> &mut Self

where T: ToolTrait + Send + Sync + 'static,

Adds a tool to the agent’s toolset.

Tools extend the agent’s capabilities by allowing it to perform external actions like web searches, calculations, database queries, etc.

Arguments

• tool - Any type implementing ToolTrait

Examples

use ceylon_next::agent::Agent;
use ceylon_next::tools::ToolTrait;
use serde_json::{json, Value};

struct WeatherTool;

impl ToolTrait for WeatherTool {
    fn name(&self) -> String { "get_weather".to_string() }
    fn description(&self) -> String { "Get weather for a location".to_string() }
    fn input_schema(&self) -> Value { json!({"type": "object"}) }
    fn execute(&self, input: Value) -> Value { json!({"temp": 72}) }
}

let mut agent = Agent::new("Assistant", "openai::gpt-4");
agent.add_tool(WeatherTool);

Examples found in repository

examples/02_with_tools.rs (line 151)

async fn main() {
    println!("🤖 Ceylon Agent - Tools Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MathAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful math and text assistant. \
         Use the available tools to help the user. \
         Be clear about what tools you're using and why."
    );

    // Step 2: Register custom tools with the agent
    println!("🔧 Registering tools...");
    agent.add_tool(CalculatorTool);
    agent.add_tool(StringToolTool);
    println!("✓ Tools registered\n");

    // Step 3: Create a task that requires tool usage
    let mut task = TaskRequest::new(
        "Please calculate 25 + 15 + 10, and then tell me the uppercase version of the word 'hello'"
    );
    task.with_name("Complex Task")
        .with_description("A task requiring multiple tools")
        .with_priority(8);

    // Step 4: Run the agent
    println!("📋 Task: {}\n", task.id());
    let response = agent.run(task).await;

    // Step 5: Display the result
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/04_advanced_agent.rs (line 136)

async fn main() {
    println!("🤖 Ceylon Agent - Advanced Example\n");

    // Step 1: Create an agent with custom configuration
    let mut agent = Agent::new("AdvancedAssistant", "ollama::gemma3:latest");

    // Configure with custom settings
    let config = AgentConfig::new(
        5,   // Allow more retries for complex tasks
        120, // Longer timeout
    );
    agent.with_config(config);

    // Custom system prompt for the advanced agent
    agent.with_system_prompt(
        "You are an advanced AI assistant with access to specialized tools. \
         You can fetch weather data and analyze text. \
         Always explain your reasoning and use tools appropriately. \
         Provide detailed and accurate responses.",
    );

    // Step 2: Register multiple tools
    println!("🔧 Registering tools...");
    agent.add_tool(WeatherTool);
    agent.add_tool(TextAnalyzerTool);
    println!("✓ Tools registered: get_weather, analyze_text\n");

    // Step 3: Create and run multiple tasks with different priorities
    let tasks_data = vec![
        (
            "What's the weather in Paris and London? Compare them.",
            "Weather Comparison",
            "Compare weather in two cities",
            9, // High priority
        ),
        (
            "Analyze this text for readability: 'The quick brown fox jumps over the lazy dog. \
             This sentence demonstrates all letters of the English alphabet.'",
            "Text Analysis",
            "Analyze readability",
            5, // Medium priority
        ),
    ];

    for (prompt, name, description, priority) in tasks_data {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", name);
        println!("⭐ Priority: {}/10", priority);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(name)
            .with_description(description)
            .with_priority(priority);

        // Run the agent
        println!("⏳ Running agent...\n");
        let response = agent.run(task).await;

        // Handle response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✅ Task completed\n");
            }
            _ => {
                println!("⚠️ Unexpected response type\n");
            }
        }
    }

    // Step 4: Demonstrate memory capabilities
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Agent Status Summary:");
    println!("• System Prompt: Custom advanced prompt");
    println!("• Tools Available: 2 (weather, text analyzer)");
    println!("• Memory Enabled: Yes");
    println!("• Max Retries: 5");
    println!("• Timeout: 120 seconds");
    println!("• Tasks Completed: 2\n");

    println!("✅ Advanced example completed successfully!");
}

examples/10_file_saving.rs (line 115)

async fn main() {
    println!("🤖 Ceylon Agent - File Saving Example\n");

    // Define the output directory
    let output_dir = "test/web_project_output";

    // Create the output directory if it doesn't exist
    if let Err(e) = fs::create_dir_all(output_dir) {
        eprintln!("❌ Failed to create output directory: {}", e);
        return;
    }
    println!("📁 Output directory: {}/\n", output_dir);

    // Step 1: Create an agent
    let mut agent = Agent::new("ContentGenerator", "ollama::gemma3:latest");

    agent.with_system_prompt(
        &format!(
            "You are a helpful assistant that can generate content and save it to files. \
             When asked to create content, generate it and use the file_saver tool to save it. \
             \
             IMPORTANT: All files MUST be saved inside the '{}' directory. \
             For example, to save 'server.js', use '{}/server.js' as the filename. \
             For files in subdirectories, use '{}/src/app.js' format. \
             \
             Be clear about what you're creating and where you're saving it.",
            output_dir, output_dir, output_dir
        )
    );

    // Step 2: Register the file saver tool
    println!("🔧 Registering file saver tool...");
    agent.add_tool(FileSaverTool);
    println!("✓ Tool registered\n");

    // Step 3: Create a task that generates content and saves it
    let mut task = TaskRequest::new(
        &format!(
            "Create a simple web project with a file upload API. Save all files in the '{}' directory:\
             \n1. server.js - A Node.js Express server with POST /upload endpoint\
             \n2. package.json - Package configuration with dependencies\
             \n3. test.http - HTTP test file to test the upload endpoint\
             \n4. README.md - Instructions on how to install and run the server\
             \n\nMake sure ALL files are saved in the '{}' directory!",
            output_dir, output_dir
        )
    );
    task.with_name("Generate and Save Web Project")
        .with_description("Generate a complete web project with file upload API")
        .with_priority(7);

    // Step 4: Run the agent
    println!("📋 Task: {}\n", task.id());
    println!("🔄 Running agent...\n");

    let response = agent.run(task).await;

    // Step 5: Display the result
    match response.result() {
        OutputData::Text(answer) => {
            println!("\n📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    // Step 6: Verify files were created
    println!("🔍 Checking created files in '{}/'\n", output_dir);

    let expected_files = vec![
        "server.js",
        "package.json",
        "test.http",
        "README.md"
    ];

    let mut created_count = 0;

    for file in &expected_files {
        let file_path = format!("{}/{}", output_dir, file);
        if Path::new(&file_path).exists() {
            created_count += 1;
            println!("✓ {} created successfully", file);

            if let Ok(content) = fs::read_to_string(&file_path) {
                let preview: String = content.chars().take(100).collect();
                println!("  Preview: {}", preview.replace('\n', " "));
            }
        } else {
            println!("⚠ {} not found", file);
        }
    }

    println!("\n📊 Summary: {}/{} expected files created", created_count, expected_files.len());

    // Show directory structure
    println!("\n📂 Directory structure:");
    if let Ok(entries) = fs::read_dir(output_dir) {
        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_file() {
                if let Some(filename) = path.file_name() {
                    if let Ok(metadata) = entry.metadata() {
                        println!("  - {} ({} bytes)",
                                 filename.to_string_lossy(),
                                 metadata.len());
                    }
                }
            }
        }
    }

    println!("\n✅ Example completed successfully!");
    println!("📁 All files are in: {}/", output_dir);
}

pub fn get_tool_invoker(&self) -> &ToolInvoker

Returns a reference to the agent’s tool invoker.

This can be used to inspect registered tools or invoke them manually.

pub async fn run(&mut self, task: TaskRequest) -> TaskResponse

Executes a task using the agent.

This is the main method for running the agent. It:

1. Analyzes the task and creates a goal structure (if enabled)
2. Loads relevant conversation history from memory
3. Iteratively processes the task with the LLM
4. Invokes tools as needed
5. Tracks progress towards goal completion
6. Saves the conversation to memory

Arguments

• task - A TaskRequest containing the user’s request

Returns

A TaskResponse containing the agent’s final output

Examples

use ceylon_next::agent::Agent;
use ceylon_next::tasks::{TaskRequest, OutputData};

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

    let task = TaskRequest::new("Write a haiku about Rust");
    let response = agent.run(task).await;

    match response.result() {
        OutputData::Text(text) => println!("{}", text),
        _ => println!("Unexpected output type"),
    }
}

Examples found in repository

examples/02_with_tools.rs (line 165)

async fn main() {
    println!("🤖 Ceylon Agent - Tools Example\n");

    // Step 1: Create an agent
    let mut agent = Agent::new("MathAssistant", "ollama::gemma3:latest");

    agent.with_system_prompt(
        "You are a helpful math and text assistant. \
         Use the available tools to help the user. \
         Be clear about what tools you're using and why."
    );

    // Step 2: Register custom tools with the agent
    println!("🔧 Registering tools...");
    agent.add_tool(CalculatorTool);
    agent.add_tool(StringToolTool);
    println!("✓ Tools registered\n");

    // Step 3: Create a task that requires tool usage
    let mut task = TaskRequest::new(
        "Please calculate 25 + 15 + 10, and then tell me the uppercase version of the word 'hello'"
    );
    task.with_name("Complex Task")
        .with_description("A task requiring multiple tools")
        .with_priority(8);

    // Step 4: Run the agent
    println!("📋 Task: {}\n", task.id());
    let response = agent.run(task).await;

    // Step 5: Display the result
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/01_basic_agent.rs (line 40)

async fn main() {
    println!("🤖 Ceylon Agent - Basic Example\n");

    // Step 1: Create a new agent with a name and model
    // The model should be one supported by the LLM library (openai, anthropic, ollama, etc.)
    let mut agent = Agent::new("Assistant", "ollama::gemma3:latest");

    // Step 2: (Optional) Configure the agent with custom settings
    let config = AgentConfig::new(
        3,   // max_retries
        60,  // timeout in seconds
    );
    agent.with_config(config);

    // Step 3: (Optional) Customize the system prompt
    agent.with_system_prompt(
        "You are a helpful assistant that answers questions accurately and concisely. \
         Always provide well-structured responses."
    );

    // Step 4: Create a task request
    let mut task = TaskRequest::new("What is the capital of France?");
    task.with_name("Geography Question")
        .with_description("A simple geography question")
        .with_priority(5);

    // Step 5: Run the agent with the task
    println!("📋 Task: {}\n", "What is the capital of France?");
    let response = agent.run(task).await;

    // Step 6: Handle the response
    match response.result() {
        OutputData::Text(answer) => {
            println!("📝 Agent Response:\n{}\n", answer);
        }
        _ => {
            println!("❌ Unexpected response type");
        }
    }

    println!("✅ Example completed successfully!");
}

examples/08_llm_providers.rs (line 132)

async fn basic_provider_usage() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Using different providers with simple syntax:\n");

    // OpenAI
    println!("📘 OpenAI GPT-4:");
    let mut openai_agent = Agent::new("OpenAI Assistant", "openai::gpt-4");
    let task1 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = openai_agent.run(task1).await;
    println!("   Response: {:?}\n", response.result());

    // Anthropic Claude
    println!("📗 Anthropic Claude:");
    let mut anthropic_agent = Agent::new("Claude Assistant", "anthropic::claude-3-sonnet-20240229");
    let task2 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = anthropic_agent.run(task2).await;
    println!("   Response: {:?}\n", response.result());

    // Ollama (local)
    println!("📙 Ollama (Local):");
    let mut ollama_agent = Agent::new("Ollama Assistant", "ollama::llama3.2");
    let task3 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = ollama_agent.run(task3).await;
    println!("   Response: {:?}\n", response.result());

    // Google Gemini
    println!("📕 Google Gemini:");
    let mut gemini_agent = Agent::new("Gemini Assistant", "google::gemini-pro");
    let task4 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = gemini_agent.run(task4).await;
    println!("   Response: {:?}\n", response.result());

    // Groq
    println!("📔 Groq:");
    let mut groq_agent = Agent::new("Groq Assistant", "groq::mixtral-8x7b-32768");
    let task5 = TaskRequest::new("What is 2 + 2? Answer briefly.");
    let response = groq_agent.run(task5).await;
    println!("   Response: {:?}\n", response.result());

    Ok(())
}

/// Example 2: Advanced configuration with LLMConfig
async fn advanced_configuration() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Using LLMConfig for advanced configuration:\n");

    // Method 1: Using Agent::new_with_config() (Recommended for explicit API keys)
    println!("📘 Using Agent::new_with_config() with explicit API key:");
    if let Ok(api_key) = std::env::var("OPENAI_API_KEY") {
        let config = LLMConfig::new("openai::gpt-4")
            .with_api_key(api_key)
            .with_temperature(0.7)
            .with_max_tokens(150)
            .with_top_p(0.9);

        if let Ok(mut agent) = Agent::new_with_config("Configured Assistant", config) {
            let task1 = TaskRequest::new("Explain quantum computing in one sentence.");
            let response = agent.run(task1).await;
            println!("   Response: {:?}\n", response.result());
        }
    } else {
        println!("   Skipped (OPENAI_API_KEY not set)\n");
    }

    // Method 2: Using Agent::new() then with_llm_config() (Alternative approach)
    println!("📗 Using Agent::new() then with_llm_config():");
    let mut agent = Agent::new("Configured Assistant", "openai::gpt-4");

    let config = LLMConfig::new("openai::gpt-4")
        .with_temperature(0.8)
        .with_max_tokens(200);

    if let Ok(_) = agent.with_llm_config(config) {
        let task2 = TaskRequest::new("What is machine learning in one sentence?");
        let response = agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Anthropic with reasoning
    println!("📗 Anthropic with extended thinking:");
    let mut claude_agent = Agent::new("Thinking Claude", "anthropic::claude-3-opus-20240229");

    let claude_config = LLMConfig::new("anthropic::claude-3-opus-20240229")
        .with_api_key(std::env::var("ANTHROPIC_API_KEY").unwrap_or_default())
        .with_temperature(0.5)
        .with_max_tokens(200)
        .with_reasoning(true);

    if let Ok(_) = claude_agent.with_llm_config(claude_config) {
        let task2 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = claude_agent.run(task2).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Ollama with custom system prompt
    println!("📙 Ollama with custom system prompt:");
    let mut ollama_agent = Agent::new("Custom Ollama", "ollama::llama3.2");

    let ollama_config = LLMConfig::new("ollama::llama3.2")
        .with_system("You are a concise and technical AI assistant.")
        .with_max_tokens(100)
        .with_temperature(0.3);

    if let Ok(_) = ollama_agent.with_llm_config(ollama_config) {
        let task3 = TaskRequest::new("Explain quantum computing in one sentence.");
        let response = ollama_agent.run(task3).await;
        println!("   Response: {:?}\n", response.result());
    }

    Ok(())
}

/// Example 3: Provider-specific features
async fn provider_specific_features() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Provider-specific features:\n");

    // Azure OpenAI
    println!("☁️  Azure OpenAI with deployment configuration:");
    let mut azure_agent = Agent::new("Azure Assistant", "azure::gpt-4");

    let azure_config = LLMConfig::new("azure::gpt-4")
        .with_api_key(std::env::var("AZURE_OPENAI_API_KEY").unwrap_or_default())
        .with_deployment_id("your-deployment-id")
        .with_api_version("2024-02-01")
        .with_base_url("https://your-resource.openai.azure.com");

    if let Ok(_) = azure_agent.with_llm_config(azure_config) {
        println!("   ✓ Azure agent configured with deployment settings");
    }

    // OpenAI with web search
    println!("\n🌐 OpenAI with web search enabled:");
    let mut search_agent = Agent::new("Search Assistant", "openai::gpt-4");

    let search_config = LLMConfig::new("openai::gpt-4")
        .with_api_key(std::env::var("OPENAI_API_KEY").unwrap_or_default())
        .with_openai_web_search(true);

    if let Ok(_) = search_agent.with_llm_config(search_config) {
        let task1 = TaskRequest::new("What are the latest developments in AI?");
        let response = search_agent.run(task1).await;
        println!("   Response (with web search): {:?}\n", response.result());
    }

    // DeepSeek
    println!("🔍 DeepSeek for code-focused tasks:");
    let mut deepseek_agent = Agent::new("DeepSeek Assistant", "deepseek::deepseek-coder");

    let deepseek_config = LLMConfig::new("deepseek::deepseek-coder")
        .with_api_key(std::env::var("DEEPSEEK_API_KEY").unwrap_or_default())
        .with_temperature(0.2);

    if let Ok(_) = deepseek_agent.with_llm_config(deepseek_config) {
        let code_task = TaskRequest::new("Write a Rust function to calculate fibonacci numbers");
        let response = deepseek_agent.run(code_task).await;
        println!("   Response: {:?}\n", response.result());
    }

    // Mistral
    println!("🌟 Mistral for European AI:");
    let mut mistral_agent = Agent::new("Mistral Assistant", "mistral::mistral-large-latest");

    let mistral_config = LLMConfig::new("mistral::mistral-large-latest")
        .with_api_key(std::env::var("MISTRAL_API_KEY").unwrap_or_default())
        .with_temperature(0.7)
        .with_max_tokens(500);

    if let Ok(_) = mistral_agent.with_llm_config(mistral_config) {
        println!("   ✓ Mistral agent configured");
    }

    Ok(())
}

/// Example 4: Compare providers
async fn compare_providers() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n✨ Comparing responses across providers:\n");

    let providers = vec![
        ("OpenAI GPT-4", "openai::gpt-4", std::env::var("OPENAI_API_KEY").ok()),
        ("Anthropic Claude", "anthropic::claude-3-sonnet-20240229", std::env::var("ANTHROPIC_API_KEY").ok()),
        ("Ollama Llama", "ollama::llama3.2", None),
        ("Google Gemini", "google::gemini-pro", std::env::var("GOOGLE_API_KEY").ok()),
        ("Groq Mixtral", "groq::mixtral-8x7b-32768", std::env::var("GROQ_API_KEY").ok()),
    ];

    for (name, model, api_key) in providers {
        println!("🤖 {}:", name);

        let mut agent = Agent::new(name, model);

        // Configure with LLMConfig if API key is available
        if let Some(key) = api_key {
            let config = LLMConfig::new(model)
                .with_api_key(key)
                .with_temperature(0.7)
                .with_max_tokens(100);

            if let Ok(_) = agent.with_llm_config(config) {
                let task = TaskRequest::new("Explain the concept of 'ownership' in Rust in one sentence.");
                let response = agent.run(task).await;
                println!("   ✓ {:?}", response.result());
            }
        } else {
            // Try without explicit API key (for Ollama or env vars)
            let task = TaskRequest::new("Explain the concept of 'ownership' in Rust in one sentence.");
            let response = agent.run(task).await;
            println!("   ✓ {:?}", response.result());
        }

        println!();
    }

    Ok(())
}

examples/05_with_goals.rs (line 62)

async fn example_1_manual_goal() {
    println!("=== Example 1: Manual Goal Creation ===\n");

    // Create an agent
    let mut agent = Agent::new("MealPlanner", "ollama::gemma3:latest");

    // Create a goal manually for a complex task
    let mut goal = Goal::new(
        "Plan a healthy meal prep for the week".to_string()
    );

    // Define what success looks like
    println!("📋 Setting success criteria...");
    goal.add_criterion("7 breakfast recipes selected".to_string());
    goal.add_criterion("7 lunch recipes selected".to_string());
    goal.add_criterion("7 dinner recipes selected".to_string());
    goal.add_criterion("Shopping list created".to_string());
    goal.add_criterion("Prep schedule created".to_string());

    // Break down into steps (sub-goals)
    println!("🎯 Breaking down into sub-goals...\n");
    goal.add_sub_goal("Ask user about dietary preferences".to_string(), 0);
    goal.add_sub_goal("Ask about time available for prep".to_string(), 1);
    goal.add_sub_goal("Suggest breakfast options".to_string(), 2);
    goal.add_sub_goal("Suggest lunch options".to_string(), 3);
    goal.add_sub_goal("Suggest dinner options".to_string(), 4);
    goal.add_sub_goal("Create shopping list".to_string(), 5);
    goal.add_sub_goal("Create prep schedule".to_string(), 6);

    // Start working on the goal
    goal.status = GoalStatus::InProgress;

    // Set the goal on the agent
    agent.set_goal(goal.clone());

    // Create a task aligned with the goal
    let task = TaskRequest::new("I need help with meal planning");

    // Run the agent
    println!("⏳ Agent is working on the meal planning task...\n");
    let _response = agent.run(task).await;

    // Show the goal summary
    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: Goal Progress Tracking
// ============================================

async fn example_2_goal_progress_tracking() {
    println!("\n=== Example 2: Goal Progress Tracking ===\n");

    // Create a goal for a project
    let mut goal = Goal::new(
        "Create a project plan for building a mobile app".to_string()
    );

    // Add success criteria
    goal.add_criterion("Project requirements documented".to_string());
    goal.add_criterion("Timeline created with milestones".to_string());
    goal.add_criterion("Resource allocation plan completed".to_string());
    goal.add_criterion("Risk assessment performed".to_string());

    // Add sub-goals
    goal.add_sub_goal("Gather stakeholder requirements".to_string(), 0);
    goal.add_sub_goal("Define project scope".to_string(), 1);
    goal.add_sub_goal("Create development timeline".to_string(), 2);
    goal.add_sub_goal("Allocate resources".to_string(), 3);
    goal.add_sub_goal("Identify risks and mitigation strategies".to_string(), 4);

    goal.status = GoalStatus::InProgress;

    // Simulate progress through the goal
    println!("📈 Tracking goal progress...\n");

    // Complete first sub-goal
    println!("Step 1: Gathering requirements");
    goal.complete_sub_goal(0, Some("Interviewed 5 stakeholders".to_string()));
    goal.mark_criterion_met(0, "Requirements documented".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete second sub-goal
    println!("Step 2: Defining scope");
    goal.complete_sub_goal(1, Some("Scope document created".to_string()));
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete third sub-goal
    println!("Step 3: Creating timeline");
    goal.complete_sub_goal(2, Some("12-month timeline with milestones".to_string()));
    goal.mark_criterion_met(1, "Timeline created".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fourth sub-goal
    println!("Step 4: Allocating resources");
    goal.complete_sub_goal(3, Some("Resource allocation table created".to_string()));
    goal.mark_criterion_met(2, "Resources allocated".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Complete fifth sub-goal
    println!("Step 5: Assessing risks");
    goal.complete_sub_goal(4, Some("Risk register created with 8 identified risks".to_string()));
    goal.mark_criterion_met(3, "Risks identified".to_string());
    println!("  Progress: {}%\n", goal.get_progress());

    // Show final status
    println!("\n📊 Final Goal Status:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: Job Interview Preparation Goal
// ============================================

async fn example_3_interview_preparation() {
    println!("\n=== Example 3: Job Interview Preparation Goal ===\n");

    let mut agent = Agent::new("InterviewCoach", "ollama::gemma3:latest");

    // Create a structured goal for interview prep
    let mut goal = Goal::new(
        "Prepare for a senior software engineer interview at a tech company".to_string()
    );

    // Define success criteria
    println!("🎯 Success criteria:");
    goal.add_criterion("Technical topics reviewed (algorithms, data structures, system design)".to_string());
    goal.add_criterion("Behavioral questions prepared with STAR method examples".to_string());
    goal.add_criterion("Company research completed".to_string());
    goal.add_criterion("Practice mock interview conducted".to_string());
    goal.add_criterion("Questions to ask the interviewer prepared".to_string());

    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    // Define steps
    println!("\n📋 Steps to take:");
    goal.add_sub_goal("Review core algorithms and data structures".to_string(), 0);
    goal.add_sub_goal("Study system design patterns".to_string(), 1);
    goal.add_sub_goal("Prepare STAR method stories from past projects".to_string(), 2);
    goal.add_sub_goal("Research company background and culture".to_string(), 3);
    goal.add_sub_goal("Practice mock interview with a friend".to_string(), 4);
    goal.add_sub_goal("Prepare thoughtful questions about the role".to_string(), 5);

    for sub_goal in &goal.sub_goals {
        println!("  {}. {}", sub_goal.priority + 1, sub_goal.description);
    }

    goal.status = GoalStatus::InProgress;

    // Set goal on agent
    agent.set_goal(goal.clone());

    // Create related task
    let task = TaskRequest::new("Help me prepare for my senior engineer interview");

    println!("\n⏳ Agent is creating interview preparation plan...\n");
    let _response = agent.run(task).await;

    println!("\n📊 Goal Summary:");
    println!("{}", goal.get_summary());

    println!("\n✅ Example 3 completed!\n");
}

examples/06_nextjs_app_generator.rs (line 83)

async fn example_1_basic_nextjs_app() {
    println!("=== Example 1: Generate a Basic Next.js App ===\n");

    // Create an agent that will generate the app
    let mut agent = Agent::new("NextJsGenerator", "ollama::gemma3:latest");

    // Create a goal for generating a Next.js app
    let mut goal = Goal::new(
        "Generate a Next.js web application with essential structure".to_string()
    );

    // Define success criteria
    goal.add_criterion("package.json created with dependencies".to_string());
    goal.add_criterion("next.config.js configuration file generated".to_string());
    goal.add_criterion("pages directory with index and api route created".to_string());
    goal.add_criterion("styles directory with global CSS".to_string());
    goal.add_criterion("README.md with setup instructions".to_string());

    // Define sub-goals (steps to generate the app)
    goal.add_sub_goal("Analyze Next.js requirements and best practices".to_string(), 0);
    goal.add_sub_goal("Generate package.json with required dependencies".to_string(), 1);
    goal.add_sub_goal("Create next.config.js configuration".to_string(), 2);
    goal.add_sub_goal("Generate pages (index.tsx, _app.tsx, _document.tsx)".to_string(), 3);
    goal.add_sub_goal("Create API route examples".to_string(), 4);
    goal.add_sub_goal("Generate styling setup (global.css, utilities)".to_string(), 5);
    goal.add_sub_goal("Create components directory with example components".to_string(), 6);
    goal.add_sub_goal("Generate README with setup and usage instructions".to_string(), 7);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    // Create a task to generate a Next.js app
    let task = TaskRequest::new(
        "Generate a modern Next.js 14 application with TypeScript, Tailwind CSS, and best practices. \
         Include package.json, next.config.js, sample pages, API routes, and components. \
         The app should be production-ready and follow Next.js conventions."
    );

    println!("📝 Task: Generate a Next.js application\n");
    println!("🎯 Success Criteria:");
    for criterion in &goal.success_criteria {
        println!("  • {}", criterion.description);
    }

    println!("\n⏳ Agent is generating the Next.js app...\n");
    let response = agent.run(task).await;

    // Extract and display the output
    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    // Show progress
    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("Status: {:?}", goal.status);

    println!("\n✅ Example 1 completed!\n");
}

// ============================================
// Example 2: E-Commerce Next.js App
// ============================================

async fn example_2_ecommerce_app() {
    println!("\n=== Example 2: Generate E-Commerce Next.js App ===\n");

    let mut agent = Agent::new("EcommerceGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a complete e-commerce Next.js application".to_string()
    );

    // Success criteria for e-commerce
    goal.add_criterion("Product listing page with filtering and sorting".to_string());
    goal.add_criterion("Product detail pages with dynamic routes".to_string());
    goal.add_criterion("Shopping cart functionality".to_string());
    goal.add_criterion("User authentication setup".to_string());
    goal.add_criterion("Payment integration structure".to_string());
    goal.add_criterion("Database models and API endpoints".to_string());
    goal.add_criterion("Admin dashboard layout".to_string());

    // Sub-goals
    goal.add_sub_goal("Design database schema for products and orders".to_string(), 0);
    goal.add_sub_goal("Create product API endpoints".to_string(), 1);
    goal.add_sub_goal("Build product listing and search components".to_string(), 2);
    goal.add_sub_goal("Implement product detail pages".to_string(), 3);
    goal.add_sub_goal("Create shopping cart context and management".to_string(), 4);
    goal.add_sub_goal("Build checkout flow pages".to_string(), 5);
    goal.add_sub_goal("Integrate payment gateway API".to_string(), 6);
    goal.add_sub_goal("Create admin dashboard pages".to_string(), 7);
    goal.add_sub_goal("Add authentication middleware".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a complete e-commerce Next.js application with: \
         1. Product management system (listing, search, filters)\n\
         2. Shopping cart with add/remove/update functionality\n\
         3. User authentication and profile pages\n\
         4. Payment integration endpoints\n\
         5. Order history and tracking\n\
         6. Admin dashboard for managing products and orders\n\
         7. Database models for PostgreSQL or MongoDB\n\
         8. RESTful API endpoints\n\
         Use TypeScript, Tailwind CSS, and modern React patterns."
    );

    println!("📝 Task: Generate E-Commerce Next.js Application\n");
    println!("🎯 Features to Generate:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating e-commerce app...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 2 completed!\n");
}

// ============================================
// Example 3: SaaS Dashboard App
// ============================================

async fn example_3_saas_dashboard() {
    println!("\n=== Example 3: Generate SaaS Dashboard Next.js App ===\n");

    let mut agent = Agent::new("SaasDashboardGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a SaaS dashboard application with user management".to_string()
    );

    goal.add_criterion("User authentication and authorization".to_string());
    goal.add_criterion("Multi-tenant database structure".to_string());
    goal.add_criterion("Dashboard with analytics and metrics".to_string());
    goal.add_criterion("User and team management pages".to_string());
    goal.add_criterion("Settings and preferences pages".to_string());
    goal.add_criterion("Billing and subscription management".to_string());
    goal.add_criterion("API for data collection and reporting".to_string());

    goal.add_sub_goal("Design multi-tenant database schema".to_string(), 0);
    goal.add_sub_goal("Implement OAuth authentication".to_string(), 1);
    goal.add_sub_goal("Create dashboard with charts and metrics".to_string(), 2);
    goal.add_sub_goal("Build team and user management interfaces".to_string(), 3);
    goal.add_sub_goal("Create settings pages for users and organization".to_string(), 4);
    goal.add_sub_goal("Implement billing API integration".to_string(), 5);
    goal.add_sub_goal("Create analytics and reporting system".to_string(), 6);
    goal.add_sub_goal("Add email notification templates".to_string(), 7);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a complete SaaS dashboard Next.js application with:\n\
         1. Multi-tenant authentication (OAuth + JWT)\n\
         2. Organization and team management\n\
         3. Comprehensive dashboard with charts and analytics\n\
         4. User permission and role management\n\
         5. Billing integration with Stripe\n\
         6. Settings pages for users and teams\n\
         7. Email notifications system\n\
         8. API logging and activity tracking\n\
         9. Dark mode support\n\
         10. Mobile responsive design\n\
         Include TypeScript, Tailwind CSS, Recharts for visualizations, \
         and PostgreSQL database models."
    );

    println!("📝 Task: Generate SaaS Dashboard Application\n");
    println!("🎯 Dashboard Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating SaaS dashboard...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 3 completed!\n");
}

// ============================================
// Example 4: Blog Platform with CMS
// ============================================

async fn example_4_blog_platform() {
    println!("\n=== Example 4: Generate Blog Platform with CMS ===\n");

    let mut agent = Agent::new("BlogCMSGenerator", "ollama::gemma3:latest");

    let mut goal = Goal::new(
        "Generate a comprehensive blog platform with CMS".to_string()
    );

    goal.add_criterion("Blog post management system".to_string());
    goal.add_criterion("Rich text editor with markdown support".to_string());
    goal.add_criterion("Category and tag system".to_string());
    goal.add_criterion("Search and filtering functionality".to_string());
    goal.add_criterion("Comments system with moderation".to_string());
    goal.add_criterion("SEO optimization (meta tags, sitemap)".to_string());
    goal.add_criterion("Author management and permissions".to_string());
    goal.add_criterion("Analytics and engagement tracking".to_string());

    goal.add_sub_goal("Design blog database schema".to_string(), 0);
    goal.add_sub_goal("Create CMS backend API".to_string(), 1);
    goal.add_sub_goal("Build post editor with markdown".to_string(), 2);
    goal.add_sub_goal("Create blog listing and search pages".to_string(), 3);
    goal.add_sub_goal("Build individual post pages with SEO".to_string(), 4);
    goal.add_sub_goal("Implement comments system".to_string(), 5);
    goal.add_sub_goal("Create author profiles and bio".to_string(), 6);
    goal.add_sub_goal("Build admin dashboard for content management".to_string(), 7);
    goal.add_sub_goal("Add analytics tracking and reporting".to_string(), 8);

    goal.status = GoalStatus::InProgress;
    agent.set_goal(goal.clone());

    let task = TaskRequest::new(
        "Generate a full-featured blog platform with CMS:\n\
         1. Post creation and editing with rich text editor\n\
         2. Markdown support with preview\n\
         3. Category and tag system\n\
         4. Advanced search with filters\n\
         5. Comments system with nested replies\n\
         6. Author profiles with biography\n\
         7. SEO optimization (sitemaps, meta tags, structured data)\n\
         8. Social sharing integration\n\
         9. Email newsletter subscription\n\
         10. Analytics dashboard for authors\n\
         11. Reading time estimates\n\
         12. Related posts suggestions\n\
         Include TypeScript, Tailwind CSS, next-mdx-remote for markdown, \
         and MongoDB/PostgreSQL models."
    );

    println!("📝 Task: Generate Blog Platform with CMS\n");
    println!("🎯 Blog Features:");
    for criterion in &goal.success_criteria {
        println!("  ✓ {}", criterion.description);
    }

    println!("\n⏳ Agent is generating blog platform...\n");
    let response = agent.run(task).await;

    let output = extract_output_text(&response.result());
    println!("📄 Generated Output:\n");
    println!("{}\n", output);

    println!("📊 Goal Progress: {}%", goal.get_progress());
    println!("\n✅ Example 4 completed!\n");
}

// ============================================
// Example 5: Extracting and Processing Output
// ============================================

async fn example_5_output_extraction() {
    println!("\n=== Example 5: Output Extraction and Processing ===\n");

    let mut agent = Agent::new("OutputProcessor", "ollama::gemma3:latest");

    // Create a simple task to generate specific file outputs
    let task = TaskRequest::new(
        "Generate ONLY the following files in proper format:\n\
         1. A complete package.json file for a Next.js project\n\
         2. A next.config.js configuration\n\
         3. A TypeScript types file for common types\n\
         Format each file with proper headers like:\n\
         === FILE: package.json ===\n\
         [file content]\n\
         === FILE: next.config.js ===\n\
         [file content]"
    );

    println!("📝 Task: Generate Specific Configuration Files\n");
    println!("⏳ Processing...\n");

    let response = agent.run(task).await;
    let output = extract_output_text(&response.result());

    // Parse output by file
    let files: HashMap<String, String> = parse_output_by_file(&output);

    println!("📦 Generated Files:\n");
    for (filename, content) in &files {
        println!("📄 File: {}", filename);
        println!("   Lines: {}", content.lines().count());
        println!("   Size: {} bytes\n", content.len());
    }

    println!("✅ Example 5 completed!\n");
}

examples/04_advanced_agent.rs (line 171)

async fn main() {
    println!("🤖 Ceylon Agent - Advanced Example\n");

    // Step 1: Create an agent with custom configuration
    let mut agent = Agent::new("AdvancedAssistant", "ollama::gemma3:latest");

    // Configure with custom settings
    let config = AgentConfig::new(
        5,   // Allow more retries for complex tasks
        120, // Longer timeout
    );
    agent.with_config(config);

    // Custom system prompt for the advanced agent
    agent.with_system_prompt(
        "You are an advanced AI assistant with access to specialized tools. \
         You can fetch weather data and analyze text. \
         Always explain your reasoning and use tools appropriately. \
         Provide detailed and accurate responses.",
    );

    // Step 2: Register multiple tools
    println!("🔧 Registering tools...");
    agent.add_tool(WeatherTool);
    agent.add_tool(TextAnalyzerTool);
    println!("✓ Tools registered: get_weather, analyze_text\n");

    // Step 3: Create and run multiple tasks with different priorities
    let tasks_data = vec![
        (
            "What's the weather in Paris and London? Compare them.",
            "Weather Comparison",
            "Compare weather in two cities",
            9, // High priority
        ),
        (
            "Analyze this text for readability: 'The quick brown fox jumps over the lazy dog. \
             This sentence demonstrates all letters of the English alphabet.'",
            "Text Analysis",
            "Analyze readability",
            5, // Medium priority
        ),
    ];

    for (prompt, name, description, priority) in tasks_data {
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
        println!("📋 Task: {}", name);
        println!("⭐ Priority: {}/10", priority);
        println!("📝 Description: {}", description);
        println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

        let mut task = TaskRequest::new(prompt);
        task.with_name(name)
            .with_description(description)
            .with_priority(priority);

        // Run the agent
        println!("⏳ Running agent...\n");
        let response = agent.run(task).await;

        // Handle response
        match response.result() {
            OutputData::Text(answer) => {
                println!("✅ Task completed\n");
            }
            _ => {
                println!("⚠️ Unexpected response type\n");
            }
        }
    }

    // Step 4: Demonstrate memory capabilities
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📚 Agent Status Summary:");
    println!("• System Prompt: Custom advanced prompt");
    println!("• Tools Available: 2 (weather, text analyzer)");
    println!("• Memory Enabled: Yes");
    println!("• Max Retries: 5");
    println!("• Timeout: 120 seconds");
    println!("• Tasks Completed: 2\n");

    println!("✅ Advanced example completed successfully!");
}

Additional examples can be found in:

• examples/09_test_groq.rs
• examples/07_python_project_generator.rs
• examples/03_with_memory.rs
• examples/10_file_saving.rs
• examples/11_persistent_memory.rs

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.