Why @hilbras/sdk?

Most LLM SDKs just wrap one provider's API. @hilbras/sdk is an AI Execution Engine that optimizes, controls, validates, and observes every request, even when you use only one provider.

Application
     │
     ▼
┌───────────────────────────────────────────────┐
│              @hilbras/sdk                     │
│                                               │
│  Model Router          Execution Policies     │
│  Structured Output     Observability Hooks    │
│  Provider Abstraction  SSRF-safe Registration │
│  Streaming & Tools     Reasoning Normalizer   │
│  Circuit Breaker       Retry & Backoff        │
│  Token Counting        Cost Enforcement       │
│  Prompt Caching        Auto-Repair Output     │
│  Middleware Pipeline   Typed Errors           │
└──────────────────────┬────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       OpenAI      Anthropic      Gemini
          │            │            │
        Groq         Ollama       Azure

Zero runtime dependencies. Runs everywhere: Node 18+, Bun, Deno, browsers, VS Code extensions, CLIs, edge runtimes.

Install

npm install @hilbras/sdk

Quick start

import { HilbrasClient } from "@hilbras/sdk";

const client = new HilbrasClient();

client.addProvider({
  name: "OpenAI",
  baseUrl: "https://api.openai.com/v1",
  authentication: { type: "bearer", apiKey: process.env.OPENAI_API_KEY! },
  adapter: "openai",
  models: [
    { id: "gpt-5.6", contextWindow: 1_048_576, maxOutputTokens: 131_072,
      capabilities: { streaming: true, tools: true, vision: true, reasoning: true, structuredOutput: true, parallelTools: true, systemPrompts: true } },
  ],
});

// Streaming
for await (const chunk of client.stream({
  provider: "OpenAI",
  model: "gpt-5.6",
  messages: [{ role: "user", content: "Hello!" }],
})) {
  if (chunk.type === "text") process.stdout.write(chunk.text);
}

// Non-streaming
const reply = await client.complete({
  provider: "OpenAI",
  model: "gpt-5.6",
  messages: [{ role: "user", content: "Hello!" }],
});

Features at a glance

| Feature | Summary | Docs | |---|---|---| | Provider abstraction | 6 built-in adapters (OpenAI, Anthropic, Gemini, Azure, Groq, Ollama) | Providers | | Streaming | Async iteration over text/reasoning/tool-call/usage/finish chunks | Getting Started | | Tool calling | Native function calling + text-embedded <tool_call> markup | Getting Started | | Structured output | Zod/Valibot schemas with automatic JSON repair | API Reference | | Model routing | Pick the best model across providers by task, cost, capabilities | API Reference | | Circuit breaker | Per-provider failure isolation with half-open recovery | API Reference | | Retry & backoff | Exponential backoff with jitter for 429/5xx/network errors | API Reference | | Cost enforcement | Atomic reservations, per-request and session budgets, streaming included | Cost & Budget | | Observability | Typed lifecycle events for OpenTelemetry/Datadog/etc. | Observability | | SSRF safety | Default-reject http://, block AWS metadata, opt-in for local Ollama | Security | | Error redaction | API keys auto-redacted from provider error bodies | Security | | Reasoning normalization | Detect & normalize <thinking> / <reasoning> tags and native fields | API Reference | | Zero runtime deps | Pure TypeScript, no transitive dependencies | — |

Documentation

• Getting Started — install, configure, first request
• Providers — adapter configuration for each provider
• Cost & Budget — budget enforcement and the reservation lifecycle
• Security — SSRF protection, opt-in flags, error redaction
• Observability — lifecycle events
• API Reference — complete type and function reference
• CHANGELOG — version history

Subpath imports

import { HilbrasClient } from "@hilbras/sdk";                   // Full SDK
import { OpenAIAdapter } from "@hilbras/sdk/adapters/openai";   // Single adapter
import type { AIProvider } from "@hilbras/sdk/adapter";         // Provider contract
import { estimateTokens } from "@hilbras/sdk/tokens";           // Token utilities
import { loadConfig } from "@hilbras/sdk/config";               // Config
import { FetchTransport } from "@hilbras/sdk/transport/fetch";  // Transport
import { validateBaseUrl } from "@hilbras/sdk";                 // SSRF guard

Development

npm install
npm run build        # Compile TypeScript
npm test             # Run 878 tests
npm run test:watch   # Watch mode
npm run lint         # Lint with oxlint

License

MIT