brainy/docs/DEPLOYMENT.md

Brainy Deployment Guide

Model Management

Brainy uses the Xenova/all-MiniLM-L6-v2 transformer model (87MB) for embeddings. The model is critical for operations and intelligently handles availability.

How It Works

1. First Use: Automatically downloads from Hugging Face → GitHub → CDN (fallback chain)
2. Cached Forever: Once downloaded, never re-downloads
3. Multiple Sources: Falls back to our GitHub/CDN if Hugging Face is unavailable
4. Smart Detection: Automatically finds models in cache, bundled, or downloads as needed

Deployment Scenarios

🚀 Standard Deployment (Recommended)

npm install @soulcraft/brainy
# Models download automatically on first use

🐳 Docker with Restricted Production

FROM node:24-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install @soulcraft/brainy
# Download models during build (internet available)
RUN npm run download-models
COPY . .

FROM node:24-slim
WORKDIR /app
COPY --from=builder /app .
# Production has models, works offline
CMD ["node", "server.js"]

⚡ Serverless (AWS Lambda)

// Lambda Layer with pre-downloaded models
process.env.TRANSFORMERS_CACHE = '/opt/models'

// Or include in deployment package
// Run locally: npm run download-models
// Then include ./models/ in your deployment zip

☸️ Kubernetes

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      initContainers:
      - name: model-downloader
        image: node:24-slim
        command: 
        - sh
        - -c
        - |
          npm install @soulcraft/brainy
          npm run download-models
        volumeMounts:
        - name: models
          mountPath: /models
      containers:
      - name: app
        volumeMounts:
        - name: models
          mountPath: /app/models
      volumes:
      - name: models
        emptyDir: {}

🔒 Air-Gapped Environment

# On machine with internet:
npm install @soulcraft/brainy
npm run download-models
tar -czf brainy-models.tar.gz models/

# On air-gapped machine:
tar -xzf brainy-models.tar.gz
# Models now available offline

Model Scripts

# Intelligent preparation (auto-detects context)
npm run prepare-models

# Force download from all sources
npm run models:download  

# Verify models exist (for CI/CD)
npm run models:verify

# Legacy download script
npm run download-models

Environment Variables

# Skip automatic model download
BRAINY_SKIP_MODEL_DOWNLOAD=true

# Allow remote model downloads in production
BRAINY_ALLOW_REMOTE_MODELS=true

# Custom model cache directory
TRANSFORMERS_CACHE=/custom/path/to/models

# Force specific model source
BRAINY_MODEL_SOURCE=github  # github | cdn | huggingface

Model Files

The complete model consists of:

• config.json (650 bytes)
• tokenizer.json (695 KB)
• tokenizer_config.json (366 bytes)
• onnx/model.onnx (87 MB)

Total: ~87.7 MB

Fallback Chain

If Hugging Face is unavailable, Brainy automatically tries:

1. GitHub Releases: github.com/soulcraftlabs/brainy-models
2. Soulcraft CDN: models.soulcraft.com (future)
3. Local Cache: Previously downloaded models

Verification

Models are verified by:

• File existence check
• Size verification (model.onnx must be ~87MB)
• SHA256 hash (optional, for high security)
• Load test (can the model actually run?)

Best Practices

1. Development: Let models auto-download on first use
2. CI/CD: Pre-download in build stage with npm run download-models
3. Production: Include models in container/deployment package
4. High Availability: Host models on your own CDN as backup

Troubleshooting

Models not downloading?

# Check network access
curl -I https://huggingface.co

# Force download with verbose output
BRAINY_VERBOSE=true npm run download-models

# Use specific source
BRAINY_MODEL_SOURCE=github npm run download-models

Models too large for deployment?

• Consider using a shared volume or layer
• Host models on your CDN and download at startup
• Use model quantization (future feature)

Verification failing?

# Check model integrity
npm run models:verify

# Re-download if corrupted
rm -rf models/
npm run download-models