cobalt-ai-sdk

Runtime SDK for Cobalt. Reads prompt config from your Firestore, calls Anthropic / OpenAI / Gemini / OpenRouter on your behalf, and sends fire-and-forget execution telemetry back to Cobalt.

This is a personal-tool SDK. It assumes:

• The runtime is inside a GCP project (Cloud Functions, Cloud Run, GCE).
• That project has been registered with Cobalt via cobalt install (CLI).
• Prompt config lives in the project's own Firestore at ai_features/{function_id}/environments/{env}, populated by Cobalt's dual-write on publish.
• Provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY) are bound from Secret Manager into the function's env (also handled by cobalt install).

If you're looking for an HTTP-mode SDK with apiKey: cblt_..., that's v1.x. v2 dropped it.

Install

npm install cobalt-ai-sdk

Bind the provider secrets in your Cloud Functions v2 deployment:

import { defineSecret } from "firebase-functions/params";
const anthropic = defineSecret("ANTHROPIC_API_KEY");
const openai = defineSecret("OPENAI_API_KEY");
const google = defineSecret("GOOGLE_API_KEY");
const openrouter = defineSecret("OPENROUTER_API_KEY");

export const myFn = onRequest(
  { secrets: [anthropic, openai, google, openrouter] },
  handler,
);

Usage

import { Cobalt } from "cobalt-ai-sdk";
import * as admin from "firebase-admin";

if (!admin.apps.length) admin.initializeApp();

const cobalt = new Cobalt({
  firestore: admin.firestore(),  // required
});

const result = await cobalt.run("my_function_slug", {
  variables: { article_text: "..." },
});

console.log(result.output);

The SDK picks the provider adapter automatically from the prompt config's model_provider field, reads the matching env var (ANTHROPIC_API_KEY etc.), and calls the provider's API.

Options

new Cobalt({
  firestore: admin.firestore(),  // required
  environment: "prod",           // default "prod"
  realtime: false,               // true = onSnapshot listener instead of TTL-cached .get()
  cacheTtlMs: 60_000,            // .get() TTL when realtime=false
  executionTracing: true,        // send execution telemetry after each .run()
});

Run options

await cobalt.run("my_function_slug", {
  variables: { input: "..." },                     // {{var}} substitution
  metadata: { userId: "abc" },                     // attached to execution
  transformPrompt: (p) => ({                       // mutate the resolved prompt
    ...p,
    systemPrompt: p.systemPrompt + "\nExtra: ...",
  }),
  callModel: async (params) => {                   // BYO provider (overrides built-in)
    /* ... */
    return { outputText, promptTokens, completionTokens };
  },
  requestId: "req_xyz",
  sessionId: "sess_abc",
  userIdHash: "hashed_user_id",
});

Execution telemetry

After every successful run(), the SDK posts the execution payload to Cobalt's API. Authentication uses GCP Application Default Credentials: the SDK fetches a Google-signed ID token from the metadata server with aud=<cobalt-api-url> and sends it as Authorization: Bearer <jwt>. Cobalt's backend verifies the JWT and matches the email claim against the registered_projects collection.

Telemetry is fire-and-forget and silent on failure. If the metadata server isn't available (local dev) or Cobalt's API is down, your AI calls still succeed — the telemetry just doesn't land.

What's NOT in v2

• apiKey / apiUrl / fetchTimeoutMs options — gone. Auth is ADC; URL is hardcoded (override via COBALT_API_URL env var for testing only).
• HTTP-mode config fetching — gone. Firestore-direct is the only path.
• runtimeSource option — gone. The source label comes from registered_projects.display_name on the backend.
• anthropicApiKey option — gone. Use ANTHROPIC_API_KEY env var.

Versions

• 2.x — current. Firestore-only, four built-in providers, ADC auth. GCP-only.
• 1.x — legacy. HTTP-mode + cblt_... keys. Still published on npm for projects pinned to it.