ai-agent-system 1.2.1

A comprehensive AI agent framework with memory, tool integration, visible reasoning, and enhanced output formatting with colors, animations, and syntax highlighting.

AI Agent System

v1.2.0 - Introduce interactive mode ai-agent-system --interactive v1.1.0 - Enhanced with beautiful output formatting, syntax highlighting, and animations!

Installation

pip install ai_agent_system

Installation interactive

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:

pip install -r requirements.txt

3. Set up your OpenAI API key:

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

🚀 Quick Start

Basic Usage

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

# Initialize the agent with enhanced output
agent = AIAgent(
    model_name="gpt-4",
    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:

cd ai_agent_system
python examples/demo.py --interactive

Demo Mode

Run the full enhanced demonstration:

cd ai_agent_system
python examples/demo.py

Test Enhanced Output

Test all the enhanced output features:

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

# 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:

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

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

# Clear all memory
agent.clear_memory()

Tool Information

# 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

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