Struct Config 

pub struct Config {
    pub llm: LLMConfig,
}

The main configuration for the Helios Engine.

Fields

llm: LLMConfig

The configuration for the remote LLM.

Implementations

impl Config

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>

Loads the configuration from a TOML file.

Arguments

• path - The path to the TOML file.

Returns

A Result containing the loaded Config.

Examples found in repository

examples/basic_chat.rs (line 12)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create a simple agent named "BasicAgent".
    let mut agent = Agent::builder("BasicAgent")
        .config(config)
        .system_prompt("You are a helpful assistant.")
        .build()
        .await?;

    // --- Send a message to the agent ---
    let response = agent.chat("Hello! How are you?").await?;
    println!("Agent: {}", response);

    // --- Continue the conversation ---
    let response = agent.chat("What can you help me with?").await?;
    println!("Agent: {}", response);

    Ok(())
}

examples/custom_tool.rs (line 76)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "WeatherAgent" and equip it with the `WeatherTool`.
    let mut agent = Agent::builder("WeatherAgent")
        .config(config)
        .system_prompt("You are a helpful weather assistant. Use the weather tool to answer questions about weather.")
        .tool(Box::new(WeatherTool))
        .build()
        .await?;

    // --- Ask the agent about the weather ---
    let response = agent.chat("What's the weather like in New York?").await?;
    println!("Agent: {}\n", response);

    // --- Ask again, but with a different unit ---
    let response = agent.chat("How about in London, but in celsius?").await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/agent_with_tools.rs (line 11)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // Create an agent named "ToolAgent" and equip it with the `CalculatorTool` and `EchoTool`.
    let mut agent = Agent::builder("ToolAgent")
        .config(config)
        .system_prompt("You are a helpful assistant with access to tools. Use them when needed.")
        .tool(Box::new(CalculatorTool))
        .tool(Box::new(EchoTool))
        .max_iterations(5)
        .build()
        .await?;

    println!(
        "Available tools: {:?}\n",
        agent.tool_registry().list_tools()
    );

    // --- Test the calculator tool ---
    let response = agent.chat("What is 25 * 4 + 10?").await?;
    println!("Agent: {}\n", response);

    // --- Test the echo tool ---
    let response = agent
        .chat("Can you echo this message: 'Hello from Helios!'")
        .await?;
    println!("Agent: {}\n", response);

    Ok(())
}

examples/serve_agent.rs (line 16)

async fn main() -> helios_engine::Result<()> {
    // Initialize tracing
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::INFO)
        .init();

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create an agent with tools
    let agent = Agent::builder("API Agent")
        .config(config)
        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
        .tool(Box::new(CalculatorTool))
        .max_iterations(5)
        .build()
        .await?;

    // Start the server
    println!("Starting server on http://127.0.0.1:8000");
    println!("Try: curl http://127.0.0.1:8000/v1/chat/completions \\");
    println!("  -H 'Content-Type: application/json' \\");
    println!("  -d '{{\"model\": \"local-model\", \"messages\": [{{\"role\": \"user\", \"content\": \"What is 15 * 7?\"}}]}}'");

    helios_engine::serve::start_server_with_agent(
        agent,
        "local-model".to_string(),
        "127.0.0.1:8000",
    )
    .await?;

    Ok(())
}

examples/multiple_agents.rs (line 12)

async fn main() -> helios_engine::Result<()> {
    // Load configuration from `config.toml`.
    let config = Config::from_file("config.toml")?;

    // --- Create multiple agents with different personalities and tools ---

    // An agent specialized in math, equipped with a calculator tool.
    let mut math_agent = Agent::builder("MathAgent")
        .config(config.clone())
        .system_prompt("You are a math expert. You love numbers and equations.")
        .tool(Box::new(CalculatorTool))
        .build()
        .await?;

    // A creative agent for writing and storytelling.
    let mut creative_agent = Agent::builder("CreativeAgent")
        .config(config)
        .system_prompt("You are a creative writer who loves storytelling and poetry.")
        .build()
        .await?;

    // --- Interact with the Math Agent ---
    println!("=== Math Agent ===");
    let response = math_agent.chat("What is the square root of 144?").await?;
    println!("Math Agent: {}\n", response);

    // --- Interact with the Creative Agent ---
    println!("=== Creative Agent ===");
    let response = creative_agent
        .chat("Write a haiku about programming.")
        .await?;
    println!("Creative Agent: {}\n", response);

    Ok(())
}

examples/serve_with_custom_endpoints.rs (line 16)

async fn main() -> helios_engine::Result<()> {
    // Initialize tracing
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::INFO)
        .init();

    // Load configuration
    let config = Config::from_file("config.toml")?;

    // Create an agent with tools
    let agent = Agent::builder("API Agent")
        .config(config)
        .system_prompt("You are a helpful AI assistant with access to a calculator tool.")
        .tool(Box::new(CalculatorTool))
        .max_iterations(5)
        .build()
        .await?;

    // Define custom endpoints
    let custom_endpoints = CustomEndpointsConfig {
        endpoints: vec![
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/version".to_string(),
                response: serde_json::json!({
                    "version": "0.2.8",
                    "service": "Helios Engine",
                    "features": ["agents", "tools", "streaming", "custom_endpoints"]
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "GET".to_string(),
                path: "/api/status".to_string(),
                response: serde_json::json!({
                    "status": "operational",
                    "uptime": "unknown",
                    "model": "agent-based"
                }),
                status_code: 200,
            },
            CustomEndpoint {
                method: "POST".to_string(),
                path: "/api/echo".to_string(),
                response: serde_json::json!({
                    "message": "Echo endpoint - this returns static data",
                    "note": "For dynamic responses, use the chat completions endpoint"
                }),
                status_code: 200,
            },
        ],
    };

    // Start the server with custom endpoints
    println!("Starting server on http://127.0.0.1:8000");
    println!("📡 OpenAI-compatible API endpoints:");
    println!("   POST /v1/chat/completions");
    println!("   GET  /v1/models");
    println!("📡 Custom endpoints:");
    println!("   GET  /api/version");
    println!("   GET  /api/status");
    println!("   POST /api/echo");
    println!();
    println!("Try: curl http://127.0.0.1:8000/api/version");

    helios_engine::serve::start_server_with_agent_and_custom_endpoints(
        agent,
        "local-model".to_string(),
        "127.0.0.1:8000",
        Some(custom_endpoints),
    )
    .await?;

    Ok(())
}

Additional examples can be found in:

• examples/agent_with_file_tools.rs
• examples/agent_with_memory_db.rs
• examples/agent_with_rag.rs
• examples/complete_demo.rs

pub fn new_default() -> Self

Creates a new default configuration.

Examples found in repository

examples/agent_with_file_tools.rs (line 17)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with File Tools Example");
    println!("=================================================\n");

    // Load configuration
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "FileAssistant" and equip it with file tools.
    let mut agent = Agent::builder("FileAssistant")
        .config(config)
        .system_prompt(
            "You are a helpful file management assistant. You can search for files, \
             read file contents, and edit files. Always confirm with the user before \
             making changes to files. Keep track of important session information.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with file tools");
    println!("✓ Available tools: file_search, file_read, file_edit, file_write\n");

    // Set initial session memory for the agent.
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("tasks_completed", "0");

    // --- Example 1: Search for Rust files ---
    println!("Example 1: Searching for Rust files");
    println!("====================================\n");

    let response = agent
        .chat("Find all Rust source files in the src directory")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_search");

    // --- Example 2: Read a specific file ---
    println!("\nExample 2: Reading file contents");
    println!("==================================\n");

    let response = agent
        .chat("Read the contents of src/lib.rs and give me a summary")
        .await?;
    println!("Agent: {}\n", response);

    // Update session memory after the task.
    agent.increment_tasks_completed();
    agent.set_memory("last_task", "file_read");

    // --- Example 3: Show session summary ---
    println!("\nExample 3: Session Summary");
    println!("==========================\n");

    println!("{}", agent.get_session_summary());

    // --- Example 4: Check session memory ---
    println!("\nExample 4: Checking Session Memory");
    println!("===================================\n");

    println!(
        "Working directory: {}",
        agent
            .get_memory("working_directory")
            .unwrap_or(&"unknown".to_string())
    );
    println!(
        "Tasks completed: {}",
        agent
            .get_memory("tasks_completed")
            .unwrap_or(&"0".to_string())
    );
    println!(
        "Last task: {}",
        agent.get_memory("last_task").unwrap_or(&"none".to_string())
    );

    println!("\n✅ Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • File search with pattern matching and content search");
    println!("  • File reading with line range support");
    println!("  • File editing with find/replace functionality");
    println!("  • Session memory for tracking agent state");
    println!("  • Streaming responses (works with both local and remote models)");

    Ok(())
}

examples/agent_with_memory_db.rs (line 17)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with Memory DB Example");
    println!("================================================\n");

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "DataAgent" and equip it with the MemoryDBTool.
    let mut agent = Agent::builder("DataAgent")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to an in-memory database. \
             You can store and retrieve information using the memory_db tool. \
             Operations available: set, get, delete, list, clear, exists. \
             Use this to remember important information across our conversation.",
        )
        .tool(Box::new(MemoryDBTool::new()))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with memory database tool\n");

    // --- Example 1: Store user preferences ---
    println!("Example 1: Storing User Preferences");
    println!("====================================\n");

    let response = agent
        .chat("Store my name as 'Alice' and my favorite color as 'blue' in the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 2: Retrieve stored data ---
    println!("\nExample 2: Retrieving Stored Data");
    println!("==================================\n");

    let response = agent.chat("What's my name and favorite color?").await?;
    println!("Agent: {}\n", response);

    // --- Example 3: Store calculations ---
    println!("\nExample 3: Caching Calculations");
    println!("================================\n");

    let response = agent
        .chat("Calculate 123 * 456 and store the result in the database with key 'calculation_result'")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 4: List all stored data ---
    println!("\nExample 4: Listing All Data");
    println!("===========================\n");

    let response = agent
        .chat("Show me everything stored in the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 5: Check if key exists ---
    println!("\nExample 5: Checking Key Existence");
    println!("==================================\n");

    let response = agent
        .chat("Check if 'name' and 'age' exist in the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 6: Delete specific data ---
    println!("\nExample 6: Deleting Data");
    println!("========================\n");

    let response = agent
        .chat("Delete the 'calculation_result' from the database")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 7: Final state ---
    println!("\nExample 7: Final Database State");
    println!("================================\n");

    let response = agent
        .chat("List all remaining items in the database")
        .await?;
    println!("Agent: {}\n", response);

    println!("\n✅ Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • Setting key-value pairs in memory database");
    println!("  • Retrieving stored values");
    println!("  • Listing all database contents");
    println!("  • Checking key existence");
    println!("  • Deleting specific entries");
    println!("  • Persistent data across multiple agent interactions");
    println!("\n📝 Use Cases:");
    println!("  • Caching expensive computations");
    println!("  • Storing user preferences during conversation");
    println!("  • Maintaining context across multiple queries");
    println!("  • Temporary data storage for complex workflows");

    Ok(())
}

examples/agent_with_rag.rs (line 36)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Agent with RAG Example");
    println!("==========================================\n");

    // Check for the required OpenAI API key.
    let embedding_api_key = std::env::var("OPENAI_API_KEY").unwrap_or_else(|_| {
        println!("⚠ Warning: OPENAI_API_KEY not set. Using placeholder.");
        "your-api-key-here".to_string()
    });

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create a new `QdrantRAGTool`.
    let rag_tool = QdrantRAGTool::new(
        "http://localhost:6333",                // Qdrant URL
        "helios_knowledge",                     // Collection name
        "https://api.openai.com/v1/embeddings", // Embedding API
        embedding_api_key,                      // API key
    );

    // Create an agent named "KnowledgeAgent" and equip it with the RAG tool.
    let mut agent = Agent::builder("KnowledgeAgent")
        .config(config)
        .system_prompt(
            "You are a helpful assistant with access to a RAG (Retrieval-Augmented Generation) system. \
             You can store documents and retrieve relevant information to answer questions. \
             When answering questions, first search for relevant documents, then provide informed answers based on the retrieved context."
        )
        .tool(Box::new(rag_tool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created with RAG capabilities\n");

    // --- Example 1: Add knowledge to the database ---
    println!("Example 1: Adding Documents to Knowledge Base");
    println!("==============================================\n");

    let response = agent
        .chat(
            "Store this information: Rust is a systems programming language that runs blazingly fast, \
             prevents segfaults, and guarantees thread safety. It was created by Mozilla Research."
        )
        .await?;
    println!("Agent: {}\n", response);

    let response = agent
        .chat(
            "Store this: Python is a high-level, interpreted programming language known for its \
             clear syntax and readability. It was created by Guido van Rossum in 1991.",
        )
        .await?;
    println!("Agent: {}\n", response);

    let response = agent
        .chat(
            "Store this: JavaScript is a programming language commonly used for web development. \
             It allows developers to create interactive web pages and runs in web browsers.",
        )
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 2: Semantic search - ask questions ---
    println!("\nExample 2: Semantic Search and Q&A");
    println!("===================================\n");

    let response = agent
        .chat("What programming language is known for preventing segfaults?")
        .await?;
    println!("Agent: {}\n", response);

    let response = agent
        .chat("Tell me about the programming language created in 1991")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 3: Multi-document retrieval ---
    println!("\nExample 3: Multi-Document Retrieval");
    println!("====================================\n");

    let response = agent
        .chat("Search for information about programming languages and summarize what you find")
        .await?;
    println!("Agent: {}\n", response);

    // --- Example 4: Adding documents with metadata ---
    println!("\nExample 4: Documents with Metadata");
    println!("===================================\n");

    let response = agent
        .chat(
            "Store this with metadata: \
             The Helios Engine is a Rust framework for building LLM agents. \
             Metadata: category=framework, language=rust, year=2024",
        )
        .await?;
    println!("Agent: {}\n", response);

    println!("\n✅ Example completed successfully!");
    println!("\n💡 Key Features Demonstrated:");
    println!("  • Document embedding with OpenAI embeddings");
    println!("  • Vector storage in Qdrant database");
    println!("  • Semantic search with cosine similarity");
    println!("  • RAG workflow for context-aware answers");
    println!("  • Metadata support for document organization");

    println!("\n📝 RAG Use Cases:");
    println!("  • Question answering over custom knowledge bases");
    println!("  • Document search and retrieval");
    println!("  • Building chatbots with domain-specific knowledge");
    println!("  • Information extraction from large document sets");

    println!("\n🔧 Setup Instructions:");
    println!("  1. Start Qdrant: docker run -p 6333:6333 qdrant/qdrant");
    println!("  2. Set API key: export OPENAI_API_KEY=your-key");
    println!("  3. Run example: cargo run --example agent_with_rag");

    Ok(())
}

examples/complete_demo.rs (line 19)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Complete Feature Demo");
    println!("=========================================\n");

    // Load configuration from `config.toml` or use default.
    let config = Config::from_file("config.toml").unwrap_or_else(|_| {
        println!("⚠ No config.toml found, using default configuration");
        Config::new_default()
    });

    // Create an agent named "SmartAssistant" and equip it with all file tools.
    println!("📦 Creating agent with file tools...");
    let mut agent = Agent::builder("SmartAssistant")
        .config(config)
        .system_prompt(
            "You are an intelligent assistant with file management capabilities. \
             You can search files, read them, and make edits. Always explain what \
             you're doing and track important information in session memory.",
        )
        .tool(Box::new(FileSearchTool))
        .tool(Box::new(FileReadTool))
        .tool(Box::new(FileEditTool))
        .tool(Box::new(FileWriteTool))
        .max_iterations(10)
        .build()
        .await?;

    println!("✓ Agent created successfully!\n");

    // Initialize session memory with some starting values.
    println!("🧠 Initializing session memory...");
    agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
    agent.set_memory(
        "working_directory",
        std::env::current_dir()?.display().to_string(),
    );
    agent.set_memory("files_accessed", "0");
    agent.set_memory("edits_made", "0");
    println!("✓ Session memory initialized\n");

    // --- Demo 1: Search for files with streaming response ---
    println!("Demo 1: File Search with Streaming");
    println!("===================================");
    println!("User: Find all Rust example files\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response1 = agent
        .chat("Find all Rust example files in the examples directory")
        .await?;
    println!("{}\n", response1);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_search");

    // --- Demo 2: Read a file ---
    println!("\nDemo 2: Reading File Contents");
    println!("==============================");
    println!("User: Read the NEW_FEATURES.md file and summarize the key points\n");

    print!("Agent: ");
    io::stdout().flush()?;

    let response2 = agent
        .chat("Read the NEW_FEATURES.md file and give me a brief summary of what's new")
        .await?;
    println!("{}\n", response2);

    // Update session memory after the task.
    agent.increment_counter("files_accessed");
    agent.set_memory("last_action", "file_read");

    // --- Demo 3: Show session summary ---
    println!("\nDemo 3: Session Summary");
    println!("=======================\n");
    println!("{}", agent.get_session_summary());

    // --- Demo 4: Interactive mode ---
    println!("\n\nDemo 4: Interactive Mode");
    println!("========================");
    println!("You can now interact with the agent. Type 'exit' to quit.\n");

    loop {
        print!("\nYou: ");
        io::stdout().flush()?;

        let mut input = String::new();
        io::stdin().read_line(&mut input)?;
        let input = input.trim();

        if input.is_empty() {
            continue;
        }

        match input.to_lowercase().as_str() {
            "exit" | "quit" => {
                println!("\n👋 Goodbye!");
                break;
            }
            "summary" => {
                println!("\n📊 Session Summary:");
                println!("{}", agent.get_session_summary());
                continue;
            }
            "memory" => {
                println!("\n🧠 Session Memory:");
                if let Some(start) = agent.get_memory("session_start") {
                    println!("  Session started: {}", start);
                }
                if let Some(dir) = agent.get_memory("working_directory") {
                    println!("  Working directory: {}", dir);
                }
                if let Some(files) = agent.get_memory("files_accessed") {
                    println!("  Files accessed: {}", files);
                }
                if let Some(edits) = agent.get_memory("edits_made") {
                    println!("  Edits made: {}", edits);
                }
                if let Some(action) = agent.get_memory("last_action") {
                    println!("  Last action: {}", action);
                }
                continue;
            }
            "help" => {
                println!("\n📖 Available Commands:");
                println!("  exit, quit  - Exit the demo");
                println!("  summary     - Show session summary");
                println!("  memory      - Show session memory");
                println!("  help        - Show this help");
                println!("\n💡 Try asking the agent to:");
                println!("  • Search for specific files");
                println!("  • Read file contents");
                println!("  • Summarize what it has done");
                continue;
            }
            _ => {}
        }

        // Send message to agent with streaming.
        print!("\nAgent: ");
        io::stdout().flush()?;

        match agent.chat(input).await {
            Ok(response) => {
                println!("{}", response);

                // Update memory after each interaction.
                agent.increment_counter("files_accessed");
            }
            Err(e) => {
                eprintln!("\n❌ Error: {}", e);
            }
        }
    }

    // --- Final summary ---
    println!("\n📊 Final Session Summary:");
    println!("{}", agent.get_session_summary());

    println!("\n✅ Demo completed successfully!");
    println!("\n💡 Features Demonstrated:");
    println!("  ✓ Streaming responses (local/remote models)");
    println!("  ✓ File search with pattern matching");
    println!("  ✓ File reading with summaries");
    println!("  ✓ Session memory tracking");
    println!("  ✓ Interactive conversation");
    println!("  ✓ Real-time progress updates");

    Ok(())
}

pub fn save<P: AsRef<Path>>(&self, path: P) -> Result<()>

Saves the configuration to a TOML file.

Arguments

• path - The path to the TOML file.

Returns

A Result indicating success or failure.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Config

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Config

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.