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

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

### 2. Start Cloud Endpoint

```bash
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).

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

**POST /api/config/default**
Set default provider.

```bash
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.

```bash
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).

```bash
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.

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

### Generation

**POST /api/generate**
Generate response from selected provider.

```bash
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.

```bash
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.

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

**GET /api/health**
Health check.

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

---

## Environment Variables

For security, use environment variables instead of hardcoding keys:

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

```python
# 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):

```json
{
  "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

```bash
#!/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

```python
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

```python
# 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)

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

```python
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

```dockerfile
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

```ini
[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.

```bibtex
@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.