JuliusBrussee/caveman-setup

Estás conectando este repositorio a través del gateway de Caveman. Caveman es un proxy LLM que preserva bytes: en modo registro mide lo que tu aplicación envía y cuánto cuesta, y no cambia nada más. Tu trabajo es una integración mínima y verificada, no una refactorización.

El prompt que te envió aquí proporciona cuatro valores. Refiérete a ellos como:

• GATEWAY — la URL base del gateway (ej. https://gateway.caveman.so o http://127.0.0.1:8787)
• CAVE_API_KEY — el secreto de autenticación del gateway (trátalo como cualquier clave API: solo variable de entorno, nunca se confirma, nunca se imprime completo)
• PROVIDER_KEYS — stored (las claves del proveedor viven encriptadas en Caveman Cloud) o byok (esta aplicación envía su propia clave de proveedor por solicitud)
• DASHBOARD — la URL base del panel de control (ej. https://app.caveman.so)

Si falta algún valor, detente y pídelo. No adivines una URL ni crees una clave.

Reglas (no negociables)

1. Integración coherente. Conecta cada punto de llamada LLM en vivo a través de la configuración existente y las uniones responsables. Toca cada capa que la corrección requiera. Sin refactorizaciones o barridos de formato; añade una abstracción solo cuando aclare la propiedad o reduzca el costo del ciclo de vida.
2. Los secretos permanecen en variables de entorno. CAVE_API_KEY va al archivo de entorno que el repositorio ya usa (.env, .env.local, …). Si ese archivo no está en .gitignore, agrégalo a .gitignore y dilo. Nunca codifiques la clave en el código fuente.
3. Reporta solo lo que observaste. El informe final indica el estado HTTP y los números de uso de la respuesta de verificación real, nunca el éxito asumido. Si la verificación falla, reporta la plantilla de fallo correspondiente.
4. Solo modo registro. Estás agregando medición. No habilitas ninguna optimización, y no reclamas ningún ahorro; los ahorros verificados son $0 hasta que un optimizador se active explícitamente y pase su puerta de evaluación.
5. Las claves del proveedor no son tu problema. Con PROVIDER_KEYS: stored nunca ves una. Con byok, la clave de proveedor existente de la aplicación permanece exactamente donde ya está.

Paso 1 — Encuentra cada punto de llamada LLM en vivo

Lee los archivos de dependencias (package.json, requirements.txt, pyproject.toml, go.mod, lockfiles) y busca en el código fuente clientes LLM:

• Importaciones de SDK: openai, @anthropic-ai/sdk, anthropic, ai + @ai-sdk/* (Vercel), langchain*, litellm, google-genai / @google/genai, crewai, pydantic_ai, openai-agents / agents
• HTTP directo a api.openai.com, api.anthropic.com, generativelanguage.googleapis.com
• Variables de entorno de URL base existentes: OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_BASE_URL, GEMINI_BASE_URL, GOOGLE_GEMINI_BASE_URL

Enumera lo que encuentres (archivo:línea por punto de llamada) antes de cambiar nada. Si no encuentras ningún punto de llamada LLM, detente y reporta la plantilla "nada que conectar" al final de este archivo — no inventes una integración.

Paso 2 — Elige el slug de la aplicación

Un slug nombra esta aplicación en la ruta del gateway: GATEWAY/w/<app>. Derívalo del nombre del paquete/módulo (ej. support-bot, acme-api). Gramática: minúsculas [a-z0-9] primero, luego [a-z0-9._-], máximo 64 caracteres. El gasto de toda esta aplicación se agrupa bajo ese slug en el panel de control.

Paso 3 — Conecta cada punto de llamada

El patrón es siempre el mismo: URL base → el gateway con /w/<app>, más un encabezado de autenticación. La autenticación del gateway es x-cave-api-key: CAVE_API_KEY (también funciona Authorization: Bearer CAVE_API_KEY donde un encabezado sea incómodo). Con PROVIDER_KEYS: byok, envía también x-cave-upstream-key: <la clave de proveedor que la aplicación ya usa>.

Dos hechos que hacen segura la conexión (ambos son aplicados por el gateway, no esperanzas): el gateway reconstruye los encabezados de autenticación ascendentes desde cero, por lo que el valor Authorization/x-api-key de un cliente nunca se reenvía al proveedor; y con stored, la autenticación ascendente proviene de la conexión encriptada del lado del servidor. Así que en modo stored, cuando un SDK insiste en un parámetro api-key, establécelo a la clave Cave — autentica el gateway y no va más allá.

Formas exactas (usa la que coincida con cada punto de llamada — estas son las recetas publicadas del producto, no sugerencias):

SDK de OpenAI (TS) — Chat Completions y Responses ambos pasan por:

const client = new OpenAI({
  baseURL: `${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1`,
  apiKey: process.env.OPENAI_API_KEY,           // byok: sin cambios · stored: usa CAVE_API_KEY
  defaultHeaders: {
    "x-cave-api-key": process.env.CAVE_API_KEY!,
    // solo byok:
    "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
  },
});

SDK de OpenAI (Python) — misma forma: base_url=f"{gw}/w/<app>/openai/v1", default_headers={"x-cave-api-key": ..., "x-cave-upstream-key": ...}.

SDK de Anthropic (TS/Python) — el SDK agrega /v1/messages por sí mismo. El encabezado x-cave-api-key es obligatorio aquí en ambos modos (el propio parámetro de clave de este SDK va en x-api-key, que no es un encabezado de autenticación del gateway):

client = anthropic.Anthropic(
    base_url=f"{os.environ['CAVE_GATEWAY_URL']}/w/<app>",
    api_key=os.environ["ANTHROPIC_API_KEY"],      # byok: sin cambios · stored: usa CAVE_API_KEY
    default_headers={
        "x-cave-api-key": os.environ["CAVE_API_KEY"],
        # solo byok:
        "x-cave-upstream-key": os.environ["ANTHROPIC_API_KEY"],
    },
)

SDK de Vercel AI — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1, headers: { "x-cave-api-key": ... } }); modelos de Anthropic a través de createAnthropic({ baseURL: ${gw}/w//v1, headers: { ... } }).

LangChain / LangGraph — ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1", default_headers={...}); ChatAnthropic(base_url=f"{gw}/w/<app>", default_headers={...}). LangGraph hereda cualquier modelo que le pases.

LiteLLM — por llamada api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}, o para toda la flota en el config.yaml del proxy LiteLLM.

HTTP directo / cualquier otro — intercambia el host, mantén la ruta nativa del proveedor: GATEWAY/w/<app>/v1/chat/completions (protocolo OpenAI) o GATEWAY/w/<app>/v1/messages (protocolo Anthropic), agrega los encabezados.

Concretamente, con el slug support-bot y el gateway alojado, una URL base del SDK de OpenAI se lee como https://gateway.caveman.so/w/support-bot/openai/v1. Y en modo stored, elimina cada línea x-cave-upstream-key por completo — es solo para byok.

Para frameworks no listados (google-genai, crewai, pydantic-ai, openai-agents), obtén la página correspondiente bajo <origen de docs>/docs/integrations/ — el mismo origen del que proviene este skill — y síguela.

Agrega al archivo de entorno del repositorio (y referencia desde el código — sin literales):

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

Paso 4 — Verifica con una solicitud real

El usuario pegó el prompt de configuración para autorizar exactamente esto: una pequeña solicitud de verificación. Envíala ahora — no te detengas a pedir permiso. Una integración que termina sin verificar porque dudaste es un resultado peor que una solicitud minúscula; completar la verificación y el informe de forma autónoma es el objetivo de este skill.

Envía una solicitud mínima a través de la conexión que acabas de construir — la ruta más barata de la propia aplicación si tiene un script para ello, de lo contrario curl en la ruta que coincida con el protocolo que acabas de conectar con el modelo propio de la aplicación y un límite pequeño (max_tokens ≤ 32):

# Conexión con protocolo OpenAI:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/chat/completions" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"<modelo que el repositorio ya usa>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Conexión con protocolo Anthropic:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/messages" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"<modelo que el repositorio ya usa>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

(byok: agrega -H "x-cave-upstream-key: $PROVIDER_KEY".) Esta es una solicitud real y facturable al proveedor — ese es el objetivo: tráfico real, medición real.

Lee la respuesta. Éxito = HTTP 200 con un bloque usage. Cualquier otra cosa = la plantilla de fallo correspondiente a continuación.

Paso 5 — Reporta

Termina exactamente con esta forma, con los valores completados de lo que realmente hiciste y viste:

## Caveman está activo en este repositorio

Conectados: <n> punto(s) de llamada en <n> archivo(s)
  - <archivo> — <una línea de lo que cambió>
Slug de la aplicación: <app> — el gasto de esta aplicación se agrupa bajo él
Verificado: HTTP 200 · modelo <modelo> · <entrada> tokens de entrada / <salida> tokens de salida (una solicitud real)
Modo: registro — solo medición. Sin cambios en bytes visibles para el modelo, sin optimización
habilitada. Los ahorros verificados son $0 hasta que actives un optimizador y pase
su puerta de evaluación. Esa honestidad es el producto.

Ve los dólares: <DASHBOARD>/traces — tu solicitud es la primera fila, valorada según el
catálogo público. <DASHBOARD>/getting-started cambia a "Primera solicitud recibida."

¿Quieres dividir el gasto por flujo de trabajo (ej. respuesta-soporte vs resumen-nocturno), no solo
por aplicación? Di "descubrir flujos de trabajo" — obtendré <origen de docs>/docs/discover-workflows.md
y etiquetaré cada punto de llamada según el trabajo que realiza.

Plantillas de fallo (usa textualmente, completadas — nunca las suavices)

• Nada que conectar: "No encontré puntos de llamada LLM en este repositorio (busqué SDKs, HTTP directo a proveedores, variables de entorno de URL base). Si este repositorio ejecuta un agente de codificación en lugar de enviar código LLM, usa caveman wrap <agente> en su lugar — consulta /getting-started."
• Gateway inalcanzable: "La solicitud de verificación no pudo alcanzar GATEWAY (). La conexión está en su lugar pero no verificada — no se medirá nada hasta que el gateway sea alcanzable. Verifica la URL y la red, luego vuelve a ejecutar el curl de verificación anterior."
• 401 cave_invalid_api_key: "El gateway rechazó CAVE_API_KEY. Crea una nueva clave en /getting-started y actualiza el archivo de entorno; la conexión en sí no cambia."
• 404 cave_route_not_found: "El gateway no encontró ninguna ruta — generalmente un slug /w/ malformado (minúsculas [a-z0-9] primero, luego [a-z0-9._-], máximo 64) o una ruta que no coincide con el protocolo del SDK. Corrige la URL y vuelve a verificar."
• Error del proveedor (4xx/5xx a través del gateway): reporta el estado + el cuerpo textualmente; el gateway es alcanzable y la autenticación pasó, la llamada ascendente falló — generalmente un problema de clave de proveedor o nombre de modelo en la propia aplicación.

Nunca reportes éxito en ninguno de estos casos. Una integración no verificada se reporta como no verificada."