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:

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:

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

# 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

# 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

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

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:

.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:

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:

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

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

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

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:

[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:

[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:

[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:

[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

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

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

Example 2: Increase Agent Learning Window

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

Example 3: Adjust Team Budgets

[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

[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

# 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

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

resources:
  - deployment.yaml

With KCL Provisioning

# 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

# 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

# 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