caveman-setup

Vous connectez ce dépôt à la passerelle Caveman. Caveman est un proxy LLM qui préserve les octets : en mode enregistrement, il mesure ce que votre application envoie et son coût, et ne change rien d'autre. Votre travail est une intégration minimale et vérifiée — pas une refactorisation.

L'invite qui vous a envoyé ici fournit quatre valeurs. Référez-vous à elles comme :

• GATEWAY — l'URL de base de la passerelle (par ex. https://gateway.caveman.so ou http://127.0.0.1:8787)
• CAVE_API_KEY — le secret d'authentification de la passerelle (à traiter comme toute clé API : variable d'environnement uniquement, jamais commitée, jamais affichée en entier)
• PROVIDER_KEYS — stored (les clés du fournisseur vivent chiffrées dans Caveman Cloud) ou byok (cette application envoie sa propre clé fournisseur par requête)
• DASHBOARD — l'URL de base du tableau de bord (par ex. https://app.caveman.so)

Si une valeur manque, arrêtez-vous et demandez-la. Ne devinez pas d'URL et ne créez pas de clé.

Règles (non négociables)

1. Intégration cohérente. Connectez chaque point d'appel LLM en direct via la configuration existante et les jonctions responsables. Touchez chaque couche que l'exactitude exige. Pas de refactorisations ou de révisions de formatage intempestives ; n'ajoutez une abstraction que lorsqu'elle clarifie la propriété ou réduit le coût du cycle de vie.
2. Les secrets restent dans les variables d'environnement. CAVE_API_KEY va dans le fichier d'environnement que le dépôt utilise déjà (.env, .env.local, …). Si ce fichier n'est pas dans .gitignore, ajoutez-le à .gitignore et mentionnez-le. Ne codez jamais la clé en dur dans la source.
3. Signalez uniquement ce que vous avez observé. Le rapport final indique le statut HTTP et les chiffres d'utilisation de la réponse de vérification réelle — jamais un succès supposé. Si la vérification échoue, signalez le modèle d'échec approprié.
4. Mode enregistrement uniquement. Vous ajoutez de la mesure. Vous n'activez aucune optimisation, et vous ne revendiquez aucune économie — les économies vérifiées sont de 0 € tant qu'un optimiseur n'est pas explicitement activé et n'a pas passé sa porte d'évaluation.
5. Les clés du fournisseur ne sont pas vos affaires. Avec PROVIDER_KEYS: stored, vous n'en voyez jamais une. Avec byok, la clé du fournisseur existante de l'application reste exactement là où elle est déjà.

Étape 1 — Trouver chaque point d'appel LLM en direct

Lisez les fichiers de dépendances (package.json, requirements.txt, pyproject.toml, go.mod, lockfiles) et recherchez dans la source les clients LLM :

• Importations SDK : openai, @anthropic-ai/sdk, anthropic, ai + @ai-sdk/* (Vercel), langchain*, litellm, google-genai / @google/genai, crewai, pydantic_ai, openai-agents / agents
• HTTP brut vers api.openai.com, api.anthropic.com, generativelanguage.googleapis.com
• Variables d'environnement d'URL de base existantes : OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_BASE_URL, GEMINI_BASE_URL, GOOGLE_GEMINI_BASE_URL

Listez ce que vous avez trouvé (fichier:ligne par point d'appel) avant de modifier quoi que ce soit. Si vous ne trouvez aucun point d'appel LLM, arrêtez-vous et signalez le modèle « rien à connecter » à la fin de ce fichier — n'inventez pas d'intégration.

Étape 2 — Choisir un slug d'application

Un slug nomme cette application dans le chemin de la passerelle : GATEWAY/w/<app>. Dérivez-le du nom du paquet/module (par ex. support-bot, acme-api). Grammaire : minuscules [a-z0-9] d'abord, puis [a-z0-9._-], max 64 caractères. Les dépenses pour cette application entière se regroupent sous ce slug dans le tableau de bord.

Étape 3 — Connecter chaque point d'appel

Le motif est toujours le même : URL de base → la passerelle avec /w/<app>, et un en-tête d'authentification. L'authentification de la passerelle est x-cave-api-key: CAVE_API_KEY (Authorization: Bearer CAVE_API_KEY fonctionne aussi là où un en-tête est difficile). Avec PROVIDER_KEYS: byok, envoyez aussi x-cave-upstream-key: <la clé du fournisseur que l'application utilise déjà>.

Deux faits qui rendent la connexion sûre (tous deux sont appliqués par la passerelle, pas de simples espoirs) : la passerelle reconstruit les en-têtes d'authentification en amont à partir de zéro, donc une valeur Authorization/x-api-key du client n'est jamais transmise au fournisseur; et avec stored, l'authentification en amont provient de la connexion chiffrée côté serveur. Donc en mode stored, lorsqu'un SDK insiste pour un paramètre api-key, définissez-le sur la clé Cave — elle authentifie la passerelle et ne va pas plus loin.

Formes exactes (utilisez celle correspondant à chaque point d'appel — ce sont les recettes publiées du produit, pas des suggestions) :

SDK OpenAI (TS) — Chat Completions et Responses passent tous deux par :

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

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

SDK Anthropic (TS/Python) — le SDK ajoute lui-même /v1/messages. L'en-tête x-cave-api-key est requis ici dans les deux modes (le propre paramètre de clé de ce SDK emprunte x-api-key, qui n'est pas un en-tête d'authentification de passerelle) :

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

SDK Vercel AI — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1, headers: { "x-cave-api-key": ... } }) ; modèles Anthropic via 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 hérite du modèle que vous lui transmettez.

LiteLLM — par appel api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}, ou à l'échelle de la flotte dans config.yaml du proxy LiteLLM.

HTTP brut / autre — échangez l'hôte, conservez le chemin natif du fournisseur : GATEWAY/w/<app>/v1/chat/completions (protocole OpenAI) ou GATEWAY/w/<app>/v1/messages (protocole Anthropic), ajoutez le(s) en-tête(s).

Concrètement, avec le slug support-bot et la passerelle hébergée, une URL de base du SDK OpenAI se lit https://gateway.caveman.so/w/support-bot/openai/v1. Et en mode stored, supprimez entièrement chaque ligne x-cave-upstream-key — elle est uniquement pour byok.

Pour les frameworks non listés (google-genai, crewai, pydantic-ai, openai-agents), consultez la page correspondante sous <docs origin>/docs/integrations/ — même origine d'où vient ce skill — et suivez-la.

Ajoutez au fichier d'environnement du dépôt (et référencez-le depuis le code — pas de littéraux) :

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

Étape 4 — Vérifier avec une seule requête réelle

L'utilisateur a collé l'invite de configuration pour autoriser exactement cela : une petite requête de vérification. Envoyez-la maintenant — ne faites pas de pause pour en demander la permission. Une intégration qui se termine sans vérification parce que vous avez hésité est un résultat pire qu'une minuscule requête ; terminer la vérification et le rapport de manière autonome est l'objectif de ce skill.

Envoyez une seule requête minimale via la connexion que vous venez de construire — le chemin le moins coûteux de l'application lui-même s'il a un script pour cela, sinon curl sur le chemin correspondant au protocole que vous venez de connecter avec le propre modèle de l'application et un petit plafond (max_tokens ≤ 32) :

# Connexion protocole 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":"<modèle que le dépôt utilise déjà>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Connexion protocole 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":"<modèle que le dépôt utilise déjà>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

(byok : ajoutez -H "x-cave-upstream-key: $PROVIDER_KEY".) Il s'agit d'une seule requête réelle et facturable au fournisseur — c'est le but : trafic réel, mesure réelle.

Lisez la réponse. Succès = HTTP 200 avec un bloc usage. Tout autre chose = le modèle d'échec correspondant ci-dessous.

Étape 5 — Rapporter

Terminez exactement avec cette forme, les valeurs remplies à partir de ce que vous avez réellement fait et vu :

## Caveman est actif dans ce dépôt

Connecté : <n> point(s) d'appel dans <n> fichier(s)
  - <fichier> — <une ligne : ce qui a changé>
Slug d'application : <app> — les dépenses de cette application se regroupent sous celui-ci
Vérifié : HTTP 200 · modèle <modèle> · <entrée> jetons d'entrée / <sortie> jetons de sortie (une seule requête réelle)
Mode : enregistrement — mesuré uniquement. Aucun octet visible par le modèle modifié, aucune optimisation
activée. Les économies vérifiées sont de 0 € jusqu'à ce que vous activiez un optimiseur et qu'il
passe sa porte d'évaluation. Cette honnêteté est le produit.

Voir les dollars : <DASHBOARD>/traces — votre requête est la première ligne, tarifée à partir du
catalogue public. <DASHBOARD>/getting-started passe à « Première requête reçue. »

Vous voulez que les dépenses soient réparties par workflow (par ex. réponse-support vs résumé-nocturne), pas
seulement par application ? Dites « découvrir workflows » — j'irai chercher <docs origin>/docs/discover-workflows.md
et étiqueterai chaque point d'appel par le travail qu'il effectue.

Modèles d'échec (à utiliser textuellement, remplis — jamais adoucis)

• Rien à connecter : « Je n'ai trouvé aucun point d'appel LLM dans ce dépôt (recherche dans les SDKs, HTTP fournisseur brut, variables d'environnement d'URL de base). Si ce dépôt exécute un agent de codage plutôt que de livrer du code LLM, utilisez caveman wrap <agent> à la place — voir /getting-started. »
• Passerelle inaccessible : « La requête de vérification n'a pas pu atteindre GATEWAY (). La connexion est en place mais non vérifiée — rien ne sera mesuré jusqu'à ce que la passerelle soit accessible. Vérifiez l'URL et le réseau, puis réexécutez la commande curl de vérification ci-dessus. »
• 401 cave_invalid_api_key : « La passerelle a rejeté CAVE_API_KEY. Créez une nouvelle clé à /getting-started et mettez à jour le fichier d'environnement ; la connexion elle-même est inchangée. »
• 404 cave_route_not_found : « La passerelle n'a trouvé aucune route — généralement un slug /w/ mal formé (minuscules [a-z0-9] d'abord, puis [a-z0-9._-], max 64) ou un chemin qui ne correspond pas au protocole du SDK. Corrigez l'URL et revérifiez. »
• Erreur du fournisseur (4xx/5xx via passerelle) : signalez le statut + le corps textuellement ; la passerelle est accessible et l'authentification a réussi, l'appel en amont a échoué — généralement un problème de clé fournisseur ou de nom de modèle dans l'application elle-même.

Ne signalez jamais un succès sur l'un de ces cas. Une intégration non vérifiée est signalée comme non vérifiée.