AI Service (@izri/ai-service)

FastAPI-based AI service for intelligent code analysis and test generation

⚠️ Development Status

Current Implementation: Real AI Integration (Phase 1 Complete)

The AI service now provides real AI integration with OpenAI and Anthropic for E2E testing MVP. All endpoints use actual AI models for code analysis and test generation.

What's Implemented:

✅ FastAPI application structure with real AI integration
✅ OpenAI GPT-4 and Anthropic Claude integration
✅ AI-powered repository analysis for E2E testing
✅ AI-powered Playwright test generation
✅ Staging environment detection support
✅ OpenAPI documentation and CORS configuration
✅ Production-ready async endpoints

What's Planned:

🔄 LangChain orchestration for complex workflows
🔄 Multi-model comparison and selection
🔄 Token usage optimization and cost tracking
🔄 Advanced prompt engineering

📋 Overview

The AI Service is a Python-based microservice designed to provide AI-powered code analysis and test generation capabilities. Built with FastAPI, it will offer RESTful endpoints for analyzing repositories, generating tests, and optimizing test suites using advanced AI models from OpenAI and Anthropic.

Architecture Benefits:

✅ FastAPI with automatic OpenAPI documentation
✅ Pydantic models for validation
✅ CORS enabled for frontend integration
✅ Async/await for high performance
✅ Production-ready server (Uvicorn)
🔄 Multi-provider AI support (planned)

📦 Service Structure

packages/ai-service/
├── main.py                # FastAPI application entry point
├── requirements.txt       # Python dependencies
├── README.md              # Service documentation
├── __pycache__/           # Python bytecode cache
└── src/                   # Future: Organized source code
    ├── ai/               # AI provider integrations
    ├── analysis/         # Code analysis logic
    ├── generation/       # Test generation
    ├── models/           # Pydantic models
    └── utils/            # Utility functions

🏗️ Architecture

┌─────────────────────────────────────────┐
│         FastAPI Application              │
│         (CORS + OpenAPI Docs)            │
└─────────────────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
    ▼             ▼             ▼
┌────────┐   ┌─────────┐   ┌─────────┐
│Analyze │   │Generate │   │Optimize │
│  Code  │   │  Tests  │   │  Tests  │
└────────┘   └─────────┘   └─────────┘
    │             │             │
    ▼             ▼             ▼
┌─────────────────────────────────────────┐
│         AI Providers (Future)            │
│  ┌─────────┐         ┌──────────────┐  │
│  │ OpenAI  │         │ Anthropic    │  │
│  │ GPT-4   │         │ Claude       │  │
│  └─────────┘         └──────────────┘  │
└─────────────────────────────────────────┘

🚀 Quick Start

Installation

cd packages/ai-service

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Running the Service

# Development
python main.py
# Service runs on http://localhost:8000

# Production
uvicorn main:app --host 0.0.0.0 --port 8000

# With auto-reload (development)
uvicorn main:app --reload

Environment Variables

Create a .env file in the project root:

# AI Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Service Configuration
AI_SERVICE_PORT=8000
AI_SERVICE_HOST=0.0.0.0
LOG_LEVEL=INFO

# Environment
ENVIRONMENT=development
DEBUG=true

📡 API Endpoints

Service Information

GET `/`

Get service information and status.

Response:

{
  "message": "Izri AI Service",
  "version": "1.0.0",
  "status": "healthy"
}

cURL Example:

curl http://localhost:8000/

GET `/health`

Health check endpoint with AI provider status.

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:00:00.000Z",
  "ai_providers": {
    "openai": "available",
    "anthropic": "available"
  }
}

cURL Example:

curl http://localhost:8000/health

Code Analysis

POST `/analyze`

Analyze a code repository and return comprehensive insights.

Request Body:

{
  repository_url: string      // Repository URL
  language: string            // Primary language
  framework?: string          // Optional framework
  branch?: string             // Branch name (default: 'main')
}

Pydantic Model:

class CodeAnalysisRequest(BaseModel):
    repository_url: str
    language: str
    framework: Optional[str] = None
    branch: str = "main"

Response:

{
  "status": "success",
  "analysis": {
    "repository": "https://github.com/user/repo",
    "language": "typescript",
    "framework": "nextjs",
    "structure": {
      "total_files": 45,
      "source_files": 32,
      "test_files": 8,
      "config_files": 5
    },
    "dependencies": {
      "production": ["react", "typescript"],
      "development": ["jest", "playwright", "@testing-library/react"]
    },
    "testing_coverage": {
      "current": 65.5,
      "target": 80.0,
      "missing_areas": ["API endpoints", "Error handling", "Edge cases"]
    },
    "complexity": {
      "average_cyclomatic": 3.2,
      "high_complexity_files": ["src/components/DataTable.tsx"]
    },
    "recommendations": [
      "Add unit tests for utility functions",
      "Implement E2E tests for critical user flows"
    ]
  },
  "timestamp": "2025-01-15T10:00:00.000Z"
}

cURL Example:

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "repository_url": "https://github.com/user/repo",
    "language": "typescript",
    "framework": "nextjs",
    "branch": "main"
  }'

Python Example:

import httpx

response = httpx.post(
    "http://localhost:8000/analyze",
    json={
        "repository_url": "https://github.com/user/repo",
        "language": "typescript",
        "framework": "nextjs",
        "branch": "main"
    }
)

analysis = response.json()
print(f"Coverage: {analysis['analysis']['testing_coverage']['current']}%")

TypeScript/JavaScript Example:

const response = await fetch('http://localhost:8000/analyze', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    repository_url: 'https://github.com/user/repo',
    language: 'typescript',
    framework: 'nextjs',
    branch: 'main'
  })
})

const { analysis } = await response.json()
console.log(`Total files: ${analysis.structure.total_files}`)

Test Generation

POST `/generate-tests`

Generate test cases based on code analysis results.

Request Body:

{
  code_analysis: Record<string, any>  // Analysis results from /analyze
  test_type: 'unit' | 'integration' | 'e2e' | 'all'
  framework?: string                  // Test framework (jest, pytest, etc.)
  ai_provider?: 'openai' | 'anthropic'  // AI provider (default: 'openai')
  ai_model?: string                   // Model name (default: 'gpt-4')
}

Pydantic Models:

class TestGenerationRequest(BaseModel):
    code_analysis: Dict[str, Any]
    test_type: str  # unit, integration, e2e, all
    framework: Optional[str] = None
    ai_provider: str = "openai"
    ai_model: str = "gpt-4"

class TestGenerationResponse(BaseModel):
    tests: List[Dict[str, Any]]
    coverage_estimate: float
    test_count: int
    execution_time: str

Response:

{
  "tests": {
    "unit_tests": [
      {
        "name": "should format date correctly",
        "file": "src/utils/dateHelpers.test.ts",
        "code": "describe('formatDate', () => {\n  it('should format date correctly', () => {\n    expect(formatDate(new Date('2024-01-15'))).toBe('2024-01-15');\n  });\n});",
        "coverage": "src/utils/dateHelpers.ts"
      }
    ],
    "integration_tests": [...],
    "e2e_tests": [...]
  },
  "coverage_estimate": 85.5,
  "test_count": 12,
  "execution_time": "2m 30s"
}

cURL Example:

curl -X POST http://localhost:8000/generate-tests \
  -H "Content-Type: application/json" \
  -d '{
    "code_analysis": {
      "repository": "https://github.com/user/repo",
      "language": "typescript",
      "framework": "nextjs"
    },
    "test_type": "unit",
    "framework": "jest",
    "ai_provider": "openai",
    "ai_model": "gpt-4"
  }'

Python Example:

import httpx

# First analyze the code
analysis_response = httpx.post(
    "http://localhost:8000/analyze",
    json={"repository_url": "https://github.com/user/repo", "language": "typescript"}
)
analysis = analysis_response.json()["analysis"]

# Then generate tests
tests_response = httpx.post(
    "http://localhost:8000/generate-tests",
    json={
        "code_analysis": analysis,
        "test_type": "unit",
        "framework": "jest",
        "ai_provider": "openai",
        "ai_model": "gpt-4"
    }
)

tests = tests_response.json()
print(f"Generated {tests['test_count']} tests")
print(f"Coverage estimate: {tests['coverage_estimate']}%")

Test Optimization

POST `/optimize-tests`

Optimize an existing test suite for better coverage and performance.

Request Body:

Array<{
  name: string
  file: string
  code: string
}>

Response:

{
  "status": "success",
  "optimization": {
    "original_count": 15,
    "optimized_count": 18,
    "coverage_improvement": 12.5,
    "performance_improvement": "15% faster execution",
    "suggestions": [
      "Add edge case testing for null values",
      "Consolidate similar test cases",
      "Add performance benchmarks"
    ]
  },
  "timestamp": "2025-01-15T10:00:00.000Z"
}

cURL Example:

curl -X POST http://localhost:8000/optimize-tests \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "should validate email",
      "file": "tests/validation.test.ts",
      "code": "it(\"should validate email\", () => { ... })"
    }
  ]'

🎨 Pydantic Models

Request Models

CodeAnalysisRequest

from pydantic import BaseModel
from typing import Optional

class CodeAnalysisRequest(BaseModel):
    repository_url: str
    language: str
    framework: Optional[str] = None
    branch: str = "main"

    class Config:
        json_schema_extra = {
            "example": {
                "repository_url": "https://github.com/user/repo",
                "language": "typescript",
                "framework": "nextjs",
                "branch": "main"
            }
        }

TestGenerationRequest

from pydantic import BaseModel, validator
from typing import Dict, Any, Optional

class TestGenerationRequest(BaseModel):
    code_analysis: Dict[str, Any]
    test_type: str  # unit, integration, e2e, all
    framework: Optional[str] = None
    ai_provider: str = "openai"
    ai_model: str = "gpt-4"

    @validator('test_type')
    def validate_test_type(cls, v):
        allowed_types = ['unit', 'integration', 'e2e', 'all']
        if v not in allowed_types:
            raise ValueError(f'test_type must be one of {allowed_types}')
        return v

Response Models

TestGenerationResponse

from pydantic import BaseModel
from typing import List, Dict, Any

class TestGenerationResponse(BaseModel):
    tests: List[Dict[str, Any]]
    coverage_estimate: float
    test_count: int
    execution_time: str

    class Config:
        json_schema_extra = {
            "example": {
                "tests": [{"name": "test", "file": "test.ts"}],
                "coverage_estimate": 85.5,
                "test_count": 12,
                "execution_time": "2m 30s"
            }
        }

🌐 CORS Configuration

The service is configured to accept requests from any origin (for development):

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],          # ⚠️ Configure for production
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Production Configuration:

# Only allow specific origins
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://yourapp.com",
        "https://api.yourapp.com"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["Content-Type", "Authorization"],
)

📖 Interactive API Documentation

FastAPI automatically generates interactive API documentation:

Swagger UI

Visit: http://localhost:8000/docs

Interactive endpoint testing
Request/response schemas
Example requests
Try it out functionality

ReDoc

Visit: http://localhost:8000/redoc

Alternative documentation UI
Better for reading
Cleaner layout

🧪 Development Workflow

1. Setup Development Environment

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies with development tools
pip install -r requirements.txt
pip install pytest pytest-asyncio httpx

# Install pre-commit hooks (if configured)
pre-commit install

2. Run Development Server

# With auto-reload
uvicorn main:app --reload --port 8000

# With custom log level
uvicorn main:app --reload --log-level debug

3. Test Endpoints

# Using httpx
python -c "
import httpx
response = httpx.get('http://localhost:8000/health')
print(response.json())
"

# Using pytest (future)
pytest tests/

🚀 Production Deployment

Docker Deployment

Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY main.py .

# Expose port
EXPOSE 8000

# Run with gunicorn + uvicorn workers
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

Build and Run:

# Build image
docker build -t izri-ai-service .

# Run container
docker run -p 8000:8000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  izri-ai-service

Docker Compose

version: '3.8'

services:
  ai-service:
    build: ./packages/ai-service
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - ENVIRONMENT=production
    restart: unless-stopped

Environment Variables

# Production environment
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=INFO
AI_SERVICE_HOST=0.0.0.0
AI_SERVICE_PORT=8000

📦 Dependencies

fastapi==0.115.6           # Web framework
uvicorn[standard]==0.34.0  # ASGI server
pydantic==2.10.3           # Data validation
openai==1.58.1             # OpenAI API client
anthropic==0.40.0          # Anthropic API client
python-dotenv==1.0.1       # Environment variables
httpx==0.28.1              # HTTP client

🗺️ Roadmap

Phase 2: Real AI Integration

Implement OpenAI GPT-4 integration
Implement Anthropic Claude integration
Context optimization for LLM prompts
Token usage tracking and optimization

Phase 3: Advanced Features

Repository cloning and analysis
Code parsing with AST analysis
Framework-specific test generation
Test quality scoring
Intelligent test suggestions

Phase 4: Production Features

Rate limiting
API key authentication
Request caching
Async task queue (Celery)
Monitoring and logging (OpenTelemetry)
Cost tracking per request

🔗 Related Documentation

Package Documentation

Repo Analyzer - Code analysis integration
tRPC Package - API integration

Backend Documentation

API Server Setup - Main API server
Architecture - System architecture

Last Updated: January 2025
Service Version: 1.0.0
Status: 🚧 Mock Implementation, Real AI Integration Planned

AI Service (@izri/ai-service)

⚠️ Development Status

📋 Overview

📦 Service Structure

🏗️ Architecture

🚀 Quick Start

Installation

Running the Service

Environment Variables

📡 API Endpoints

Service Information

GET /

GET /health

Code Analysis

POST /analyze

Test Generation

POST /generate-tests

Test Optimization

POST /optimize-tests

🎨 Pydantic Models

Request Models

CodeAnalysisRequest

TestGenerationRequest

Response Models

TestGenerationResponse

🌐 CORS Configuration

📖 Interactive API Documentation

Swagger UI

ReDoc

🧪 Development Workflow

1. Setup Development Environment

2. Run Development Server

3. Test Endpoints

🚀 Production Deployment

Docker Deployment

Docker Compose

Environment Variables

📦 Dependencies

🗺️ Roadmap

Phase 2: Real AI Integration

Phase 3: Advanced Features

Phase 4: Production Features

🔗 Related Documentation

Package Documentation

Backend Documentation

GET `/`

GET `/health`

POST `/analyze`

POST `/generate-tests`

POST `/optimize-tests`