GitHub - nullchimp/ai-agent: This is a PoC implementation of an AI agent (original) (raw)

AI Agent

License: MIT Python Version Code style: black Imports: isort

An advanced AI agent with a modern web interface, capable of performing complex tasks, answering questions, and interacting with various tools and data sources. This project features a comprehensive REST API, session management, debug capabilities, and seamless integration with Large Language Models (LLMs), Retrieval Augmented Generation (RAG), and Model Context Protocol (MCP) servers.

Table of Contents

Features

🎯 Core Capabilities

🌐 Web Interface & API

🔧 Advanced Features

🛡️ Security & Quality

Architecture

The AI Agent features a sophisticated, modular architecture designed for scalability and maintainability:

🏗️ Core Components

🧰 Supporting Infrastructure

🔄 Session Management

For detailed architectural information, see the Project Architecture Document.

Project Structure

The project follows a modular, well-organized structure:

ai-agent/
├── .github/                # GitHub Actions workflows and Copilot configuration
│   ├── prompts/            # Custom prompts for GitHub Copilot
│   └── workflows/          # CI/CD automation workflows
├── config/                 # Configuration files
│   ├── mcp.json            # MCP server configurations
│   ├── mcp-demo.json       # Demo MCP configurations
│   └── mcp.template.json   # Template for MCP setup
├── docs/                   # Comprehensive project documentation
│   ├── ADRs/               # Architecture Decision Records
│   │   ├── frontend-integration.md
│   │   ├── rag-integration.md
│   │   └── rest-api-integration.md
│   ├── architecture.md     # Main architecture overview
│   └── chat.png           # UI screenshot
├── src/                    # Main source code
│   ├── agent.py            # Core agent orchestration logic
│   ├── main.py             # Application entry point (CLI & API modes)
│   ├── api/                # REST API implementation
│   │   ├── app.py          # FastAPI application factory
│   │   ├── auth.py         # API authentication middleware
│   │   ├── models.py       # Pydantic request/response models
│   │   └── routes.py       # API endpoint definitions
│   ├── core/               # Core business logic
│   │   ├── debug_capture.py # Session-based debugging system
│   │   ├── llm/            # LLM client implementations
│   │   │   ├── chat.py     # High-level chat interface
│   │   │   └── client.py   # Azure OpenAI API clients
│   │   ├── mcp/            # Model Context Protocol integration
│   │   │   ├── session.py  # Individual MCP session management
│   │   │   └── sessions_manager.py # Multi-session coordination
│   │   └── rag/            # Retrieval Augmented Generation
│   │       ├── dbhandler/  # Graph database interfaces
│   │       │   ├── __init__.py     # Generic GraphClient
│   │       │   └── memgraph.py     # Memgraph implementation
│   │       ├── embedder/   # Text embedding services
│   │       └── schema.py   # RAG data models and relationships
│   ├── libs/               # Reusable utility libraries
│   │   ├── dataloader/     # Data loading from various sources
│   │   │   ├── document.py # Document processing
│   │   │   └── web.py      # Web scraping and crawling
│   │   ├── fileops.py      # File system operations
│   │   └── search.py       # Search functionality
│   ├── tools/              # Extensible tool system
│   │   ├── __init__.py     # Base tool interface
│   │   ├── google_search.py # Web search capabilities
│   │   ├── read_file.py    # File reading operations
│   │   ├── write_file.py   # File writing operations
│   │   ├── list_files.py   # Directory listing
│   │   └── context7.py     # Context7 API integration
│   └── ui/                 # Modern web interface
│       ├── index.html      # Main HTML structure
│       ├── styles.css      # Responsive CSS styling
│       ├── chat.ts         # TypeScript application logic
│       └── dist/           # Compiled frontend assets
├── tests/                  # Comprehensive test suite
│   ├── test_api_*          # API endpoint tests
│   ├── test_core_*         # Core component tests
│   ├── test_frontend_*     # Frontend integration tests
│   ├── test_tools_*        # Tool functionality tests
│   └── test_ui_*           # User interface tests
├── scripts/                # Utility scripts
│   ├── doc_loader.py       # Document processing scripts
│   ├── url_loader.py       # Web content loader
│   └── loader_config.py    # Configuration for data loaders
├── examples/               # Usage examples and demos
│   ├── 1-chat.py           # Basic chat example
│   ├── 2-tool.py           # Tool usage example
│   ├── 3-chat-with-tools.py # Combined chat and tools
│   ├── 4-chat-with-tools-and-mcp.py # Full MCP integration
│   ├── 5-memgraph.py       # RAG/Memgraph example
│   └── 6-embeddings.py     # Embedding generation example
├── .env                    # Environment variables (not in repo)
├── requirements.txt        # Python dependencies
├── package.json            # Node.js dependencies for frontend
├── tsconfig.json           # TypeScript configuration
└── pyproject.toml          # Python project configuration

Setup and Installation

  1. Clone the repository:
    git clone https://github.com/nullchimp/ai-agent.git
    cd ai-agent
  2. Create and activate a virtual environment:
    python3 -m venv .venv
    source .venv/bin/activate # On Windows: .venv\Scripts\activate
  3. Install dependencies:
    pip install -r requirements.txt
  4. **Set up environment variables:**Copy .env.example to .env and fill in the required API keys and configurations (e.g., OPENAI_API_KEY, MEMGRAPH_HOST).
    cp .env.example .env

Edit .env with your credentials

  1. Ensure Memgraph is running (if using the RAG features with Memgraph). Refer to the Memgraph documentation for setup instructions.

Usage

The AI Agent supports multiple interaction modes to accommodate different use cases and deployment scenarios.

🖥️ CLI Mode (Command Line Interface)

For direct terminal interaction with the agent:

This mode provides a simple command-line chat interface for testing and development.

The agent includes a modern, ChatGPT-like web interface for the best user experience.

Building the Frontend

First, build the frontend assets (required for web interface):

npm install npm run ui:build

Starting the Web Server

Run the agent with the integrated web server:

The application will be available at http://localhost:5555 (or your configured host/port).

🎯 Web Interface Features

AI Agent Chat Interface

The web interface provides a rich, interactive experience:

💬 Chat Experience

🗂️ Session Management

🔧 Tool Configuration

🐛 Advanced Debugging

⚡ Performance Features

User Interface

The AI Agent features a modern, ChatGPT-inspired web interface that provides an intuitive and powerful user experience.

🎨 Design & User Experience

Modern Interface Design

Chat Experience

📱 Responsive Design

The interface is fully responsive and works seamlessly across:

🎛️ Interactive Controls

Session Management

Tool Configuration Panel

Advanced Debug Panel

⚡ Performance & Accessibility

Fast & Efficient

Accessible Design

Configuration

The AI Agent uses a flexible configuration system supporting environment variables, JSON configuration files, and runtime settings.

🔐 Environment Variables (.env)

Create a .env file in the project root with the following configuration:

Azure OpenAI Configuration

AZURE_OPENAI_API_KEY=your_azure_openai_api_key AZURE_OPENAI_CHAT_MODEL=gpt-4 AZURE_OPENAI_CHAT_ENDPOINT=https://your-resource.openai.azure.com/openai/deployments/gpt-4/chat/completions?api-version=2024-02-15-preview AZURE_OPENAI_EMBEDDINGS_MODEL=text-embedding-3-small
AZURE_OPENAI_EMBEDDINGS_ENDPOINT=https://your-resource.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-02-15-preview

API Server Configuration

API_KEY=your_secure_api_key_here API_HOST=localhost API_PORT=5555

Memgraph Database Configuration (for RAG features)

MEMGRAPH_URI=localhost MEMGRAPH_PORT=7687 MEMGRAPH_USERNAME=memgraph MEMGRAPH_PASSWORD=memgraph

Google Search Configuration (optional)

GOOGLE_API_KEY=your_google_api_key GOOGLE_CSE_ID=your_custom_search_engine_id

Context7 API Configuration (optional)

CONTEXT7_API_KEY=your_context7_api_key

🔧 MCP Configuration (config/mcp.json)

Configure external Model Context Protocol servers and tools:

{ "servers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"], "env": { "NODE_ENV": "production" } }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token" } }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:password@localhost/dbname"] } } }

⚙️ Advanced Configuration Options

Debug Configuration

RAG System Configuration

Tool Configuration

Session Configuration

Tools & Integrations

The AI Agent features an extensible tool system that enables interaction with various external services and data sources.

🧰 Built-in Tools

Core Tools

Specialized Integrations

🔗 Model Context Protocol (MCP) Support

The agent seamlessly integrates with MCP-compatible external services:

Supported MCP Servers

MCP Features

🛠️ Tool Development

Creating Custom Tools

Tools are located in the src/tools/ directory. Create new tools by implementing the Tool interface:

from tools import Tool

class MyCustomTool(Tool): def init(self, name: str): super().init(name, "Description of what this tool does")

async def execute(self, **kwargs):
    # Tool implementation
    return result

Tool Configuration

Tool Discovery

RAG (Retrieval Augmented Generation)

The AI Agent includes a sophisticated RAG system that enhances responses with relevant information from a knowledge graph and vector embeddings.

🧠 Knowledge Graph Architecture

Memgraph Integration

Data Schema

The RAG system uses a comprehensive graph schema:

🔍 Embedding & Search

Text Embedding

📚 Data Loading & Processing

Supported Data Sources

Processing Pipeline

⚙️ Configuration & Customization

RAG Configuration

Vector store configuration

VECTOR_STORE_CONFIG = { "model": "text-embedding-3-small", "dimension": 1536, "capacity": 1000000, "metric": "cosine" }

Retrieval settings

RETRIEVAL_CONFIG = { "max_chunks": 5, "similarity_threshold": 0.8, "context_window": 4000 }

Data Loader Scripts

Contributing

We welcome contributions to the AI Agent project! Please follow these guidelines to ensure a smooth collaboration process.

🤝 How to Contribute

  1. Fork the repository and create your feature branch:
    git checkout -b feature/your-feature-name
  2. Set up your development environment:
    python3 -m venv .venv
    source .venv/bin/activate # On Windows: .venv\Scripts\activate
    pip install -r requirements.txt
    npm install # For frontend development
  3. Make your changes following our coding standards and architecture patterns.
  4. Run the full test suite to ensure your changes don't break existing functionality:
    pytest --cov=src tests/
    npm run ui:test # Frontend tests
  5. Ensure code quality by running our linting and formatting tools:
    black src tests
    isort src tests
    pylint src tests
    mypy src
  6. Commit your changes with descriptive commit messages:
    git commit -m 'Add comprehensive session management with debug isolation'
  7. Push to your branch and create a Pull Request:
    git push origin feature/your-feature-name

📋 Development Guidelines

Code Quality Standards

Architecture Principles

Testing Requirements

🎯 Priority Areas for Contribution

High Priority

Medium Priority

Nice to Have

🐛 Reporting Issues

When reporting bugs or requesting features:

  1. Search existing issues to avoid duplicates
  2. Use our issue templates for consistent reporting
  3. Provide detailed information including:
    • Steps to reproduce the issue
    • Expected vs actual behavior
    • Environment details (OS, Python version, etc.)
    • Debug logs and error messages
    • Screenshots for UI issues

📖 Development Resources

License

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

API Documentation

The AI Agent provides a comprehensive REST API built with FastAPI, featuring automatic OpenAPI documentation and robust session management.

🔌 Core API Endpoints

Session Management

Chat & Interaction

Debug & Monitoring

🔐 Authentication

API endpoints (except session creation) require authentication via API key:

curl -H "X-API-Key: your_secure_api_key_here" http://localhost:5555/api/{session_id}/ask

Configure your API key in the .env file:

API_KEY=your_secure_api_key_here

📊 Session Isolation

Each session maintains:

🔧 Interactive API Documentation

When running in API mode, visit http://localhost:5555/docs for:

Debug & Monitoring

The AI Agent includes a comprehensive debugging and monitoring system designed for development, troubleshooting, and performance analysis.

🐛 Per-Session Debug System

Session Isolation

Event Capture

📊 Debug Panel Features

Real-time Visualization

Event Management

🎛️ Debug Controls

Session-Level Controls

Developer Tools

📈 Performance Monitoring

Metrics Collection

Performance Analysis

🔧 Configuration & Customization

Debug Configuration

Debug system settings

DEBUG_CONFIG = { "max_events_per_session": 1000, "event_retention_hours": 24, "auto_enable_on_panel_open": True, "capture_sensitive_data": False }

Integration Examples

Custom debug event capture

from core.debug_capture import get_debug_capture_instance

debug_capture = get_debug_capture_instance(session_id) debug_capture.capture_event( event_type="custom_operation", message="Custom operation completed", data={"operation": "data_processing", "duration": 1.5} )