@hilbras/sdk weekly downloads statistics

@hilbras/sdk

Provider-agnostic AI execution engine for TypeScript. Streaming, tool calling, structured output, circuit breaker, retry, reasoning normalization, cost enforcement, plugin system, RBAC, SLA monitoring, A/B testing, and SSRF-safe provider registration — for OpenAI, Anthropic, Gemini, Azure, Groq, Ollama, Bedrock, Vertex AI, HuggingFace, Deepgram, ElevenLabs, Voyage AI, and Cohere Rerank. Zero runtime dependencies.

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.

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

Install

React (optional)

Quick start

Configuration

Per-client tokenizer

By default, token counting uses a heuristic word-based estimator. Pass a custom tokenizer to scope it to a single client instance:

v2.5.0+: The global setTokenizer() / getTokenizer() singletons are deprecated. Use the per-client tokenizer config instead to avoid cross-client interference.

Middleware

Wrap the transport with middleware for auth, logging, or custom transforms. Middleware runs on every request (including retries) for the client:

You can also use MiddlewareTransport directly to wrap any transport:

Configuration

v3.3 adds a typed configuration resolver with explicit precedence and secret-safe diagnostics:

See Configuration and the v3.2 migration guide.

Features at a glance

| Feature | Summary | Docs |

| Provider abstraction | 23 adapters (OpenAI, Anthropic, Gemini, Azure, Groq, Ollama, Bedrock, Vertex AI, HuggingFace, Deepgram, ElevenLabs, Voyage AI, Cohere Rerank) | Providers | | Streaming | Async iteration over text/reasoning/tool-call/usage/finish chunks | Getting Started | | Tool calling | Native function calling + text-embedded markup | Getting Started | | Structured output | Schema validation 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 | | Plugin system | Lifecycle hooks (onRequest/onResponse/onError) for extensibility | API Reference | | RBAC | Role-based access control with provider/model restrictions and per-role rate limiting | Security | | SLA monitoring | Latency, error rate, and availability tracking with breach alerts | Observability | | Cost alerts | Configurable threshold alerts via webhook or callback | Cost & Budget | | A/B prompt testing | Compare prompt variants against datasets with built-in metrics | Eval | | 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 / tags and native fields | API Reference | | Per-client tokenizer | Scoped BPE tokenizer per client instance — no global singletons | API Reference | | Configuration resolver | Typed layered configuration with strict validation and redacted diagnostics | Configuration | | Authorization enforcement | RBAC that actually evaluates, enforced tool policy, body-bound request signing with replay protection | Security | | Middleware pipeline | Transport-level middleware: auth headers, logging, custom request/response transforms | API Reference | | Agent framework | ToolLoopAgent, ReActAgent, PlanAndExecuteAgent with approval, budget, cost tracking | Agent | | Evaluation | LLM output evaluation with built-in metrics (exact_match, similarity, toxicity) | Eval | | React hooks | useChat, useCompletion, useCost with streaming, abort, retry | React | | Framework hooks | Vue, Svelte, Solid, Qwik, Angular, Next.js, Astro, Remix | Frameworks | | RAG primitives | VectorStore, Retriever, RAGPipeline, chunking | RAG | | Provider catalog | Runtime provider/model discovery with search | Catalog | | CLI | hilbras CLI — chat REPL, provider benchmarking, cost reports, dashboard | CLI | | Migration | Guide from Vercel AI SDK | Migration | | Fine-tuning | Export training data in 6 formats, data splitting, quality validation | Fine-tune | | Scaffolding | npx create-hilbras-app project scaffolding | CLI | | Zero runtime deps | Pure TypeScript, no transitive dependencies | — |

What's New in v3.4.0

Authorization now enforces. config.rbac was accepted by the configuration resolver but read by nothing, and even when the RBAC middleware was wired up manually its permission check was unreachable: it read provider from the request body, which no adapter sends. RBAC now resolves the provider from the request URL, maps caller identity onto a role, and enforces the result. A configured rbac block is enforced by the client automatically, and a malformed policy is rejected at construction instead of degrading to "no restrictions".

Tool policy is enforced. allowedTools and deniedTools were declared, overlap-checked, and then ignored. The client now rejects a request that names a denied tool, and ToolLoopAgent refuses to execute one. See getToolPolicy().

Request signing binds the body. The HMAC signature covered the method, path, and configured headers, but not the request body: the body digest was emitted as an unsigned header, and verify() trusted a received digest header rather than recomputing it. The new v2 profile binds the body, the key id, and a nonce, and recomputes the digest from the received bytes. The v1 wire format is frozen and unchanged, so existing verifiers keep working.…

Description from the npm listing.