JuliusBrussee/caveman-setup

Sie verdrahten dieses Repository mit dem Caveman Gateway. Caveman ist ein byte-erhaltender LLM-Proxy: Im Aufzeichnungsmodus misst er, was Ihre App sendet und was das kostet, und ändert nichts anderes. Ihre Aufgabe ist eine minimale, verifizierte Integration – kein Refactoring.

Der Prompt, der Sie hierher geschickt hat, liefert vier Werte. Beziehen Sie sich darauf als:

• GATEWAY — die Gateway-Basis-URL (z.B. https://gateway.caveman.so oder http://127.0.0.1:8787)
• CAVE_API_KEY — das Gateway-Auth-Secret (behandeln wie jeden API-Key: nur als Env-Variable, niemals committen, niemals vollständig ausgeben)
• PROVIDER_KEYS — stored (Provider-Keys liegen verschlüsselt in der Caveman Cloud) oder byok (diese App sendet ihren eigenen Provider-Key pro Anfrage)
• DASHBOARD — die Dashboard-Basis-URL (z.B. https://app.caveman.so)

Fehlt ein Wert, stoppen Sie und fragen Sie danach. Raten Sie niemals eine URL oder erstellen Sie einen Key.

Regeln (nicht verhandelbar)

1. Kohärente Integration. Verdrahten Sie jede aktive LLM-Aufrufstelle über bestehende Konfiguration und verantwortungsvolle Schnittstellen. Berühren Sie jede Schicht, die die Korrektheit erfordert. Keine unnötigen Refactorings oder Formatierungsaktionen; fügen Sie eine Abstraktion nur hinzu, wenn sie die Zuständigkeit klärt oder die Lebenszykluskosten senkt.
2. Geheimnisse bleiben in Env-Variablen. CAVE_API_KEY kommt in die Env-Datei, die das Repository bereits verwendet (.env, .env.local, …). Wenn diese Datei nicht gitignoriert ist, fügen Sie sie zu .gitignore hinzu und erwähnen Sie dies. Codieren Sie den Schlüssel niemals fest im Quellcode.
3. Berichten Sie nur, was Sie beobachtet haben. Der abschließende Bericht enthält den HTTP-Status und die Nutzungszahlen aus der echten Verifikationsantwort – niemals angenommenen Erfolg. Wenn die Verifikation fehlschlägt, berichten Sie stattdessen die entsprechende Fehlervorlage.
4. Nur Aufzeichnungsmodus. Sie fügen Messung hinzu. Sie aktivieren keine Optimierung, und Sie beanspruchen keine Einsparungen – verifizierte Einsparungen sind $0, bis ein Optimierer explizit eingeschaltet wird und sein Evaluierungsgate passiert.
5. Provider-Keys sind nicht Ihre Angelegenheit. Bei PROVIDER_KEYS: stored sehen Sie niemals einen. Bei byok bleibt der vorhandene Provider-Key der App genau dort, wo er bereits ist.

Schritt 1 — Finden Sie jede aktive LLM-Aufrufstelle

Lesen Sie Abhängigkeitsdateien (package.json, requirements.txt, pyproject.toml, go.mod, Lockfiles) und durchsuchen Sie den Quellcode nach LLM-Clients:

• SDK-Imports: openai, @anthropic-ai/sdk, anthropic, ai + @ai-sdk/* (Vercel), langchain*, litellm, google-genai / @google/genai, crewai, pydantic_ai, openai-agents / agents
• Rohes HTTP an api.openai.com, api.anthropic.com, generativelanguage.googleapis.com
• Vorhandene Base-URL-Env-Variablen: OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_BASE_URL, GEMINI_BASE_URL, GOOGLE_GEMINI_BASE_URL

Listen Sie auf, was Sie gefunden haben (Datei:Zeile pro Aufrufstelle), bevor Sie Änderungen vornehmen. Wenn Sie keine LLM-Aufrufstellen finden, stoppen Sie und melden Sie die Vorlage „nichts zu verdrahten“ am Ende dieser Datei – erfinden Sie keine Integration.

Schritt 2 — Wählen Sie den App-Slug

Ein Slug benennt diese App im Gateway-Pfad: GATEWAY/w/<app>. Leiten Sie ihn aus dem Paket-/Modulnamen ab (z.B. support-bot, acme-api). Grammatik: Kleinbuchstaben [a-z0-9] zuerst, dann [a-z0-9._-], max. 64 Zeichen. Die Ausgaben für diese gesamte App werden unter diesem Slug im Dashboard gruppiert.

Schritt 3 — Verdrahten Sie jede Aufrufstelle

Das Muster ist immer dasselbe: Basis-URL → das Gateway mit /w/<app>, plus einen Auth-Header. Gateway-Auth ist x-cave-api-key: CAVE_API_KEY (Authorization: Bearer CAVE_API_KEY funktioniert auch, wo ein Header umständlich ist). Bei PROVIDER_KEYS: byok senden Sie auch x-cave-upstream-key: <den Provider-Key, den die App bereits verwendet>.

Zwei Tatsachen, die die Verdrahtung sicher machen (beide sind Gateway-erzwungen, keine Hoffnungen): Das Gateway baut die Upstream-Auth-Header von Grund auf neu auf, sodass ein Authorization-/x-api-key-Wert eines Clients niemals an den Provider weitergeleitet wird; und bei stored kommt die Upstream-Auth von der verschlüsselten Verbindung serverseitig. Im stored-Modus setzen Sie daher, wo ein SDK auf einem api-key-Parameter besteht, diesen auf den Cave-Key – er authentifiziert das Gateway und geht nicht weiter.

Exakte Formen (verwenden Sie die passende für jede Aufrufstelle – dies sind die veröffentlichten Rezepte des Produkts, keine Vorschläge):

OpenAI SDK (TS) — Chat Completions und Responses werden beide über:

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

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

Anthropic SDK (TS/Python) — das SDK hängt selbst /v1/messages an. Der x-cave-api-key-Header ist hier in beiden Modi erforderlich (der eigene Key-Parameter dieses SDKs fährt auf x-api-key, was kein Gateway-Auth-Header ist):

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

Vercel AI SDK — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1, headers: { "x-cave-api-key": ... } }); Anthropic-Modelle über 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 erbt das Modell, das Sie übergeben.

LiteLLM — pro Aufruf api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}, oder flottenweit in der LiteLLM-Proxy-config.yaml.

Rohes HTTP / alles andere — tauschen Sie den Host, behalten Sie den nativen Pfad des Providers: GATEWAY/w/<app>/v1/chat/completions (OpenAI-Protokoll) oder GATEWAY/w/<app>/v1/messages (Anthropic-Protokoll), fügen Sie die Header hinzu.

Konkret, mit dem Slug support-bot und dem gehosteten Gateway, lautet eine OpenAI-SDK-Basis-URL https://gateway.caveman.so/w/support-bot/openai/v1. Und im stored-Modus entfernen Sie jede x-cave-upstream-key-Zeile vollständig – sie ist nur-byok.

Für nicht aufgeführte Frameworks (google-genai, crewai, pydantic-ai, openai-agents) rufen Sie die entsprechende Seite unter <docs origin>/docs/integrations/ auf – gleiche Herkunft, von der dieser Skill stammt – und folgen Sie ihr.

Fügen Sie zur Env-Datei des Repos hinzu (und referenzieren Sie daraus im Code – keine Literale):

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

Schritt 4 — Mit einer echten Anfrage verifizieren

Der Benutzer hat den Setup-Prompt eingefügt, um genau dies zu autorisieren: eine kleine Verifikationsanfrage. Senden Sie sie jetzt – warten Sie nicht, um um Erlaubnis zu bitten. Eine Integration, die unverifiziert endet, weil Sie gezögert haben, ist ein schlechteres Ergebnis als eine winzige Anfrage; die Verifikation und den Bericht autonom abzuschließen, ist der Sinn dieses Skills.

Senden Sie eine minimale Anfrage durch die soeben erstellte Verdrahtung – den eigenen günstigsten Pfad der App, falls sie ein Skript dafür hat, ansonsten curl auf dem Pfad, der dem soeben verdrahteten Protokoll entspricht, mit dem eigenen Modell der App und einer kleinen Obergrenze (max_tokens ≤ 32):

# OpenAI-Protokoll-Verdrahtung:
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":"<Modell, das das Repo bereits verwendet>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Anthropic-Protokoll-Verdrahtung:
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":"<Modell, das das Repo bereits verwendet>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

(byok: -H "x-cave-upstream-key: $PROVIDER_KEY" hinzufügen.) Dies ist eine echte, kostenpflichtige Provider-Anfrage – das ist der Punkt: echter Traffic, echte Messung.

Lesen Sie die Antwort. Erfolg = HTTP 200 mit einem usage-Block. Alles andere = die passende Fehlervorlage unten.

Schritt 5 — Bericht

Enden Sie mit genau dieser Form, Werte ausgefüllt mit dem, was Sie tatsächlich getan und gesehen haben:

## Caveman ist in diesem Repository live

Verdrahtet: <n> Aufrufstelle(n) in <n> Datei(en)
  - <Datei> — <einzeilig, was geändert wurde>
App-Slug: <App> — Ausgaben für diese App werden darunter gruppiert
Verifiziert: HTTP 200 · Modell <Modell> · <in> eingehende / <aus> ausgehende Token (eine echte Anfrage)
Modus: Aufzeichnung — nur gemessen. Keine modellsichtbaren Bytes geändert, keine Optimierung
aktiviert. Verifizierte Einsparungen sind $0, bis Sie einen Optimierer einschalten und er
sein Evaluierungsgate passiert. Diese Ehrlichkeit ist das Produkt.

Sehen Sie die Ausgaben: <DASHBOARD>/traces — Ihre Anfrage ist die oberste Zeile, bepreist aus
dem öffentlichen Katalog. <DASHBOARD>/getting-started zeigt „Erste Anfrage empfangen.