docs/CLOUD_INTEGRATION_GUIDE.md

COSMOS Cloud Integration Guide

Enable optional cloud services (Azure, IBM) while maintaining local-first operation.

---

Quick Start

1. Install Cloud Support

pip install flask openai ibm-cloud-sdk-core ibm-cloud-sdk-watsonx requests

2. Start Cloud Endpoint

python cloud_endpoint.py

The dashboard opens at: http://localhost:5000

3. Configure Your Cloud Services

Azure OpenAI

1. Go to dashboard → Azure tab
2. Enable Azure OpenAI
3. Enter:
   • API Key: Your Azure OpenAI key (from portal)
   • API Endpoint: https://{resource-name}.openai.azure.com/
   • Deployment Name: Name of your deployed model (e.g., gpt-4)
   • Model Blob: Reference name (e.g., gpt-4-vision)
4. Click Test Connection

IBM Watsonx

1. Go to dashboard → IBM tab
2. Enable IBM Watsonx
3. Enter:
   • API Key: Your IBM Cloud API key
   • API Endpoint: Your Watsonx endpoint URL
   • Model Name: Model ID (e.g., granite-13b-chat-v2)
   • Model Blob: Reference (e.g., ibm/granite)
4. Click Test Connection

---

Architecture

┌─────────────────────────────────────┐
│  Genesis_Engine (Local COSMOS)      │
│  - Ollama (default)                 │
│  - Hebbian learning                 │
│  - Quantum heart                    │
└──────────────────┬──────────────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐   ┌──────────┐   ┌────────┐
│ Ollama │   │  Azure   │   │  IBM   │
│ (Local)│   │ OpenAI   │   │ Watsonx│
└────────┘   └──────────┘   └────────┘

Cloud Router (cloud_endpoint.py)
- Config management
- Credential handling
- Request routing
- Vision processing

---

API Endpoints

Configuration

GET /api/config Get current configuration (sanitized).

curl http://localhost:5000/api/config

POST /api/config/default Set default provider.

curl -X POST http://localhost:5000/api/config/default \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure"}'

POST /api/config/provider/{provider} Update provider settings.

curl -X POST http://localhost:5000/api/config/provider/azure \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://myresource.openai.azure.com/",
    "model_name": "gpt-4",
    "model_blob": "gpt-4-vision"
  }'

Credentials

POST /api/credentials/{provider} Set API credentials (from environment variable or request body).

curl -X POST http://localhost:5000/api/credentials/azure \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_AZURE_KEY"}'

POST /api/credentials/test/{provider} Test provider connectivity.

curl -X POST http://localhost:5000/api/credentials/test/azure

Generation

POST /api/generate Generate response from selected provider.

curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello, what is your name?",
    "provider": "azure"
  }'

POST /api/vision Analyze image with vision model.

curl -X POST http://localhost:5000/api/vision \
  -F "image=@photo.jpg" \
  -F "prompt=Describe this image" \
  -F "provider=azure"

Status

GET /api/status Get system status and provider info.

curl http://localhost:5000/api/status

GET /api/health Health check.

curl http://localhost:5000/api/health

---

Environment Variables

For security, use environment variables instead of hardcoding keys:

# Azure
export COSMOS_AZURE_KEY="your-azure-key-here"

# IBM
export COSMOS_IBM_KEY="your-ibm-key-here"

# Start endpoint
python cloud_endpoint.py

The dashboard will automatically load credentials from environment.

---

Integration with Genesis_Engine

Add cloud routing to your Genesis_Engine:

# In soul/loop.py or serve.py

from cloud_router import CloudConfig, CloudRouter

# Initialize
config = CloudConfig()
router = CloudRouter(config)

# Generate with cloud (or local fallback)
response = router.generate(
    prompt="Your message",
    provider="azure"  # or "ibm", "ollama"
)

# Handle vision
image_analysis = router.vision(
    image_path="/path/to/image.jpg",
    prompt="Describe this",
    provider="azure"  # gpt-4-vision
)

---

Configuration File

Cloud settings are stored in cloud_config.json (credentials not persisted):

{
  "enabled": true,
  "default_provider": "ollama",
  "providers": {
    "azure": {
      "enabled": false,
      "api_key": "[SET_VIA_ENV]",
      "api_endpoint": "https://myresource.openai.azure.com/",
      "deployment_name": "gpt-4",
      "model_blob": "gpt-4-vision",
      "temperature": 0.7,
      "timeout": 30
    },
    "ibm": {
      "enabled": false,
      "api_key": "[SET_VIA_ENV]",
      "api_endpoint": "https://api.us-south.watson-platform.net/instances/...",
      "model_name": "granite-13b-chat-v2",
      "model_blob": "ibm/granite",
      "temperature": 0.7,
      "timeout": 30
    },
    "ollama": {
      "enabled": true,
      "api_endpoint": "http://localhost:11434",
      "model_name": "cosmos-q4:latest",
      "timeout": 60
    }
  }
}

---

Example: Full Cloud Setup

Setup Script

#!/bin/bash

# Install dependencies
pip install flask openai ibm-cloud-sdk-core ibm-cloud-sdk-watsonx requests

# Set credentials
export COSMOS_AZURE_KEY="your-azure-key"
export COSMOS_IBM_KEY="your-ibm-key"

# Start endpoint
python cloud_endpoint.py

Client Code

import requests
import json

# Configure Azure as default
requests.post('http://localhost:5000/api/config/default',
              json={'provider': 'azure'})

# Generate response
response = requests.post('http://localhost:5000/api/generate',
                        json={'prompt': 'Hello!'})

print(response.json()['response'])

---

Fallback Behavior

If cloud service fails, routes to:

1. Default provider (if enabled)
2. Ollama (if available)
3. Error

# Graceful fallback
try:
    response = router.generate(prompt, provider='azure')
except Exception as e:
    print(f"Azure failed, falling back to Ollama: {e}")
    response = router.generate(prompt, provider='ollama')

---

Vision Support

Currently supported:

• ✅ Azure OpenAI (gpt-4-vision)
• ⏳ IBM Watsonx (coming soon)
• ✅ Ollama (with multimodal models)

# Azure vision
analysis = router.vision(
    image_path="photo.jpg",
    prompt="What's in this image?",
    provider="azure"
)

---

Troubleshooting

"Azure not enabled or API key not set"

• Ensure COSMOS_AZURE_KEY environment variable is set
• Or use dashboard to set credentials

"Connection timeout"

• Check endpoint URL is correct
• Verify network access to cloud service
• Increase timeout in cloud_config.json

"Invalid deployment name"

• Check deployment exists in Azure portal
• Name is case-sensitive
• Use "gpt-4" not "GPT-4"

"Model not found"

• For IBM: check model ID in Watsonx console
• For Azure: verify deployment is created

---

Security Best Practices

1. Never commit API keys to version control
2. Use environment variables for credentials
3. Rotate keys regularly in cloud portals
4. Use API key with minimal permissions if possible
5. Monitor usage in cloud provider dashboards
6. Set rate limits on endpoint if exposed

---

Performance

Typical latencies:

• Ollama (local): 50-500ms
• Azure OpenAI: 500-2000ms (network + model)
• IBM Watsonx: 500-2000ms (network + model)

For best performance:

• Use Ollama for interactive chat
• Use Azure/IBM for heavy lifting (vision, reasoning)
• Implement caching for repeated prompts

---

Advanced: Custom Providers

Extend CloudRouter to add custom providers:

class CustomRouter(CloudRouter):
    def _generate_custom(self, prompt: str, **kwargs) -> str:
        """Add your custom provider here."""
        # Implementation
        pass
    
    def generate(self, prompt, provider=None, **kwargs):
        if provider == "custom":
            return self._generate_custom(prompt, **kwargs)
        return super().generate(prompt, provider, **kwargs)

---

Deployment

Docker

FROM python:3.9
WORKDIR /cosmos
COPY cloud_*.py .
COPY templates/ templates/
RUN pip install flask openai requests

EXPOSE 5000
CMD ["python", "cloud_endpoint.py"]

Systemd Service

[Unit]
Description=COSMOS Cloud Router
After=network.target

[Service]
Type=simple
User=cosmos
WorkingDirectory=/opt/cosmos
EnvironmentFile=/etc/cosmos/cloud.env
ExecStart=/usr/bin/python3 cloud_endpoint.py
Restart=always

[Install]
WantedBy=multi-user.target

---

License & Citation

COSMOS Cloud Integration is part of the COSMOS project.

@misc{phera2026cosmos,
  title={COSMOS: A 54D Quantum-Inspired Transformer with Cloud Integration},
  author={Phera},
  year={2026},
  url={https://zenodo.org/records/17574447}
}

---

Questions? Check /docs endpoint or review cloud_router.py source code.