Metadata-Version: 2.1
Name: ai-agent-system
Version: 1.0.0
Summary: A comprehensive AI agent framework with memory, tool integration, and visible reasoning capabilities.
Home-page: https://github.com/PaulGG-Code/ai_agent_system_complete
Author: Paul Gedeon
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: chromadb>=0.4.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.31.0
Requires-Dist: markdown>=3.5.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-multipart>=0.0.6

# AI Agent System

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

## Installation

```bash
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:

```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

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

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

### Demo Mode

Run the full demonstration:

```bash
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

```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())
```

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

```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**

