Struct ChatSession 

pub struct ChatSession {
    pub messages: Vec<ChatMessage>,
    pub system_prompt: Option<String>,
    pub metadata: HashMap<String, String>,
}

Represents a chat session, including the conversation history and metadata.

Fields

messages: Vec<ChatMessage>

The messages in the chat session.

system_prompt: Option<String>

The system prompt for the chat session.

metadata: HashMap<String, String>

Metadata associated with the chat session.

Implementations

impl ChatSession

pub fn new() -> Self

Creates a new, empty chat session.

Examples found in repository

examples/direct_llm_usage.rs (line 103)

async fn conversation_with_context() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // Use a `ChatSession` to manage the conversation history.
    let mut session = ChatSession::new()
        .with_system_prompt("You are a helpful math tutor. Give brief, clear explanations.");

    // --- First turn ---
    println!("Turn 1:");
    session.add_user_message("What is 15 * 23?");
    print!("  User: What is 15 * 23?\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
            return Ok(());
        }
    }

    // --- Second turn (with context from the first turn) ---
    println!("\nTurn 2:");
    session.add_user_message("Now divide that by 5.");
    print!("  User: Now divide that by 5.\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
        }
    }

    println!("\n💡 Notice how the assistant remembered the result from the first calculation!");

    Ok(())
}

/// Provides information about using different LLM providers.
fn different_providers_info() {
    println!("You can use Helios with various LLM providers:\n");

    println!("🔵 OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-4\".to_string(),");
    println!("       base_url: \"https://api.openai.com/v1\".to_string(),");
    println!("       api_key: env::var(\"OPENAI_API_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🟢 Local LM Studio:");
    println!("   LLMConfig {{");
    println!("       model_name: \"local-model\".to_string(),");
    println!("       base_url: \"http://localhost:1234/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🦙 Ollama:");
    println!("   LLMConfig {{");
    println!("       model_name: \"llama2\".to_string(),");
    println!("       base_url: \"http://localhost:11434/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🔷 Azure OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-35-turbo\".to_string(),");
    println!("       base_url: \"https://your-resource.openai.azure.com/...\".to_string(),");
    println!("       api_key: env::var(\"AZURE_OPENAI_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");
}

/// Starts an interactive chat session with the LLM.
async fn interactive_chat() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;
    let mut session =
        ChatSession::new().with_system_prompt("You are a friendly and helpful AI assistant.");

    println!("Chat started! Type 'exit' or 'quit' to end the conversation.\n");

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

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

        if input.is_empty() {
            continue;
        }

        if input == "exit" || input == "quit" {
            println!("\n👋 Goodbye!");
            break;
        }

        // Handle special commands.
        if input == "clear" {
            session.clear();
            println!("🧹 Conversation cleared!\n");
            continue;
        }

        if input == "history" {
            println!("\n📜 Conversation history:");
            for (i, msg) in session.messages.iter().enumerate() {
                println!("  {}. {:?}: {}", i + 1, msg.role, msg.content);
            }
            println!();
            continue;
        }

        session.add_user_message(input);

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

        match client.chat(session.get_messages(), None).await {
            Ok(response) => {
                session.add_assistant_message(&response.content);
                println!("{}\n", response.content);
            }
            Err(e) => {
                println!("\n❌ Error: {}", e);
                println!("   (Make sure OPENAI_API_KEY is set correctly)\n");
                // Remove the last user message since it failed.
                session.messages.pop();
            }
        }
    }

    Ok(())
}

examples/local_streaming.rs (line 65)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Local Model Streaming Example");
    println!("=================================================\n");

    // Configure the local model to use.
    let local_config = LocalConfig {
        huggingface_repo: "unsloth/Qwen2.5-0.5B-Instruct-GGUF".to_string(),
        model_file: "Qwen2.5-0.5B-Instruct-Q4_K_M.gguf".to_string(),
        context_size: 2048,
        temperature: 0.7,
        max_tokens: 512,
    };

    println!("📥 Loading local model...");
    println!("   Repository: {}", local_config.huggingface_repo);
    println!("   Model: {}\n", local_config.model_file);

    // Create a new LLM client with the local model configuration.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Local(local_config)).await?;

    println!("✓ Model loaded successfully!\n");

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful coding assistant."),
        ChatMessage::user("Write a short explanation of what Rust is."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n");

    // --- Example 2: Interactive streaming ---
    println!("Example 2: Interactive Streaming");
    println!("==================================\n");

    let questions = vec![
        "What are the main benefits of Rust?",
        "Give me a simple code example.",
    ];

    let mut session = helios_engine::ChatSession::new()
        .with_system_prompt("You are a helpful programming assistant.");

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    println!("✅ Local model streaming completed successfully!");
    println!("\n💡 Features:");
    println!("  • Token-by-token streaming for local models");
    println!("  • Real-time response display (no more instant full responses)");
    println!("  • Same streaming API for both local and remote models");
    println!("  • Improved user experience with progressive output");

    Ok(())
}

examples/streaming_chat.rs (line 57)

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

    // Set up the LLM configuration.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful assistant."),
        ChatMessage::user("Write a short poem about coding."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n");

    // --- Example 2: Interactive streaming chat ---
    println!("Example 2: Interactive Streaming Chat");
    println!("======================================\n");

    let mut session = ChatSession::new().with_system_prompt("You are a helpful coding assistant.");

    let questions = vec![
        "What is Rust?",
        "What are its main benefits?",
        "Show me a simple example.",
    ];

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    // --- Example 3: Streaming with thinking tags ---
    println!("\nExample 3: Streaming with Thinking Tags");
    println!("=========================================\n");
    println!("When using models that support thinking tags (like o1),");
    println!("you can detect and display them during streaming.\n");

    /// A helper struct to track and display thinking tags in streamed responses.
    struct ThinkingTracker {
        in_thinking: bool,
        thinking_buffer: String,
    }

    impl ThinkingTracker {
        /// Creates a new `ThinkingTracker`.
        fn new() -> Self {
            Self {
                in_thinking: false,
                thinking_buffer: String::new(),
            }
        }

        /// Processes a chunk of a streamed response and returns the processed output.
        fn process_chunk(&mut self, chunk: &str) -> String {
            let mut output = String::new();
            let mut chars = chunk.chars().peekable();

            while let Some(c) = chars.next() {
                if c == '<' {
                    let remaining: String = chars.clone().collect();
                    if remaining.starts_with("thinking>") {
                        self.in_thinking = true;
                        self.thinking_buffer.clear();
                        output.push_str("\n💭 [Thinking");
                        for _ in 0..9 {
                            chars.next();
                        }
                        continue;
                    } else if remaining.starts_with("/thinking>") {
                        self.in_thinking = false;
                        output.push_str("]\n");
                        for _ in 0..10 {
                            chars.next();
                        }
                        continue;
                    }
                }

                if self.in_thinking {
                    self.thinking_buffer.push(c);
                    if self.thinking_buffer.len() % 3 == 0 {
                        output.push('.');
                    }
                } else {
                    output.push(c);
                }
            }

            output
        }
    }

    let messages = vec![ChatMessage::user(
        "Solve this problem: What is 15 * 234 + 89?",
    )];

    let mut tracker = ThinkingTracker::new();
    print!("Assistant: ");
    io::stdout().flush()?;

    // Stream the response, processing thinking tags as they arrive.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            let output = tracker.process_chunk(chunk);
            print!("{}", output);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n✅ Streaming examples completed!");
    println!("\nKey benefits of streaming:");
    println!("  • Real-time response display");
    println!("  • Better user experience for long responses");
    println!("  • Ability to show thinking/reasoning process");
    println!("  • Early cancellation possible (future feature)");

    Ok(())
}

pub fn with_system_prompt(self, prompt: impl Into<String>) -> Self

Sets the system prompt for the chat session.

Examples found in repository

examples/direct_llm_usage.rs (line 104)

async fn conversation_with_context() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // Use a `ChatSession` to manage the conversation history.
    let mut session = ChatSession::new()
        .with_system_prompt("You are a helpful math tutor. Give brief, clear explanations.");

    // --- First turn ---
    println!("Turn 1:");
    session.add_user_message("What is 15 * 23?");
    print!("  User: What is 15 * 23?\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
            return Ok(());
        }
    }

    // --- Second turn (with context from the first turn) ---
    println!("\nTurn 2:");
    session.add_user_message("Now divide that by 5.");
    print!("  User: Now divide that by 5.\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
        }
    }

    println!("\n💡 Notice how the assistant remembered the result from the first calculation!");

    Ok(())
}

/// Provides information about using different LLM providers.
fn different_providers_info() {
    println!("You can use Helios with various LLM providers:\n");

    println!("🔵 OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-4\".to_string(),");
    println!("       base_url: \"https://api.openai.com/v1\".to_string(),");
    println!("       api_key: env::var(\"OPENAI_API_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🟢 Local LM Studio:");
    println!("   LLMConfig {{");
    println!("       model_name: \"local-model\".to_string(),");
    println!("       base_url: \"http://localhost:1234/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🦙 Ollama:");
    println!("   LLMConfig {{");
    println!("       model_name: \"llama2\".to_string(),");
    println!("       base_url: \"http://localhost:11434/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🔷 Azure OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-35-turbo\".to_string(),");
    println!("       base_url: \"https://your-resource.openai.azure.com/...\".to_string(),");
    println!("       api_key: env::var(\"AZURE_OPENAI_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");
}

/// Starts an interactive chat session with the LLM.
async fn interactive_chat() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;
    let mut session =
        ChatSession::new().with_system_prompt("You are a friendly and helpful AI assistant.");

    println!("Chat started! Type 'exit' or 'quit' to end the conversation.\n");

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

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

        if input.is_empty() {
            continue;
        }

        if input == "exit" || input == "quit" {
            println!("\n👋 Goodbye!");
            break;
        }

        // Handle special commands.
        if input == "clear" {
            session.clear();
            println!("🧹 Conversation cleared!\n");
            continue;
        }

        if input == "history" {
            println!("\n📜 Conversation history:");
            for (i, msg) in session.messages.iter().enumerate() {
                println!("  {}. {:?}: {}", i + 1, msg.role, msg.content);
            }
            println!();
            continue;
        }

        session.add_user_message(input);

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

        match client.chat(session.get_messages(), None).await {
            Ok(response) => {
                session.add_assistant_message(&response.content);
                println!("{}\n", response.content);
            }
            Err(e) => {
                println!("\n❌ Error: {}", e);
                println!("   (Make sure OPENAI_API_KEY is set correctly)\n");
                // Remove the last user message since it failed.
                session.messages.pop();
            }
        }
    }

    Ok(())
}

examples/local_streaming.rs (line 66)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Local Model Streaming Example");
    println!("=================================================\n");

    // Configure the local model to use.
    let local_config = LocalConfig {
        huggingface_repo: "unsloth/Qwen2.5-0.5B-Instruct-GGUF".to_string(),
        model_file: "Qwen2.5-0.5B-Instruct-Q4_K_M.gguf".to_string(),
        context_size: 2048,
        temperature: 0.7,
        max_tokens: 512,
    };

    println!("📥 Loading local model...");
    println!("   Repository: {}", local_config.huggingface_repo);
    println!("   Model: {}\n", local_config.model_file);

    // Create a new LLM client with the local model configuration.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Local(local_config)).await?;

    println!("✓ Model loaded successfully!\n");

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful coding assistant."),
        ChatMessage::user("Write a short explanation of what Rust is."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n");

    // --- Example 2: Interactive streaming ---
    println!("Example 2: Interactive Streaming");
    println!("==================================\n");

    let questions = vec![
        "What are the main benefits of Rust?",
        "Give me a simple code example.",
    ];

    let mut session = helios_engine::ChatSession::new()
        .with_system_prompt("You are a helpful programming assistant.");

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    println!("✅ Local model streaming completed successfully!");
    println!("\n💡 Features:");
    println!("  • Token-by-token streaming for local models");
    println!("  • Real-time response display (no more instant full responses)");
    println!("  • Same streaming API for both local and remote models");
    println!("  • Improved user experience with progressive output");

    Ok(())
}

examples/streaming_chat.rs (line 57)

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

    // Set up the LLM configuration.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful assistant."),
        ChatMessage::user("Write a short poem about coding."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n");

    // --- Example 2: Interactive streaming chat ---
    println!("Example 2: Interactive Streaming Chat");
    println!("======================================\n");

    let mut session = ChatSession::new().with_system_prompt("You are a helpful coding assistant.");

    let questions = vec![
        "What is Rust?",
        "What are its main benefits?",
        "Show me a simple example.",
    ];

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    // --- Example 3: Streaming with thinking tags ---
    println!("\nExample 3: Streaming with Thinking Tags");
    println!("=========================================\n");
    println!("When using models that support thinking tags (like o1),");
    println!("you can detect and display them during streaming.\n");

    /// A helper struct to track and display thinking tags in streamed responses.
    struct ThinkingTracker {
        in_thinking: bool,
        thinking_buffer: String,
    }

    impl ThinkingTracker {
        /// Creates a new `ThinkingTracker`.
        fn new() -> Self {
            Self {
                in_thinking: false,
                thinking_buffer: String::new(),
            }
        }

        /// Processes a chunk of a streamed response and returns the processed output.
        fn process_chunk(&mut self, chunk: &str) -> String {
            let mut output = String::new();
            let mut chars = chunk.chars().peekable();

            while let Some(c) = chars.next() {
                if c == '<' {
                    let remaining: String = chars.clone().collect();
                    if remaining.starts_with("thinking>") {
                        self.in_thinking = true;
                        self.thinking_buffer.clear();
                        output.push_str("\n💭 [Thinking");
                        for _ in 0..9 {
                            chars.next();
                        }
                        continue;
                    } else if remaining.starts_with("/thinking>") {
                        self.in_thinking = false;
                        output.push_str("]\n");
                        for _ in 0..10 {
                            chars.next();
                        }
                        continue;
                    }
                }

                if self.in_thinking {
                    self.thinking_buffer.push(c);
                    if self.thinking_buffer.len() % 3 == 0 {
                        output.push('.');
                    }
                } else {
                    output.push(c);
                }
            }

            output
        }
    }

    let messages = vec![ChatMessage::user(
        "Solve this problem: What is 15 * 234 + 89?",
    )];

    let mut tracker = ThinkingTracker::new();
    print!("Assistant: ");
    io::stdout().flush()?;

    // Stream the response, processing thinking tags as they arrive.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            let output = tracker.process_chunk(chunk);
            print!("{}", output);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n✅ Streaming examples completed!");
    println!("\nKey benefits of streaming:");
    println!("  • Real-time response display");
    println!("  • Better user experience for long responses");
    println!("  • Ability to show thinking/reasoning process");
    println!("  • Early cancellation possible (future feature)");

    Ok(())
}

pub fn add_message(&mut self, message: ChatMessage)

Adds a message to the chat session.

pub fn add_user_message(&mut self, content: impl Into<String>)

Adds a user message to the chat session.

Examples found in repository

examples/direct_llm_usage.rs (line 108)

async fn conversation_with_context() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // Use a `ChatSession` to manage the conversation history.
    let mut session = ChatSession::new()
        .with_system_prompt("You are a helpful math tutor. Give brief, clear explanations.");

    // --- First turn ---
    println!("Turn 1:");
    session.add_user_message("What is 15 * 23?");
    print!("  User: What is 15 * 23?\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
            return Ok(());
        }
    }

    // --- Second turn (with context from the first turn) ---
    println!("\nTurn 2:");
    session.add_user_message("Now divide that by 5.");
    print!("  User: Now divide that by 5.\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
        }
    }

    println!("\n💡 Notice how the assistant remembered the result from the first calculation!");

    Ok(())
}

/// Provides information about using different LLM providers.
fn different_providers_info() {
    println!("You can use Helios with various LLM providers:\n");

    println!("🔵 OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-4\".to_string(),");
    println!("       base_url: \"https://api.openai.com/v1\".to_string(),");
    println!("       api_key: env::var(\"OPENAI_API_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🟢 Local LM Studio:");
    println!("   LLMConfig {{");
    println!("       model_name: \"local-model\".to_string(),");
    println!("       base_url: \"http://localhost:1234/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🦙 Ollama:");
    println!("   LLMConfig {{");
    println!("       model_name: \"llama2\".to_string(),");
    println!("       base_url: \"http://localhost:11434/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🔷 Azure OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-35-turbo\".to_string(),");
    println!("       base_url: \"https://your-resource.openai.azure.com/...\".to_string(),");
    println!("       api_key: env::var(\"AZURE_OPENAI_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");
}

/// Starts an interactive chat session with the LLM.
async fn interactive_chat() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;
    let mut session =
        ChatSession::new().with_system_prompt("You are a friendly and helpful AI assistant.");

    println!("Chat started! Type 'exit' or 'quit' to end the conversation.\n");

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

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

        if input.is_empty() {
            continue;
        }

        if input == "exit" || input == "quit" {
            println!("\n👋 Goodbye!");
            break;
        }

        // Handle special commands.
        if input == "clear" {
            session.clear();
            println!("🧹 Conversation cleared!\n");
            continue;
        }

        if input == "history" {
            println!("\n📜 Conversation history:");
            for (i, msg) in session.messages.iter().enumerate() {
                println!("  {}. {:?}: {}", i + 1, msg.role, msg.content);
            }
            println!();
            continue;
        }

        session.add_user_message(input);

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

        match client.chat(session.get_messages(), None).await {
            Ok(response) => {
                session.add_assistant_message(&response.content);
                println!("{}\n", response.content);
            }
            Err(e) => {
                println!("\n❌ Error: {}", e);
                println!("   (Make sure OPENAI_API_KEY is set correctly)\n");
                // Remove the last user message since it failed.
                session.messages.pop();
            }
        }
    }

    Ok(())
}

examples/local_streaming.rs (line 70)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Local Model Streaming Example");
    println!("=================================================\n");

    // Configure the local model to use.
    let local_config = LocalConfig {
        huggingface_repo: "unsloth/Qwen2.5-0.5B-Instruct-GGUF".to_string(),
        model_file: "Qwen2.5-0.5B-Instruct-Q4_K_M.gguf".to_string(),
        context_size: 2048,
        temperature: 0.7,
        max_tokens: 512,
    };

    println!("📥 Loading local model...");
    println!("   Repository: {}", local_config.huggingface_repo);
    println!("   Model: {}\n", local_config.model_file);

    // Create a new LLM client with the local model configuration.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Local(local_config)).await?;

    println!("✓ Model loaded successfully!\n");

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful coding assistant."),
        ChatMessage::user("Write a short explanation of what Rust is."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n");

    // --- Example 2: Interactive streaming ---
    println!("Example 2: Interactive Streaming");
    println!("==================================\n");

    let questions = vec![
        "What are the main benefits of Rust?",
        "Give me a simple code example.",
    ];

    let mut session = helios_engine::ChatSession::new()
        .with_system_prompt("You are a helpful programming assistant.");

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    println!("✅ Local model streaming completed successfully!");
    println!("\n💡 Features:");
    println!("  • Token-by-token streaming for local models");
    println!("  • Real-time response display (no more instant full responses)");
    println!("  • Same streaming API for both local and remote models");
    println!("  • Improved user experience with progressive output");

    Ok(())
}

examples/streaming_chat.rs (line 67)

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

    // Set up the LLM configuration.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful assistant."),
        ChatMessage::user("Write a short poem about coding."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n");

    // --- Example 2: Interactive streaming chat ---
    println!("Example 2: Interactive Streaming Chat");
    println!("======================================\n");

    let mut session = ChatSession::new().with_system_prompt("You are a helpful coding assistant.");

    let questions = vec![
        "What is Rust?",
        "What are its main benefits?",
        "Show me a simple example.",
    ];

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    // --- Example 3: Streaming with thinking tags ---
    println!("\nExample 3: Streaming with Thinking Tags");
    println!("=========================================\n");
    println!("When using models that support thinking tags (like o1),");
    println!("you can detect and display them during streaming.\n");

    /// A helper struct to track and display thinking tags in streamed responses.
    struct ThinkingTracker {
        in_thinking: bool,
        thinking_buffer: String,
    }

    impl ThinkingTracker {
        /// Creates a new `ThinkingTracker`.
        fn new() -> Self {
            Self {
                in_thinking: false,
                thinking_buffer: String::new(),
            }
        }

        /// Processes a chunk of a streamed response and returns the processed output.
        fn process_chunk(&mut self, chunk: &str) -> String {
            let mut output = String::new();
            let mut chars = chunk.chars().peekable();

            while let Some(c) = chars.next() {
                if c == '<' {
                    let remaining: String = chars.clone().collect();
                    if remaining.starts_with("thinking>") {
                        self.in_thinking = true;
                        self.thinking_buffer.clear();
                        output.push_str("\n💭 [Thinking");
                        for _ in 0..9 {
                            chars.next();
                        }
                        continue;
                    } else if remaining.starts_with("/thinking>") {
                        self.in_thinking = false;
                        output.push_str("]\n");
                        for _ in 0..10 {
                            chars.next();
                        }
                        continue;
                    }
                }

                if self.in_thinking {
                    self.thinking_buffer.push(c);
                    if self.thinking_buffer.len() % 3 == 0 {
                        output.push('.');
                    }
                } else {
                    output.push(c);
                }
            }

            output
        }
    }

    let messages = vec![ChatMessage::user(
        "Solve this problem: What is 15 * 234 + 89?",
    )];

    let mut tracker = ThinkingTracker::new();
    print!("Assistant: ");
    io::stdout().flush()?;

    // Stream the response, processing thinking tags as they arrive.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            let output = tracker.process_chunk(chunk);
            print!("{}", output);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n✅ Streaming examples completed!");
    println!("\nKey benefits of streaming:");
    println!("  • Real-time response display");
    println!("  • Better user experience for long responses");
    println!("  • Ability to show thinking/reasoning process");
    println!("  • Early cancellation possible (future feature)");

    Ok(())
}

pub fn add_assistant_message(&mut self, content: impl Into<String>)

Adds an assistant message to the chat session.

Examples found in repository

examples/direct_llm_usage.rs (line 113)

async fn conversation_with_context() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // Use a `ChatSession` to manage the conversation history.
    let mut session = ChatSession::new()
        .with_system_prompt("You are a helpful math tutor. Give brief, clear explanations.");

    // --- First turn ---
    println!("Turn 1:");
    session.add_user_message("What is 15 * 23?");
    print!("  User: What is 15 * 23?\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
            return Ok(());
        }
    }

    // --- Second turn (with context from the first turn) ---
    println!("\nTurn 2:");
    session.add_user_message("Now divide that by 5.");
    print!("  User: Now divide that by 5.\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
        }
    }

    println!("\n💡 Notice how the assistant remembered the result from the first calculation!");

    Ok(())
}

/// Provides information about using different LLM providers.
fn different_providers_info() {
    println!("You can use Helios with various LLM providers:\n");

    println!("🔵 OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-4\".to_string(),");
    println!("       base_url: \"https://api.openai.com/v1\".to_string(),");
    println!("       api_key: env::var(\"OPENAI_API_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🟢 Local LM Studio:");
    println!("   LLMConfig {{");
    println!("       model_name: \"local-model\".to_string(),");
    println!("       base_url: \"http://localhost:1234/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🦙 Ollama:");
    println!("   LLMConfig {{");
    println!("       model_name: \"llama2\".to_string(),");
    println!("       base_url: \"http://localhost:11434/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🔷 Azure OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-35-turbo\".to_string(),");
    println!("       base_url: \"https://your-resource.openai.azure.com/...\".to_string(),");
    println!("       api_key: env::var(\"AZURE_OPENAI_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");
}

/// Starts an interactive chat session with the LLM.
async fn interactive_chat() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;
    let mut session =
        ChatSession::new().with_system_prompt("You are a friendly and helpful AI assistant.");

    println!("Chat started! Type 'exit' or 'quit' to end the conversation.\n");

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

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

        if input.is_empty() {
            continue;
        }

        if input == "exit" || input == "quit" {
            println!("\n👋 Goodbye!");
            break;
        }

        // Handle special commands.
        if input == "clear" {
            session.clear();
            println!("🧹 Conversation cleared!\n");
            continue;
        }

        if input == "history" {
            println!("\n📜 Conversation history:");
            for (i, msg) in session.messages.iter().enumerate() {
                println!("  {}. {:?}: {}", i + 1, msg.role, msg.content);
            }
            println!();
            continue;
        }

        session.add_user_message(input);

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

        match client.chat(session.get_messages(), None).await {
            Ok(response) => {
                session.add_assistant_message(&response.content);
                println!("{}\n", response.content);
            }
            Err(e) => {
                println!("\n❌ Error: {}", e);
                println!("   (Make sure OPENAI_API_KEY is set correctly)\n");
                // Remove the last user message since it failed.
                session.messages.pop();
            }
        }
    }

    Ok(())
}

examples/local_streaming.rs (line 83)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Local Model Streaming Example");
    println!("=================================================\n");

    // Configure the local model to use.
    let local_config = LocalConfig {
        huggingface_repo: "unsloth/Qwen2.5-0.5B-Instruct-GGUF".to_string(),
        model_file: "Qwen2.5-0.5B-Instruct-Q4_K_M.gguf".to_string(),
        context_size: 2048,
        temperature: 0.7,
        max_tokens: 512,
    };

    println!("📥 Loading local model...");
    println!("   Repository: {}", local_config.huggingface_repo);
    println!("   Model: {}\n", local_config.model_file);

    // Create a new LLM client with the local model configuration.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Local(local_config)).await?;

    println!("✓ Model loaded successfully!\n");

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful coding assistant."),
        ChatMessage::user("Write a short explanation of what Rust is."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n");

    // --- Example 2: Interactive streaming ---
    println!("Example 2: Interactive Streaming");
    println!("==================================\n");

    let questions = vec![
        "What are the main benefits of Rust?",
        "Give me a simple code example.",
    ];

    let mut session = helios_engine::ChatSession::new()
        .with_system_prompt("You are a helpful programming assistant.");

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    println!("✅ Local model streaming completed successfully!");
    println!("\n💡 Features:");
    println!("  • Token-by-token streaming for local models");
    println!("  • Real-time response display (no more instant full responses)");
    println!("  • Same streaming API for both local and remote models");
    println!("  • Improved user experience with progressive output");

    Ok(())
}

examples/streaming_chat.rs (line 80)

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

    // Set up the LLM configuration.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful assistant."),
        ChatMessage::user("Write a short poem about coding."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n");

    // --- Example 2: Interactive streaming chat ---
    println!("Example 2: Interactive Streaming Chat");
    println!("======================================\n");

    let mut session = ChatSession::new().with_system_prompt("You are a helpful coding assistant.");

    let questions = vec![
        "What is Rust?",
        "What are its main benefits?",
        "Show me a simple example.",
    ];

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    // --- Example 3: Streaming with thinking tags ---
    println!("\nExample 3: Streaming with Thinking Tags");
    println!("=========================================\n");
    println!("When using models that support thinking tags (like o1),");
    println!("you can detect and display them during streaming.\n");

    /// A helper struct to track and display thinking tags in streamed responses.
    struct ThinkingTracker {
        in_thinking: bool,
        thinking_buffer: String,
    }

    impl ThinkingTracker {
        /// Creates a new `ThinkingTracker`.
        fn new() -> Self {
            Self {
                in_thinking: false,
                thinking_buffer: String::new(),
            }
        }

        /// Processes a chunk of a streamed response and returns the processed output.
        fn process_chunk(&mut self, chunk: &str) -> String {
            let mut output = String::new();
            let mut chars = chunk.chars().peekable();

            while let Some(c) = chars.next() {
                if c == '<' {
                    let remaining: String = chars.clone().collect();
                    if remaining.starts_with("thinking>") {
                        self.in_thinking = true;
                        self.thinking_buffer.clear();
                        output.push_str("\n💭 [Thinking");
                        for _ in 0..9 {
                            chars.next();
                        }
                        continue;
                    } else if remaining.starts_with("/thinking>") {
                        self.in_thinking = false;
                        output.push_str("]\n");
                        for _ in 0..10 {
                            chars.next();
                        }
                        continue;
                    }
                }

                if self.in_thinking {
                    self.thinking_buffer.push(c);
                    if self.thinking_buffer.len() % 3 == 0 {
                        output.push('.');
                    }
                } else {
                    output.push(c);
                }
            }

            output
        }
    }

    let messages = vec![ChatMessage::user(
        "Solve this problem: What is 15 * 234 + 89?",
    )];

    let mut tracker = ThinkingTracker::new();
    print!("Assistant: ");
    io::stdout().flush()?;

    // Stream the response, processing thinking tags as they arrive.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            let output = tracker.process_chunk(chunk);
            print!("{}", output);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n✅ Streaming examples completed!");
    println!("\nKey benefits of streaming:");
    println!("  • Real-time response display");
    println!("  • Better user experience for long responses");
    println!("  • Ability to show thinking/reasoning process");
    println!("  • Early cancellation possible (future feature)");

    Ok(())
}

pub fn get_messages(&self) -> Vec<ChatMessage>

Returns all messages in the chat session, including the system prompt.

Examples found in repository

examples/direct_llm_usage.rs (line 111)

async fn conversation_with_context() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // Use a `ChatSession` to manage the conversation history.
    let mut session = ChatSession::new()
        .with_system_prompt("You are a helpful math tutor. Give brief, clear explanations.");

    // --- First turn ---
    println!("Turn 1:");
    session.add_user_message("What is 15 * 23?");
    print!("  User: What is 15 * 23?\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
            return Ok(());
        }
    }

    // --- Second turn (with context from the first turn) ---
    println!("\nTurn 2:");
    session.add_user_message("Now divide that by 5.");
    print!("  User: Now divide that by 5.\n  ");

    match client.chat(session.get_messages(), None).await {
        Ok(response) => {
            session.add_assistant_message(&response.content);
            println!("Assistant: {}", response.content);
        }
        Err(e) => {
            println!("Error: {}", e);
        }
    }

    println!("\n💡 Notice how the assistant remembered the result from the first calculation!");

    Ok(())
}

/// Provides information about using different LLM providers.
fn different_providers_info() {
    println!("You can use Helios with various LLM providers:\n");

    println!("🔵 OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-4\".to_string(),");
    println!("       base_url: \"https://api.openai.com/v1\".to_string(),");
    println!("       api_key: env::var(\"OPENAI_API_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🟢 Local LM Studio:");
    println!("   LLMConfig {{");
    println!("       model_name: \"local-model\".to_string(),");
    println!("       base_url: \"http://localhost:1234/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🦙 Ollama:");
    println!("   LLMConfig {{");
    println!("       model_name: \"llama2\".to_string(),");
    println!("       base_url: \"http://localhost:11434/v1\".to_string(),");
    println!("       api_key: \"not-needed\".to_string(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");

    println!("🔷 Azure OpenAI:");
    println!("   LLMConfig {{");
    println!("       model_name: \"gpt-35-turbo\".to_string(),");
    println!("       base_url: \"https://your-resource.openai.azure.com/...\".to_string(),");
    println!("       api_key: env::var(\"AZURE_OPENAI_KEY\").unwrap(),");
    println!("       temperature: 0.7,");
    println!("       max_tokens: 2048,");
    println!("   }}\n");
}

/// Starts an interactive chat session with the LLM.
async fn interactive_chat() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;
    let mut session =
        ChatSession::new().with_system_prompt("You are a friendly and helpful AI assistant.");

    println!("Chat started! Type 'exit' or 'quit' to end the conversation.\n");

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

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

        if input.is_empty() {
            continue;
        }

        if input == "exit" || input == "quit" {
            println!("\n👋 Goodbye!");
            break;
        }

        // Handle special commands.
        if input == "clear" {
            session.clear();
            println!("🧹 Conversation cleared!\n");
            continue;
        }

        if input == "history" {
            println!("\n📜 Conversation history:");
            for (i, msg) in session.messages.iter().enumerate() {
                println!("  {}. {:?}: {}", i + 1, msg.role, msg.content);
            }
            println!();
            continue;
        }

        session.add_user_message(input);

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

        match client.chat(session.get_messages(), None).await {
            Ok(response) => {
                session.add_assistant_message(&response.content);
                println!("{}\n", response.content);
            }
            Err(e) => {
                println!("\n❌ Error: {}", e);
                println!("   (Make sure OPENAI_API_KEY is set correctly)\n");
                // Remove the last user message since it failed.
                session.messages.pop();
            }
        }
    }

    Ok(())
}

examples/local_streaming.rs (line 77)

async fn main() -> helios_engine::Result<()> {
    println!("🚀 Helios Engine - Local Model Streaming Example");
    println!("=================================================\n");

    // Configure the local model to use.
    let local_config = LocalConfig {
        huggingface_repo: "unsloth/Qwen2.5-0.5B-Instruct-GGUF".to_string(),
        model_file: "Qwen2.5-0.5B-Instruct-Q4_K_M.gguf".to_string(),
        context_size: 2048,
        temperature: 0.7,
        max_tokens: 512,
    };

    println!("📥 Loading local model...");
    println!("   Repository: {}", local_config.huggingface_repo);
    println!("   Model: {}\n", local_config.model_file);

    // Create a new LLM client with the local model configuration.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Local(local_config)).await?;

    println!("✓ Model loaded successfully!\n");

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful coding assistant."),
        ChatMessage::user("Write a short explanation of what Rust is."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n");

    // --- Example 2: Interactive streaming ---
    println!("Example 2: Interactive Streaming");
    println!("==================================\n");

    let questions = vec![
        "What are the main benefits of Rust?",
        "Give me a simple code example.",
    ];

    let mut session = helios_engine::ChatSession::new()
        .with_system_prompt("You are a helpful programming assistant.");

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    println!("✅ Local model streaming completed successfully!");
    println!("\n💡 Features:");
    println!("  • Token-by-token streaming for local models");
    println!("  • Real-time response display (no more instant full responses)");
    println!("  • Same streaming API for both local and remote models");
    println!("  • Improved user experience with progressive output");

    Ok(())
}

examples/streaming_chat.rs (line 74)

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

    // Set up the LLM configuration.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;

    // --- Example 1: Simple streaming response ---
    println!("Example 1: Simple Streaming Response");
    println!("======================================\n");

    let messages = vec![
        ChatMessage::system("You are a helpful assistant."),
        ChatMessage::user("Write a short poem about coding."),
    ];

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

    // Stream the response from the model, printing each chunk as it arrives.
    let response = client
        .chat_stream(messages, None, |chunk| {
            print!("{}", chunk);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n");

    // --- Example 2: Interactive streaming chat ---
    println!("Example 2: Interactive Streaming Chat");
    println!("======================================\n");

    let mut session = ChatSession::new().with_system_prompt("You are a helpful coding assistant.");

    let questions = vec![
        "What is Rust?",
        "What are its main benefits?",
        "Show me a simple example.",
    ];

    for question in questions {
        println!("User: {}", question);
        session.add_user_message(question);

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

        // Stream the response, maintaining the conversation context.
        let response = client
            .chat_stream(session.get_messages(), None, |chunk| {
                print!("{}", chunk);
                io::stdout().flush().unwrap();
            })
            .await?;

        session.add_assistant_message(&response.content);
        println!("\n");
    }

    // --- Example 3: Streaming with thinking tags ---
    println!("\nExample 3: Streaming with Thinking Tags");
    println!("=========================================\n");
    println!("When using models that support thinking tags (like o1),");
    println!("you can detect and display them during streaming.\n");

    /// A helper struct to track and display thinking tags in streamed responses.
    struct ThinkingTracker {
        in_thinking: bool,
        thinking_buffer: String,
    }

    impl ThinkingTracker {
        /// Creates a new `ThinkingTracker`.
        fn new() -> Self {
            Self {
                in_thinking: false,
                thinking_buffer: String::new(),
            }
        }

        /// Processes a chunk of a streamed response and returns the processed output.
        fn process_chunk(&mut self, chunk: &str) -> String {
            let mut output = String::new();
            let mut chars = chunk.chars().peekable();

            while let Some(c) = chars.next() {
                if c == '<' {
                    let remaining: String = chars.clone().collect();
                    if remaining.starts_with("thinking>") {
                        self.in_thinking = true;
                        self.thinking_buffer.clear();
                        output.push_str("\n💭 [Thinking");
                        for _ in 0..9 {
                            chars.next();
                        }
                        continue;
                    } else if remaining.starts_with("/thinking>") {
                        self.in_thinking = false;
                        output.push_str("]\n");
                        for _ in 0..10 {
                            chars.next();
                        }
                        continue;
                    }
                }

                if self.in_thinking {
                    self.thinking_buffer.push(c);
                    if self.thinking_buffer.len() % 3 == 0 {
                        output.push('.');
                    }
                } else {
                    output.push(c);
                }
            }

            output
        }
    }

    let messages = vec![ChatMessage::user(
        "Solve this problem: What is 15 * 234 + 89?",
    )];

    let mut tracker = ThinkingTracker::new();
    print!("Assistant: ");
    io::stdout().flush()?;

    // Stream the response, processing thinking tags as they arrive.
    let _response = client
        .chat_stream(messages, None, |chunk| {
            let output = tracker.process_chunk(chunk);
            print!("{}", output);
            io::stdout().flush().unwrap();
        })
        .await?;

    println!("\n\n✅ Streaming examples completed!");
    println!("\nKey benefits of streaming:");
    println!("  • Real-time response display");
    println!("  • Better user experience for long responses");
    println!("  • Ability to show thinking/reasoning process");
    println!("  • Early cancellation possible (future feature)");

    Ok(())
}

pub fn clear(&mut self)

Clears all messages from the chat session.

Examples found in repository

examples/direct_llm_usage.rs (line 221)

async fn interactive_chat() -> helios_engine::Result<()> {
    // Create a configuration for the LLM.
    let llm_config = LLMConfig {
        model_name: "gpt-3.5-turbo".to_string(),
        base_url: "https://api.openai.com/v1".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")
            .unwrap_or_else(|_| "your-api-key-here".to_string()),
        temperature: 0.7,
        max_tokens: 2048,
    };

    // Create a new LLM client.
    let client = LLMClient::new(helios_engine::llm::LLMProviderType::Remote(llm_config)).await?;
    let mut session =
        ChatSession::new().with_system_prompt("You are a friendly and helpful AI assistant.");

    println!("Chat started! Type 'exit' or 'quit' to end the conversation.\n");

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

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

        if input.is_empty() {
            continue;
        }

        if input == "exit" || input == "quit" {
            println!("\n👋 Goodbye!");
            break;
        }

        // Handle special commands.
        if input == "clear" {
            session.clear();
            println!("🧹 Conversation cleared!\n");
            continue;
        }

        if input == "history" {
            println!("\n📜 Conversation history:");
            for (i, msg) in session.messages.iter().enumerate() {
                println!("  {}. {:?}: {}", i + 1, msg.role, msg.content);
            }
            println!();
            continue;
        }

        session.add_user_message(input);

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

        match client.chat(session.get_messages(), None).await {
            Ok(response) => {
                session.add_assistant_message(&response.content);
                println!("{}\n", response.content);
            }
            Err(e) => {
                println!("\n❌ Error: {}", e);
                println!("   (Make sure OPENAI_API_KEY is set correctly)\n");
                // Remove the last user message since it failed.
                session.messages.pop();
            }
        }
    }

    Ok(())
}

pub fn set_metadata(&mut self, key: impl Into<String>, value: impl Into<String>)

Sets a metadata key-value pair for the session.

pub fn get_metadata(&self, key: &str) -> Option<&String>

Gets a metadata value by key.

pub fn remove_metadata(&mut self, key: &str) -> Option<String>

Removes a metadata key-value pair.

pub fn get_summary(&self) -> String

Returns a summary of the chat session.

Trait Implementations

impl Clone for ChatSession

fn clone(&self) -> ChatSession

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChatSession

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

Formats the value using the given formatter.

impl Default for ChatSession

fn default() -> Self

Creates a new, empty chat session.