# AI Architecture

Complete system architecture of Provisioning's AI capabilities, from user interface through infrastructure generation.

## System Overview

```text
┌──────────────────────────────────────────────────┐
│  User Interface Layer                            │
│  • CLI (natural language)                        │
│  • TypeDialog AI forms                           │
│  • Interactive wizards                           │
│  • Web dashboard                                 │
└────────────────────┬─────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────────┐
│  Request Processing Layer                        │
│  • Intent recognition                            │
│  • Entity extraction                             │
│  • Context parsing                               │
│  • Request validation                            │
└────────────────────┬─────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────────┐
│  Knowledge & Retrieval Layer (RAG)              │
│  • Document embedding                            │
│  • Vector similarity search                      │
│  • Keyword matching (BM25)                       │
│  • Hybrid ranking                                │
└────────────────────┬─────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────────┐
│  LLM Integration Layer                           │
│  • MCP tool registration                         │
│  • Context augmentation                          │
│  • Prompt engineering                            │
│  • LLM API calls (OpenAI, Anthropic, etc.)      │
└────────────────────┬─────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────────┐
│  Configuration Generation Layer                  │
│  • Nickel code generation                        │
│  • Schema validation                             │
│  • Constraint checking                           │
│  • Cost estimation                               │
└────────────────────┬─────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────────┐
│  Execution & Feedback Layer                      │
│  • DAG planning                                  │
│  • Dry-run simulation                            │
│  • Deployment execution                          │
│  • Performance monitoring                        │
└──────────────────────────────────────────────────┘
```

## Component Architecture

### 1. User Interface Layer

**Entry Points**:

```text
Natural Language Input
    ├─ CLI: provisioning ai "create kubernetes cluster"
    ├─ Interactive: provisioning ai interactive
    ├─ Forms: TypeDialog AI-enhanced forms
    └─ Web Dashboard: /ai/infrastructure-builder
```

**Processing**:

- Tokenization and normalization
- Command pattern matching
- Ambiguity resolution
- Confidence scoring

### 2. Intent Recognition

```text
User Request
    ↓
Intent Classification
    ├─ Create infrastructure (60%)
    ├─ Modify configuration (25%)
    ├─ Query knowledge (10%)
    └─ Troubleshoot issue (5%)
    ↓
Entity Extraction
    ├─ Resource type (server, database, cluster)
    ├─ Cloud provider (AWS, UpCloud, Hetzner)
    ├─ Count/Scale (3 nodes, 10GB)
    ├─ Requirements (HA, encrypted, monitoring)
    └─ Constraints (budget, region, environment)
    ↓
Request Structure
```

### 3. RAG Knowledge Retrieval

**Embedding Process**:

```text
Query: "Create 3 web servers with load balancer"
    ↓
Embed Query → Vector [0.234, 0.567, 0.891, ...]
    ↓
Search Relevant Documents
    ├─ Vector similarity (semantic)
    ├─ BM25 keyword matching (syntactic)
    └─ Hybrid ranking
    ↓
Top Results:
    1. "Web Server HA Patterns" (0.94 similarity)
    2. "Load Balancing Best Practices" (0.87)
    3. "Auto-Scaling Configuration" (0.76)
    ↓
Extract Context & Augment Prompt
```

**Knowledge Organization**:

```text
knowledge/
├── infrastructure/           (450 docs)
│   ├── kubernetes/
│   ├── databases/
│   ├── networking/
│   └── web-services/
├── best-practices/          (300 docs)
│   ├── high-availability/
│   ├── disaster-recovery/
│   └── performance/
├── providers/               (250 docs)
│   ├── aws/
│   ├── upcloud/
│   └── hetzner/
└── security/                (200 docs)
    ├── encryption/
    ├── authentication/
    └── compliance/
```

### 4. LLM Integration (MCP)

**Tool Registration**:

```text
LLM (GPT-4, Claude 3)
    ↓
MCP Server (provisioning-mcp)
    ↓
Available Tools:
    ├─ create_infrastructure
    ├─ analyze_configuration
    ├─ generate_policies
    ├─ estimate_costs
    ├─ check_compatibility
    ├─ validate_nickel
    ├─ query_knowledge_base
    └─ get_recommendations
    ↓
Tool Execution
```

**Prompt Engineering Pipeline**:

```text
Base Prompt Template
    ↓
Add Context (RAG results)
    ↓
Add Constraints
    ├─ Budget limit
    ├─ Region restrictions
    ├─ Compliance requirements
    └─ Performance targets
    ↓
Add Examples
    ├─ Successful deployments
    ├─ Error patterns
    └─ Best practices
    ↓
Enhanced Prompt
    ↓
LLM Inference
```

### 5. Configuration Generation

**Nickel Code Generation**:

```text
LLM Output (structured)
    ↓
Nickel Template Filling
    ├─ Server definitions
    ├─ Network configuration
    ├─ Storage setup
    └─ Monitoring config
    ↓
Generated Nickel File
    ↓
Syntax Validation
    ↓
Schema Validation (Type Checking)
    ↓
Constraint Verification
    ├─ Resource limits
    ├─ Budget constraints
    ├─ Compliance policies
    └─ Provider capabilities
    ↓
Cost Estimation
    ↓
Final Configuration
```

### 6. Execution & Feedback

**Deployment Planning**:

```text
Configuration
    ↓
DAG Generation (Directed Acyclic Graph)
    ├─ Task decomposition
    ├─ Dependency analysis
    ├─ Parallelization
    └─ Scheduling
    ↓
Dry-Run Simulation
    ├─ Check resources available
    ├─ Validate API access
    ├─ Estimate time
    └─ Identify risks
    ↓
Execution with Checkpoints
    ├─ Create resources
    ├─ Monitor progress
    ├─ Collect metrics
    └─ Save checkpoints
    ↓
Post-Deployment
    ├─ Verify functionality
    ├─ Run health checks
    ├─ Collect performance data
    └─ Store feedback for future improvements
```

## Data Flow Examples

### Example 1: Simple Request

```text
User: "Create 3 web servers with load balancer"
    ↓
Intent: Create Infrastructure
Entities: type=server, count=3, load_balancer=true
    ↓
RAG Retrieval: "Web Server Patterns", "Load Balancing"
    ↓
LLM Prompt:
"Generate Nickel config for 3 web servers with load balancer.
Context: [web server best practices from knowledge base]
Constraints: High availability, auto-scaling enabled"
    ↓
Generated Nickel:
{
  servers = [
    {name = "web-01", cpu = 4, memory = 8},
    {name = "web-02", cpu = 4, memory = 8},
    {name = "web-03", cpu = 4, memory = 8}
  ]
  load_balancer = {
    type = "application"
    health_check = "/health"
  }
}
    ↓
Configuration Generated & Validated ✓
    ↓
User Approval
    ↓
Deployment
```

### Example 2: Complex Multi-Cloud Request

```text
User: "Deploy Kubernetes to AWS, UpCloud, and Hetzner with replication"
    ↓
Intent: Multi-Cloud Infrastructure
Entities: type=kubernetes, providers=[aws, upcloud, hetzner], replicas=3
    ↓
RAG Retrieval:
    - "Multi-Cloud Kubernetes Patterns"
    - "Inter-Region Replication"
    - "AWS Kubernetes Setup"
    - "UpCloud Kubernetes Setup"
    - "Hetzner Kubernetes Setup"
    ↓
LLM Processes:
    1. Analyze multi-cloud topology
    2. Identify networking requirements
    3. Plan data replication strategy
    4. Consider regional compliance
    ↓
Generated Nickel:
    - Infrastructure definitions for each provider
    - Inter-region networking configuration
    - Replication topology
    - Failover policies
    ↓
Cost Breakdown:
    AWS: $2,500/month
    UpCloud: $1,800/month
    Hetzner: $1,500/month
    Total: $5,800/month
    ↓
Compliance Check: EU GDPR ✓, US HIPAA ✓
    ↓
Ready for Deployment
```

## Key Technologies

### LLM Providers

Supported external LLM providers:

| Provider | Models | Latency | Cost |
| --- | --- | --- | --- |
| **OpenAI** | GPT-4, GPT-3.5 | 2-3s | $0.05-0.15/1K tokens |
| **Anthropic** | Claude 3 Opus | 2-4s | $0.03-0.015/1K tokens |
| **Local (Ollama)** | Llama 2, Mistral | 5-10s | Free |

### Vector Databases

- **SurrealDB** (default): Embedded vector database with HNSW indexing
- **Pinecone**: Cloud vector database (optional)
- **Milvus**: Open-source vector database (optional)

### Embedding Models

- **text-embedding-3-small** (OpenAI): 1,536 dimensions
- **text-embedding-3-large** (OpenAI): 3,072 dimensions
- **all-MiniLM-L6-v2** (local): 384 dimensions

## Performance Characteristics

### Latency Breakdown

For a typical infrastructure creation request:

| Stage | Latency | Details |
| --- | --- | --- |
| Intent Recognition | 50-100ms | Local NLP |
| RAG Retrieval | 50-100ms | Vector search |
| LLM Inference | 2-5s | External API |
| Nickel Generation | 100-200ms | Template filling |
| Validation | 200-500ms | Type checking |
| **Total** | **2.5-6 seconds** | End-to-end |

### Concurrency

- **Concurrent Requests**: 100+ (with load balancing)
- **RAG QPS**: 50+ searches/second
- **LLM Throughput**: 10+ concurrent requests per API key
- **Memory**: 500MB-2GB (depends on cache size)

## Security Architecture

### Data Protection

```text
User Input
    ↓
Input Sanitization
    ├─ Remove PII
    ├─ Validate constraints
    └─ Check permissions
    ↓
Processing (encrypted in transit)
    ├─ TLS 1.3 to LLM provider
    ├─ Secrets stored in vault-service
    └─ Credentials never logged
    ↓
Generated Configuration
    ├─ Encrypted at rest (AES-256)
    ├─ Signed for integrity
    └─ Audit trail maintained
    ↓
Output
```

### Access Control

- API key validation
- RBAC permission checking
- Rate limiting per user/key
- Audit logging of all operations

## Extensibility

### Custom Tools

Register custom tools with MCP:

```rust
// Custom tool example
register_tool("custom-validator", | confi| g {
    validate_custom_requirements(&config)
});
```

### Custom RAG Documents

Add domain-specific knowledge:

```bash
provisioning ai knowledge import \
  --source ./custom-docs \
  --category infrastructure
```

### Fine-tuning (Future)

- Support for fine-tuned LLM models
- Custom prompt templates
- Organization-specific knowledge bases

## Related Documentation

- [AI Overview](./README.md) - Quick start
- [AI Service Crate](./ai-service-crate.md) - Microservice implementation
- [RAG & Knowledge](./rag-and-knowledge.md) - Knowledge retrieval
- [TypeDialog Integration](./typedialog-integration.md) - Form integration
- [Natural Language Infrastructure](./natural-language-infrastructure.md) - Usage guide
