SDK Reference

pip install noburn

from noburn import NoburnGuard

guard = NoburnGuard(
    api_key="sk-nb-xxxxxxxxxxxxxxxx",
    project_id="your-project-id",
    budget_cap_usd=10.00,
)

result = guard.check(
    model="gpt-4o",
    estimated_tokens_in=1500,
    estimated_tokens_out=500,
    end_user_id="user_abc123",   # optional — for per-user tracking
    context={"plan": "free"},    # optional — matched against policy rules
)

guard.record(
    model="gpt-4o",
    tokens_in=1423,
    tokens_out=487,
    cost_usd=0.00848,
    was_blocked=False,
    end_user_id="user_abc123",
    latency_ms=1240,
)

# Each user has independent spend tracking
result = guard.check(
    model="claude-3-5-sonnet-20241022",
    estimated_tokens_in=800,
    estimated_tokens_out=200,
    end_user_id=f"user_{request.user.id}",
)

from noburn import NoburnGuard, NoburnAuthError

guard = NoburnGuard(api_key="sk-nb-…", project_id="…", on_error="block")

try:
    result = guard.check(model="gpt-4o", estimated_tokens_in=1000, estimated_tokens_out=300)
except NoburnAuthError:
    # Invalid SDK key — fix your credentials
    raise

if result.blocked:
    handle_blocked(result.block_reason)

run = guard.start_run(budget_cap_usd=0.50)   # StartRunResult(run_id, budget_cap_usd, started_at)

result = guard.check(
    model="gpt-4o",
    estimated_tokens_in=1000,
    estimated_tokens_out=300,
    run_id=run.run_id,
)
# ... make the LLM call ...
guard.record(model="gpt-4o", tokens_in=980, tokens_out=290,
             cost_usd=0.005, was_blocked=False, run_id=run.run_id)

summary = guard.end_run(run.run_id)   # EndRunResult(status="completed" | "budget_exceeded", spend_usd, ...)

npm install @noburn/sdk

import { NoburnGuard } from '@noburn/sdk';

const guard = new NoburnGuard({
  apiKey: process.env.NOBURN_API_KEY!,
  projectId: process.env.NOBURN_PROJECT_ID!,
  budgetCapUsd: 10.00,
});

const result = await guard.check({
  model: 'gpt-4o',
  estimatedTokensIn: 1500,
  estimatedTokensOut: 500,
  endUserId: 'user_abc123',
  context: { plan: 'free' },  // optional — matched against policy rules
});

if (result.blocked) {
  return new Response('Budget exceeded', { status: 402 });
}

interface CheckResult {
  blocked: boolean;
  // 'budget_exceeded' | 'user_budget_exceeded' | 'run_budget_exceeded'
  // | 'policy_rule' | 'plan_limit_exceeded' | 'noburn_unreachable' | null
  blockReason: string | null;
  forcedModelTier: 'small' | 'big' | null;  // set by a force_small/force_big rule
  spendUsd: number;
  budgetCapUsd: number | null;
  remainingUsd: number | null;
  // Present when endUserId / runId are supplied:
  userSpendUsd?: number;
  userCapUsd?: number | null;
  userRemainingUsd?: number | null;
  runSpendUsd?: number;
  runCapUsd?: number | null;
  runRemainingUsd?: number | null;
}

await guard.record({
  model: 'gpt-4o',
  tokensIn: response.usage.prompt_tokens,
  tokensOut: response.usage.completion_tokens,
  costUsd: 0.00848,
  wasBlocked: false,
  endUserId: 'user_abc123',
  latencyMs: 1240,
});

const run = await guard.startRun({ budgetCapUsd: 0.5 });

const check = await guard.check({
  model: 'gpt-4o',
  estimatedTokensIn: 1000,
  estimatedTokensOut: 300,
  runId: run.runId,
});
// ... make the LLM call ...
await guard.record({ model: 'gpt-4o', tokensIn: 980, tokensOut: 290, costUsd: 0.005, wasBlocked: false, runId: run.runId });

const summary = await guard.endRun(run.runId); // { status: 'completed' | 'budget_exceeded', spendUsd, ... }

// middleware.ts
import { NoburnGuard } from '@noburn/sdk';

const guard = new NoburnGuard({
  apiKey: process.env.NOBURN_API_KEY!,
  projectId: process.env.NOBURN_PROJECT_ID!,
  budgetCapUsd: 50,
});

export async function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/api/ai')) {
    const userId = request.headers.get('x-user-id') ?? undefined;
    const check = await guard.check({
      model: 'gpt-4o',
      estimatedTokensIn: 1000,
      estimatedTokensOut: 500,
      endUserId: userId,
    });

    if (check.blocked) {
      return Response.json(
        { error: 'Budget exceeded', code: 'BUDGET_EXCEEDED' },
        { status: 402 }
      );
    }
  }
}

import express from 'express';
import { NoburnGuard } from '@noburn/sdk';

const guard = new NoburnGuard({ apiKey: '...', projectId: '...' });
const app = express();

app.use('/api/ai', async (req, res, next) => {
  const check = await guard.check({
    model: req.body.model ?? 'gpt-4o',
    estimatedTokensIn: 1000,
    estimatedTokensOut: 500,
    endUserId: req.user?.id,
  });

  if (check.blocked) {
    return res.status(402).json({ error: check.blockReason });
  }
  next();
});