# New Features Added to Helios Engine
## Summary
Three major features have been added to Helios Engine:
1. **Streaming for Local Models** - Real-time token-by-token output
2. **File Management Tools** - Search, read, write, and edit files
3. **Session Memory** - Track conversation state and metadata
---
## 1. Streaming for Local Models 🚀
### What Changed
Previously, local models displayed their full response instantly. Now they support **token-by-token streaming** just like remote models!
### Key Features
- Real-time token streaming for local models
- Same API for both local and remote providers
- Uses async channels for efficient token delivery
- Improved user experience with progressive output
### Usage Example
```rust
use helios_engine::{ChatMessage, LLMClient};
use helios_engine::config::LocalConfig;
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,
};
let client = LLMClient::new(
helios_engine::llm::LLMProviderType::Local(local_config)
).await?;
// Stream responses token-by-token
client.chat_stream(messages, None, |chunk| {
print!("{}", chunk);
}).await?;
```
See `examples/local_streaming.rs` for a complete example.
**Note**: When using local models, llama.cpp may output some debug information to stderr. This is normal and doesn't affect the streaming functionality. You can redirect stderr if you want cleaner output: `cargo run 2>/dev/null`
---
## 2. File Management Tools 📁
### New Tools Added
#### FileSearchTool
Search for files by name pattern or content within files.
**Parameters:**
- `path` - Directory to search (default: current directory)
- `pattern` - File name pattern (supports wildcards like *.rs)
- `content` - Text content to search for
- `max_results` - Maximum results (default: 50)
**Features:**
- Recursive directory traversal
- Wildcard pattern matching
- Content search with line numbers
- Auto-skips hidden files and common ignore dirs
#### FileReadTool
Read file contents with optional line range selection.
**Parameters:**
- `path` - File path (required)
- `start_line` - Starting line number (optional)
- `end_line` - Ending line number (optional)
#### FileWriteTool
Write content to a file (creates or overwrites).
**Parameters:**
- `path` - File path (required)
- `content` - Content to write (required)
**Features:**
- Creates parent directories automatically
- Safe file writing with error handling
#### FileEditTool
Edit files by replacing specific text.
**Parameters:**
- `path` - File path (required)
- `find` - Text to find (required)
- `replace` - Replacement text (required)
**Features:**
- Find and replace functionality
- Reports number of replacements made
- Error if text not found
### Usage Example
```rust
use helios_engine::{Agent, Config, FileSearchTool, FileReadTool, FileEditTool};
let mut agent = Agent::builder("FileAssistant")
.config(config)
.system_prompt("You are a file management assistant.")
.tool(Box::new(FileSearchTool))
.tool(Box::new(FileReadTool))
.tool(Box::new(FileEditTool))
.build()
.await?;
let response = agent
.chat("Find all Rust files in the src directory")
.await?;
```
See `examples/agent_with_file_tools.rs` for a complete example.
---
## 3. Session Memory 🧠
### What's New
Agents and chat sessions can now track metadata and session state.
### Features
#### ChatSession Metadata
```rust
// Set metadata
session.set_metadata("user_preference", "dark_mode");
session.set_metadata("last_action", "file_search");
// Get metadata
let preference = session.get_metadata("user_preference");
// Remove metadata
session.remove_metadata("last_action");
// Get session summary
println!("{}", session.get_summary());
```
#### Agent Session Memory
```rust
// Set memory
agent.set_memory("working_directory", "/home/user/project");
agent.set_memory("tasks_completed", "5");
// Get memory
let dir = agent.get_memory("working_directory");
// Remove memory
agent.remove_memory("tasks_completed");
// Get session summary
println!("{}", agent.get_session_summary());
// Clear all memory
agent.clear_memory();
```
### Session Summary Output
The `get_summary()` and `get_session_summary()` methods provide:
- Total message count
- Breakdown by role (user, assistant, tool)
- All metadata key-value pairs
- Agent-specific memory (for agents)
### Usage Example
```rust
use helios_engine::Agent;
let mut agent = Agent::builder("Assistant")
.config(config)
.build()
.await?;
// Track session information
agent.set_memory("session_start", chrono::Utc::now().to_rfc3339());
agent.set_memory("user_name", "Alice");
agent.set_memory("tasks_completed", "0");
// Use agent...
let response = agent.chat("Hello!").await?;
// Update memory
let tasks = agent.get_memory("tasks_completed")
.and_then(|v| v.parse::<u32>().ok())
.unwrap_or(0);
agent.set_memory("tasks_completed", (tasks + 1).to_string());
// View summary
println!("{}", agent.get_session_summary());
```
---
## Interactive CLI Updates
New commands added to the interactive chat mode:
- `summary` - Show session summary with metadata
- Updated help text to reflect new features
The CLI now shows:
```
💡 Features:
• Streaming responses for real-time output (local & remote)
• Thinking tags displayed when model uses them
• Full conversation context maintained
• Session memory for tracking conversation state
```
---
## Technical Details
### Dependencies Added
- `walkdir = "2.4"` - For recursive directory traversal
- `regex = "1.10"` - For pattern matching in file search
### Code Changes
- `src/llm.rs` - Added streaming support for local models
- `src/tools.rs` - Added 4 new file management tools
- `src/chat.rs` - Added metadata support to ChatSession
- `src/agent.rs` - Added session memory methods
- `src/lib.rs` - Exported new tools
- `src/main.rs` - Added summary command
- `Cargo.toml` - Added new dependencies
### Examples Added
- `examples/local_streaming.rs` - Demonstrates local model streaming
- `examples/agent_with_file_tools.rs` - Demonstrates file tools and session memory
---
## Testing
Build and test the new features:
```bash
# Build with examples
cargo build --examples
# Run local streaming example
cargo run --example local_streaming
# Run file tools example
cargo run --example agent_with_file_tools
# Run interactive chat
cargo run -- chat
```
---
## Breaking Changes
None! All changes are backwards compatible. Existing code will continue to work without modifications.
---
## Future Enhancements
Potential improvements for future releases:
- Add more file tools (move, delete, copy)
- Persistent session memory (save/load to disk)
- Session memory search and filtering
- More advanced pattern matching for file search
- File permissions and safety checks
