ai-agent-system 1.0.0

A comprehensive AI agent framework with memory, tool integration, and visible reasoning capabilities.

AI Agent System

Installation

pip install ai_agent_system

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
• Typographic Output: Beautiful, formatted output with color coding and structured display
• 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

# Initialize the agent
agent = AIAgent(
    model_name="gpt-4",
    memory_persist_path="./agent_memory",
    enable_reasoning_display=True
)

# Process a query
response = agent.process_query("Calculate the factorial of 5 using Python")

# Get formatted output
formatted_response = agent.get_formatted_response(response)
print(formatted_response)

Interactive Mode

Run the demonstration script in interactive mode:

cd ai_agent_system
python examples/demo.py interactive

Demo Mode

Run the full demonstration:

cd ai_agent_system
python examples/demo.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())

📊 Output Format

The agent provides detailed, formatted output including:

• Execution Summary: Time taken, tools used, reasoning steps
• Reasoning Process: Step-by-step breakdown of decision making
• Tool Output: Detailed results from tool execution
• Final Response: Synthesized answer to the user's query
• Memory Updates: Information stored for future reference

🎯 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