# Vigthoria CLI - Direct API Architecture

## Version 1.6.0 - Architecture Fix

**Date:** February 5, 2026

## Problem Statement

The CLI was experiencing "AI service unavailable" errors (502 Bad Gateway) because of an over-complicated routing architecture:

```
OLD ARCHITECTURE (BROKEN):
CLI → coder.vigthoria.io → /api/ai/chat → Model Router (4009) → Ollama
     (port 5000)           (internal)       (internal)          (internal)
```

This created multiple failure points and was only designed for server-side development, not for external users.

## Solution

Implemented direct API access from CLI to the centralized Vigthoria Models API:

```
NEW ARCHITECTURE (FIXED):
CLI → api.vigthoria.io → Model Router → Ollama/OpenRouter
      (public API)       (port 4009)    (intelligent routing)
```

## Changes Made

### 1. Caddy Configuration (`/etc/caddy/Caddyfile`)

Added new domain `api.vigthoria.io` routing directly to Model Router:

```caddyfile
api.vigthoria.io {
    # Security headers
    respond /.env* 444
    respond /.git* 444
    
    # CORS for external CLI/SDK access
    header {
        Access-Control-Allow-Origin "*"
        Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
        Access-Control-Allow-Headers "Content-Type, Authorization, X-API-Key"
    }
    
    # Proxy to Model Router with unlimited timeouts for AI inference
    reverse_proxy localhost:4009 {
        transport http {
            dial_timeout 30s
            response_header_timeout 0
            read_timeout 0
            write_timeout 0
        }
    }
}
```

### 2. CLI Configuration (`src/utils/config.ts`)

Added separate `modelsApiUrl` for AI operations:

```typescript
export interface VigthoriaCLIConfig {
  apiUrl: string;           // Coder API (auth, projects)
  modelsApiUrl: string;     // Direct AI Models API
  wsUrl: string;
  // ...
}

const defaultConfig: VigthoriaCLIConfig = {
  apiUrl: 'https://coder.vigthoria.io',
  modelsApiUrl: 'https://api.vigthoria.io',  // NEW: Direct AI Models API
  wsUrl: 'wss://coder.vigthoria.io/ws',
  // ...
};
```

### 3. API Client (`src/utils/api.ts`)

Changed chat strategy to use direct API as primary:

```typescript
// STRATEGY 1: Direct Vigthoria Models API (api.vigthoria.io)
// This is the preferred method - direct access to Model Router
const response = await this.modelRouterClient.post('/v1/chat/completions', {
  model: resolvedModel,
  messages,
  max_tokens: this.config.get('preferences').maxTokens,
  temperature: 0.7,
  stream: false,
});
```

**Removed localhost fallbacks** - CLI is for external users, not server-side testing!

## API Endpoints

### Public API (`api.vigthoria.io`)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check with model status |
| `/v1/models` | GET | List available models (51 models) |
| `/v1/chat/completions` | POST | OpenAI-compatible chat API |
| `/v1/completions` | POST | Text completion API |
| `/v1/embeddings` | POST | Text embeddings |

### Example Request

```bash
curl -X POST https://api.vigthoria.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder:7b",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'
```

## Benefits

1. **Reduced Latency**: Direct access to Model Router, no Coder proxy
2. **Better Reliability**: Fewer hops = fewer failure points
3. **OpenAI Compatible**: Standard `/v1/chat/completions` endpoint
4. **Public Access**: Works for unauthenticated users
5. **51 Models Available**: All Ollama models + OpenAI aliases + cloud fallbacks

## Model Highlights

- `qwen2.5-coder:7b` / `qwen2.5-coder:32b` - Primary coding models
- `gpt-4-turbo` (alias) → Routes to `qwen2.5-coder:32b`
- `deepseek-v3.1:671b-cloud` - Cloud model via OpenRouter
- `vigthoria_master:latest` - Custom Vigthoria model

## Upgrade Notes

Users with existing CLI installations should:

1. Update CLI: `npm update -g vigthoria-cli`
2. Clear config: `vigthoria config reset` (optional)
3. Test: `vigthoria chat`

The CLI will automatically use the new direct API endpoint.
