SDK reference

@gigadrive/lupe-sdk lets you run a lupe review from your own code — a build script, a bot, a custom CI step — and get back typed findings, a summary, and a cost breakdown. The surface is a plain Promise-based facade: you pass an options object and await a result.

Install

pnpm add @gigadrive/lupe-sdk

The package ships two functions:

• reviewDiff(options) — review a raw unified diff string or a local git range.
• reviewPullRequest(options) — fetch a GitHub PR diff, review it, and optionally post the review back.

Both return a ReviewResult (reviewPullRequest adds a posted flag).

The AI config

Every review needs an ai object describing which provider and models to use. This mirrors the ai section of .lupe.yaml.

See providers and models for the full provider matrix.

reviewDiff(options)

Review a diff you already have, or a range in a local checkout.

Provide either diff (a raw unified diff string) or a base/head range against rootDir. All of the shared tuning knobs are also accepted.

reviewPullRequest(options)

Fetch a pull request's diff over the GitHub API, review it, and — when you opt in — post the result as one batched review with inline comments and a sticky summary.

In addition to ai, rootDir, and the shared tuning knobs:

Posting requires both post: true and a headSha. With either missing, the review runs but nothing is written to GitHub, and posted is false.

reviewPullRequest returns a ReviewResult extended with a posted: boolean.

ReviewResult

Both functions resolve to this shape:

Each Finding carries ruleId, title, path, startLine/endLine, side, severity, category, message, an optional suggestion, a confidence score, and grounding evidence. See findings and output for the full model and the SARIF shape.

cost reports { usage, costUsd, byModel }, where usage breaks down into inputTokens, outputTokens, cacheReadTokens, and cacheCreationTokens.

ReviewTuning

These knobs are shared by both functions and mirror the keys in .lupe.yaml. All are optional.

Severity is one of critical, high, medium, low, info. Category is one of correctness, security, performance, concurrency, error-handling, resource-leak, api-misuse, data-loss, maintainability, style, test, docs. See cost and budget for how maxCostUsd and modelPrices interact.

Examples

Review a raw diff string

import { readFileSync } from 'node:fs';
import { reviewDiff } from '@gigadrive/lupe-sdk';

const diff = readFileSync('changes.diff', 'utf8');

const result = await reviewDiff({
  ai: {
    provider: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  diff,
  confidenceThreshold: 0.6,
  maxCostUsd: 1.5,
});

for (const finding of result.findings) {
  console.log(`[${finding.severity}] ${finding.path}:${finding.startLine} — ${finding.title}`);
}

console.log(`\n${result.findings.length} findings · $${result.cost.costUsd.toFixed(4)}`);

Review a pull request and post the result

import { reviewPullRequest } from '@gigadrive/lupe-sdk';

const result = await reviewPullRequest({
  ai: {
    provider: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  github: {
    owner: 'gigadrive',
    repo: 'lupe',
    number: 42,
    token: process.env.GITHUB_TOKEN!,
  },
  headSha: process.env.HEAD_SHA!,
  post: true,
  minSeverityToComment: 'medium',
});

console.log(`Posted: ${result.posted} · ${result.findings.length} findings`);

Related

• Configuration — the .lupe.yaml keys these options mirror.
• Findings and output — the Finding model and SARIF output.
• Cost and budget — budgets, price overrides, and cost accounting.