# 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

```bash
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

```bash
# 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:

```bash
# 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:**

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

**cURL Example:**

```bash
curl http://localhost:8000/
```

---

#### GET `/health`

Health check endpoint with AI provider status.

**Response:**

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

**cURL Example:**

```bash
curl http://localhost:8000/health
```

---

### Code Analysis

#### POST `/analyze`

Analyze a code repository and return comprehensive insights.

**Request Body:**

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

**Pydantic Model:**

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

**Response:**

```json
{
  "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:**

```bash
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:**

```python
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:**

```typescript
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:**

```typescript
{
  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:**

```python
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:**

```json
{
  "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:**

```bash
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:**

```python
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:**

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

**Response:**

```json
{
  "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:**

```bash
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

```python
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

```python
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

```python
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):

```python
from fastapi.middleware.cors import CORSMiddleware

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

**Production Configuration:**

```python
# 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

```bash
# 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

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

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

### 3. Test Endpoints

```bash
# 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:**

```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:**

```bash
# 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

```yaml
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

```bash
# 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

```txt
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](./repo-analyzer.md) - Code analysis integration
- [tRPC Package](./trpc-package.md) - API integration

### Backend Documentation

- [API Server Setup](../backend/api-server-setup.md) - Main API server
- [Architecture](../architecture/overview.md) - System architecture

---

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