Skip to content

Lewis121025/MAX-AI

BranchesTags

Repository files navigation

Max AI Agent 🚀

FastAgent Architecture | <800ms Response Time | Zero-Hallucination Planning

A production-grade intelligent Agent system featuring deterministic planning + parallel execution architecture with 13+ tools and powerful task automation capabilities.

Version Python License

🖼️ Web Interface Preview

Web Interface

📑 Table of Contents

🛠️ Tech Stack

Core Framework

  • Backend: FastAPI - High-performance async web framework
  • Orchestration: LangGraph - State machine for agent workflows
  • AI/NLP: Claude 3.5 Sonnet (via OpenRouter), spaCy
  • Data Processing: Pandas, Pydantic, NumPy
  • Database: SQLite (built-in), Weaviate (optional, for long-term memory)
  • Web Server: Uvicorn with ASGI support

Tools & Libraries

  • Browser Automation: Playwright
  • Image Processing: Pillow
  • PDF Operations: PyPDF2, ReportLab
  • File Processing: python-docx, openpyxl
  • HTTP Client: httpx
  • Vector Database: Weaviate (optional)

External Services

  • LLM: OpenRouter API (Claude 3.5 Sonnet)
  • Search: Tavily API (optional)
  • Code Execution: E2B Sandbox (optional)
  • Web Scraping: Firecrawl API (optional)

✨ Core Features

🎯 FastAgent Architecture

  • Zero-LLM Planner: Lightweight NLP + PDDL scheduler, <120ms task decomposition
  • Single LLM Polish: Only 1 LLM call at the end for natural language generation
  • Zero Hallucination: Fully deterministic planning phase, eliminating hallucination risks
  • Context Memory: Automatic conversation history saving, supports multi-turn dialogues

📊 Performance Metrics

  • Response Speed: <800ms for simple tasks, <5s for complex tasks
  • Cost Optimization: 78% cost reduction per task ($0.015 per task)
  • Reliability: 99%+ success rate, zero planning hallucinations
  • Concurrency: Supports 10+ tools executing in parallel
  • LLM Calls: Only 1 call (80% reduction compared to traditional approaches)

🏗️ Architecture

Architecture Diagram

User Input
    │
    ▼
┌───────────────────┐
│ Zero-LLM Planner  │ (Deterministic NLP)
│   <120ms          │
└───────────────────┘
    │
    ▼
┌───────────────────┐
│ Tool Dispatcher   │ (Rule-based mapping)
└───────────────────┘
    │
    ▼
┌───────────────────┐
│ Parallel Executor │ (LangGraph async flow)
│   10+ tools      │
└───────────────────┘
    │
    ▼
┌───────────────────┐
│ Result Polisher   │ (Single LLM polish)
│   <500ms          │
└───────────────────┘
    │
    ▼
Final Output

Key Innovations

  1. Deterministic by Design: Eliminates LLM-induced hallucinations during planning
  2. Zero-LLM Planner: Fast local NLP drives latency and cost reductions
  3. Parallel Execution Engine: Exploits asyncio and LangGraph for complex workflows

🛠️ System Capabilities

Core Tools (No Additional Setup)

Tool Functionality Status
📁 File Operations Read, write, search files (txt/docx/pdf) ✅ Ready
👁️ AI Vision Analysis Image recognition, OCR, chart analysis ✅ Ready
💾 Database Operations SQL queries (SQLite/PostgreSQL/MySQL) ✅ Ready
📊 Data Analysis Pandas-based data processing (CSV/Excel) ✅ Ready
📄 PDF Operations Extract text, create, merge, get info ✅ Ready
🖼️ Image Processing Resize, crop, rotate, filter, convert ✅ Ready
🔗 HTTP Client REST API requests (GET/POST/PUT/DELETE) ✅ Ready
🔧 Git Operations Clone, commit, push, branch management ⚠️ Requires system Git
⚡ Shell Commands Secure command execution with safety checks ✅ Ready

Requires Additional Setup

Tool Functionality Requirement
🌐 Browser Automation Playwright web automation, screenshots Run playwright install

Requires API Keys

Tool Functionality Requirement
🔍 Intelligent Search Tavily API network search Configure TAVILY_API_KEY
🕷️ Web Scraping Firecrawl web content extraction Configure FIRECRAWL_API_KEY
💻 Code Execution E2B sandbox for secure Python execution Configure E2B_API_KEY

🚀 Quick Start

Prerequisites

  • Python 3.9+
  • Git
  • Windows / Linux / macOS

Installation

# Clone the repository
git clone https://github.com/Lewis121025/MAX-AI.git
cd MAX-AI

# Create virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1  # Windows PowerShell
# or
source .venv/bin/activate    # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers (optional, for browser automation)
playwright install

Configuration

Create a .env file in the project root:

# Required: LLM Inference
OPENROUTER_API_KEY=your_openrouter_key

# Optional: Tool API Keys
TAVILY_API_KEY=your_tavily_key          # Intelligent search
E2B_API_KEY=your_e2b_key                # Code execution
FIRECRAWL_API_KEY=your_firecrawl_key    # Web scraping

# Optional: Weaviate (for long-term memory)
WEAVIATE_URL=http://localhost:8080
WEAVIATE_API_KEY=

API Key Sources:

  • OpenRouter - LLM inference (required)
  • Tavily - Intelligent search (optional)
  • E2B - Code sandbox (optional)
  • Firecrawl - Web scraping (optional)

Verify Configuration

python check_settings.py

Expected output:

✅ OpenRouter: Configured
⚠️ Tavily: Not configured (search tool unavailable)
⚠️ E2B: Not configured (code execution unavailable)

Run

# Start FastAPI service
python start_fastapi.py

Then access:

🐳 Docker Deployment

Quick Start with Docker

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker Compose Services

  • max-ai: Main application service (port 5000)
  • weaviate: Optional vector database for long-term memory (port 8080)

Environment Variables

Set environment variables in .env file or pass them to Docker:

# Using .env file (recommended)
docker-compose up -d

# Or pass environment variables directly
docker-compose up -d -e OPENROUTER_API_KEY=your_key

Build Custom Image

# Build image
docker build -t max-ai:latest .

# Run container
docker run -d \
  -p 5000:5000 \
  -e OPENROUTER_API_KEY=your_key \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/.env:/app/.env:ro \
  --name max-ai \
  max-ai:latest

Production Deployment

For production, use multiple workers:

# Modify Dockerfile CMD or use docker-compose override
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Or run directly with uvicorn:

uvicorn src.fastapi_app:app --host 0.0.0.0 --port 5000 --workers 4

Optional: Weaviate Service

To enable long-term memory with Weaviate:

# Start with Weaviate profile
docker-compose --profile weaviate up -d

📖 Usage Guide

Web Interface

After starting the service, access http://localhost:5000 to use the web interface.

Features:

  • 💬 Real-time streaming conversations
  • 📤 File uploads (images, documents, etc.)
  • 💾 Session history management
  • 🎨 Modern minimalist interface

Usage Examples:

  1. Search Information: "Query weather in Hangzhou" Search Demo

  2. File Analysis: Upload an image and ask "What is this?" Image Analysis

  3. Document Processing: Upload txt/docx files and request "Summarize the content" Document Processing

  4. Code Execution: "Build an LLM API client." Code Execution

Command Line Interface

# Interactive mode
python src/main.py

# Single query
python src/main.py --query "Search latest quantum computing breakthroughs"

# With image analysis
python src/main.py --query "Analyze this image" --image path/to/image.jpg

🗂️ Project Structure

MAX-AI/
├── src/                          # Source code
│   ├── agent/                    # Agent state definitions
│   ├── config/                   # Configuration management
│   ├── orchestrator/             # Orchestrator (FastAgent)
│   │   ├── fast_planner.py       # Zero-LLM planner
│   │   ├── parallel_executor.py  # Parallel executor
│   │   ├── result_polisher.py    # Result polisher
│   │   └── graph.py              # LangGraph orchestration
│   ├── tools/                    # Tool collection (13+)
│   │   ├── registry.py           # Tool registry
│   │   ├── tavily_tool.py        # Intelligent search
│   │   ├── e2b_tool.py           # Code execution
│   │   ├── vision_tool.py        # AI vision analysis
│   │   ├── file_tool.py          # File operations
│   │   └── ...                   # Other tools
│   ├── memory/                   # Memory system
│   │   ├── weaviate_client.py    # Weaviate client
│   │   └── rag_pipeline.py      # RAG retrieval
│   ├── static/                   # Static resources
│   │   ├── css/style.css         # Styles
│   │   └── js/app.js             # Frontend scripts
│   ├── templates/                # HTML templates
│   │   └── index.html            # Main page
│   ├── utils/                    # Utility functions
│   ├── fastapi_app.py            # FastAPI application
│   └── main.py                   # CLI entry point
├── Example/                      # Feature demo screenshots
├── scripts/                      # Utility scripts
├── tests/                        # Test files
├── data/                         # Data directory
│   ├── sessions/                 # Session history
│   └── uploads/                  # Uploaded files
├── .env                          # Environment variables (create this)
├── requirements.txt              # Dependencies
├── Dockerfile                    # Docker image definition
├── docker-compose.yml            # Docker Compose configuration
├── start_fastapi.py              # Startup script
├── check_settings.py             # Configuration checker
└── README.md                     # This file

📚 API Documentation

Detailed REST API documentation: API_DOCUMENTATION.md

Main Endpoints

  • POST /api/chat - Send message (supports streaming response)
  • GET /api/sessions - Get session list
  • GET /api/session_history - Get session history
  • POST /api/save_session - Save session
  • POST /api/delete_session - Delete session
  • GET /health - Health check
  • GET /api/metrics - Performance metrics

🐛 Troubleshooting

Configuration Issues

Q: "OPENROUTER_API_KEY not configured" error

A: Check if .env file exists and contains the correct key:

# Windows
type .env

# Linux/Mac
cat .env

Q: Search/Code execution tools report errors

A: These tools require additional API keys. If not configured, tools return friendly error messages without affecting other functionality.

Functionality Issues

Q: Cannot read files after upload

A: Ensure files are successfully uploaded to data/uploads/ directory and file types are in the allowed list (txt, docx, pdf, jpg, etc.).

Q: Browser automation error "playwright not installed"

A: Execute playwright install to install browser drivers:

playwright install

Q: PDF operations error

A: Ensure dependencies are installed:

pip install PyPDF2 reportlab

These dependencies are usually in requirements.txt. If errors persist, check installation.

Q: Git operations fail

A: Requires system Git installation. Windows users can download from Git website.

Technical Issues

Q: Port already in use

A: Modify port in start_fastapi.py or stop the process using the port:

# Windows
netstat -ano | findstr ":5000"
taskkill /F /PID <process_id>

# Linux/Mac
lsof -ti:5000 | xargs kill

Q: LangSmith warning (403 Forbidden)

A: This is a non-blocking warning and can be ignored. To disable, set in .env:

LANGCHAIN_TRACING_V2=false

Q: Docker container fails to start

A: Check logs:

docker-compose logs max-ai

Ensure .env file exists and contains required API keys.

🛠️ Advanced Features

Weaviate Memory System

Enable long-term memory:

# 1. Start Weaviate (Docker)
docker-compose --profile weaviate up -d

# 2. Configure .env
WEAVIATE_URL=http://localhost:8080

# 3. Initialize Schema
python scripts/ingest_docs.py --init-schema

Custom Tools

Add new tools in src/tools/ and register in registry.py:

# src/tools/my_tool.py
def my_tool(param: str) -> str:
    return f"Processing result: {param}"

# src/tools/registry.py
from tools.my_tool import my_tool
registry.register("my_tool", my_tool, "My tool description")

🧪 Testing

# Run all tests
pytest

# Run specific tests
pytest tests/test_tools.py -v
pytest tests/test_integration.py -v

📋 Development Roadmap

  • ✅ FastAgent architecture implementation
  • ✅ 13+ tool integration
  • ✅ Web interface development
  • ✅ Session history management
  • ✅ File upload support
  • ⏳ Performance optimization
  • ⏳ Additional tool integration

🤝 Contributing

Contributions are welcome! Please feel free to submit Issues and Pull Requests.

📄 License

MIT License

👤 Author

Built with ❤️ using LangGraph + FastAPI + Claude 3.5 Sonnet

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages