🤖 Agent Advisor Platform

AI-powered Python code analysis platform using Crew AI with multiple specialized agents.

🎯 Overview

The Agent Advisor Platform is a modern static code analysis platform for Python that uses multiple AI agents (Crew AI) to provide comprehensive analysis of:

• Code Quality: Detection of code smells, anti-patterns, and PEP8 violations
• Performance: Identification of bottlenecks and optimization suggestions
• Security: Analysis of vulnerabilities (OWASP) and insecure practices
• Documentation: Verification of docstrings, type hints, and comments
• Complexity: Cyclomatic complexity metrics and maintainability index

✨ Key Features

🚀 Real-Time Code Analysis

• Synchronous Analysis: Immediate response for small snippets (<100 lines)
• Asynchronous Analysis: Background processing for large files via Celery
• Multiple Agents: 4 specialized agents working in parallel

📊 Comprehensive Metrics

• AST Analysis: Native Python Abstract Syntax Tree analysis
• Complexity Metrics: Radon for cyclomatic complexity calculation
• Maintainability Index: Maintainability score (0-100)
• Security Scanning: Detection of common vulnerabilities (SQL Injection, XSS, etc.)

🔄 Scalability and Performance

• Multi-Layer Cache: In-memory LRU + Redis + PostgreSQL
• Horizontal Scaling: Celery workers can be scaled independently
• Connection Pooling: SQLAlchemy async pool
• Rate Limiting: Configurable per endpoint

📈 Test Coverage & Metrics

Metric	Value	Description
Overall Coverage	47.88%	207+ comprehensive tests
Unit Tests	113	Fast, isolated tests
Integration Tests	94	API, database, and cache tests
Lines of Code	~5,000	Well-structured Python 3.11+ codebase
Services Coverage	90%+	AST, Complexity, Code Analyzers
Repositories Coverage	85%+	Database operations with JSONB
API Coverage	85%+	39 endpoint tests

🚀 Quick Start (5 minutes)

Prerequisites

• Docker 24+ and Docker Compose 2.20+
• Python 3.11+ (for local development)
• OpenAI API Key

Installation

# 1. Clone the repository
git clone https://github.com/willianpinho/agent-advisor-platform.git
cd agent-advisor-platform

# 2. Configure environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 3. Start all services
docker-compose up -d

# 4. Wait for health checks (1-2 minutes)
docker-compose ps

# 5. Test the API
curl http://localhost:8000/health

Access Services

• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Flower (Celery): http://localhost:5555
• RabbitMQ: http://localhost:15672 (guest/guest)
• PgAdmin: http://localhost:5050 (admin@admin.com/admin)

First Analysis

curl -X POST "http://localhost:8000/api/v1/analysis/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "source_code": "def hello():\n    print(\"Hello World\")",
    "filename": "example.py",
    "analysis_type": "full"
  }'

🏗️ Architecture

The platform follows Clean Architecture principles with Hexagonal Architecture:

┌─────────────────────────────────────────────┐
│         API Layer (FastAPI)                 │
│  /analysis/sync  │  /analysis/async  │ etc │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│        Service Layer                        │
│  CodeAnalyzer → CrewAI Orchestrator         │
│  AST, Complexity, Security Analyzers        │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│      Repository Layer                       │
│  AnalysisRepository (CRUD + Queries)        │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│    Infrastructure Layer                     │
│  PostgreSQL  │  Redis  │  RabbitMQ          │
└─────────────────────────────────────────────┘

Technology Stack

Category	Technologies
Backend	FastAPI 0.109+, Python 3.11+, Uvicorn
Database	PostgreSQL 16, SQLAlchemy 2.0 (async)
Cache & Queue	Redis 7, Celery 5.3, RabbitMQ 3
AI & Analysis	Crew AI 0.11+, OpenAI GPT-4, Radon
Validation	Pydantic V2, Type Hints, MyPy
Testing	pytest, pytest-asyncio, httpx
Infrastructure	Docker, Docker Compose, Poetry

📚 Documentation

Complete documentation is available in VitePress format:

📖 Getting Started

• Getting Started Guide - Installation and setup
• Quick Start - 5-minute guide
• Installation Guide - Detailed installation instructions

🏗️ Architecture & Design

• System Architecture - Detailed architecture design
• Project Structure - Code organization
• Design Patterns - Patterns used

🔧 Development

• Testing Guide - Test suite documentation
• Docker Guide - Docker deployment
• Celery Workers - Background task processing
• Redis Cache - Caching strategies
• Crew AI Integration - AI agent setup

📖 API & Examples

• REST API Reference - Complete API documentation
• Basic Usage Examples - Usage examples

🚀 View Documentation Site

# Install dependencies
npm install

# Start documentation server
npm run docs:dev

# Build documentation
npm run docs:build

# Access at http://localhost:5173

💻 Development

Local Development Setup

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

# Start infrastructure
docker-compose up -d postgres redis rabbitmq

# Run migrations
poetry run alembic upgrade head

# Start API server
poetry run uvicorn src.main:app --reload

# Start Celery worker (in another terminal)
poetry run celery -A src.workers.celery_app worker --loglevel=info

Running Tests

# All tests
poetry run pytest

# With coverage
poetry run pytest --cov=src

# Unit tests only
poetry run pytest tests/unit/

# Integration tests only
poetry run pytest tests/integration/

Code Quality

# Linting
poetry run ruff check .

# Formatting
poetry run black .
poetry run isort .

# Type checking
poetry run mypy src/

📊 Project Structure

agent-advisor-platform/
├── src/
│   ├── api/              # FastAPI routes and dependencies
│   ├── core/             # Configuration and settings
│   ├── domain/           # Models, schemas, enums
│   ├── services/         # Business logic and analyzers
│   ├── repositories/     # Data access layer
│   ├── infrastructure/   # Database, cache, queue
│   ├── workers/          # Celery workers
│   └── main.py           # Application entry point
├── tests/
│   ├── unit/             # Unit tests (113 tests)
│   ├── integration/      # Integration tests (94 tests)
│   └── conftest.py       # Shared fixtures
├── docs/                 # VitePress documentation
├── scripts/              # Utility scripts
├── docker-compose.yml    # Docker orchestration
├── pyproject.toml        # Poetry configuration
└── README.md             # This file

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🔒 Security

• Input validation with Pydantic V2
• SQL injection prevention via SQLAlchemy ORM
• Environment-based secrets management
• CORS configuration
• Rate limiting support

📄 License

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

🙏 Acknowledgments

Built with modern technologies:

• FastAPI - Modern web framework
• Crew AI - Multi-agent orchestration
• SQLAlchemy - Python SQL toolkit
• Celery - Distributed task queue
• PostgreSQL - Advanced database
• Redis - In-memory data store

📞 Support

• Documentation: View Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Developed with ❤️ for the Technical Innovation Challenge