Deploy from GitHub commit 1b2eb65

.env.example

@@ -0,0 +1,40 @@
+# LLM Provider Configuration
+# Choose: "openai" or "groq"
+LLM_PROVIDER=openai
+
+# OpenAI Configuration
+OPENAI_API_KEY=sk-your-openai-api-key-here
+OPENAI_MODEL=gpt-4o-mini
+
+# Groq Configuration (optional, alternative to OpenAI)
+GROQ_API_KEY=gsk_your-groq-api-key-here
+GROQ_MODEL=llama-3.3-70b-versatile
+
+# API Authentication
+REVIEW_API_KEY=your-secure-api-key-here
+
+# Rate Limiting
+RATE_LIMIT_PER_MINUTE=10
+
+# Ray Serve Configuration
+ENABLE_RAY_SERVE=false
+RAY_SERVE_HOST=0.0.0.0
+RAY_SERVE_PORT=8000
+RAY_NUM_REPLICAS=2
+RAY_MAX_CONCURRENT_QUERIES=10
+
+# Guardrails Configuration
+MAX_FINDINGS_PER_REVIEW=20
+MAX_TOKENS_PER_REVIEW=15000
+ENABLE_LLM_JUDGE_GUARDRAILS=true
+
+# Application Settings
+LOG_LEVEL=INFO
+REQUEST_TIMEOUT_SECONDS=120
+MAX_DIFF_SIZE_BYTES=1048576
+
+# CORS Settings (comma-separated origins)
+CORS_ORIGINS=*
+
+# Debug Mode
+DEBUG=false

.spacesignore

@@ -0,0 +1,69 @@
+# Exclude files not needed in Hugging Face Space
+# This reduces upload time and space size
+
+# Development files
+tests/
+.pytest_cache/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# CI/CD
+.github/
+.git/
+.gitignore
+
+# Documentation
+DEPLOYMENT.md
+README.md
+docs/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+.env.*.local
+venv/
+env/
+ENV/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+wheels/
+
+# Logs
+logs/
+*.log
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Ray (not used in HF deployment)
+/tmp/ray/
+
+# MacOS
+.DS_Store
+
+# Scripts and tools
+scripts/
+run_e2e_tests.sh
+verify_deployment.py
+
+# Original Dockerfile (use Dockerfile.hf instead)
+Dockerfile
+
+# Large test fixtures
+tests/fixtures/*.pdf
+tests/fixtures/*.mp4

Dockerfile

@@ -0,0 +1,56 @@
+# Optimized Dockerfile for Hugging Face Spaces Free Tier
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy dependency files first (for layer caching)
+COPY pyproject.toml ./
+
+# Install Python dependencies (minimal for HF free tier)
+# Exclude Ray Serve and heavy dependencies to reduce image size
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+    fastapi==0.124.0 \
+    uvicorn==0.38.0 \
+    pydantic==2.11.10 \
+    pydantic-settings==2.10.1 \
+    python-dotenv==1.1.1 \
+    httpx==0.27.0 \
+    python-multipart==0.0.20 \
+    pyyaml==6.0.1 \
+    tiktoken==0.9.0 \
+    openai==1.83.0 \
+    crewai==1.7.0 \
+    crewai-tools==1.7.0
+
+# Copy application code
+COPY app ./app
+
+# Create necessary directories
+RUN mkdir -p /app/logs
+
+# Set environment variables for HF optimization
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    LOG_LEVEL=INFO \
+    ENABLE_RAY_SERVE=false \
+    RATE_LIMIT_PER_MINUTE=5 \
+    REQUEST_TIMEOUT_SECONDS=90 \
+    MAX_FINDINGS_PER_REVIEW=15
+
+# Expose port 7860 (required by Hugging Face)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Run the application
+CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Code Reviewer CI Agent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

QUICKSTART_HF.md

@@ -0,0 +1,69 @@
+# 🚀 Quick Start: Deploy to Hugging Face
+
+Follow these steps to deploy your Code Reviewer CI Agent to Hugging Face Spaces for FREE!
+
+## Prerequisites
+
+- GitHub account with this repository
+- Hugging Face account (sign up at https://huggingface.co)
+- LLM API key (Groq or OpenAI)
+
+## Setup Steps
+
+### 1. Create Hugging Face Token
+
+1. Go to https://huggingface.co/settings/tokens
+2. Click "New token" → Name: `github-deployment` → Type: **Write**
+3. Copy the token
+
+### 2. Create Hugging Face Space
+
+1. Go to https://huggingface.co/new-space
+2. Space name: `code-reviewer-ci`
+3. SDK: **Docker**
+4. Create Space
+
+### 3. Add GitHub Secrets
+
+Go to: **GitHub Repository → Settings → Secrets → Actions**
+
+Add 3 secrets:
+- `HF_TOKEN` = your token from step 1
+- `HF_USERNAME` = your HF username  
+- `HF_SPACE_NAME` = `code-reviewer-ci`
+
+### 4. Configure HF Space
+
+Go to: **Your HF Space → Settings → Variables**
+
+Add variables:
+- `LLM_PROVIDER` = `groq`
+- `REVIEW_API_KEY` = `(random secure string)`
+- `GROQ_API_KEY` = `gsk_your_groq_key`
+
+### 5. Deploy!
+
+```bash
+git add .
+git commit -m "Deploy to Hugging Face"
+git push origin main
+```
+
+✅ **Done!** GitHub Actions will automatically deploy to HF.
+
+## Verify Deployment
+
+```bash
+# Health check
+curl https://YOUR-USERNAME-YOUR-SPACE.hf.space/health
+```
+
+## Full Documentation
+
+- **Detailed setup:** [DEPLOYMENT.md](./DEPLOYMENT.md)
+- **Troubleshooting:** See DEPLOYMENT.md#troubleshooting
+- **Setup wizard:** Run `./scripts/setup_hf_deployment.sh`
+
+---
+
+**Need help?** See [DEPLOYMENT.md](./DEPLOYMENT.md) for complete instructions.

README.md

@@ -1,11 +1,165 @@
 ---
-title: Code Reviewer Ci
-emoji: 🏆
-colorFrom: yellow
-colorTo: red
+title: Code Reviewer CI Agent
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: docker
-pinned: false
-short_description: a code reviewer ai agent
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 AI Code Reviewer Agent
+
+**Production-ready AI-powered code review using CrewAI multi-agent framework**
+
+Automatically review code changes with specialized AI agents analyzing security, performance, code quality, and maintainability.
+
+## 🚀 Quick Start
+
+### API Endpoints
+
+#### Health Check
+```bash
+curl https://YOUR-USERNAME-YOUR-SPACE.hf.space/health
+```
+
+#### Code Review
+```bash
+curl -X POST https://YOUR-USERNAME-YOUR-SPACE.hf.space/review \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "diff": "diff --git a/app.py b/app.py\n+def login(user, pwd):\n+    query = f\"SELECT * FROM users WHERE user='\''{user}'\''\"",
+    "language": "python",
+    "context": {
+      "repo": "myorg/myrepo",
+      "pr_number": 123
+    }
+  }'
+```
+
+## 📊 Multi-Agent Architecture
+
+This system uses **5 specialized AI agents** working in parallel:
+
+| Agent | Role | Focus |
+|-------|------|-------|
+| 🔍 **Code Analyzer** | Senior Engineer | Logic, complexity, architecture |
+| 🔒 **Security Reviewer** | AppSec Engineer | Vulnerabilities, injection attacks |
+| ⚡ **Performance Reviewer** | Performance Engineer | N+1 queries, algorithmic complexity |
+| ✨ **Style Reviewer** | Staff Engineer | Naming, maintainability, SOLID |
+| 📝 **Review Synthesizer** | Tech Lead | Prioritization, final report |
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+**Required** (set in Space Settings → Variables):
+
+- `LLM_PROVIDER` - `openai` or `groq`
+- `OPENAI_API_KEY` or `GROQ_API_KEY` - Your LLM API key
+- `REVIEW_API_KEY` - API key for authenticating requests
+
+**Optional:**
+
+- `RATE_LIMIT_PER_MINUTE` - Max requests per minute (default: 5)
+- `REQUEST_TIMEOUT_SECONDS` - Review timeout (default: 90)
+- `MAX_FINDINGS_PER_REVIEW` - Max findings to return (default: 15)
+
+### Recommended LLM Configuration
+
+**For Free Tier:**
+```bash
+LLM_PROVIDER=groq
+GROQ_API_KEY=gsk_your_key_here
+GROQ_MODEL=llama-3.3-70b-versatile
+```
+
+**For Production:**
+```bash
+LLM_PROVIDER=openai
+OPENAI_API_KEY=sk_your_key_here
+OPENAI_MODEL=gpt-4o-mini
+```
+
+## 📝 API Response Format
+
+```json
+{
+  "summary": "Found 2 security issues and 1 performance concern",
+  "score": 7.5,
+  "findings": [
+    {
+      "category": "security",
+      "severity": "high",
+      "file": "app/auth.py",
+      "line": 24,
+      "message": "SQL injection vulnerability detected",
+      "suggestion": "Use parameterized queries instead of string interpolation"
+    }
+  ],
+  "metadata": {
+    "execution_time_ms": 15234,
+    "tokens_used": 12453,
+    "agent_count": 5,
+    "model": "gpt-4o-mini"
+  }
+}
+```
+
+## 🔧 GitHub Integration
+
+Integrate with your CI/CD pipeline:
+
+```yaml
+# .github/workflows/code-review.yml
+- name: AI Code Review
+  run: |
+    curl -X POST https://YOUR-SPACE.hf.space/review \
+      -H "Authorization: Bearer ${{ secrets.REVIEW_API_KEY }}" \
+      -d @review_request.json
+```
+
+## 📈 Performance
+
+| Metric | Value |
+|--------|-------|
+| Avg review time | 15-45 seconds |
+| Max diff size | 1 MB |
+| Token usage | ~10K per review |
+| Cost per review | $0.002 - $0.15 |
+
+## ⚠️ Limitations on Free Tier
+
+- **Single worker**: Can handle 1 request at a time
+- **Cold starts**: First request after sleep takes ~60 seconds
+- **Resource limits**: 2 vCPU, 16GB RAM
+- **Timeouts**: Long reviews may timeout (increase `REQUEST_TIMEOUT_SECONDS`)
+
+## 🔒 Security
+
+- API key authentication required for `/review` endpoint
+- Rate limiting prevents abuse
+- No data persistence (stateless reviews)
+- Secrets managed via HF Space settings
+
+## 📚 Documentation
+
+Full documentation: [GitHub Repository](https://github.com/YOUR-USERNAME/code-reviewer-ci-agent)
+
+## 💡 Tips
+
+1. **Use Groq for free tier** - Faster and free API calls
+2. **Keep diffs small** - Large changes may timeout
+3. **Set rate limits** - Prevent quota exhaustion
+4. **Monitor usage** - Track LLM API costs
+
+## 🙏 Credits
+
+Built with:
+- [CrewAI](https://www.crewai.com/) - Multi-agent orchestration
+- [FastAPI](https://fastapi.tiangolo.com/) - API framework
+- [OpenAI](https://openai.com/) / [Groq](https://groq.com/) - LLM providers
+
+---
+
+**Made with ❤️ for better code reviews**

app/__init__.py

@@ -0,0 +1,3 @@
+"""Code Reviewer CI Agent - AI-powered code review using CrewAI."""
+
+__version__ = "0.1.0"

app/api.py

@@ -0,0 +1,301 @@
+"""FastAPI gateway for code review service."""
+
+import logging
+import os
+import time
+from contextlib import asynccontextmanager
+from typing import Annotated, Optional
+
+from fastapi import Depends, FastAPI, HTTPException, Request, Security, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from fastapi.responses import JSONResponse
+
+from app import __version__
+from app.config import config
+# Lazy import: get_crew imported after env cleanup in lifespan
+from app.guardrails import get_guardrail_orchestrator
+from app.schemas import HealthResponse, ReviewRequest, ReviewResponse
+from app.utils import generate_request_id, sanitize_diff
+
+# Configure logging
+config.configure_logging()
+logger = logging.getLogger(__name__)
+
+# Security
+security = HTTPBearer()
+
+# Rate limiting (simple in-memory store for MVP)
+request_timestamps: dict[str, list[float]] = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    logger.info("Starting Code Reviewer CI Agent API")
+    logger.info(f"Version: {__version__}")
+    logger.info(f"LLM Provider: {config.llm_provider}")
+    logger.info(f"LLM Model: {config.llm_model}")
+    logger.info(f"Ray Serve Enabled: {config.enable_ray_serve}")
+
+    # CRITICAL: Clean up unused LLM provider API keys BEFORE importing crew
+    # CrewAI reads environment variables directly, must remove wrong ones early
+    if config.llm_provider == "groq":
+        # Set dummy OPENAI_API_KEY to prevent CrewAI errors (it checks even when not used)
+        os.environ["OPENAI_API_KEY"] = "sk-dummy-key-not-used"
+        logger.info("✓ Set dummy OPENAI_API_KEY (using Groq - OpenAI not used)")
+    elif config.llm_provider == "openai":
+        os.environ.pop("GROQ_API_KEY", None)
+        logger.info("✓ Removed GROQ_API_KEY from environment (using OpenAI)")
+
+    # Initialize crew (warm up) - import here after env cleanup
+    try:
+        from app.crew.crew import get_crew
+        get_crew()
+        logger.info("Code review crew initialized successfully")
+    except Exception as e:
+        logger.error(f"Failed to initialize crew: {e}")
+
+    yield
+
+    logger.info("Shutting down Code Reviewer CI Agent API")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Code Reviewer CI Agent",
+    description="AI-powered code review using CrewAI multi-agent framework",
+    version=__version__,
+    lifespan=lifespan,
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Middleware for request logging
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    """Log all requests with timing."""
+    request_id = generate_request_id()
+    start_time = time.time()
+
+    # Add request ID to state
+    request.state.request_id = request_id
+
+    logger.info(
+        f"[{request_id}] {request.method} {request.url.path} - "
+        f"Client: {request.client.host if request.client else 'unknown'}"
+    )
+
+    response = await call_next(request)
+
+    duration_ms = int((time.time() - start_time) * 1000)
+    logger.info(
+        f"[{request_id}] Completed in {duration_ms}ms - Status: {response.status_code}"
+    )
+
+    return response
+
+
+def verify_api_key(
+    credentials: Optional[HTTPAuthorizationCredentials] = Security(security)
+) -> str:
+    """Verify API key from Authorization header.
+    
+    If review_api_key is empty (demo mode), authentication is disabled.
+    """
+    # Skip authentication if API key is not configured (demo mode)
+    if not config.review_api_key:
+        logger.warning("⚠️  Authentication disabled - review_api_key not configured (DEMO MODE)")
+        return "demo-mode"
+    
+    if not credentials:
+        logger.warning("Missing authorization header")
+        raise HTTPException(
+            status_code=401,
+            detail="Missing authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if credentials.credentials != config.review_api_key:
+        # Log first 10 chars only for security
+        logger.warning(f"Invalid API key attempt: {credentials.credentials[:10]}...")
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return credentials.credentials
+
+
+def check_rate_limit(api_key: str) -> None:
+    """
+    Check rate limit for API key.
+
+    Args:
+        api_key: API key to check
+
+    Raises:
+        HTTPException: If rate limit exceeded
+    """
+    current_time = time.time()
+    minute_ago = current_time - 60
+
+    # Clean up old timestamps
+    if api_key in request_timestamps:
+        request_timestamps[api_key] = [
+            ts for ts in request_timestamps[api_key] if ts > minute_ago
+        ]
+    else:
+        request_timestamps[api_key] = []
+
+    # Check limit
+    if len(request_timestamps[api_key]) >= config.rate_limit_per_minute:
+        logger.warning(f"Rate limit exceeded for API key: {api_key[:10]}...")
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail=f"Rate limit exceeded. Maximum {config.rate_limit_per_minute} requests per minute.",
+        )
+
+    # Add current request
+    request_timestamps[api_key].append(current_time)
+
+
+@app.get("/health", response_model=HealthResponse, tags=["Health"])
+async def health_check() -> HealthResponse:
+    """
+    Health check endpoint.
+
+    Returns:
+        Health status information
+    """
+    return HealthResponse(
+        status="healthy",
+        version=__version__,
+        ray_serve_enabled=config.enable_ray_serve,
+        llm_provider=config.llm_provider,
+    )
+
+
+@app.post("/review", response_model=ReviewResponse, tags=["Review"])
+async def review_code(
+    request: ReviewRequest,
+    api_key: Annotated[str, Depends(verify_api_key)],
+) -> ReviewResponse:
+    """
+    Review code changes using AI agents.
+
+    Args:
+        request: Review request with diff and context
+        api_key: API key for authentication
+
+    Returns:
+        Structured review response with findings and summary
+
+    Raises:
+        HTTPException: If review fails or timeout occurs
+    """
+    # Check rate limit
+    check_rate_limit(api_key)
+
+    logger.info(f"Received review request for {request.language} code")
+
+    try:
+        # Sanitize diff
+        sanitized_diff = sanitize_diff(request.diff)
+        request.diff = sanitized_diff
+
+        # Get crew and execute review (lazy import)
+        from app.crew.crew import get_crew
+        crew = get_crew()
+
+        # Execute with timeout
+        import asyncio
+        from concurrent.futures import TimeoutError
+
+        try:
+            # Run crew in thread pool to avoid blocking
+            loop = asyncio.get_event_loop()
+            response = await asyncio.wait_for(
+                loop.run_in_executor(None, crew.review_code, request),
+                timeout=config.request_timeout_seconds,
+            )
+        except asyncio.TimeoutError:
+            logger.error("Review timed out")
+            raise HTTPException(
+                status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+                detail=f"Review timed out after {config.request_timeout_seconds} seconds",
+            )
+
+        # Apply guardrails
+        orchestrator = get_guardrail_orchestrator()
+        response = orchestrator.apply(
+            response,
+            context={
+                "diff": request.diff,
+                "language": request.language,
+            },
+        )
+
+        logger.info(
+            f"Review completed successfully: {len(response.findings)} findings, "
+            f"score: {response.score:.1f}"
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during code review: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Code review failed: {str(e)}",
+        )
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    """Handle HTTP exceptions with structured error responses."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": exc.detail,
+            "status_code": exc.status_code,
+            "request_id": getattr(request.state, "request_id", "unknown"),
+        },
+    )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request: Request, exc: Exception):
+    """Handle unexpected exceptions."""
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "Internal server error",
+            "status_code": 500,
+            "request_id": getattr(request.state, "request_id", "unknown"),
+        },
+    )
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "app.api:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=config.debug,
+        log_level=config.log_level.lower(),
+    )

app/config.py

@@ -0,0 +1,169 @@
+"""Application configuration using Pydantic Settings."""
+
+import logging
+import os
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def is_huggingface_space() -> bool:
+    """Detect if running in Hugging Face Spaces environment."""
+    return os.getenv("SPACE_ID") is not None or os.getenv("SPACE_REPO_NAME") is not None
+
+
+class AppConfig(BaseSettings):
+    """Application configuration loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # LLM Provider Configuration
+    llm_provider: Literal["openai", "groq"] = Field(
+        "openai", description="LLM provider to use"
+    )
+    openai_api_key: str = Field("", description="OpenAI API key")
+    openai_model: str = Field("gpt-4o-mini", description="OpenAI model to use")
+    groq_api_key: str = Field("", description="Groq API key")
+    groq_model: str = Field("llama-3.3-70b-versatile", description="Groq model to use")
+
+    # API Authentication
+    review_api_key: str = Field(
+        "", 
+        description="API key for authentication. Leave empty to disable authentication (not recommended for production)"
+    )
+
+    # Rate Limiting
+    rate_limit_per_minute: int = Field(10, ge=1, le=100, description="Max requests per minute")
+
+    # Ray Serve Configuration
+    enable_ray_serve: bool = Field(False, description="Enable Ray Serve deployment")
+    ray_serve_host: str = Field("0.0.0.0", description="Ray Serve host")
+    ray_serve_port: int = Field(8000, ge=1024, le=65535, description="Ray Serve port")
+    ray_num_replicas: int = Field(2, ge=1, le=10, description="Number of Ray replicas")
+    ray_max_concurrent_queries: int = Field(
+        10, ge=1, le=100, description="Max concurrent queries per replica"
+    )
+
+    # Guardrails Configuration
+    max_findings_per_review: int = Field(
+        20, ge=1, le=100, description="Maximum findings to return"
+    )
+    max_tokens_per_review: int = Field(
+        15000, ge=1000, le=100000, description="Maximum tokens per review"
+    )
+    enable_llm_judge_guardrails: bool = Field(
+        True, description="Enable LLM-as-Judge guardrails"
+    )
+
+    # Application Settings
+    log_level: str = Field("INFO", description="Logging level")
+    request_timeout_seconds: int = Field(
+        120, ge=30, le=300, description="Request timeout in seconds"
+    )
+    max_diff_size_bytes: int = Field(
+        1_048_576, ge=1024, le=10_485_760, description="Max diff size in bytes"
+    )
+
+    # CORS Settings
+    cors_origins: str = Field("*", description="Comma-separated CORS origins")
+
+    # Debug Mode
+    debug: bool = Field(False, description="Enable debug mode")
+
+    @field_validator("llm_provider")
+    @classmethod
+    def validate_llm_provider(cls, v: str) -> str:
+        """Validate LLM provider is supported."""
+        if v not in ["openai", "groq"]:
+            raise ValueError(f"Unsupported LLM provider: {v}")
+        return v
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Validate log level."""
+        valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        v_upper = v.upper()
+        if v_upper not in valid_levels:
+            raise ValueError(f"Invalid log level: {v}. Must be one of {valid_levels}")
+        return v_upper
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        """Parse CORS origins into a list."""
+        if self.cors_origins == "*":
+            return ["*"]
+        return [origin.strip() for origin in self.cors_origins.split(",") if origin.strip()]
+
+    @property
+    def llm_api_key(self) -> str:
+        """Get API key for the active LLM provider."""
+        if self.llm_provider == "openai":
+            if not self.openai_api_key:
+                raise ValueError("OpenAI API key not configured")
+            return self.openai_api_key
+        elif self.llm_provider == "groq":
+            if not self.groq_api_key:
+                raise ValueError("Groq API key not configured")
+            return self.groq_api_key
+        raise ValueError(f"Unknown LLM provider: {self.llm_provider}")
+
+    @property
+    def llm_model(self) -> str:
+        """Get model name for the active LLM provider."""
+        if self.llm_provider == "openai":
+            return self.openai_model
+        elif self.llm_provider == "groq":
+            return self.groq_model
+        raise ValueError(f"Unknown LLM provider: {self.llm_provider}")
+
+    def optimize_for_huggingface(self) -> None:
+        """Automatically optimize settings for Hugging Face Spaces free tier."""
+        if not is_huggingface_space():
+            return
+        
+        logger = logging.getLogger(__name__)
+        logger.info("🤗 Detected Hugging Face Spaces environment - optimizing configuration")
+        
+        # Disable Ray Serve (not suitable for free tier)
+        if self.enable_ray_serve:
+            logger.warning("Disabling Ray Serve for HF free tier")
+            self.enable_ray_serve = False
+        
+        # Lower rate limits for free tier
+        if self.rate_limit_per_minute > 5:
+            logger.info(f"Adjusting rate limit from {self.rate_limit_per_minute} to 5 for HF free tier")
+            self.rate_limit_per_minute = 5
+        
+        # Shorter timeout to prevent resource exhaustion
+        if self.request_timeout_seconds > 90:
+            logger.info(f"Adjusting timeout from {self.request_timeout_seconds} to 90s for HF free tier")
+            self.request_timeout_seconds = 90
+        
+        # Reduce max findings to save tokens
+        if self.max_findings_per_review > 15:
+            logger.info(f"Adjusting max findings from {self.max_findings_per_review} to 15 for HF free tier")
+            self.max_findings_per_review = 15
+        
+        logger.info("✅ Configuration optimized for Hugging Face Spaces")
+
+    def configure_logging(self) -> None:
+        """Configure application logging."""
+        logging.basicConfig(
+            level=getattr(logging, self.log_level),
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+
+# Global config instance
+config = AppConfig()
+
+# Auto-optimize for Hugging Face if detected
+config.optimize_for_huggingface()

app/crew/__init__.py

@@ -0,0 +1,5 @@
+"""CrewAI orchestration for code review agents."""
+
+from app.crew.crew import CodeReviewCrew
+
+__all__ = ["CodeReviewCrew"]

app/crew/agents.yaml

@@ -0,0 +1,85 @@
+code_analyzer:
+  role: >
+    Senior Software Engineer
+  goal: >
+    Analyze code structure, identify complexity patterns, architectural issues,
+    and logical flaws in the provided code diff
+  backstory: >
+    You are a seasoned software engineer with 15+ years of experience across
+    multiple programming languages and paradigms. You have a deep understanding
+    of software architecture, design patterns, and code organization. You excel
+    at quickly understanding code structure and identifying potential issues
+    in logic flow, complexity, and maintainability. You focus on the "what"
+    and "why" of code, not just the "how".
+  verbose: true
+  allow_delegation: false
+  max_iter: 3
+
+security_reviewer:
+  role: >
+    Application Security Engineer
+  goal: >
+    Identify security vulnerabilities, potential attack vectors, and unsafe
+    coding practices in the code diff
+  backstory: >
+    You are an OWASP expert and certified penetration tester with extensive
+    experience in application security. You've discovered critical vulnerabilities
+    in production systems and understand both common and exotic attack patterns.
+    You are particularly skilled at identifying SQL injection, XSS, CSRF,
+    authentication/authorization flaws, cryptographic issues, secrets leakage,
+    unsafe deserialization, and input validation problems. You think like an
+    attacker to find security flaws before they can be exploited.
+  verbose: true
+  allow_delegation: false
+  max_iter: 3
+
+performance_reviewer:
+  role: >
+    Performance Engineering Specialist
+  goal: >
+    Detect performance bottlenecks, inefficient algorithms, and resource
+    management issues in the code diff
+  backstory: >
+    You are a performance optimization expert who has tuned systems handling
+    millions of requests per second. You understand algorithmic complexity,
+    database query optimization, caching strategies, and resource management.
+    You can quickly spot N+1 query patterns, blocking I/O in async contexts,
+    inefficient loops, memory leaks, and suboptimal data structures. You think
+    in terms of Big O notation and real-world scalability implications.
+  verbose: true
+  allow_delegation: false
+  max_iter: 3
+
+style_reviewer:
+  role: >
+    Staff Engineer and Code Quality Advocate
+  goal: >
+    Assess code maintainability, readability, naming conventions, and adherence
+    to best practices
+  backstory: >
+    You are a Staff Engineer who has mentored hundreds of developers and shaped
+    coding standards at multiple organizations. You're an advocate for clean code
+    principles, SOLID design, and pragmatic refactoring. You understand that code
+    is read far more often than it's written, and you prioritize clarity,
+    consistency, and testability. You can identify code smells and suggest
+    practical improvements that make code easier to understand and modify.
+  verbose: true
+  allow_delegation: false
+  max_iter: 3
+
+review_synthesizer:
+  role: >
+    Engineering Tech Lead
+  goal: >
+    Synthesize findings from all specialist reviewers into a cohesive, prioritized,
+    and actionable code review report
+  backstory: >
+    You are an experienced Tech Lead who has managed complex code reviews and
+    technical decisions for large engineering teams. You excel at synthesizing
+    diverse technical feedback, removing duplicates, prioritizing issues by
+    impact and urgency, and communicating findings clearly to developers of
+    all skill levels. You understand the balance between perfectionism and
+    pragmatism, and you know how to focus on changes that truly matter.
+  verbose: true
+  allow_delegation: false
+  max_iter: 5

app/crew/crew.py

@@ -0,0 +1,291 @@
+"""CrewAI orchestration for code review multi-agent system."""
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+from crewai import Agent, Crew, LLM, Process, Task
+from crewai.project import CrewBase, agent, crew, task
+import yaml
+
+from app.config import config
+from app.schemas import ReviewMetadata, ReviewRequest, ReviewResponse
+from app.utils import count_tokens, detect_language
+
+logger = logging.getLogger(__name__)
+
+
+@CrewBase
+class CodeReviewCrew:
+    """CrewAI-based code review orchestration."""
+
+    # Use absolute paths to avoid CrewAI path resolution issues
+    agents_config = str(Path(__file__).parent / "agents.yaml")
+    tasks_config = str(Path(__file__).parent / "tasks.yaml")
+
+    def __init__(self):
+        """Initialize the code review crew."""
+        self.llm = self._initialize_llm()
+        logger.info(
+            f"Initialized CodeReviewCrew with {config.llm_provider} "
+            f"using model {config.llm_model}"
+        )
+
+    def _initialize_llm(self):
+        """Initialize the LLM based on configuration."""
+        # CrewAI's LLM class uses format: 'provider/model'
+        # For Groq: 'groq/model-name'
+        # For OpenAI: 'openai/model-name' or just 'model-name'
+        if config.llm_provider == "groq":
+            model_string = f"groq/{config.llm_model}"
+        elif config.llm_provider == "openai":
+            model_string = config.llm_model  # OpenAI is default, no prefix needed
+        else:
+            raise ValueError(f"Unsupported LLM provider: {config.llm_provider}")
+        
+        return LLM(
+            model=model_string,
+            api_key=config.llm_api_key,
+            temperature=0.1,  # Low temperature for consistent reviews
+        )
+
+    @agent
+    def code_analyzer(self) -> Agent:
+        """Create code analyzer agent."""
+        return Agent(
+            config=self.agents_config["code_analyzer"],
+            llm=self.llm,
+        )
+
+    @agent
+    def security_reviewer(self) -> Agent:
+        """Create security reviewer agent."""
+        return Agent(
+            config=self.agents_config["security_reviewer"],
+            llm=self.llm,
+        )
+
+    @agent
+    def performance_reviewer(self) -> Agent:
+        """Create performance reviewer agent."""
+        return Agent(
+            config=self.agents_config["performance_reviewer"],
+            llm=self.llm,
+        )
+
+    @agent
+    def style_reviewer(self) -> Agent:
+        """Create style reviewer agent."""
+        return Agent(
+            config=self.agents_config["style_reviewer"],
+            llm=self.llm,
+        )
+
+    @agent
+    def review_synthesizer(self) -> Agent:
+        """Create review synthesizer agent."""
+        return Agent(
+            config=self.agents_config["review_synthesizer"],
+            llm=self.llm,
+        )
+
+    @task
+    def analyze_code_task(self) -> Task:
+        """Create code analysis task."""
+        return Task(
+            config=self.tasks_config["analyze_code"],
+        )
+
+    @task
+    def review_security_task(self) -> Task:
+        """Create security review task."""
+        return Task(
+            config=self.tasks_config["review_security"],
+        )
+
+    @task
+    def review_performance_task(self) -> Task:
+        """Create performance review task."""
+        return Task(
+            config=self.tasks_config["review_performance"],
+        )
+
+    @task
+    def review_style_task(self) -> Task:
+        """Create style review task."""
+        return Task(
+            config=self.tasks_config["review_style"],
+        )
+
+    @task
+    def synthesize_review_task(self) -> Task:
+        """Create review synthesis task."""
+        return Task(
+            config=self.tasks_config["synthesize_review"],
+        )
+
+    @crew
+    def crew(self) -> Crew:
+        """Create the code review crew with hybrid parallel-sequential execution."""
+        return Crew(
+            agents=self.agents,
+            tasks=self.tasks,
+            process=Process.sequential,  # CrewAI handles async tasks internally
+            verbose=config.debug,
+            memory=False,  # Disable memory for MVP (deterministic behavior)
+        )
+
+    def review_code(self, request: ReviewRequest) -> ReviewResponse:
+        """
+        Execute code review using the multi-agent crew.
+
+        Args:
+            request: Review request with diff and context
+
+        Returns:
+            Structured review response
+
+        Raises:
+            Exception: If review execution fails
+        """
+        start_time = time.time()
+
+        # Auto-detect language if not provided or set to default
+        language = request.language
+        if language == "python" or not language:
+            detected = detect_language(request.diff)
+            if detected != "unknown":
+                language = detected
+
+        logger.info(
+            f"Starting code review for {language} code, "
+            f"diff size: {len(request.diff)} chars"
+        )
+
+        # Prepare inputs for the crew
+        inputs = {
+            "diff": request.diff,
+            "language": language,
+        }
+
+        try:
+            # Execute the crew
+            result = self.crew().kickoff(inputs=inputs)
+
+            # Parse the result
+            review_data = self._parse_crew_output(result)
+
+            # Calculate execution time
+            execution_time_ms = int((time.time() - start_time) * 1000)
+
+            # Count tokens (approximate)
+            total_tokens = count_tokens(request.diff + str(review_data), config.llm_model)
+
+            # Create metadata
+            metadata = ReviewMetadata(
+                execution_time_ms=execution_time_ms,
+                tokens_used=total_tokens,
+                agent_count=5,
+                guardrails_applied=[],  # Will be populated by guardrails layer
+                model=config.llm_model,
+            )
+
+            # Create response
+            response = ReviewResponse(
+                summary=review_data.get("summary", "Code review completed"),
+                score=review_data.get("score", 8.0),
+                findings=review_data.get("findings", []),
+                metadata=metadata,
+            )
+
+            logger.info(
+                f"Review completed: {len(response.findings)} findings, "
+                f"score: {response.score:.1f}, time: {execution_time_ms}ms"
+            )
+
+            return response
+
+        except Exception as e:
+            logger.error(f"Error during code review: {e}", exc_info=True)
+            # Return a fallback response
+            execution_time_ms = int((time.time() - start_time) * 1000)
+            metadata = ReviewMetadata(
+                execution_time_ms=execution_time_ms,
+                tokens_used=0,
+                agent_count=5,
+                guardrails_applied=[],
+                model=config.llm_model,
+            )
+            return ReviewResponse(
+                summary=f"Review failed: {str(e)}",
+                score=5.0,
+                findings=[],
+                metadata=metadata,
+            )
+
+    def _parse_crew_output(self, result: Any) -> dict:
+        """
+        Parse crew output into structured data.
+
+        Args:
+            result: Raw crew output
+
+        Returns:
+            Parsed review data
+        """
+        try:
+            # CrewAI result can be accessed via result.raw
+            output_str = str(result.raw) if hasattr(result, "raw") else str(result)
+
+            # Try to extract JSON from the output
+            # The synthesizer should return JSON, but we need to handle markdown code blocks
+            json_str = output_str
+
+            # Remove markdown code blocks if present
+            if "```json" in json_str:
+                json_str = json_str.split("```json")[1].split("```")[0].strip()
+            elif "```" in json_str:
+                json_str = json_str.split("```")[1].split("```")[0].strip()
+
+            # Parse JSON
+            data = json.loads(json_str)
+
+            # Validate structure
+            if not isinstance(data, dict):
+                raise ValueError("Output is not a dictionary")
+
+            # Ensure required fields
+            if "findings" not in data:
+                data["findings"] = []
+            if "summary" not in data:
+                data["summary"] = "Code review completed"
+            if "score" not in data:
+                data["score"] = 8.0
+
+            return data
+
+        except Exception as e:
+            logger.warning(f"Failed to parse crew output as JSON: {e}")
+            logger.debug(f"Raw output: {result}")
+
+            # Return a safe fallback
+            return {
+                "summary": "Review completed but output parsing failed",
+                "score": 7.0,
+                "findings": [],
+            }
+
+
+# Singleton instance for reuse
+_crew_instance: Optional[CodeReviewCrew] = None
+
+
+def get_crew() -> CodeReviewCrew:
+    """Get or create the singleton crew instance."""
+    global _crew_instance
+    if _crew_instance is None:
+        _crew_instance = CodeReviewCrew()
+    return _crew_instance

app/crew/tasks.yaml

@@ -0,0 +1,202 @@
+analyze_code:
+  description: >
+    Analyze the following code diff for code quality issues, architectural
+    problems, logical flaws, and complexity concerns.
+
+    Code Diff:
+    {diff}
+
+    Programming Language: {language}
+
+    Focus on:
+    - Code structure and organization
+    - Logical correctness and potential bugs
+    - Algorithmic complexity
+    - Design patterns usage (appropriate or inappropriate)
+    - Error handling
+    - Edge cases
+
+    Return findings in JSON format as a list of objects with these fields:
+    - category: "logic" or "maintainability"
+    - severity: "low", "medium", "high", or "critical"
+    - file: file path where issue is found
+    - line: line number (if applicable)
+    - message: clear description of the issue
+    - suggestion: actionable fix or improvement
+
+  expected_output: >
+    A JSON-formatted list of code analysis findings. Each finding must include
+    category, severity, file path, line number (if applicable), a clear message
+    explaining the issue, and an actionable suggestion for improvement.
+    Focus on high-impact issues. Maximum 10 findings.
+
+  agent: code_analyzer
+  async_execution: true
+
+review_security:
+  description: >
+    Review the following code diff for security vulnerabilities and unsafe
+    coding practices.
+
+    Code Diff:
+    {diff}
+
+    Programming Language: {language}
+
+    Focus on:
+    - SQL injection, NoSQL injection
+    - Cross-site scripting (XSS)
+    - Authentication and authorization flaws
+    - Secrets and credentials in code
+    - Unsafe deserialization
+    - Path traversal vulnerabilities
+    - Cryptographic issues
+    - Input validation and sanitization
+    - CSRF vulnerabilities
+    - Insecure dependencies
+
+    Return findings in JSON format as a list of objects with these fields:
+    - category: "security"
+    - severity: "low", "medium", "high", or "critical"
+    - file: file path where issue is found
+    - line: line number (if applicable)
+    - message: clear description of the vulnerability
+    - suggestion: actionable remediation
+
+  expected_output: >
+    A JSON-formatted list of security findings. Each finding must include
+    category "security", severity level, file path, line number (if applicable),
+    a clear description of the vulnerability, and an actionable remediation
+    suggestion. Prioritize critical and high-severity issues. Maximum 10 findings.
+
+  agent: security_reviewer
+  async_execution: true
+
+review_performance:
+  description: >
+    Analyze the following code diff for performance issues, inefficiencies,
+    and scalability concerns.
+
+    Code Diff:
+    {diff}
+
+    Programming Language: {language}
+
+    Focus on:
+    - N+1 query patterns
+    - Blocking I/O in async contexts
+    - Inefficient algorithms (poor Big O complexity)
+    - Unnecessary loops or iterations
+    - Missing database indexes
+    - Inefficient data structures
+    - Memory leaks
+    - Missing caching opportunities
+    - Resource management issues
+
+    Return findings in JSON format as a list of objects with these fields:
+    - category: "performance"
+    - severity: "low", "medium", "high", or "critical"
+    - file: file path where issue is found
+    - line: line number (if applicable)
+    - message: clear description of the performance issue
+    - suggestion: actionable optimization
+
+  expected_output: >
+    A JSON-formatted list of performance findings. Each finding must include
+    category "performance", severity level, file path, line number (if applicable),
+    a clear description of the performance problem, and an actionable optimization
+    suggestion. Focus on issues with real-world impact. Maximum 10 findings.
+
+  agent: performance_reviewer
+  async_execution: true
+
+review_style:
+  description: >
+    Review the following code diff for code style, maintainability, readability,
+    and adherence to best practices.
+
+    Code Diff:
+    {diff}
+
+    Programming Language: {language}
+
+    Focus on:
+    - Naming conventions (variables, functions, classes)
+    - Code duplication
+    - Function/method length and complexity
+    - Comment quality and documentation
+    - Magic numbers and hard-coded values
+    - Proper use of language idioms
+    - Type hints and annotations (if applicable)
+    - Test coverage hints
+    - SOLID principle violations
+    - Code smells
+
+    Return findings in JSON format as a list of objects with these fields:
+    - category: "style" or "maintainability"
+    - severity: "low", "medium", "high", or "critical"
+    - file: file path where issue is found
+    - line: line number (if applicable)
+    - message: clear description of the style/maintainability issue
+    - suggestion: actionable improvement
+
+  expected_output: >
+    A JSON-formatted list of style and maintainability findings. Each finding
+    must include category ("style" or "maintainability"), severity level, file
+    path, line number (if applicable), a clear description of the issue, and an
+    actionable improvement suggestion. Focus on high-impact improvements.
+    Maximum 10 findings.
+
+  agent: style_reviewer
+  async_execution: true
+
+synthesize_review:
+  description: >
+    Synthesize all review findings from the specialist agents into a comprehensive,
+    prioritized code review report.
+
+    You have received findings from:
+    1. Code Analyzer (logic and architecture)
+    2. Security Reviewer (vulnerabilities)
+    3. Performance Reviewer (efficiency)
+    4. Style Reviewer (maintainability)
+
+    Your tasks:
+    1. Merge all findings from the specialist reviewers
+    2. Remove any duplicate findings (same issue identified by multiple agents)
+    3. Prioritize findings by severity and impact
+    4. Calculate an overall code quality score (0-10) based on:
+       - Critical issues: -3 points each
+       - High severity: -1.5 points each
+       - Medium severity: -0.5 points each
+       - Low severity: -0.1 points each
+       - Start from 10 and subtract
+    5. Create a concise summary (2-3 sentences) of the overall review
+
+    Return a JSON object with:
+    - summary: string (concise overview of the review)
+    - score: float (0-10, code quality score)
+    - findings: array of finding objects (merged, deduplicated, sorted by severity)
+
+    Each finding must have:
+    - category: "security", "performance", "style", "logic", or "maintainability"
+    - severity: "low", "medium", "high", or "critical"
+    - file: string
+    - line: integer or null
+    - message: string
+    - suggestion: string
+
+  expected_output: >
+    A complete JSON code review report with: (1) a summary string providing
+    a high-level overview, (2) a score (0-10) indicating code quality, and
+    (3) a findings array containing all unique, prioritized issues from all
+    reviewers. The findings must be sorted by severity (critical first) and
+    should be comprehensive but concise. Ensure no duplicate findings.
+
+  agent: review_synthesizer
+  context:
+    - analyze_code_task
+    - review_security_task
+    - review_performance_task
+    - review_style_task
+  async_execution: false

app/guardrails.py

@@ -0,0 +1,250 @@
+"""Guardrails for ensuring review quality and safety."""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from typing import Tuple
+
+from app.config import config
+from app.schemas import ReviewResponse, FindingSeverity
+from app.utils import extract_files_from_diff
+
+logger = logging.getLogger(__name__)
+
+
+class Guardrail(ABC):
+    """Base class for guardrails."""
+
+    @abstractmethod
+    def validate(
+        self, response: ReviewResponse, context: dict
+    ) -> Tuple[bool, ReviewResponse, str]:
+        """
+        Validate and potentially modify the review response.
+
+        Args:
+            response: Review response to validate
+            context: Additional context (e.g., original diff)
+
+        Returns:
+            Tuple of (is_valid, modified_response, guardrail_name)
+        """
+        pass
+
+
+class MaxFindingsGuardrail(Guardrail):
+    """Limit the maximum number of findings to prevent noise."""
+
+    def validate(
+        self, response: ReviewResponse, context: dict
+    ) -> Tuple[bool, ReviewResponse, str]:
+        """Limit findings to maximum allowed."""
+        max_findings = config.max_findings_per_review
+
+        if len(response.findings) <= max_findings:
+            return True, response, "max_findings"
+
+        logger.warning(
+            f"Truncating findings from {len(response.findings)} to {max_findings}"
+        )
+
+        # Keep highest severity findings
+        sorted_findings = sorted(
+            response.findings,
+            key=lambda f: (
+                ["low", "medium", "high", "critical"].index(f.severity.value),
+                f.category.value,
+            ),
+            reverse=True,
+        )
+
+        response.findings = sorted_findings[:max_findings]
+        response.metadata.guardrails_applied.append("max_findings")
+
+        return True, response, "max_findings"
+
+
+class FileNameValidationGuardrail(Guardrail):
+    """Ensure all file references exist in the original diff."""
+
+    def validate(
+        self, response: ReviewResponse, context: dict
+    ) -> Tuple[bool, ReviewResponse, str]:
+        """Validate file names against diff."""
+        diff = context.get("diff", "")
+        valid_files = set(extract_files_from_diff(diff))
+
+        if not valid_files:
+            # If we can't extract files, skip validation
+            logger.warning("Could not extract files from diff, skipping file validation")
+            return True, response, "file_validation"
+
+        # Filter findings with invalid file references
+        original_count = len(response.findings)
+        response.findings = [
+            f for f in response.findings if f.file in valid_files or f.file == "unknown"
+        ]
+
+        removed = original_count - len(response.findings)
+        if removed > 0:
+            logger.warning(f"Removed {removed} findings with invalid file references")
+            response.metadata.guardrails_applied.append("file_validation")
+
+        return True, response, "file_validation"
+
+
+class EmptyMessageGuardrail(Guardrail):
+    """Remove findings with empty or trivial messages."""
+
+    def validate(
+        self, response: ReviewResponse, context: dict
+    ) -> Tuple[bool, ReviewResponse, str]:
+        """Remove findings with empty messages."""
+        original_count = len(response.findings)
+
+        response.findings = [
+            f
+            for f in response.findings
+            if f.message.strip()
+            and f.suggestion.strip()
+            and len(f.message) > 10
+            and len(f.suggestion) > 10
+        ]
+
+        removed = original_count - len(response.findings)
+        if removed > 0:
+            logger.warning(f"Removed {removed} findings with empty/trivial messages")
+            response.metadata.guardrails_applied.append("empty_message")
+
+        return True, response, "empty_message"
+
+
+class DuplicateDetectionGuardrail(Guardrail):
+    """Remove duplicate findings."""
+
+    def validate(
+        self, response: ReviewResponse, context: dict
+    ) -> Tuple[bool, ReviewResponse, str]:
+        """Remove duplicate findings based on file, line, and message similarity."""
+        seen = set()
+        unique_findings = []
+
+        for finding in response.findings:
+            # Create a fingerprint for the finding
+            fingerprint = (
+                finding.file,
+                finding.line,
+                finding.category.value,
+                # Use first 50 chars of message for similarity
+                finding.message[:50].lower().strip(),
+            )
+
+            if fingerprint not in seen:
+                seen.add(fingerprint)
+                unique_findings.append(finding)
+
+        removed = len(response.findings) - len(unique_findings)
+        if removed > 0:
+            logger.info(f"Removed {removed} duplicate findings")
+            response.findings = unique_findings
+            response.metadata.guardrails_applied.append("duplicate_detection")
+
+        return True, response, "duplicate_detection"
+
+
+class SeverityValidationGuardrail(Guardrail):
+    """Ensure severity levels are reasonable."""
+
+    def validate(
+        self, response: ReviewResponse, context: dict
+    ) -> Tuple[bool, ReviewResponse, str]:
+        """Validate severity assignments."""
+        # Downgrade security findings marked as "low" for serious vulnerabilities
+        # This is a simple heuristic-based check
+
+        serious_keywords = [
+            "injection",
+            "xss",
+            "sql",
+            "authentication",
+            "authorization",
+            "credential",
+            "password",
+            "secret",
+            "token",
+        ]
+
+        modified = False
+        for finding in response.findings:
+            if finding.category.value == "security" and finding.severity == FindingSeverity.LOW:
+                # Check if message contains serious keywords
+                message_lower = finding.message.lower()
+                if any(keyword in message_lower for keyword in serious_keywords):
+                    logger.warning(
+                        f"Upgrading security finding severity from LOW to MEDIUM: {finding.message[:50]}"
+                    )
+                    finding.severity = FindingSeverity.MEDIUM
+                    modified = True
+
+        if modified:
+            response.metadata.guardrails_applied.append("severity_validation")
+
+        return True, response, "severity_validation"
+
+
+class GuardrailOrchestrator:
+    """Orchestrate multiple guardrails."""
+
+    def __init__(self):
+        """Initialize guardrails."""
+        self.guardrails: list[Guardrail] = [
+            EmptyMessageGuardrail(),
+            DuplicateDetectionGuardrail(),
+            FileNameValidationGuardrail(),
+            SeverityValidationGuardrail(),
+            MaxFindingsGuardrail(),  # Run last to limit final count
+        ]
+        logger.info(f"Initialized {len(self.guardrails)} guardrails")
+
+    def apply(self, response: ReviewResponse, context: dict) -> ReviewResponse:
+        """
+        Apply all guardrails to the review response.
+
+        Args:
+            response: Review response to validate
+            context: Additional context (original diff, etc.)
+
+        Returns:
+            Validated and potentially modified response
+        """
+        logger.info(
+            f"Applying guardrails to review with {len(response.findings)} findings"
+        )
+
+        for guardrail in self.guardrails:
+            try:
+                is_valid, response, name = guardrail.validate(response, context)
+                if not is_valid:
+                    logger.warning(f"Guardrail {name} marked response as invalid")
+            except Exception as e:
+                logger.error(f"Error in guardrail {guardrail.__class__.__name__}: {e}")
+                # Continue with other guardrails
+
+        logger.info(
+            f"Guardrails applied: {response.metadata.guardrails_applied}, "
+            f"final findings count: {len(response.findings)}"
+        )
+
+        return response
+
+
+# Singleton instance
+_orchestrator: GuardrailOrchestrator | None = None
+
+
+def get_guardrail_orchestrator() -> GuardrailOrchestrator:
+    """Get or create the singleton guardrail orchestrator."""
+    global _orchestrator
+    if _orchestrator is None:
+        _orchestrator = GuardrailOrchestrator()
+    return _orchestrator

app/schemas.py

@@ -0,0 +1,178 @@
+"""Pydantic schemas for structured code review output."""
+
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class FindingCategory(str, Enum):
+    """Category of code review finding."""
+
+    SECURITY = "security"
+    PERFORMANCE = "performance"
+    STYLE = "style"
+    LOGIC = "logic"
+    MAINTAINABILITY = "maintainability"
+
+
+class FindingSeverity(str, Enum):
+    """Severity level of finding."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class ReviewFinding(BaseModel):
+    """Individual code review finding."""
+
+    category: FindingCategory = Field(
+        ..., description="Category of the issue (security, performance, style, logic, maintainability)"
+    )
+    severity: FindingSeverity = Field(..., description="Severity level of the issue")
+    file: str = Field(..., description="File path where the issue was found")
+    line: Optional[int] = Field(None, description="Line number where the issue occurs")
+    message: str = Field(..., description="Clear description of the issue")
+    suggestion: str = Field(..., description="Actionable suggestion for fixing the issue")
+
+    @field_validator("message", "suggestion")
+    @classmethod
+    def validate_not_empty(cls, v: str) -> str:
+        """Ensure message and suggestion are not empty."""
+        if not v or not v.strip():
+            raise ValueError("Field cannot be empty")
+        return v.strip()
+
+
+class ReviewContext(BaseModel):
+    """Additional context about the code review request."""
+
+    repo: str = Field(..., description="Repository identifier (org/repo)")
+    commit_sha: Optional[str] = Field(None, description="Commit SHA being reviewed")
+    pr_number: Optional[int] = Field(None, description="Pull request number if applicable")
+    author: Optional[str] = Field(None, description="Code author username")
+    branch: Optional[str] = Field(None, description="Branch name")
+
+
+class ReviewRequest(BaseModel):
+    """Code review request payload."""
+
+    diff: str = Field(..., description="Git diff to review", min_length=1)
+    language: str = Field(
+        "python", description="Primary programming language of the diff"
+    )
+    context: Optional[ReviewContext] = Field(
+        None, description="Additional context about the request"
+    )
+
+    @field_validator("diff")
+    @classmethod
+    def validate_diff_size(cls, v: str) -> str:
+        """Ensure diff is not too large."""
+        max_size = 1_048_576  # 1MB
+        if len(v.encode("utf-8")) > max_size:
+            raise ValueError(f"Diff exceeds maximum size of {max_size} bytes")
+        return v
+
+
+class ReviewMetadata(BaseModel):
+    """Metadata about the review execution."""
+
+    execution_time_ms: int = Field(..., description="Time taken to execute review in milliseconds")
+    tokens_used: int = Field(..., description="Total tokens consumed by LLM")
+    agent_count: int = Field(5, description="Number of agents involved in review")
+    guardrails_applied: list[str] = Field(
+        default_factory=list, description="List of guardrails that were applied"
+    )
+    model: str = Field(..., description="LLM model used for review")
+
+
+class ReviewResponse(BaseModel):
+    """Structured code review response."""
+
+    summary: str = Field(..., description="High-level summary of the review")
+    score: float = Field(
+        ..., ge=0.0, le=10.0, description="Overall code quality score (0-10)"
+    )
+    findings: list[ReviewFinding] = Field(
+        default_factory=list, description="List of review findings"
+    )
+    metadata: ReviewMetadata = Field(..., description="Execution metadata")
+
+    @property
+    def critical_count(self) -> int:
+        """Count of critical severity findings."""
+        return sum(1 for f in self.findings if f.severity == FindingSeverity.CRITICAL)
+
+    @property
+    def high_count(self) -> int:
+        """Count of high severity findings."""
+        return sum(1 for f in self.findings if f.severity == FindingSeverity.HIGH)
+
+    @property
+    def findings_by_category(self) -> dict[FindingCategory, list[ReviewFinding]]:
+        """Group findings by category."""
+        result: dict[FindingCategory, list[ReviewFinding]] = {cat: [] for cat in FindingCategory}
+        for finding in self.findings:
+            result[finding.category].append(finding)
+        return result
+
+    def to_markdown(self) -> str:
+        """Convert review to markdown format for GitHub PR comments."""
+        lines = [
+            "## 🤖 AI Code Review",
+            "",
+            f"**Summary:** {self.summary}",
+            f"**Quality Score:** {self.score:.1f}/10",
+            "",
+        ]
+
+        if not self.findings:
+            lines.append("✅ No issues found! Great work!")
+            return "\n".join(lines)
+
+        # Group by severity
+        critical = [f for f in self.findings if f.severity == FindingSeverity.CRITICAL]
+        high = [f for f in self.findings if f.severity == FindingSeverity.HIGH]
+        medium = [f for f in self.findings if f.severity == FindingSeverity.MEDIUM]
+        low = [f for f in self.findings if f.severity == FindingSeverity.LOW]
+
+        def format_findings(findings: list[ReviewFinding], emoji: str, title: str) -> list[str]:
+            if not findings:
+                return []
+            result = [f"### {emoji} {title}", ""]
+            for f in findings:
+                location = f"`{f.file}:{f.line}`" if f.line else f"`{f.file}`"
+                result.append(f"- **{f.category.value.title()}** in {location}")
+                result.append(f"  > {f.message}")
+                result.append(f"  > **Suggestion:** {f.suggestion}")
+                result.append("")
+            return result
+
+        lines.extend(format_findings(critical, "🔴", "Critical Issues"))
+        lines.extend(format_findings(high, "🟠", "High Severity"))
+        lines.extend(format_findings(medium, "🟡", "Medium Severity"))
+        lines.extend(format_findings(low, "🟢", "Low Severity"))
+
+        # Footer
+        lines.extend(
+            [
+                "---",
+                f"*Reviewed by {self.metadata.agent_count} AI agents "
+                f"using {self.metadata.model} "
+                f"in {self.metadata.execution_time_ms}ms*",
+            ]
+        )
+
+        return "\n".join(lines)
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str = Field(..., description="Service status")
+    version: str = Field(..., description="Application version")
+    ray_serve_enabled: bool = Field(..., description="Whether Ray Serve is enabled")
+    llm_provider: str = Field(..., description="Active LLM provider")

app/serve.py

@@ -0,0 +1,74 @@
+"""Ray Serve deployment for scalable code review service."""
+
+import logging
+from typing import Dict
+
+from ray import serve
+from fastapi import FastAPI
+
+from app.api import app as fastapi_app
+from app.config import config
+from app.crew.crew import CodeReviewCrew
+from app.guardrails import GuardrailOrchestrator
+from app.schemas import ReviewRequest, ReviewResponse
+
+logger = logging.getLogger(__name__)
+
+
+@serve.deployment(
+    num_replicas=config.ray_num_replicas,
+    max_concurrent_queries=config.ray_max_concurrent_queries,
+    ray_actor_options={
+        "num_cpus": 2,
+        "num_gpus": 0,
+    },
+)
+@serve.ingress(fastapi_app)
+class CodeReviewDeployment:
+    """
+    Ray Serve deployment for code review service.
+
+    This wraps the FastAPI app and provides horizontal scaling capabilities.
+    """
+
+    def __init__(self):
+        """Initialize the deployment."""
+        logger.info("Initializing CodeReviewDeployment")
+        config.configure_logging()
+
+        # Initialize crew and guardrails (warm up)
+        self.crew = CodeReviewCrew()
+        self.guardrails = GuardrailOrchestrator()
+
+        logger.info(
+            f"CodeReviewDeployment initialized with {config.ray_num_replicas} replicas"
+        )
+
+
+# Deployment configuration
+deployment = CodeReviewDeployment.bind()
+
+
+def start_serve():
+    """Start Ray Serve deployment."""
+    import ray
+
+    # Initialize Ray if not already initialized
+    if not ray.is_initialized():
+        ray.init()
+
+    # Deploy the application
+    serve.run(
+        deployment,
+        host=config.ray_serve_host,
+        port=config.ray_serve_port,
+        name="code_review_service",
+    )
+
+    logger.info(
+        f"Ray Serve deployment started at http://{config.ray_serve_host}:{config.ray_serve_port}"
+    )
+
+
+if __name__ == "__main__":
+    start_serve()

app/utils.py

@@ -0,0 +1,205 @@
+"""Utility functions for code review processing."""
+
+import hashlib
+import logging
+import re
+from typing import Optional
+
+import tiktoken
+
+logger = logging.getLogger(__name__)
+
+
+def count_tokens(text: str, model: str = "gpt-4") -> int:
+    """
+    Count tokens in text using tiktoken.
+
+    Args:
+        text: Text to count tokens for
+        model: Model name for tokenizer
+
+    Returns:
+        Number of tokens
+    """
+    try:
+        encoding = tiktoken.encoding_for_model(model)
+    except KeyError:
+        # Fallback to cl100k_base for unknown models
+        encoding = tiktoken.get_encoding("cl100k_base")
+
+    return len(encoding.encode(text))
+
+
+def extract_files_from_diff(diff: str) -> list[str]:
+    """
+    Extract file paths from a git diff.
+
+    Args:
+        diff: Git diff content
+
+    Returns:
+        List of file paths mentioned in the diff
+    """
+    files = set()
+    # Match lines like: diff --git a/path/to/file b/path/to/file
+    # or +++ b/path/to/file
+    patterns = [
+        r"^diff --git a/(.*?) b/",
+        r"^\+\+\+ b/(.*?)$",
+        r"^--- a/(.*?)$",
+    ]
+
+    for line in diff.splitlines():
+        for pattern in patterns:
+            match = re.match(pattern, line)
+            if match:
+                file_path = match.group(1)
+                # Skip /dev/null (for deleted/new files)
+                if file_path != "/dev/null":
+                    files.add(file_path)
+
+    return sorted(files)
+
+
+def sanitize_diff(diff: str) -> str:
+    """
+    Sanitize diff content to prevent injection attacks.
+
+    Args:
+        diff: Raw diff content
+
+    Returns:
+        Sanitized diff
+    """
+    # Remove any potential shell commands or suspicious patterns
+    # This is a basic sanitization - in production, use more robust methods
+    sanitized = diff
+
+    # Remove null bytes
+    sanitized = sanitized.replace("\x00", "")
+
+    # Limit line length to prevent DOS
+    max_line_length = 1000
+    lines = sanitized.splitlines()
+    sanitized_lines = [line[:max_line_length] for line in lines]
+
+    return "\n".join(sanitized_lines)
+
+
+def detect_language(diff: str) -> str:
+    """
+    Detect the primary programming language from a diff.
+
+    Args:
+        diff: Git diff content
+
+    Returns:
+        Detected language (defaults to "python")
+    """
+    files = extract_files_from_diff(diff)
+
+    # Count file extensions
+    extension_counts: dict[str, int] = {}
+    for file in files:
+        if "." in file:
+            ext = file.rsplit(".", 1)[-1].lower()
+            extension_counts[ext] = extension_counts.get(ext, 0) + 1
+
+    if not extension_counts:
+        return "python"
+
+    # Map extensions to languages
+    extension_map = {
+        "py": "python",
+        "js": "javascript",
+        "ts": "typescript",
+        "jsx": "javascript",
+        "tsx": "typescript",
+        "java": "java",
+        "go": "go",
+        "rs": "rust",
+        "cpp": "c++",
+        "c": "c",
+        "rb": "ruby",
+        "php": "php",
+        "swift": "swift",
+        "kt": "kotlin",
+        "scala": "scala",
+        "cs": "csharp",
+    }
+
+    # Find most common extension
+    most_common_ext = max(extension_counts, key=extension_counts.get)  # type: ignore
+    return extension_map.get(most_common_ext, "unknown")
+
+
+def generate_request_id() -> str:
+    """
+    Generate a unique request ID for tracing.
+
+    Returns:
+        Unique request ID
+    """
+    import time
+    import uuid
+
+    timestamp = str(time.time())
+    unique_id = str(uuid.uuid4())
+    combined = f"{timestamp}-{unique_id}"
+    return hashlib.sha256(combined.encode()).hexdigest()[:16]
+
+
+def truncate_text(text: str, max_length: int = 1000, suffix: str = "...") -> str:
+    """
+    Truncate text to a maximum length.
+
+    Args:
+        text: Text to truncate
+        max_length: Maximum length
+        suffix: Suffix to add when truncated
+
+    Returns:
+        Truncated text
+    """
+    if len(text) <= max_length:
+        return text
+    return text[: max_length - len(suffix)] + suffix
+
+
+def parse_severity_score(severity: str) -> int:
+    """
+    Convert severity to numeric score for sorting.
+
+    Args:
+        severity: Severity level (critical, high, medium, low)
+
+    Returns:
+        Numeric score (higher = more severe)
+    """
+    severity_map = {
+        "critical": 4,
+        "high": 3,
+        "medium": 2,
+        "low": 1,
+    }
+    return severity_map.get(severity.lower(), 0)
+
+
+def format_elapsed_time(milliseconds: int) -> str:
+    """
+    Format elapsed time in a human-readable format.
+
+    Args:
+        milliseconds: Time in milliseconds
+
+    Returns:
+        Formatted time string (e.g., "1.5s", "250ms")
+    """
+    if milliseconds < 1000:
+        return f"{milliseconds}ms"
+    elif milliseconds < 60000:
+        return f"{milliseconds / 1000:.1f}s"
+    else:
+        minutes = milliseconds // 60000
+        seconds = (milliseconds % 60000) / 1000
+        return f"{minutes}m {seconds:.1f}s"

docker-compose.yml

@@ -0,0 +1,54 @@
+version: '3.8'
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    environment:
+      - ENABLE_RAY_SERVE=false
+    volumes:
+      - ./logs:/app/logs
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # Ray Serve deployment (optional, use with --profile production)
+  ray-head:
+    profiles:
+      - production
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+      - "8265:8265"  # Ray dashboard
+    env_file:
+      - .env
+    environment:
+      - ENABLE_RAY_SERVE=true
+    command: >
+      sh -c "
+      ray start --head --port=6379 --dashboard-host=0.0.0.0 --dashboard-port=8265 &&
+      python -m app.serve
+      "
+    volumes:
+      - ./logs:/app/logs
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+volumes:
+  logs:

pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "code-reviewer-ci-agent"
+version = "0.1.0"
+description = "Production-ready AI code review agent using CrewAI multi-agent framework"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Code Reviewer Team" }
+]
+keywords = ["ai", "code-review", "crewai", "agents", "github-actions"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "crewai>=0.80.0",
+    "crewai-tools>=0.14.0",
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.27.0",
+    "pydantic>=2.6.0",
+    "pydantic-settings>=2.1.0",
+    "python-dotenv>=1.0.0",
+    "httpx>=0.27.0",
+    "python-multipart>=0.0.9",
+    "ray[serve]>=2.9.0",
+    "openai>=1.12.0",
+    "langchain-openai>=0.1.0",
+    "langchain-groq>=0.1.0",
+    "tiktoken>=0.6.0",
+    "PyYAML>=6.0.1",
+    "litellm>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "black>=24.0.0",
+    "ruff>=0.2.0",
+    "mypy>=1.8.0",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+include = '\.pyi?$'
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501",  # line too long (handled by black)
+    "B008",  # do not perform function calls in argument defaults
+]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --cov=app --cov-report=term-missing"
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true

requirements.txt

@@ -0,0 +1,36 @@
+# Core dependencies - extracted from pyproject.toml
+# This file is for deployment platforms (GitHub Actions, Hugging Face Spaces, etc.)
+# that prefer requirements.txt over pyproject.toml
+
+# CrewAI Multi-Agent Framework
+crewai>=0.80.0
+crewai-tools>=0.14.0
+
+# Web Framework
+fastapi>=0.110.0
+uvicorn[standard]>=0.27.0
+
+# Configuration & Data Validation
+pydantic>=2.6.0
+pydantic-settings>=2.1.0
+python-dotenv>=1.0.0
+
+# HTTP Client
+httpx>=0.27.0
+python-multipart>=0.0.9
+
+# LLM Providers
+openai>=1.12.0
+langchain-openai>=0.1.0
+langchain-groq>=0.1.0
+litellm>=1.0.0
+
+# Tokenization
+tiktoken>=0.6.0
+
+# Utilities
+PyYAML>=6.0.1
+
+# Optional: Ray Serve (for scaling)
+# Uncomment if deploying with Ray Serve
+# ray[serve]>=2.9.0

start.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Quick start script for Code Reviewer CI Agent
+
+set -e
+
+echo "🤖 Code Reviewer CI Agent - Setup Script"
+echo "=========================================="
+echo ""
+
+# Check if .env exists
+if [ ! -f .env ]; then
+    echo "⚠️  No .env file found. Creating from template..."
+    cp .env.example .env
+    echo "✅ Created .env file"
+    echo ""
+    echo "📝 Please edit .env and add:"
+    echo "   - Your LLM API key (OPENAI_API_KEY or GROQ_API_KEY)"
+    echo "   - A secure REVIEW_API_KEY"
+    echo ""
+    echo "Then run this script again."
+    exit 1
+fi
+
+# Source environment
+export $(cat .env | grep -v '^#' | xargs)
+
+# Check if API key is set
+if [ -z "$OPENAI_API_KEY" ] && [ -z "$GROQ_API_KEY" ]; then
+    echo "❌ No LLM API key configured in .env"
+    echo "   Please set OPENAI_API_KEY or GROQ_API_KEY"
+    exit 1
+fi
+
+if [ -z "$REVIEW_API_KEY" ]; then
+    echo "❌ No REVIEW_API_KEY configured in .env"
+    echo "   Please set a secure API key for authentication"
+    exit 1
+fi
+
+echo "✅ Environment configured"
+echo ""
+
+# Check for Docker
+if command -v docker &> /dev/null; then
+    echo "🐳 Docker detected"
+    echo ""
+    echo "Choose deployment mode:"
+    echo "  1) Development (Docker Compose - no Ray Serve)"
+    echo "  2) Production (Docker Compose with Ray Serve)"
+    echo "  3) Local development (pip install)"
+    echo ""
+    read -p "Enter choice [1-3]: " choice
+    
+    case $choice in
+        1)
+            echo ""
+            echo "🚀 Starting in development mode..."
+            docker-compose up --build
+            ;;
+        2)
+            echo ""
+            echo "🚀 Starting in production mode with Ray Serve..."
+            docker-compose --profile production up --build
+            ;;
+        3)
+            echo ""
+            echo "📦 Installing dependencies..."
+            pip install -e .
+            echo ""
+            echo "🚀 Starting API server..."
+            uvicorn app.api:app --host 0.0.0.0 --port 8000 --reload
+            ;;
+        *)
+            echo "Invalid choice"
+            exit 1
+            ;;
+    esac
+else
+    echo "📦 Installing dependencies..."
+    pip install -e .
+    echo ""
+    echo "🚀 Starting API server..."
+    uvicorn app.api:app --host 0.0.0.0 --port 8000 --reload
+fi