Vapora/provisioning/integration.md

# VAPORA Provisioning Integration Guide

Unified provisioning system combining **typedialog** (interactive forms), **Nickel** (configuration generation), and **KCL** (infrastructure-as-code) for VAPORA deployments.

## System Architecture

```
User Input → typedialog Forms → Config Generation → Deployment
                      ↓
            Nickel Schemas (vapora/)
                      ↓
            Deployment Profiles (solo/multiuser/enterprise)
                      ↓
            TOML/JSON Configuration
                      ↓
            Docker Compose / Kubernetes / KCL
```

## Workflow: From Forms to Deployment

### 1. Interactive Configuration Generation

Start with the interactive form to generate customized configuration:

```bash
cd provisioning  # From repository root

# Run interactive setup wizard
typedialog \
  --form .typedialog/vapora/forms/vapora-main-form.toml \
  --output config/runtime/vapora.custom.toml
```

**This creates:**
- `config/runtime/vapora.custom.toml` - Your customized configuration
- Includes all backend, agents, router, database, provider settings
- Ready to deploy

### 2. Or Use Predefined Profiles

For quick deployments, use example configurations:

```bash
# Development setup
cp config/examples/vapora.solo.example.toml config/runtime/vapora.toml

# Team deployment
cp config/examples/vapora.multiuser.example.toml config/runtime/vapora.toml
# Edit as needed

# Production deployment
cp config/examples/vapora.enterprise.example.toml config/runtime/vapora.toml
# Customize for your infrastructure
```

### 3. Generate via Nickel (Advanced)

For composable, mergeable configurations:

```bash
# Export to JSON
nickel export config/examples/vapora.multiuser.example.ncl > config/runtime/vapora.json

# Or create custom composition
cat > config/runtime/vapora.custom.ncl << 'EOF'
let defaults = import "../../schemas/vapora/main.ncl" in
let mode = import "../../schemas/platform/defaults/deployment/enterprise.ncl" in

std.record.merge defaults {
  backend.port = 9001,
  llm_router.providers.ollama_enabled = true,
}
EOF

nickel export config/runtime/vapora.custom.ncl > config/runtime/vapora.json
```

### 4. Deploy Configuration

#### Option A: Docker Compose

```bash
# Ensure config exists at config/runtime/vapora.toml
ls config/runtime/vapora.toml

# Use with docker-compose (backend reads vapora.toml)
docker compose up -d
```

#### Option B: Kubernetes

```bash
# Create ConfigMap from configuration
kubectl create configmap vapora-config \
  --from-file=config/runtime/vapora.toml \
  -n vapora

# Or use Kustomize
kustomize build kubernetes/overlays/production
```

#### Option C: KCL Provisioning (Advanced)

Use existing `vapora-wrksp` with generated config:

```bash
cd vapora-wrksp

# Link generated config
ln -s ../config/runtime/vapora.toml ./config.toml

# Deploy via provisioning
provisioning workflow run workflows/deploy-full-stack.yaml \
  --config config.toml
```

## File Organization

### Input: Forms (`.typedialog/`)

Interactive forms generate configurations:

```plaintext
.typedialog/vapora/
├── forms/
│   ├── vapora-main-form.toml              # Complete setup wizard
│   └── fragments/                         # Modular form fragments
│       ├── backend/auth.toml
│       ├── agents/learning-profiles.toml
│       └── llm-router/budget-enforcement.toml
```

**Features:**
- `vapora-main-form.toml` - 50+ interactive fields
- Validates port ranges, numbers, required fields
- Generates `nickel_path` mapping for Nickel integration
- User-friendly prompts and help text

### Schema: Configuration Types (`schemas/`)

Defines configuration structure:

```plaintext
schemas/
├── vapora/
│   ├── main.ncl                     # Unified service config
│   ├── backend.ncl                  # Axum REST API
│   ├── agents.ncl                   # Orchestration + learning
│   └── llm-router.ncl               # Multi-provider routing
│
└── platform/
    ├── common/helpers.ncl           # Composition utilities
    └── defaults/deployment/
        ├── solo.ncl                 # Dev mode
        ├── multiuser.ncl            # Team mode
        └── enterprise.ncl           # Production mode
```

**Features:**
- Schema-first record definition (Nickel guidelines)
- Gradual typing with defaults
- Composable via `std.record.merge`
- JSON output for all platforms

### Output: Configurations (`config/`)

Generated or manually-created configurations:

```plaintext
config/
├── examples/
│   ├── vapora.solo.example.toml          # TOML format (direct use)
│   ├── vapora.solo.example.ncl           # Nickel format (composable)
│   ├── vapora.multiuser.example.toml
│   ├── vapora.multiuser.example.ncl
│   ├── vapora.enterprise.example.toml
│   ├── vapora.enterprise.example.ncl
│   └── README.md
│
└── runtime/
    ├── vapora.toml                       # Active config (generated)
    ├── .gitkeep
    └── README.md
```

## Deployment Modes

### Solo (Development)

**Best for:** Local development, feature testing

```bash
cp config/examples/vapora.solo.example.toml config/runtime/vapora.toml
# Services on 127.0.0.1, file-based DB, no coordination
```

**Generated config includes:**
- Backend: `localhost:8001` (2 workers)
- Agents: `localhost:8002` (3 max instances)
- Router: `localhost:8003` (cost tracking disabled)
- Database: File-based SurrealDB
- Frontend: `localhost:3000`
- Security: JWT only (no TLS, no MFA)

### Multiuser (Team)

**Best for:** Team collaboration, staging environments

```bash
cp config/examples/vapora.multiuser.example.toml config/runtime/vapora.toml
# Edit for your infrastructure (SurrealDB URL, NATS cluster, etc.)
```

**Generated config includes:**
- Backend: `0.0.0.0:8001` (4 workers, MFA enabled)
- Agents: `0.0.0.0:8002` (10 instances, NATS enabled)
- Router: Cost tracking and budget enforcement (per-role limits)
- Database: Remote SurrealDB (`ws://surrealdb:8000`)
- NATS: JetStream for distributed coordination
- Security: TLS, MFA, audit logging
- Knowledge Graph: 30-day retention

### Enterprise (Production)

**Best for:** Production deployments, large organizations

```bash
cp config/examples/vapora.enterprise.example.toml config/runtime/vapora.toml
# Customize TLS certs, domains, LLM providers, backup strategy
```

**Generated config includes:**
- Backend: `0.0.0.0:8001` (8 workers, full auth)
- Agents: `0.0.0.0:8002` (50 instances, swarm enabled)
- Router: All providers enabled, aggressive cost optimization
- Database: SurrealDB cluster
- NATS: JetStream cluster
- Security: Enforced TLS, MFA, full audit logging, RBAC-ready
- Observability: Prometheus, OpenTelemetry, distributed tracing
- Knowledge Graph: 90-day retention
- Backup: Every 6 hours

## Key Features

### Cost-Aware LLM Routing

Automatic budget enforcement per role:

```toml
[llm_router.budget_enforcement]
enabled = true
window = "monthly"
near_threshold_percent = 75      # Alert at 75%
auto_fallback = true             # Fallback to cheaper provider

[llm_router.budget_enforcement.role_limits]
architect_cents = 500000         # $5000/month
developer_cents = 300000         # $3000/month
reviewer_cents = 200000          # $2000/month
testing_cents = 100000           # $1000/month
```

### Learning-Based Agent Selection

Agents improve from execution history:

```toml
[agents.learning]
enabled = true
recency_window_days = 7
recency_multiplier = 3.0         # Recent tasks weighted 3x higher

[agents.learning.scoring]
load_weight = 0.3                # Agent load importance
expertise_weight = 0.5           # Expertise profile importance
confidence_weight = 0.2          # Confidence (prevents overfitting)
```

### Knowledge Graph

Temporal execution history with learning curves:

```toml
[agents.knowledge_graph]
enabled = true
retention_days = 90              # 90-day history (enterprise mode)
causal_reasoning = true          # Understand task relationships
similarity_search = true         # Recommend past solutions
```

### Multi-Provider LLM Routing

Intelligent provider selection with cost optimization:

```toml
[llm_router.providers]
claude_enabled = true
openai_enabled = true
gemini_enabled = true
ollama_enabled = true            # Local option for cost savings

[llm_router.routing]
strategy = "cost_aware"          # Cost optimization strategy
fallback_chain = ["claude", "gpt-4", "gemini", "ollama"]
retry_attempts = 5
retry_delay = 500
```

## Customization Examples

### Example 1: Enable Ollama for Development

```toml
[providers]
ollama_enabled = true
ollama_url = "http://localhost:11434"

[llm_router.routing]
fallback_chain = ["claude", "ollama"]
```

### Example 2: Increase Agent Learning Window

```toml
[agents.learning]
recency_window_days = 30         # 30-day window instead of 7
recency_multiplier = 4.0         # Stronger recency weighting
```

### Example 3: Adjust Team Budgets

```toml
[llm_router.budget_enforcement.role_limits]
architect_cents = 1000000        # $10k/month (increased)
developer_cents = 750000         # $7.5k/month (increased)
```

### Example 4: Custom Port and TLS

```toml
[backend]
port = 9001                      # Non-standard port

[security]
tls_enabled = true
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"
```

## Integration with Existing Systems

### With Docker Compose

```yaml
# docker-compose.yml excerpt
services:
  vapora-backend:
    environment:
      VAPORA_CONFIG: /etc/vapora/vapora.toml
    volumes:
      - ./config/runtime/vapora.toml:/etc/vapora/vapora.toml:ro
```

### With Kubernetes

```yaml
# kustomization.yaml
configMapGenerator:
  - name: vapora-config
    files:
      - config/runtime/vapora.toml

resources:
  - deployment.yaml
```

### With KCL Provisioning

```bash
# Link config for KCL scripts
ln -s ../config/runtime/vapora.toml ./vapora-wrksp/config.toml

# Run provisioning
provisioning workflow run workflows/deploy-full-stack.yaml
```

## Troubleshooting

### Configuration Not Loading

1. Check path: `config/runtime/vapora.toml` must exist
2. Validate syntax: `toml-cli validate config/runtime/vapora.toml`
3. Check permissions: Must be readable by service
4. Restart services after changes

### Validation Failed

```bash
# Validate TOML
toml-cli validate config/runtime/vapora.toml

# Validate Nickel
nickel typecheck config/examples/vapora.solo.example.ncl

# Validate JSON output
nickel export config/runtime/vapora.custom.ncl | jq .
```

### Database Connection Issues

```bash
# Check SurrealDB reachability
curl -i ws://localhost:8000/health

# Update config
[database]
url = "ws://surrealdb-remote.example.com:8000"
```

### Budget Not Enforcing

1. Ensure enabled: `[llm_router.budget_enforcement] enabled = true`
2. Set provider credentials: `export ANTHROPIC_API_KEY=...`
3. Check role limits are set
4. Verify cost tracking is enabled

## Next Steps

1. **Choose deployment mode** - Solo for dev, Multiuser for teams, Enterprise for production
2. **Generate or copy configuration** - Use forms or examples
3. **Customize for your environment** - Edit database URLs, domains, budgets
4. **Validate configuration** - Run validation commands
5. **Deploy** - Use Docker Compose, Kubernetes, or KCL provisioning

## References

- **Main README**: `README.md` - Complete provisioning system
- **Examples README**: `config/examples/README.md` - Configuration options
- **VAPORA Docs**: `../../docs/architecture.md` - System architecture
- **Nickel Guideline**: `../../.claude/guidelines/nickel.md` - Configuration language
- **typedialog Docs**: Form schema reference
- **KCL Provisioning**: `vapora-wrksp/README.md` - Infrastructure as code

---

**Integration Version**: 1.0.0
**Last Updated**: January 12, 2026
**VAPORA Version**: 1.2.0