# AI Agent System
[](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**
Raw data
{
"_id": null,
"home_page": "https://github.com/PaulGG-Code/ai_agent_system_complete",
"name": "ai-agent-system",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Paul Gedeon",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d8/a0/2942b563ff109a736ed0cec7fc1819a75c63464dc7383e9b93bf00ffd02e/ai_agent_system-1.2.2.tar.gz",
"platform": null,
"description": "# AI Agent System\n\n[](https://badge.fury.io/py/ai_agent_system)\n\n> **v1.2.2** - Default model switched to `gpt-4o` for all agent operations\n> ***V1.2.1** - Some bugs fix\n> **v1.2.0** - Introduce interactive mode `ai-agent-system --interactive` \n> **v1.1.0** - Enhanced with beautiful output formatting, syntax highlighting, and animations!\n\n## Installation\n\n```bash\npip install ai_agent_system\n```\n## Installation interactive\n\n```bash\npip install -e . \n```\n\nA 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.\n\n## \ud83c\udf1f Features\n\n- **Memory Management**: Long-term memory using vector embeddings and RAG (Retrieval-Augmented Generation)\n- **Tool Integration**: Comprehensive set of tools including Python execution, web browsing, file operations, and more\n- **Visible Reasoning**: Step-by-step reasoning display with timestamps and detailed explanations\n- **Enhanced Output Formatting**: Beautiful, interactive output with colors, animations, progress bars, and typography\n- **Modular Architecture**: Extensible design allowing easy addition of new tools and capabilities\n\n## \ud83d\udee0\ufe0f Available Tools\n\n1. **Python Tool**: Execute Python code and perform calculations\n2. **Web Browser Tool**: Navigate websites and extract content\n3. **File System Tool**: Read, write, and manage files and directories\n4. **Screenshot Tool**: Capture screenshots of web pages (requires browser automation)\n5. **Web Scraper Tool**: Extract structured data from websites\n6. **Diff Checker Tool**: Compare files and text content\n7. **Content Generator Tool**: Generate books, articles, and documents\n\n## \ud83c\udfd7\ufe0f Architecture\n\nThe system follows an orchestrator-worker pattern:\n\n- **Agent Core**: Central orchestrator that manages reasoning, tool selection, and response generation\n- **Memory Manager**: Handles both short-term and long-term memory using vector embeddings\n- **Tool Registry**: Manages available tools and provides a unified interface\n- **Output Formatter**: Formats responses in a clear, typographic format\n\n## \ud83d\udce6 Installation\n\n1. Clone or download the AI agent system\n2. Install required dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n3. Set up your OpenAI API key:\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n## \ud83d\ude80 Quick Start\n\n### Basic Usage\n\n```python\nfrom core.agent import AIAgent\nfrom utils.formatter import EnhancedOutputFormatter\n\n# Initialize the agent with enhanced output\nagent = AIAgent(\n model_name=\"gpt-4o\", # Default is now gpt-4o\n memory_persist_path=\"./agent_memory\",\n enable_reasoning_display=True,\n realtime_output=True,\n minimal_output=False\n)\n\n# Initialize enhanced formatter\nformatter = EnhancedOutputFormatter(enable_animations=True)\n\n# Show beautiful banner\nformatter.print_banner(\"AI Agent System\")\n\n# Process a query with progress indication\nformatter.start_progress(\"Processing your query...\")\nresponse = agent.process_query(\"Calculate the factorial of 5 using Python\")\nformatter.stop_progress()\n\n# Get enhanced formatted output\nformatted_response = formatter.format_agent_response(response)\nprint(formatted_response)\n```\n\n### Interactive Mode\n\nRun the enhanced demonstration script in interactive mode:\n\n```bash\ncd ai_agent_system\npython examples/demo.py --interactive\n```\n\n### Demo Mode\n\nRun the full enhanced demonstration:\n\n```bash\ncd ai_agent_system\npython examples/demo.py\n```\n\n### Test Enhanced Output\n\nTest all the enhanced output features:\n\n```bash\ncd ai_agent_system\npython test_enhanced_output.py\n```\n\n## \ud83e\udde0 Memory System\n\nThe agent uses a sophisticated memory system with:\n\n- **Conversational Memory**: Recent interactions stored in memory\n- **Knowledge Base**: Long-term storage using ChromaDB vector database\n- **Semantic Search**: Retrieve relevant information using embeddings\n- **Memory Types**: Interactions, knowledge, and observations\n\n### Memory Operations\n\n```python\n# Store knowledge\nmemory_id = agent.memory_manager.store_knowledge(\n content=\"Python is a programming language\",\n source=\"user_input\"\n)\n\n# Retrieve relevant context\nrelevant_items = agent.memory_manager.retrieve_relevant_context(\n \"Tell me about Python\"\n)\n\n# Get memory statistics\nstats = agent.get_memory_stats()\n```\n\n## \ud83d\udd27 Tool Development\n\nCreate custom tools by extending the `BaseTool` class:\n\n```python\nfrom tools.tool_registry import BaseTool\n\nclass CustomTool(BaseTool):\n def __init__(self):\n super().__init__(\n name=\"custom_tool\",\n description=\"Description of what this tool does\"\n )\n \n def execute(self, query: str, context: Dict[str, Any]) -> Any:\n # Implement tool logic here\n return {\"success\": True, \"result\": \"Tool output\"}\n \n def get_capabilities(self) -> List[str]:\n return [\"custom_capability\"]\n\n# Register the tool\nagent.tool_registry.register_tool(CustomTool())\n```\n\n## \ud83c\udfa8 Enhanced Output Format\n\nThe agent provides beautiful, interactive output with enhanced formatting including:\n\n### Visual Features\n- **Color-coded sections**: Different colors for different types of information\n- **Progress animations**: Animated progress bars and spinners during processing\n- **Beautiful banners**: Eye-catching headers with gradient-like effects\n- **Enhanced typography**: Better text formatting with proper indentation and spacing\n- **Status indicators**: Visual indicators for success, warnings, and errors\n\n### Output Sections\n- **Execution Summary**: Time taken, tools used, reasoning steps with color-coded performance indicators\n- **Reasoning Process**: Step-by-step breakdown with visual hierarchy and timestamps\n- **Tool Output**: Detailed results with success/failure indicators and colorized content\n- **Final Response**: Synthesized answer with enhanced typography\n- **Final Result**: Highlighted box containing the most relevant result\n- **Memory Updates**: Information stored for future reference with bullet points\n\n### Animation Features\n- **Progress bars**: Animated progress indicators during long operations\n- **Spinner animations**: Loading spinners for various operations\n- **Typewriter effect**: Character-by-character text display (configurable)\n- **Real-time updates**: Live updates during agent processing\n\n### Color Support\n- **Automatic detection**: Automatically detects terminal color support\n- **Fallback support**: Graceful degradation when colors are not supported\n- **Environment awareness**: Respects `NO_COLOR` environment variable\n\n## \ud83c\udfaf Example Queries\n\n- `\"Calculate the sum of 25 and 37 using Python\"`\n- `\"Browse to https://example.com and extract the title\"`\n- `\"List all Python files in the current directory\"`\n- `\"Write a short article about machine learning\"`\n- `\"Compare the differences between file1.txt and file2.txt\"`\n- `\"Scrape product information from an e-commerce website\"`\n\n## \ud83d\udd0d Advanced Features\n\n### Memory Export/Import\n\n```python\n# Export memory to JSON\nagent.memory_manager.export_memory(\"memory_backup.json\")\n\n# Clear all memory\nagent.clear_memory()\n```\n\n### Tool Information\n\n```python\n# Get available tools\ntools = agent.tool_registry.get_available_tools()\n\n# Get tool descriptions\ndescriptions = agent.tool_registry.get_tool_descriptions()\n\n# Get tools by capability\nweb_tools = agent.tool_registry.get_tools_by_capability(\"web_navigation\")\n```\n\n### Custom Formatting\n\n```python\nfrom utils.formatter import OutputFormatter\n\nformatter = OutputFormatter()\n\n# Format error messages\nerror_output = formatter.format_error(\"Something went wrong\", context)\n\n# Format memory statistics\nstats_output = formatter.format_memory_stats(agent.get_memory_stats())\n\n# Format tool list\ntools_output = formatter.format_tool_list(agent.tool_registry.get_tool_info())\n```\n\n## \ud83d\udee1\ufe0f Safety and Limitations\n\n- Python code execution has basic safety checks to prevent dangerous operations\n- File operations are limited to prevent accidental deletion\n- Web browsing respects robots.txt and rate limiting\n- Memory storage is local and persistent\n\n## \ud83e\udd1d Contributing\n\nTo add new tools or improve the system:\n\n1. Create new tool classes in the `tools/` directory\n2. Follow the `BaseTool` interface\n3. Register tools in the `ToolRegistry`\n4. Add appropriate tests and documentation\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## \ud83c\udd98 Support\n\nFor issues or questions:\n1. Check the demonstration examples\n2. Review the tool implementations\n3. Examine the memory management system\n4. Test with simple queries first\n\n---\n\n**Built with \u2764\ufe0f by Paul Gedeon**\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive AI agent framework with memory, tool integration, visible reasoning, and enhanced output formatting with colors, animations, and syntax highlighting.",
"version": "1.2.2",
"project_urls": {
"Homepage": "https://github.com/PaulGG-Code/ai_agent_system_complete"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "787503dbaaa17c8186209617a0d0f5fcfa7ea16a87664a6bc5c4cdc495cf6a81",
"md5": "1a9fde2539d3669d7925ca1574a896f6",
"sha256": "f6108c38b1fb4c3f0192720c9d28d89557d198cbf4310a5e83e706811fd2b1e9"
},
"downloads": -1,
"filename": "ai_agent_system-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a9fde2539d3669d7925ca1574a896f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 51015,
"upload_time": "2025-07-21T17:36:02",
"upload_time_iso_8601": "2025-07-21T17:36:02.706014Z",
"url": "https://files.pythonhosted.org/packages/78/75/03dbaaa17c8186209617a0d0f5fcfa7ea16a87664a6bc5c4cdc495cf6a81/ai_agent_system-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d8a02942b563ff109a736ed0cec7fc1819a75c63464dc7383e9b93bf00ffd02e",
"md5": "6cd36df11db14d8289b7f9f9577511d4",
"sha256": "b80e783e93217c70cb0e474464c900faadf22bcb174509a40fc9b8c97685c42b"
},
"downloads": -1,
"filename": "ai_agent_system-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "6cd36df11db14d8289b7f9f9577511d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42688,
"upload_time": "2025-07-21T17:36:04",
"upload_time_iso_8601": "2025-07-21T17:36:04.000264Z",
"url": "https://files.pythonhosted.org/packages/d8/a0/2942b563ff109a736ed0cec7fc1819a75c63464dc7383e9b93bf00ffd02e/ai_agent_system-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 17:36:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PaulGG-Code",
"github_project": "ai_agent_system_complete",
"github_not_found": true,
"lcname": "ai-agent-system"
}
JSON
