ai-agent-system 1.2.2
A comprehensive AI agent framework with memory, tool integration, visible reasoning, and enhanced output formatting with colors, animations, and syntax highlighting.
Requires Python: >=3.8

# AI Agent System

[![PyPI version](https://badge.fury.io/py/ai_agent_system.svg)](https://badge.fury.io/py/ai_agent_system)

> **v1.2.2** - Default model switched to `gpt-4o` for all agent operations
> ***V1.2.1** - Some bugs fix
> **v1.2.0** - Introduce interactive mode `ai-agent-system --interactive` 
> **v1.1.0** - Enhanced with beautiful output formatting, syntax highlighting, and animations!

## Installation

```bash
pip install ai_agent_system
```
## Installation interactive

```bash
pip install -e . 
```

A comprehensive AI agent framework with memory capabilities, tool integration, and visible reasoning processes. This system implements the orchestrator-worker pattern with advanced memory management and a rich set of tools for various tasks.

## 🌟 Features

- **Memory Management**: Long-term memory using vector embeddings and RAG (Retrieval-Augmented Generation)
- **Tool Integration**: Comprehensive set of tools including Python execution, web browsing, file operations, and more
- **Visible Reasoning**: Step-by-step reasoning display with timestamps and detailed explanations
- **Enhanced Output Formatting**: Beautiful, interactive output with colors, animations, progress bars, and typography
- **Modular Architecture**: Extensible design allowing easy addition of new tools and capabilities

## 🛠️ Available Tools

1. **Python Tool**: Execute Python code and perform calculations
2. **Web Browser Tool**: Navigate websites and extract content
3. **File System Tool**: Read, write, and manage files and directories
4. **Screenshot Tool**: Capture screenshots of web pages (requires browser automation)
5. **Web Scraper Tool**: Extract structured data from websites
6. **Diff Checker Tool**: Compare files and text content
7. **Content Generator Tool**: Generate books, articles, and documents

## 🏗️ Architecture

The system follows an orchestrator-worker pattern:

- **Agent Core**: Central orchestrator that manages reasoning, tool selection, and response generation
- **Memory Manager**: Handles both short-term and long-term memory using vector embeddings
- **Tool Registry**: Manages available tools and provides a unified interface
- **Output Formatter**: Formats responses in a clear, typographic format

## 📦 Installation

1. Clone or download the AI agent system
2. Install required dependencies:

```bash
pip install -r requirements.txt
```

3. Set up your OpenAI API key:

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

## 🚀 Quick Start

### Basic Usage

```python
from core.agent import AIAgent
from utils.formatter import EnhancedOutputFormatter

# Initialize the agent with enhanced output
agent = AIAgent(
    model_name="gpt-4o",  # Default is now gpt-4o
    memory_persist_path="./agent_memory",
    enable_reasoning_display=True,
    realtime_output=True,
    minimal_output=False
)

# Initialize enhanced formatter
formatter = EnhancedOutputFormatter(enable_animations=True)

# Show beautiful banner
formatter.print_banner("AI Agent System")

# Process a query with progress indication
formatter.start_progress("Processing your query...")
response = agent.process_query("Calculate the factorial of 5 using Python")
formatter.stop_progress()

# Get enhanced formatted output
formatted_response = formatter.format_agent_response(response)
print(formatted_response)
```

### Interactive Mode

Run the enhanced demonstration script in interactive mode:

```bash
cd ai_agent_system
python examples/demo.py --interactive
```

### Demo Mode

Run the full enhanced demonstration:

```bash
cd ai_agent_system
python examples/demo.py
```

### Test Enhanced Output

Test all the enhanced output features:

```bash
cd ai_agent_system
python test_enhanced_output.py
```

## 🧠 Memory System

The agent uses a sophisticated memory system with:

- **Conversational Memory**: Recent interactions stored in memory
- **Knowledge Base**: Long-term storage using ChromaDB vector database
- **Semantic Search**: Retrieve relevant information using embeddings
- **Memory Types**: Interactions, knowledge, and observations

### Memory Operations

```python
# Store knowledge
memory_id = agent.memory_manager.store_knowledge(
    content="Python is a programming language",
    source="user_input"
)

# Retrieve relevant context
relevant_items = agent.memory_manager.retrieve_relevant_context(
    "Tell me about Python"
)

# Get memory statistics
stats = agent.get_memory_stats()
```

## 🔧 Tool Development

Create custom tools by extending the `BaseTool` class:

```python
from tools.tool_registry import BaseTool

class CustomTool(BaseTool):
    def __init__(self):
        super().__init__(
            name="custom_tool",
            description="Description of what this tool does"
        )
    
    def execute(self, query: str, context: Dict[str, Any]) -> Any:
        # Implement tool logic here
        return {"success": True, "result": "Tool output"}
    
    def get_capabilities(self) -> List[str]:
        return ["custom_capability"]

# Register the tool
agent.tool_registry.register_tool(CustomTool())
```

## 🎨 Enhanced Output Format

The agent provides beautiful, interactive output with enhanced formatting including:

### Visual Features
- **Color-coded sections**: Different colors for different types of information
- **Progress animations**: Animated progress bars and spinners during processing
- **Beautiful banners**: Eye-catching headers with gradient-like effects
- **Enhanced typography**: Better text formatting with proper indentation and spacing
- **Status indicators**: Visual indicators for success, warnings, and errors

### Output Sections
- **Execution Summary**: Time taken, tools used, reasoning steps with color-coded performance indicators
- **Reasoning Process**: Step-by-step breakdown with visual hierarchy and timestamps
- **Tool Output**: Detailed results with success/failure indicators and colorized content
- **Final Response**: Synthesized answer with enhanced typography
- **Final Result**: Highlighted box containing the most relevant result
- **Memory Updates**: Information stored for future reference with bullet points

### Animation Features
- **Progress bars**: Animated progress indicators during long operations
- **Spinner animations**: Loading spinners for various operations
- **Typewriter effect**: Character-by-character text display (configurable)
- **Real-time updates**: Live updates during agent processing

### Color Support
- **Automatic detection**: Automatically detects terminal color support
- **Fallback support**: Graceful degradation when colors are not supported
- **Environment awareness**: Respects `NO_COLOR` environment variable

## 🎯 Example Queries

- `"Calculate the sum of 25 and 37 using Python"`
- `"Browse to https://example.com and extract the title"`
- `"List all Python files in the current directory"`
- `"Write a short article about machine learning"`
- `"Compare the differences between file1.txt and file2.txt"`
- `"Scrape product information from an e-commerce website"`

## 🔍 Advanced Features

### Memory Export/Import

```python
# Export memory to JSON
agent.memory_manager.export_memory("memory_backup.json")

# Clear all memory
agent.clear_memory()
```

### Tool Information

```python
# Get available tools
tools = agent.tool_registry.get_available_tools()

# Get tool descriptions
descriptions = agent.tool_registry.get_tool_descriptions()

# Get tools by capability
web_tools = agent.tool_registry.get_tools_by_capability("web_navigation")
```

### Custom Formatting

```python
from utils.formatter import OutputFormatter

formatter = OutputFormatter()

# Format error messages
error_output = formatter.format_error("Something went wrong", context)

# Format memory statistics
stats_output = formatter.format_memory_stats(agent.get_memory_stats())

# Format tool list
tools_output = formatter.format_tool_list(agent.tool_registry.get_tool_info())
```

## 🛡️ Safety and Limitations

- Python code execution has basic safety checks to prevent dangerous operations
- File operations are limited to prevent accidental deletion
- Web browsing respects robots.txt and rate limiting
- Memory storage is local and persistent

## 🤝 Contributing

To add new tools or improve the system:

1. Create new tool classes in the `tools/` directory
2. Follow the `BaseTool` interface
3. Register tools in the `ToolRegistry`
4. Add appropriate tests and documentation

## 📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

## 🆘 Support

For issues or questions:
1. Check the demonstration examples
2. Review the tool implementations
3. Examine the memory management system
4. Test with simple queries first

---

**Built with ❤️ by Paul Gedeon**