# RAG & Knowledge Base

The RAG (Retrieval Augmented Generation) system enhances AI-generated infrastructure with
domain-specific knowledge. It retrieves relevant documentation, best practices, and patterns to
inform infrastructure recommendations.

## Architecture

### Components

```text
User Query
    ↓
Query Embedder (text-embedding-3-small)
    ↓
Vector Similarity Search (SurrealDB)
    ↓
Knowledge Retrieval (semantic matching)
    ↓
Context Augmentation
    ↓
LLM Processing (with knowledge context)
    ↓
Infrastructure Recommendation
```

### Knowledge Flow

```text
Documentation Input
    ↓
Document Chunking (512 tokens)
    ↓
Semantic Embedding
    ↓
Vector Storage (SurrealDB)
    ↓
Similarity Indexing
    ↓
Query Time Retrieval
```

## Knowledge Base Organization

### Document Categories

| Category | Purpose | Examples |
| --- | --- | --- |
| **Infrastructure** | IaC patterns and templates | Kubernetes, databases, networking |
| **Best Practices** | Operational guidelines | HA patterns, disaster recovery |
| **Provider Guides** | Cloud provider documentation | AWS, UpCloud, Hetzner specifics |
| **Performance** | Optimization guidelines | Resource sizing, caching strategies |
| **Security** | Security hardening guides | Encryption, authentication, compliance |
| **Troubleshooting** | Common issues and solutions | Performance, deployment, debugging |

### Document Structure

```yaml
id: "doc-k8s-ha-001"
category: "infrastructure"
subcategory: "kubernetes"
title: "High Availability Kubernetes Cluster Setup"
tags: ["kubernetes", "high-availability", "production"]
created: "2026-01-10T00:00:00Z"
updated: "2026-01-16T00:00:00Z"

content: |
  # High Availability Kubernetes Cluster

  For production Kubernetes deployments, ensure:
  - Minimum 3 control planes
  - Distributed across availability zones
  - etcd with persistent storage
  - CNI plugin with network policies

embedding: [0.123, 0.456]
metadata:
  provider: ["aws", "upcloud", "hetzner"]
  environment: ["production"]
  cost_profile: "medium"
```

## RAG Retrieval Process

### Similarity Search

When processing a user query, the system:

1. **Embed Query**: Convert natural language to vector
2. **Search Index**: Find similar documents (cosine similarity > threshold)
3. **Rank Results**: Score by relevance
4. **Extract Context**: Select top N chunks
5. **Augment Prompt**: Add context to LLM request

**Example**:

```bash
User Query: "Create a Kubernetes cluster in AWS with auto-scaling"

Vector Embedding: [0.234, 0.567, 0.891]

Top Matches:
1. "HA Kubernetes Setup" (similarity: 0.94)
2. "AWS Auto-Scaling Patterns" (similarity: 0.87)
3. "Kubernetes Security Hardening" (similarity: 0.76)

Retrieved Context:
- Minimum 3 control planes for HA
- Use AWS ASGs with cluster autoscaler
- Enable Pod Disruption Budgets
- Configure network policies

LLM Prompt with Context:
"Create a Kubernetes cluster with the following context:
[...retrieved knowledge...]
User request: Create a Kubernetes cluster in AWS with auto-scaling"
```

### Configuration

```toml
[rag]
enabled = true
similarity_threshold = 0.75
max_results = 5
chunk_size = 512
chunk_overlap = 50

[embeddings]
model = "text-embedding-3-small"
provider = "openai"
cache_embeddings = true

[vector_store]
backend = "surrealdb"
index_type = "hnsw"
ef_construction = 400
ef_search = 200

[retrieval]
bm25_weight = 0.3
semantic_weight = 0.7
date_boost = 0.1
```

## Managing Knowledge

### Adding Documents

**Via API**:

```bash
curl -X POST  [http://localhost:9091/v1/knowledge/add](http://localhost:9091/v1/knowledge/add) \
  -H "Content-Type: application/json" \
  -d '{
    "category": "infrastructure",
    "title": "PostgreSQL HA Setup",
    "content": "For production PostgreSQL: 3+ replicas, streaming replication",
    "tags": ["database", "postgresql", "ha"],
    "metadata": {
      "provider": ["aws", "upcloud"],
      "environment": ["production"]
    }
  }'
```

**Batch Import**:

```bash
# Import from markdown files
provisioning ai knowledge import \
  --source ./docs/knowledge \
  --category infrastructure \
  --auto-tag

# Import from existing documentation
provisioning ai knowledge import \
  --source provisioning/docs/src \
  --recursive
```

### Organizing Knowledge

```bash
# List knowledge documents
provisioning ai knowledge list --category infrastructure

# Search knowledge base
provisioning ai knowledge search "kubernetes high availability"

# View document
provisioning ai knowledge view doc-k8s-ha-001

# Update document
provisioning ai knowledge update doc-k8s-ha-001 \
  --content "Updated content..." \
  --tags "kubernetes,ha,production,v1.28"

# Delete document
provisioning ai knowledge delete doc-k8s-ha-001
```

### Reindexing

```bash
# Reindex all documents
provisioning ai knowledge reindex --all

# Reindex specific category
provisioning ai knowledge reindex --category infrastructure

# Check indexing status
provisioning ai knowledge index-status

# Rebuild vector index
provisioning ai knowledge rebuild-vectors --model text-embedding-3-small
```

## Knowledge Query API

### Search Endpoint

```http
POST /v1/knowledge/search
Content-Type: application/json

{
  "query": "kubernetes cluster setup",
  "category": "infrastructure",
  "tags": ["kubernetes"],
  "limit": 5,
  "similarity_threshold": 0.75,
  "metadata_filter": {
    "provider": ["aws", "upcloud"],
    "environment": ["production"]
  }
}
```

**Response**:

```json
{
  "results": [
    {
      "id": "doc-k8s-ha-001",
      "title": "High Availability Kubernetes Cluster",
      "category": "infrastructure",
      "similarity": 0.94,
      "excerpt": "For production Kubernetes deployments, ensure minimum 3 control planes",
      "tags": ["kubernetes", "ha", "production"],
      "metadata": {
        "provider": ["aws", "upcloud", "hetzner"],
        "environment": ["production"]
      }
    }
  ],
  "search_time_ms": 45,
  "total_matches": 12
}
```

## Knowledge Quality

### Maintenance

```bash
# Check knowledge quality
provisioning ai knowledge quality-report

# Remove duplicate documents
provisioning ai knowledge deduplicate

# Fix broken references
provisioning ai knowledge validate-refs

# Update outdated docs
provisioning ai knowledge mark-outdated \
  --category infrastructure \
  --older-than 180d
```

### Metrics

```bash
# Knowledge base statistics
curl  [http://localhost:9091/v1/knowledge/stats](http://localhost:9091/v1/knowledge/stats)
```

**Response**:

```json
{
  "total_documents": 1250,
  "total_chunks": 8432,
  "categories": {
    "infrastructure": 450,
    "security": 200,
    "best_practices": 300
  },
  "embedding_coverage": 0.98,
  "indexed_chunks": 8256,
  "vector_index_size_mb": 245,
  "last_reindex": "2026-01-15T23:00:00Z"
}
```

## Hybrid Search

RAG uses hybrid search combining semantic and keyword matching:

```text
BM25 Score (Keyword Match): 0.7
Semantic Score (Vector Similarity): 0.92

Hybrid Score = (0.3 × 0.7) + (0.7 × 0.92)
             = 0.21 + 0.644
             = 0.854

Relevance: High ✓
```

### Configuration

```toml
[hybrid_search]
bm25_weight = 0.3
semantic_weight = 0.7
```

## Performance

### Retrieval Latency

| Operation | Latency |
| --- | --- |
| Embed query (512 tokens) | 100-200ms |
| Vector similarity search | 20-50ms |
| BM25 keyword search | 10-30ms |
| Hybrid ranking | 5-10ms |
| Total retrieval | 50-100ms |

### Vector Index Size

- **Documents**: 1000 → 8GB storage
- **Documents**: 10000 → 80GB storage
- **Search latency**: Consistent <50ms regardless of size (with HNSW indexing)

## Security & Privacy

### Access Control

```bash
# Restrict knowledge access
provisioning ai knowledge acl set doc-k8s-ha-001 \
  --read "admin,developer" \
  --write "admin"

# Audit knowledge access
provisioning ai knowledge audit --document doc-k8s-ha-001
```

### Data Protection

- **Sensitive Info**: Automatically redacted from queries (API keys, passwords)
- **Document Encryption**: Optional at-rest encryption
- **Query Logging**: Audit trail for compliance

```toml
[security]
redact_patterns = ["password", "api_key", "secret"]
encrypt_documents = true
audit_queries = true
```

## Related Documentation

- [AI Architecture](./ai-architecture.md) - System design
- [AI Service Crate](./ai-service-crate.md) - Core microservice
- [Natural Language Infrastructure](./natural-language-infrastructure.md) - LLM usage
- [MCP Server](../architecture/component-architecture.md#mcp-server) - Tool integration
