# AI Service Crate

The AI Service crate (`provisioning/platform/crates/ai-service/`) is the central AI processing
microservice for Provisioning. It coordinates LLM integration, knowledge retrieval, and
infrastructure recommendation generation.

## Architecture

### Core Modules

The AI Service is organized into specialized modules:

| Module | Purpose |
| --- | --- |
| **config.rs** | Configuration management and AI service settings |
| **service.rs** | Main service logic and request handling |
| **mcp.rs** | Model Context Protocol integration for LLM tools |
| **knowledge.rs** | Knowledge base management and retrieval |
| **dag.rs** | Directed Acyclic Graph for workflow orchestration |
| **handlers.rs** | HTTP endpoint handlers |
| **tool_integration.rs** | Tool registration and execution |

### Request Flow

```text
User Request (natural language)
    ↓
Handlers (HTTP endpoint)
    ↓
Intent Recognition (config.rs)
    ↓
Knowledge Retrieval (knowledge.rs)
    ↓
MCP Tool Selection (mcp.rs)
    ↓
LLM Processing (external provider)
    ↓
DAG Execution Planning (dag.rs)
    ↓
Infrastructure Generation
    ↓
Response to User
```

## Configuration

### Environment Variables

```bash
# LLM Configuration
export PROVISIONING_AI_PROVIDER=openai
export PROVISIONING_AI_MODEL=gpt-4
export PROVISIONING_AI_API_KEY=sk-...

# Service Configuration
export PROVISIONING_AI_PORT=9091
export PROVISIONING_AI_LOG_LEVEL=info
export PROVISIONING_AI_TIMEOUT=30

# Knowledge Base
export PROVISIONING_AI_KNOWLEDGE_PATH=~/.provisioning/knowledge
export PROVISIONING_AI_CACHE_TTL=3600

# RAG Configuration
export PROVISIONING_AI_RAG_ENABLED=true
export PROVISIONING_AI_RAG_SIMILARITY_THRESHOLD=0.75
```

### Configuration File

```toml
# provisioning/config/ai-service.toml
[ai_service]
port = 9091
timeout = 30
max_concurrent_requests = 100

[llm]
provider = "openai"                 # openai, anthropic, local
model = "gpt-4"
api_key = "${PROVISIONING_AI_API_KEY}"
temperature = 0.7
max_tokens = 2000

[knowledge]
enabled = true
path = "~/.provisioning/knowledge"
cache_ttl = 3600
update_interval = 3600

[rag]
enabled = true
similarity_threshold = 0.75
max_results = 5
embedding_model = "text-embedding-3-small"

[dag]
max_parallel_tasks = 10
timeout_per_task = 60
enable_rollback = true

[security]
validate_inputs = true
rate_limit = 1000                   # requests/minute
audit_logging = true
```

## HTTP API

### Endpoints

#### Create Infrastructure Request

```http
POST /v1/infrastructure/create
Content-Type: application/json

{
  "request": "Create 3 web servers with load balancing",
  "context": {
    "workspace": "production",
    "provider": "upcloud",
    "environment": "prod"
  },
  "options": {
    "auto_apply": false,
    "return_nickel": true,
    "validate": true
  }
}
```

**Response**:

```json
{
  "request_id": "req-12345",
  "status": "success",
  "infrastructure": {
    "servers": [
      {"name": "web-01", "cpu": 4, "memory": 8},
      {"name": "web-02", "cpu": 4, "memory": 8},
      {"name": "web-03", "cpu": 4, "memory": 8}
    ],
    "load_balancer": {"name": "lb-01", "type": "round-robin"}
  },
  "nickel_config": "{ servers = [...] }",
  "confidence": 0.92,
  "notes": ["All servers in same availability zone", "Load balancer configured for health checks"]
}
```

#### Analyze Configuration

```http
POST /v1/configuration/analyze
Content-Type: application/json

{
  "configuration": "{ name = \"server-01\", cpu = 2, memory = 4 }",
  "context": {"provider": "upcloud", "environment": "prod"}
}
```

**Response**:

```json
{
  "analysis": {
    "resources": {
      "cpu_score": "low",
      "memory_score": "minimal",
      "recommendation": "Increase to cpu=4, memory=8 for production"
    },
    "security": {
      "findings": ["No backup configured", "No monitoring"],
      "recommendations": ["Enable automated backups", "Deploy monitoring agent"]
    },
    "cost": {
      "estimated_monthly": "$45",
      "optimization_potential": "20% cost reduction possible"
    }
  }
}
```

#### Generate Policies

```http
POST /v1/policies/generate
Content-Type: application/json

{
  "requirements": "Allow developers to create servers but not delete, admins full access",
  "format": "cedar"
}
```

**Response**:

```json
{
  "policies": [
    {
      "effect": "permit",
      "principal": {"role": "developer"},
      "action": "CreateServer",
      "resource": "Server::*"
    },
    {
      "effect": "permit",
      "principal": {"role": "admin"},
      "action": ["CreateServer", "DeleteServer", "ModifyServer"],
      "resource": "Server::*"
    }
  ],
  "format": "cedar",
  "validation": "valid"
}
```

#### Get Suggestions

```http
GET /v1/suggestions?context=database&workload=transactional&scale=large
```

**Response**:

```json
{
  "suggestions": [
    {
      "type": "database",
      "recommendation": "PostgreSQL 15 with pgvector",
      "rationale": "Optimal for transactional workload with vector support",
      "confidence": 0.95,
      "config": {
        "engine": "postgres",
        "version": "15",
        "extensions": ["pgvector"],
        "replicas": 3,
        "backup": "daily"
      }
    }
  ]
}
```

#### Get Health Status

```http
GET /v1/health
```

**Response**:

```json
{
  "status": "healthy",
  "version": "0.1.0",
  "llm": {
    "provider": "openai",
    "model": "gpt-4",
    "available": true
  },
  "knowledge": {
    "documents": 1250,
    "last_update": "2026-01-16T01:00:00Z"
  },
  "rag": {
    "enabled": true,
    "embeddings": 1250,
    "search_latency_ms": 45
  },
  "uptime_seconds": 86400
}
```

## MCP Tool Integration

### Available Tools

The AI Service registers tools with the MCP server for LLM access:

```rust
// Tools available to LLM
tools = [
  "create_infrastructure",
  "analyze_configuration",
  "generate_policies",
  "get_recommendations",
  "query_knowledge_base",
  "estimate_costs",
  "check_compatibility",
  "validate_nickel"
]
```

### Tool Definitions

```json
{
  "name": "create_infrastructure",
  "description": "Create infrastructure from natural language description",
  "parameters": {
    "type": "object",
    "properties": {
      "request": {"type": "string"},
      "provider": {"type": "string"},
      "context": {"type": "object"}
    },
    "required": ["request"]
  }
}
```

## Knowledge Base

### Structure

```text
knowledge/
├── infrastructure/         # Infrastructure patterns
│   ├── kubernetes/
│   ├── databases/
│   ├── networking/
│   └── security/
├── patterns/               # Design patterns
│   ├── high-availability/
│   ├── disaster-recovery/
│   └── performance/
├── providers/              # Provider-specific docs
│   ├── aws/
│   ├── upcloud/
│   └── hetzner/
└── best-practices/         # Best practices
    ├── security/
    ├── operations/
    └── cost-optimization/
```

### Updating Knowledge

```bash
# Add new knowledge document
curl -X POST  [http://localhost:9091/v1/knowledge/add](http://localhost:9091/v1/knowledge/add) \
  -H "Content-Type: application/json" \
  -d '{
    "category": "kubernetes",
    "title": "HA Kubernetes Setup",
    "content": "..."
  }'

# Update embeddings
curl -X POST  [http://localhost:9091/v1/knowledge/reindex](http://localhost:9091/v1/knowledge/reindex)

# Get knowledge status
curl  [http://localhost:9091/v1/knowledge/status](http://localhost:9091/v1/knowledge/status)
```

## DAG Execution

### Workflow Planning

The AI Service uses DAGs to plan complex infrastructure deployments:

```text
Validate Config
    ├→ Create Network
    │   └→ Create Nodes
    │       └→ Install Kubernetes
    │           ├→ Add Monitoring (optional)
    │           └→ Setup Backup (optional)
    │
    └→ Verify Compatibility
        └→ Estimate Costs
```

### Task Execution

```bash
# Execute DAG workflow
curl -X POST  [http://localhost:9091/v1/workflow/execute](http://localhost:9091/v1/workflow/execute) \
  -H "Content-Type: application/json" \
  -d '{
    "dag": {
      "tasks": [
        {"name": "validate", "action": "validate_config"},
        {"name": "network", "action": "create_network", "depends_on": ["validate"]},
        {"name": "nodes", "action": "create_nodes", "depends_on": ["network"]}
      ]
    }
  }'
```

## Performance Characteristics

### Latency

| Operation | Latency |
| --- | --- |
| Intent recognition | 50-100ms |
| Knowledge retrieval | 100-200ms |
| LLM inference | 2-5 seconds |
| Nickel generation | 500ms-1s |
| DAG planning | 100-500ms |
| Policy generation | 1-2 seconds |

### Throughput

- **Concurrent requests**: 100+
- **QPS**: 50+ requests/second
- **Knowledge search**: <50ms for 1000+ documents

### Resource Usage

- **Memory**: 500MB-2GB (with cache)
- **CPU**: 1-4 cores
- **Storage**: 10GB-50GB (knowledge base)
- **Network**: 10Mbps-100Mbps (LLM requests)

## Monitoring & Observability

### Metrics

```bash
# Prometheus metrics exposed at /metrics
provisioning_ai_requests_total{endpoint="/v1/infrastructure/create"}
provisioning_ai_request_duration_seconds{endpoint="/v1/infrastructure/create"}
provisioning_ai_llm_tokens{provider="openai", model="gpt-4"}
provisioning_ai_knowledge_documents_total
provisioning_ai_cache_hit_ratio
```

### Logging

```bash
# View AI Service logs
provisioning logs service ai-service --tail 100

# Debug mode
PROVISIONING_AI_LOG_LEVEL=debug provisioning service start ai-service
```

## Troubleshooting

### LLM Connection Issues

```bash
# Test LLM connection
curl -X POST  [http://localhost:9091/v1/health](http://localhost:9091/v1/health)

# Check configuration
provisioning config get ai.llm

# View logs
provisioning logs service ai-service --filter "llm| \ openai"
```

### Slow Knowledge Retrieval

```bash
# Check knowledge base status
curl  [http://localhost:9091/v1/knowledge/status](http://localhost:9091/v1/knowledge/status)

# Reindex embeddings
curl -X POST  [http://localhost:9091/v1/knowledge/reindex](http://localhost:9091/v1/knowledge/reindex)

# Monitor RAG performance
curl  [http://localhost:9091/v1/rag/benchmark](http://localhost:9091/v1/rag/benchmark)
```

## Related Documentation

- [AI Architecture](./ai-architecture.md) - System design
- [RAG & Knowledge](./rag-and-knowledge.md) - Knowledge retrieval
- [MCP Server](../architecture/component-architecture.md#mcp-server) - Model Context Protocol
- [Orchestrator](../architecture/component-architecture.md#orchestrator) - Workflow execution
