# Configuración de opencode con SIAC

Eres un asistente de IA. El usuario te ha entregado este documento para que configures **opencode** con la plataforma **SIAC**. Sigue estos pasos exactamente.

---

## Contexto

- **SIAC** es una plataforma multi-tenant que sirve modelos de IA (GLM, DeepSeek) sobre Huawei MaaS.
- **opencode** es un asistente de IA para terminal que soporta providers compatibles con la API de OpenAI.
- SIAC expone endpoints compatibles con OpenAI en `https://ia.siac.com.co/v1`.
- Cada usuario tiene un conjunto de **modelos aprobados** — el endpoint `/v1/models` solo retorna los que el usuario tiene permiso de usar.
- El consumo de tokens se registra por usuario y se descuenta de su límite mensual, igual que los complementos de Excel/Word.

---

## Paso 1: Obtener la clave de API

Pídele al usuario su clave de API de SIAC. Debe empezar con `sk-`.

Si el usuario no tiene una clave, indícale cómo crearla:
1. Entrar a `https://ia.siac.com.co` e iniciar sesión.
2. Ir a **Ajustes** en el menú lateral.
3. Pulsar **+ Nueva clave**, darle un nombre (ej. `opencode`), y pulsar **Crear clave**.
4. Copiar la clave que aparece (no se vuelve a mostrar).

---

## Paso 2: Consultar los modelos disponibles

Ejecuta este comando para obtener los modelos aprobados para el usuario:

```bash
curl -s https://ia.siac.com.co/v1/models \
  -H "Authorization: Bearer CLAVE_DEL_USUARIO"
```

La respuesta tiene este formato:

```json
{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "created": 1719254400,
      "owned_by": "siac",
      "context_limit": 198000,
      "display_name": "GLM-5.2",
      "input_per_1m_usd": 1.82,
      "output_per_1m_usd": 5.72
    }
  ]
}
```

**Importante:** Solo aparecerán los modelos que el administrador haya aprobado para este usuario. No inventes modelos que no aparezcan en la respuesta.

Los campos `input_per_1m_usd` y `output_per_1m_usd` son el **precio efectivo en USD por 1.000.000 de tokens** para el cliente del usuario (ya incluyen el margen configurado para el tenant). Se usan para que opencode muestre en pantalla el valor consumido.

---

## Paso 3: Generar la configuración de opencode

Crea o edita el archivo `~/.config/opencode/opencode.json` con este formato, rellenando con los modelos obtenidos en el Paso 2:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "siac": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "SIAC",
      "options": {
        "baseURL": "https://ia.siac.com.co/v1",
        "apiKey": "{env:SIAC_API_KEY}"
      },
      "models": {
        "ID_DEL_MODELO": {
          "name": "DISPLAY_NAME",
          "limit": { "context": CONTEXT_LIMIT, "output": 8192 },
          "cost": {
            "input": INPUT_PER_1M_USD,
            "output": OUTPUT_PER_1M_USD,
            "cache_read": CACHE_READ_PER_1M_USD,
            "cache_write": CACHE_WRITE_PER_1M_USD
          }
        }
      }
    }
  },
  "model": "siac/ID_DEL_MODELO_PREDeterminado"
}
```

### Reglas para generar el config

1. **Por cada modelo** en la respuesta del Paso 2, añade una entrada en `models`:
   - La clave es el `id` del modelo (ej. `"glm-5.2"`).
   - `name` es el `display_name` del modelo (ej. `"GLM-5.2"`).
   - `limit.context` es el `context_limit` del modelo.
   - `limit.output` es siempre `8192`.
   - `cost.input` es el `input_per_1m_usd` del modelo, y `cost.output` es el `output_per_1m_usd`.
   - `cost.cache_read` es el `cache_read_per_1m_usd` del modelo y `cost.cache_write` el
     `cache_write_per_1m_usd` (el servidor los publica en `/v1/models`). Si no vienen,
     usa `cost.input` para ambos. En modelos normales equivalen al precio de entrada
     (SIAC cobra todos los tokens de entrada al mismo precio, sin descuento por caché):
     así el costo que muestra opencode coincide con lo que registra SIAC.
   - **Modelo Automático (`siac-auto`)**: su tarifa es variable (el router elige el
     modelo real por tarea), por eso el servidor publica
     `{ input: 0, output: 0, cache_read_per_1m_usd: 1.0, cache_write_per_1m_usd: 0 }`.
     El proxy /v1 informa el costo real de cada respuesta como "tokens de facturación"
     (`usage.prompt_tokens_details.cached_tokens`, 1 token = US$0.000001), y con
     `cache_read = 1.0` opencode muestra exactamente ese costo (precio efectivo del
     modelo resuelto, margen del tenant incluido). **No cambies esos valores.**

2. **Modelo por defecto:** usa el primer modelo de la lista, o pregúntale al usuario cuál prefiere. El campo `model` debe ser `"siac/" + id_del_modelo`.

3. **API key:** usa la interpolación `{env:SIAC_API_KEY}` en el config. Luego configura la variable de entorno:
   - **Linux/Mac:** añade `export SIAC_API_KEY="sk-..."` a `~/.bashrc` o `~/.zshrc`.
   - **Si el usuario prefiere:** puede poner la clave directamente en el JSON reemplazando `{env:SIAC_API_KEY}` por la clave real, pero es menos seguro.

4. **No inventes modelos.** Solo incluye los que aparecieron en la respuesta del Paso 2.

---

## Paso 4: Verificar la configuración

1. Asegúrate de que la variable de entorno esté configurada:
   ```bash
   echo $SIAC_API_KEY
   ```
   Debe mostrar la clave `sk-...`.

2. Verifica que el archivo se creó correctamente:
   ```bash
   cat ~/.config/opencode/opencode.json
   ```

3. Si opencode está instalado, el usuario puede ejecutarlo y seleccionar el modelo `siac/...`.

---

## Paso 5: Instrucciones de uso para el usuario

Dile al usuario:

> opencode está configurado. Para usarlo:
> 1. Abre una terminal en tu proyecto.
> 2. Ejecuta `opencode`.
> 3. Selecciona el modelo SIAC (ej. `siac/glm-5.2`).
> 4. Escribe lo que necesites.
>
> El consumo de tokens se registra automáticamente en SIAC.

---

## Ver el consumo en pantalla

Con el bloque `cost` en el config, opencode **muestra el valor consumido en USD** directamente en su pantalla:

- En el **footer/estado de la sesión** verás el costo acumulado (ej. `$0.0123`), que va subiendo a medida que conversas.
- Cada respuesta también refleja su costo individual.

Este valor usa el **precio efectivo del cliente** (precio base del modelo + el margen configurado para el tenant), así que el usuario ve exactamente lo que consume según la configuración de su empresa.

**Notas:**
- El costo mostrado en opencode es una referencia inmediata. El **registro autoritativo** del consumo (para facturación y límites mensuales) está siempre en el **panel de SIAC**.
- Los precios se "hornean" en el config al momento del setup. Si el administrador cambia los precios o el margen del cliente, **vuelve a ejecutar el setup** (Pasos 2 y 3) para refrescar los valores.

---

## Actualización de modelos

Cuando el administrador de SIAC despligue modelos nuevos y los apruebe para el usuario, este mismo documento se puede usar de nuevo para actualizar la configuración. Simplemente repite los pasos 2 y 3: el endpoint `/v1/models` retornará los modelos nuevos aprobados, y se generarán las entradas correspondientes en el config.

---

## Solución de problemas

Si el usuario reporta errores:

| Error | Causa | Solución |
|-------|-------|----------|
| `401 API key inválida o revocada` | La clave es incorrecta o fue revocada | Crear una nueva clave en Ajustes del panel SIAC |
| `403 No tienes permiso para usar el modelo` | El modelo no está aprobado para el usuario | Pedir al administrador que habilite el modelo |
| `429 límite mensual de costo` | El usuario alcanzó su límite mensual | Contactar al administrador para aumentar el límite |
| opencode no muestra modelos SIAC | El config no se cargó correctamente | Verificar que `~/.config/opencode/opencode.json` existe y es JSON válido |
| No hay conexión | No se puede acceder a SIAC | Verificar `curl -s https://ia.siac.com.co/health` |

---

## Resumen de lo que debes hacer

1. [ ] Pedir la clave de API al usuario
2. [ ] Consultar `GET https://ia.siac.com.co/v1/models` con la clave
3. [ ] Generar `~/.config/opencode/opencode.json` con los modelos retornados
4. [ ] Configurar la variable de entorno `SIAC_API_KEY`
5. [ ] Verificar que todo funcione
6. [ ] Explicarle al usuario cómo usar opencode