Modelos y contexto

Con tu suscripción Theus accedes a los 20 mejores modelos de código y razonamiento, sin traer tus propias API keys. Aquí verás cómo funciona TITAN (el modelo por defecto), qué modelos incluye el catálogo, cómo elegirlos con /model, y cómo se maneja la ventana de contexto (incluida la extendida hasta 1M).

TITAN — el modelo por defecto recomendado

titan es el orquestador propio de Theus (id de catálogo titan; alias heredado theus-router-auto). Es el modelo recomendado por defecto en el modo suscripción: si una petición al gateway no indica modelo, se atiende como TITAN. Cuando pides titan, el gateway no hace un simple proxy:

1. Planifica — el cerebro de TITAN analiza tu petición y decide si la resuelve con un solo modelo o si la descompone en subtareas repartidas entre varios.
2. Ejecuta — cada subtarea corre en el proveedor upstream del modelo elegido.
3. Sintetiza — el cerebro combina los resultados en una respuesta final coherente.

TITAN solo reparte trabajo a modelos con ruta a un proveedor operativo del gateway: nunca asigna subtareas a un modelo que no puede servirse. Tras theus login, el proveedor theus-official queda instalado apuntando a TITAN, así que no necesitas configurar nada para usarlo.

Los 20 modelos incluidos en tu suscripción

Theus es un gateway multimodelo gestionado: nosotros configuramos de forma central las API keys de cada proveedor, y tú los usas a través de tu suscripción con una sola API key de Theus. No necesitas cuentas ni claves de ningún proveedor. El catálogo vigente siempre puede consultarse en GET /v1/models.

Además, theus-local-private ejecuta un modelo 100% local en tu máquina cuando necesitas privacidad total y trabajo sin conexión, y theus-embed sirve los embeddings de la memoria semántica del proyecto vía /v1/embeddings (ver Memoria).

Suscripción (gateway) vs. proveedores locales

Theus tiene dos formas de conectar un modelo, y ambas son ciudadanas de primera clase:

• Suscripción Theus. theus login hace el flujo OAuth contra theus.pe y deja instalado el proveedor theus-official en ~/.theus/providers.json, apuntando a https://theus.pe/v1 con el modelo theus-router-auto (el alias de TITAN). A partir de ahí basta con theus: una sola API key de Theus, los ~20 modelos del catálogo, cero keys de proveedor.
• Local / BYO. Defines tus propios proveedores en ~/.theus/providers.json (o con el asistente /providers): cualquier endpoint OpenAI-compatible — un modelo local, un gateway propio, tu propia clave. Ningún servicio remoto es obligatorio para arrancar.

Para BYO avanzado por entorno, sin tocar providers.json:

# apuntar la sesión a cualquier endpoint OpenAI-compatible
export THEUS_BASE_URL="http://127.0.0.1:11434/v1"
export THEUS_MODEL="llama3.1"
export THEUS_API_KEY="local"
theus

# ignorar el proveedor principal y providers.json (motor de compatibilidad)
THEUS_DISABLE_MAIN_PROVIDER=1 theus

El comando /model

El modelo del bucle principal se elige con el comando slash /model (alias /modelo). Sin argumentos abre un selector interactivo construido sobre tu catálogo real: los modelos de los proveedores configurados en ~/.theus/providers.json (con la suscripción activa, el catálogo del gateway con TITAN al frente). También acepta un argumento directo:

/model                 # abre el selector de modelos
/model default         # vuelve al modelo por defecto de la sesión
/model sonnet          # usa un alias conocido
/model opusplan        # alias de planificación
/model proveedor:modelo  # modelo de un proveedor conectado

La pista de argumentos del comando es [modelo | proveedor:modelo]. Los alias heredados solo aparecen en el selector cuando el proveedor principal es el motor de compatibilidad que los soporta; con proveedores propios o la suscripción, el selector muestra los modelos reales del catálogo. Los alias predefinidos que Theus reconoce sin validar contra el proveedor son:

Al fijar un modelo, Theus puede añadir avisos en línea: por ejemplo, cuando el modo rápido no está soportado por el modelo elegido, o cuando la selección se factura como uso adicional. Si tu organización restringe la selección, un modelo no permitido se rechaza con un mensaje del sistema.

Conectar proveedores con /providers

El comando /providers (alias /proveedores, /proveedor, /provider, /conectar, /modelos-api) abre el asistente de proveedores para conectar modelos locales, claves de API propias y endpoints personalizados. Lo que guardes ahí se persiste en el archivo de proveedores.

El archivo ~/.theus/providers.json

La configuración de proveedores vive en ~/.theus/providers.json. Puedes apuntar a otra ruta con la variable de entorno THEUS_PROVIDERS_CONFIG. Cada entrada describe un proveedor:

{
  "providers": [
    {
      "id": "local",
      "adapter": "openai-compatible",
      "enabled": true,
      "priority": 10,
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1",
        "model": "llama3.1",
        "apiKeyEnv": "MI_API_KEY"
      }
    }
  ],
  "policy": {}
}

Campos de cada entrada:

• id: identificador del proveedor.
• adapter: para ejecución en el bucle principal debe ser openai-compatible; otros adapters se ignoran para el chat de texto.
• enabled: false desactiva la entrada.
• priority: preferencia relativa para desempatar.
• options.baseURL: endpoint OpenAI-compatible (obligatorio; sin él la entrada se descarta).
• options.model: modelo por defecto de esa entrada (si falta, se usa gpt-4o).
• Clave de API, resuelta en este orden: options.apiKey (literal) → options.apiKeyRef (referencia al llavero) → options.apiKeyEnv (nombre de una variable de entorno).

Los endpoints reconocidos automáticamente por su URL incluyen api.openai.com, api.anthropic.com, api.deepseek.com, los de googleapis.com/generativelanguage y servidores ollama locales — esos son datos técnicos de conexión, no parte de la interfaz.

Orden de selección del proveedor

Para cada turno, Theus resuelve qué proveedor usar siguiendo esta cadena. Ningún servicio remoto es obligatorio para arrancar: si nada está configurado, degrada al motor compat local.

1. Si THEUS_DISABLE_MAIN_PROVIDER=1, no se usa proveedor principal ni se enumeran los de providers.json (respeta el opt-out del dueño del equipo).
2. Variables de entorno: si existe THEUS_BASE_URL (o THEUS_OPENAI_BASE_URL), se usa ese endpoint, con THEUS_MODEL (o THEUS_OPENAI_MODEL) y THEUS_API_KEY (o OPENAI_API_KEY). Puedes nombrar el proveedor con THEUS_PROVIDER_ID.
3. El primer proveedor openai-compatible habilitado de providers.json.
4. El motor compat local como último recurso.

Además existe una cadena de fallback en tiempo de llamada: si el proveedor elegido falla (red, 4xx o 5xx), Theus reintenta con el proveedor por defecto y luego con el resto de proveedores habilitados de providers.json, deduplicados por {id, baseURL, model}, antes de degradar a compat. La variable THEUS_MODEL tiene prioridad y fija el modelo para cualquier proveedor de esta cadena.

El router local de modelos

Theus incluye un router local que decide, por turno, qué modelo atiende la petición. Está encendido por defecto (opt-out). Se apaga con un valor explícito de THEUS_ROUTER:

THEUS_ROUTER=0      # también: false, off, no  → router apagado
THEUS_ROUTER=1      # (o ausente) → router activo

El router combina una capa heurística y, opcionalmente, un juez basado en modelo para clasificar la dificultad del turno. Es fail-open: cualquier error de decisión o resolución degrada de forma segura al proveedor por defecto sin romper el turno. La metadata de modelos por proveedor conocido (familia, ventana de contexto) se combina con lo que declares en options.models[] dentro de providers.json.

El router también entiende visión: cuando el turno incluye imágenes (capturas de pantalla, fotos pegadas), la decisión se clasifica como tarea de visión y los modelos sin soporte de visión quedan descartados como candidatos, de modo que el turno siempre cae en un modelo capaz de ver la imagen.

Contexto extendido (hasta 1M)

La ventana de contexto por defecto que Theus asume para decisiones locales (auto-compactación, presupuesto de tokens) es de 200k tokens. Algunos modelos admiten una ventana extendida de hasta 1.000.000 de tokens. Theus la habilita cuando el proveedor la soporta y tú la pides explícitamente.

Cómo activarla

• Sufijo [1m]: la forma explícita de opt-in del lado del cliente. Elige un modelo con ese sufijo — por ejemplo /model opus[1m] o /model sonnet[1m] — y Theus fija la ventana efectiva en 1M, por encima de cualquier otra detección.
• Capacidad del modelo: si el proveedor anuncia un max_input_tokens mayor que el por defecto, Theus lo respeta.
• Cabecera beta de contexto 1M: cuando el modelo soporta 1M y la petición incluye la beta correspondiente, la ventana pasa a 1M.

Acceso y límites

El acceso al contexto de 1M depende de tu cuenta. Las cuentas por consumo (API/PAYG) suelen tenerlo disponible; para suscriptores de Theus AI, requiere que el uso adicional esté habilitado. Si el modelo con 1M no está disponible para tu cuenta, Theus lo indica con un mensaje del sistema y te remite a esta misma página:

https://theus.pe/docs/model-config#extended-context-with-1m

Para uso interno/avanzado, THEUS_CODE_MAX_CONTEXT_TOKENS permite fijar un tope de ventana efectiva; tiene prioridad sobre la detección de 1M, de modo que puedes limitar el contexto que Theus considera para sus decisiones locales aunque el endpoint soporte más.