@kreuzberg/liter-llm-node 1.4.0-rc.19

package/README.md

@@ -0,0 +1,306 @@
+# TypeScript (Node.js)
+
+<div align="center" style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0;">
+  <!-- Language Bindings -->
+  <a href="https://crates.io/crates/liter-llm">
+    <img src="https://img.shields.io/crates/v/liter-llm?label=Rust&color=007ec6" alt="Rust">
+  </a>
+  <a href="https://pypi.org/project/liter-llm/">
+    <img src="https://img.shields.io/pypi/v/liter-llm?label=Python&color=007ec6" alt="Python">
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/liter-llm">
+    <img src="https://img.shields.io/npm/v/@kreuzberg/liter-llm?label=Node.js&color=007ec6" alt="Node.js">
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/liter-llm-wasm">
+    <img src="https://img.shields.io/npm/v/@kreuzberg/liter-llm-wasm?label=WASM&color=007ec6" alt="WASM">
+  </a>
+  <a href="https://central.sonatype.com/artifact/dev.kreuzberg/liter-llm">
+    <img src="https://img.shields.io/maven-central/v/dev.kreuzberg/liter-llm?label=Java&color=007ec6" alt="Java">
+  </a>
+  <a href="https://github.com/kreuzberg-dev/liter-llm/tree/main/packages/go">
+    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/liter-llm?label=Go&color=007ec6" alt="Go">
+  </a>
+  <a href="https://www.nuget.org/packages/LiterLlm">
+    <img src="https://img.shields.io/nuget/v/LiterLlm?label=C%23&color=007ec6" alt="C#">
+  </a>
+  <a href="https://packagist.org/packages/kreuzberg/liter-llm">
+    <img src="https://img.shields.io/packagist/v/kreuzberg/liter-llm?label=PHP&color=007ec6" alt="PHP">
+  </a>
+  <a href="https://rubygems.org/gems/liter_llm">
+    <img src="https://img.shields.io/gem/v/liter_llm?label=Ruby&color=007ec6" alt="Ruby">
+  </a>
+  <a href="https://hex.pm/packages/liter_llm">
+    <img src="https://img.shields.io/hexpm/v/liter_llm?label=Elixir&color=007ec6" alt="Elixir">
+  </a>
+  <a href="https://github.com/kreuzberg-dev/liter-llm/pkgs/container/liter-llm">
+    <img src="https://img.shields.io/badge/Docker-007ec6?logo=docker&logoColor=white" alt="Docker">
+  </a>
+  <a href="https://github.com/kreuzberg-dev/homebrew-tap/blob/main/Formula/liter-llm.rb">
+    <img src="https://img.shields.io/badge/Homebrew-007ec6?logo=homebrew&logoColor=white" alt="Homebrew">
+  </a>
+  <a href="https://github.com/kreuzberg-dev/liter-llm/tree/main/crates/liter-llm-ffi">
+    <img src="https://img.shields.io/badge/C-FFI-007ec6" alt="C FFI">
+  </a>
+
+  <!-- Project Info -->
+  <a href="https://github.com/kreuzberg-dev/liter-llm/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-007ec6" alt="License">
+  </a>
+  <a href="https://docs.liter-llm.kreuzberg.dev">
+    <img src="https://img.shields.io/badge/docs-kreuzberg.dev-007ec6" alt="Docs">
+  </a>
+</div>
+
+<div align="center" style="margin: 20px 0;">
+  <picture>
+    <img width="100%" alt="kreuzberg.dev" src="https://github.com/user-attachments/assets/1b6c6ad7-3b6d-4171-b1c9-f2026cc9deb8" />
+  </picture>
+</div>
+
+<div align="center" style="margin-bottom: 20px;">
+  <a href="https://discord.gg/xt9WY3GnKR">
+    <img height="22" src="https://img.shields.io/badge/Discord-Join%20our%20community-7289da?logo=discord&logoColor=white" alt="Discord">
+  </a>
+</div>
+
+Universal LLM API client for TypeScript and Node.js. Access 143+ LLM providers through a single interface with native NAPI-RS bindings, async/await, streaming, tool calling, and full TypeScript type definitions.
+
+## Installation
+
+### Package Installation
+
+
+Install via one of the supported package managers:
+
+
+**npm:**
+
+```bash
+npm install @kreuzberg/liter-llm
+```
+
+
+**pnpm:**
+
+```bash
+pnpm add @kreuzberg/liter-llm
+```
+
+
+**yarn:**
+
+```bash
+yarn add @kreuzberg/liter-llm
+```
+
+
+### System Requirements
+
+
+- **Node.js 22+** required (NAPI-RS native bindings)
+- API keys via environment variables (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
+
+### Platform Support
+
+Pre-built binaries available for:
+
+- macOS (arm64, x64)
+- Linux (x64)
+- Windows (x64)
+
+
+## Quick Start
+
+### Basic Chat
+
+Send a message to any provider using the `provider/model` prefix:
+
+```typescript
+import { LlmClient } from "@kreuzberg/liter-llm";
+
+const client = new LlmClient({ apiKey: process.env.OPENAI_API_KEY! });
+const response = await client.chat({
+  model: "openai/gpt-4o",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+console.log(response.choices[0].message.content);
+```
+
+### Common Use Cases
+
+
+#### Streaming Responses
+
+Stream tokens in real time:
+
+```typescript
+import { LlmClient } from "@kreuzberg/liter-llm";
+
+const client = new LlmClient({ apiKey: process.env.OPENAI_API_KEY! });
+const chunks = await client.chatStream({
+  model: "openai/gpt-4o",
+  messages: [{ role: "user", content: "Tell me a story" }],
+});
+
+for (const chunk of chunks) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}
+console.log();
+```
+
+
+#### Tool Calling
+
+Define and invoke tools:
+
+```typescript
+import { LlmClient } from "@kreuzberg/liter-llm";
+
+const client = new LlmClient({ apiKey: process.env.OPENAI_API_KEY! });
+
+const tools = [
+  {
+    type: "function" as const,
+    function: {
+      name: "get_weather",
+      description: "Get the current weather for a location",
+      parameters: {
+        type: "object",
+        properties: {
+          location: { type: "string", description: "City name" },
+        },
+        required: ["location"],
+      },
+    },
+  },
+];
+
+const response = await client.chat({
+  model: "openai/gpt-4o",
+  messages: [{ role: "user", content: "What is the weather in Berlin?" }],
+  tools,
+});
+
+for (const call of response.choices[0]?.message?.toolCalls ?? []) {
+  console.log(`Tool: ${call.function.name}, Args: ${call.function.arguments}`);
+}
+```
+
+
+### Next Steps
+
+- **[Provider Registry](https://github.com/kreuzberg-dev/liter-llm/blob/main/schemas/providers.json)** - Full list of supported providers
+- **[GitHub Repository](https://github.com/kreuzberg-dev/liter-llm)** - Source, issues, and discussions
+
+
+## NAPI-RS Implementation Details
+
+### Native Performance
+
+This binding uses NAPI-RS to provide native Node.js bindings with:
+
+- **Zero-copy data transfer** between JavaScript and Rust layers
+- **Async by default** — all LLM calls return Promises backed by Tokio
+- **Binary-compatible** pre-built native modules across platforms
+- **TypeScript definitions** generated automatically from Rust types
+
+### Threading Model
+
+- LLM calls are non-blocking — Tokio async runtime handles concurrency
+- Streaming responses use Node.js async iterators backed by Tokio streams
+- CPU-bound work runs in `spawn_blocking` to avoid blocking the event loop
+
+### Memory Management
+
+- API keys are wrapped in `secrecy::SecretString` and never logged
+- Streaming buffers are released as soon as each chunk is consumed
+- Provider registry is compiled into the binary — no runtime disk access
+
+
+## Features
+
+### Supported Providers (143+)
+
+Route to any provider using the `provider/model` prefix convention:
+
+| Provider | Example Model |
+|----------|--------------|
+| **OpenAI** | `openai/gpt-4o`, `openai/gpt-4o-mini` |
+| **Anthropic** | `anthropic/claude-3-5-sonnet-20241022` |
+| **Groq** | `groq/llama-3.1-70b-versatile` |
+| **Mistral** | `mistral/mistral-large-latest` |
+| **Cohere** | `cohere/command-r-plus` |
+| **Together AI** | `together/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo` |
+| **Fireworks** | `fireworks/accounts/fireworks/models/llama-v3p1-70b-instruct` |
+| **Google Vertex** | `vertexai/gemini-1.5-pro` |
+| **Amazon Bedrock** | `bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0` |
+
+**[Complete Provider List](https://github.com/kreuzberg-dev/liter-llm/blob/main/schemas/providers.json)**
+
+### Key Capabilities
+
+- **Provider Routing** -- Single client for 143+ LLM providers via `provider/model` prefix
+- **Local LLMs** — Connect to locally-hosted models via Ollama, LM Studio, vLLM, llama.cpp, and other local inference servers
+- **Unified API** -- Consistent `chat`, `chat_stream`, `embeddings`, `list_models` interface
+
+- **Streaming** -- Real-time token streaming via `chat_stream`
+
+
+- **Tool Calling** -- Function calling and tool use across all supporting providers
+
+- **Type Safe** -- Schema-driven types compiled from JSON schemas
+- **Secure** -- API keys never logged or serialized, managed via environment variables
+- **Observability** -- Built-in [OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/) with GenAI semantic conventions
+- **Error Handling** -- Structured errors with provider context and retry hints
+
+### Performance
+
+Built on a compiled Rust core for speed and safety:
+
+- **Provider resolution** at client construction -- zero per-request overhead
+- **Configurable timeouts** and connection pooling
+- **Zero-copy streaming** with SSE and AWS EventStream support
+- **API keys** wrapped in secure memory, zeroed on drop
+
+
+## Provider Routing
+
+Route to 143+ providers using the `provider/model` prefix convention:
+
+```text
+openai/gpt-4o
+anthropic/claude-3-5-sonnet-20241022
+groq/llama-3.1-70b-versatile
+mistral/mistral-large-latest
+```
+
+See the [provider registry](https://github.com/kreuzberg-dev/liter-llm/blob/main/schemas/providers.json) for the full list.
+
+
+## Proxy Server
+
+liter-llm also ships as an OpenAI-compatible proxy server with Docker support:
+
+```bash
+docker run -p 4000:4000 -e LITER_LLM_MASTER_KEY=sk-your-key ghcr.io/kreuzberg-dev/liter-llm
+```
+
+See the [proxy server documentation](https://docs.liter-llm.kreuzberg.dev/server/proxy/) for configuration, CLI usage, and MCP integration.
+
+## Documentation
+
+- **[Documentation](https://docs.liter-llm.kreuzberg.dev)** -- Full docs and API reference
+- **[GitHub Repository](https://github.com/kreuzberg-dev/liter-llm)** -- Source, issues, and discussions
+- **[Provider Registry](https://github.com/kreuzberg-dev/liter-llm/blob/main/schemas/providers.json)** -- 143 supported providers
+
+Part of [kreuzberg.dev](https://kreuzberg.dev).
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](https://github.com/kreuzberg-dev/liter-llm/blob/main/CONTRIBUTING.md) for guidelines.
+
+Join our [Discord community](https://discord.gg/xt9WY3GnKR) for questions and discussion.
+
+## License
+
+MIT -- see [LICENSE](https://github.com/kreuzberg-dev/liter-llm/blob/main/LICENSE) for details.

package/index.d.ts

@@ -0,0 +1,711 @@
+// This file is auto-generated by alef — DO NOT EDIT.
+// alef:hash:1a6eb53e1357f456099c9528315e1c745cd3d4df0f88e11e313e50c27b025426
+// To regenerate: alef generate
+// To verify freshness: alef verify --exit-code
+// Issues & docs: https://github.com/kreuzberg-dev/alef
+/* eslint-disable */
+
+/**
+ * Create a new LLM client with simple scalar configuration.
+ *
+ * This is the primary binding entry-point. All parameters except `api_key`
+ * are optional — omitting them uses the same defaults as
+ * [`ClientConfigBuilder`].
+ *
+ * # Errors
+ *
+ * Returns [`LiterLlmError`] if the underlying HTTP client cannot be
+ * constructed, or if the resolved provider configuration is invalid.
+ */
+export declare function createClient(
+	apiKey: string,
+	baseUrl?: string | undefined | null,
+	timeoutSecs?: number | undefined | null,
+	maxRetries?: number | undefined | null,
+	modelHint?: string | undefined | null,
+): JsDefaultClient;
+
+/**
+ * Create a new LLM client from a JSON string.
+ *
+ * The JSON object accepts the same fields as `liter-llm.toml` (snake_case).
+ *
+ * # Errors
+ *
+ * Returns [`LiterLlmError::BadRequest`] if `json` is not valid JSON or
+ * contains unknown fields.
+ */
+export declare function createClientFromJson(json: string): JsDefaultClient;
+
+export interface JsAssistantMessage {
+	content: string;
+	name: string;
+	toolCalls: Array<JsToolCall>;
+	refusal: string;
+	/** Deprecated legacy function_call field; retained for API compatibility. */
+	functionCall: JsFunctionCall;
+}
+
+export interface JsAudioContent {
+	/** Base64-encoded audio data. */
+	data: string;
+	/** Audio format (e.g., "wav", "mp3", "ogg"). */
+	format: string;
+}
+
+/** How the API key is sent in the HTTP request. */
+export declare enum JsAuthHeaderFormat {
+	/** Bearer token: `Authorization: Bearer <key>` */
+	Bearer = "Bearer",
+	/** Custom header: e.g., `X-Api-Key: <key>` */
+	ApiKey = "ApiKey",
+	/** No authentication required. */
+	None = "None",
+}
+
+export interface JsChatCompletionChunk {
+	id: string;
+	/**
+	 * Always `"chat.completion.chunk"` from OpenAI-compatible APIs.  Stored
+	 * as a plain `String` so non-standard provider values do not fail parsing.
+	 */
+	object: string;
+	created: number;
+	model: string;
+	choices: Array<JsStreamChoice>;
+	usage: JsUsage;
+	systemFingerprint: string;
+	serviceTier: string;
+}
+
+export interface JsChatCompletionRequest {
+	model: string;
+	messages: Array<JsMessage>;
+	temperature: number;
+	topP: number;
+	n: number;
+	/**
+	 * Whether to stream the response.
+	 *
+	 * Managed by the client layer — do not set directly.
+	 */
+	stream: boolean;
+	stop: JsStopSequence;
+	maxTokens: number;
+	presencePenalty: number;
+	frequencyPenalty: number;
+	/**
+	 * Token bias map.  Uses `BTreeMap` (sorted keys) for deterministic
+	 * serialization order — important when hashing or signing requests.
+	 */
+	logitBias: Record<string, number>;
+	user: string;
+	tools: Array<JsChatCompletionTool>;
+	toolChoice: JsToolChoice;
+	parallelToolCalls: boolean;
+	responseFormat: JsResponseFormat;
+	streamOptions: JsStreamOptions;
+	seed: number;
+	reasoningEffort: JsReasoningEffort;
+	/**
+	 * Provider-specific extra parameters merged into the request body.
+	 * Use for guardrails, safety settings, grounding config, etc.
+	 */
+	extraBody: unknown;
+}
+
+export interface JsChatCompletionResponse {
+	id: string;
+	/**
+	 * Always `"chat.completion"` from OpenAI-compatible APIs.  Stored as a
+	 * plain `String` so non-standard provider values do not break deserialization.
+	 */
+	object: string;
+	created: number;
+	model: string;
+	choices: Array<JsChoice>;
+	usage: JsUsage;
+	systemFingerprint: string;
+	serviceTier: string;
+}
+
+export interface JsChatCompletionTool {
+	toolType: JsToolType;
+	function: JsFunctionDefinition;
+}
+
+export interface JsChoice {
+	index: number;
+	message: JsAssistantMessage;
+	finishReason: JsFinishReason;
+}
+
+export type JsContentPart =
+	| { type: "text"; text: string }
+	| { type: "image_url"; imageUrl: JsImageUrl }
+	| { type: "document"; document: JsDocumentContent }
+	| { type: "input_audio"; inputAudio: JsAudioContent };
+
+/** Request to create images from a text prompt. */
+export interface JsCreateImageRequest {
+	prompt: string;
+	model: string;
+	n: number;
+	size: string;
+	quality: string;
+	style: string;
+	responseFormat: string;
+	user: string;
+}
+
+/** Request to generate speech audio from text. */
+export interface JsCreateSpeechRequest {
+	model: string;
+	input: string;
+	voice: string;
+	responseFormat: string;
+	speed: number;
+}
+
+/** Request to transcribe audio into text. */
+export interface JsCreateTranscriptionRequest {
+	model: string;
+	/** Base64-encoded audio file data. */
+	file: string;
+	language: string;
+	prompt: string;
+	responseFormat: string;
+	temperature: number;
+}
+
+/** Configuration for registering a custom LLM provider at runtime. */
+export interface JsCustomProviderConfig {
+	/** Unique name for this provider (e.g., "my-provider"). */
+	name: string;
+	/** Base URL for the provider's API (e.g., "https://api.my-provider.com/v1"). */
+	baseUrl: string;
+	/** Authentication header format. */
+	authHeader: JsAuthHeaderFormat;
+	/** Model name prefixes that route to this provider (e.g., ["my-"]). */
+	modelPrefixes: Array<string>;
+}
+
+/**
+ * Default client implementation backed by `reqwest`.
+ *
+ * The provider is resolved at construction time from `model_hint` (or
+ * defaults to OpenAI). However, individual requests can override the
+ * provider when their model string contains a prefix that clearly
+ * identifies a different provider (e.g. `"anthropic/claude-3"` will
+ * route to Anthropic even if the client was built without a hint).
+ *
+ * When the model prefix does not match any known provider, the
+ * construction-time provider is used as the fallback.
+ *
+ * The provider is stored behind an [`Arc`] so it can be shared cheaply into
+ * async closures and streaming tasks that must be `'static`.
+ */
+export declare class JsDefaultClient {
+	chat(req: JsChatCompletionRequest): Promise<JsChatCompletionResponse>;
+	chatStream(req: JsChatCompletionRequest): Promise<string>;
+	embed(req: JsEmbeddingRequest): Promise<JsEmbeddingResponse>;
+	listModels(): Promise<JsModelsListResponse>;
+	imageGenerate(req: JsCreateImageRequest): Promise<JsImagesResponse>;
+	transcribe(
+		req: JsCreateTranscriptionRequest,
+	): Promise<JsTranscriptionResponse>;
+	moderate(req: JsModerationRequest): Promise<JsModerationResponse>;
+	rerank(req: JsRerankRequest): Promise<JsRerankResponse>;
+	search(req: JsSearchRequest): Promise<JsSearchResponse>;
+}
+
+export interface JsDeveloperMessage {
+	content: string;
+	name: string;
+}
+
+export interface JsDocumentContent {
+	/** Base64-encoded document data or URL. */
+	data: string;
+	/** MIME type (e.g., "application/pdf", "text/csv"). */
+	mediaType: string;
+}
+
+/** The format in which the embedding vectors are returned. */
+export declare enum JsEmbeddingFormat {
+	/** 32-bit floating-point numbers (default). */
+	Float = "float",
+	/** Base64-encoded string representation of the floats. */
+	Base64 = "base64",
+}
+
+export declare enum JsEmbeddingInput {
+	Single = "Single",
+	Multiple = "Multiple",
+}
+
+export interface JsEmbeddingObject {
+	/**
+	 * Always `"embedding"` from OpenAI-compatible APIs.  Stored as a plain
+	 * `String` so non-standard provider values do not break deserialization.
+	 */
+	object: string;
+	embedding: Array<number>;
+	index: number;
+}
+
+export interface JsEmbeddingRequest {
+	model: string;
+	input: JsEmbeddingInput;
+	encodingFormat: JsEmbeddingFormat;
+	dimensions: number;
+	user: string;
+}
+
+export interface JsEmbeddingResponse {
+	/**
+	 * Always `"list"` from OpenAI-compatible APIs.  Stored as a plain
+	 * `String` so non-standard provider values do not break deserialization.
+	 */
+	object: string;
+	data: Array<JsEmbeddingObject>;
+	model: string;
+	usage: JsUsage;
+}
+
+/** Why a choice stopped generating tokens. */
+export declare enum JsFinishReason {
+	Stop = "stop",
+	Length = "length",
+	ToolCalls = "tool_calls",
+	ContentFilter = "content_filter",
+	/** Deprecated legacy finish reason; retained for API compatibility. */
+	FunctionCall = "function_call",
+	/**
+	 * Catch-all for unknown finish reasons returned by non-OpenAI providers.
+	 *
+	 * Note: this intentionally does **not** carry the original string (e.g.
+	 * `Other(String)`).  Using `#[serde(other)]` requires a unit variant, and
+	 * switching to `#[serde(untagged)]` would change deserialization semantics
+	 * for all variants.  The original value can be recovered by inspecting the
+	 * raw JSON if needed.
+	 */
+	Other = "other",
+}
+
+export interface JsFunctionCall {
+	name: string;
+	arguments: string;
+}
+
+export interface JsFunctionDefinition {
+	name: string;
+	description: string;
+	parameters: unknown;
+	strict: boolean;
+}
+
+/** Deprecated legacy function-role message body. */
+export interface JsFunctionMessage {
+	content: string;
+	name: string;
+}
+
+/** A single generated image, returned as either a URL or base64 data. */
+export interface JsImage {
+	url: string;
+	b64Json: string;
+	revisedPrompt: string;
+}
+
+export declare enum JsImageDetail {
+	Low = "low",
+	High = "high",
+	Auto = "auto",
+}
+
+/** Response containing generated images. */
+export interface JsImagesResponse {
+	created: number;
+	data: Array<JsImage>;
+}
+
+export interface JsImageUrl {
+	url: string;
+	detail: JsImageDetail;
+}
+
+export interface JsJsonSchemaFormat {
+	name: string;
+	description: string;
+	schema: unknown;
+	strict: boolean;
+}
+
+export declare class JsLiterLlmError {}
+
+/** A chat message in a conversation. */
+export type JsMessage =
+	| { role: "system"; 0: JsSystemMessage }
+	| { role: "user"; 0: JsUserMessage }
+	| { role: "assistant"; 0: JsAssistantMessage }
+	| { role: "tool"; 0: JsToolMessage }
+	| { role: "developer"; 0: JsDeveloperMessage }
+	| { role: "function"; 0: JsFunctionMessage };
+
+export interface JsModelObject {
+	id: string;
+	/**
+	 * Always `"model"` from OpenAI-compatible APIs.  Stored as a plain
+	 * `String` so non-standard provider values do not break deserialization.
+	 */
+	object: string;
+	created: number;
+	ownedBy: string;
+}
+
+export interface JsModelsListResponse {
+	/**
+	 * Always `"list"` from OpenAI-compatible APIs.  Stored as a plain
+	 * `String` so non-standard provider values do not break deserialization.
+	 */
+	object: string;
+	data: Array<JsModelObject>;
+}
+
+/** Boolean flags for each moderation category. */
+export interface JsModerationCategories {
+	sexual: boolean;
+	hate: boolean;
+	harassment: boolean;
+	selfHarm: boolean;
+	sexualMinors: boolean;
+	hateThreatening: boolean;
+	violenceGraphic: boolean;
+	selfHarmIntent: boolean;
+	selfHarmInstructions: boolean;
+	harassmentThreatening: boolean;
+	violence: boolean;
+}
+
+/** Confidence scores for each moderation category. */
+export interface JsModerationCategoryScores {
+	sexual: number;
+	hate: number;
+	harassment: number;
+	selfHarm: number;
+	sexualMinors: number;
+	hateThreatening: number;
+	violenceGraphic: number;
+	selfHarmIntent: number;
+	selfHarmInstructions: number;
+	harassmentThreatening: number;
+	violence: number;
+}
+
+/** Input to the moderation endpoint — a single string or multiple strings. */
+export declare enum JsModerationInput {
+	Single = "Single",
+	Multiple = "Multiple",
+}
+
+/** Request to classify content for policy violations. */
+export interface JsModerationRequest {
+	input: JsModerationInput;
+	model: string;
+}
+
+/** Response from the moderation endpoint. */
+export interface JsModerationResponse {
+	id: string;
+	model: string;
+	results: Array<JsModerationResult>;
+}
+
+/** A single moderation classification result. */
+export interface JsModerationResult {
+	flagged: boolean;
+	categories: JsModerationCategories;
+	categoryScores: JsModerationCategoryScores;
+}
+
+/** Document input for OCR — either a URL or inline base64 data. */
+export type JsOcrDocument =
+	| { type: "document_url"; url: string }
+	| { type: "base64"; data: string; mediaType: string };
+
+/** An image extracted from an OCR page. */
+export interface JsOcrImage {
+	/** Unique image identifier. */
+	id: string;
+	/** Base64-encoded image data. */
+	imageBase64: string;
+}
+
+/** A single page of OCR output. */
+export interface JsOcrPage {
+	/** Page index (0-based). */
+	index: number;
+	/** Extracted content as Markdown. */
+	markdown: string;
+	/** Extracted images, if `include_image_base64` was set. */
+	images: Array<JsOcrImage>;
+	/** Page dimensions in pixels, if available. */
+	dimensions: JsPageDimensions;
+}
+
+/** An OCR request. */
+export interface JsOcrRequest {
+	/** The model/provider to use (e.g. `"mistral/mistral-ocr-latest"`). */
+	model: string;
+	/** The document to process. */
+	document: JsOcrDocument;
+	/** Specific pages to process (1-indexed). `None` means all pages. */
+	pages: Array<number>;
+	/** Whether to include base64-encoded images of each page. */
+	includeImageBase64: boolean;
+}
+
+/** An OCR response. */
+export interface JsOcrResponse {
+	/** Extracted pages. */
+	pages: Array<JsOcrPage>;
+	/** The model used. */
+	model: string;
+	/** Token usage, if reported by the provider. */
+	usage: JsUsage;
+}
+
+/** Page dimensions in pixels. */
+export interface JsPageDimensions {
+	/** Width in pixels. */
+	width: number;
+	/** Height in pixels. */
+	height: number;
+}
+
+/** Controls how much reasoning effort the model should use. */
+export declare enum JsReasoningEffort {
+	Low = "low",
+	Medium = "medium",
+	High = "high",
+}
+
+/** A document to be reranked — either a plain string or an object with a text field. */
+export declare enum JsRerankDocument {
+	Text = "Text",
+	Object = "Object",
+}
+
+/** Request to rerank documents by relevance to a query. */
+export interface JsRerankRequest {
+	model: string;
+	query: string;
+	documents: Array<JsRerankDocument>;
+	topN: number;
+	returnDocuments: boolean;
+}
+
+/** Response from the rerank endpoint. */
+export interface JsRerankResponse {
+	id: string;
+	results: Array<JsRerankResult>;
+	meta: unknown;
+}
+
+/** A single reranked document with its relevance score. */
+export interface JsRerankResult {
+	index: number;
+	relevanceScore: number;
+	document: JsRerankResultDocument;
+}
+
+/** The text content of a reranked document, returned when `return_documents` is true. */
+export interface JsRerankResultDocument {
+	text: string;
+}
+
+export type JsResponseFormat =
+	| { type: "text" }
+	| { type: "json_object" }
+	| { type: "json_schema"; jsonSchema: JsJsonSchemaFormat };
+
+/** A search request. */
+export interface JsSearchRequest {
+	/** The model/provider to use (e.g. `"brave/web-search"`, `"tavily/search"`). */
+	model: string;
+	/** The search query. */
+	query: string;
+	/** Maximum number of results to return. */
+	maxResults: number;
+	/** Domain filter — restrict results to specific domains. */
+	searchDomainFilter: Array<string>;
+	/** Country code for localized results (ISO 3166-1 alpha-2). */
+	country: string;
+}
+
+/** A search response. */
+export interface JsSearchResponse {
+	/** The search results. */
+	results: Array<JsSearchResult>;
+	/** The model used. */
+	model: string;
+}
+
+/** An individual search result. */
+export interface JsSearchResult {
+	/** Title of the result. */
+	title: string;
+	/** URL of the result. */
+	url: string;
+	/** Text snippet / excerpt. */
+	snippet: string;
+	/** Publication or last-updated date, if available. */
+	date: string;
+}
+
+export interface JsSpecificFunction {
+	name: string;
+}
+
+export interface JsSpecificToolChoice {
+	choiceType: JsToolType;
+	function: JsSpecificFunction;
+}
+
+export declare enum JsStopSequence {
+	Single = "Single",
+	Multiple = "Multiple",
+}
+
+export interface JsStreamChoice {
+	index: number;
+	delta: JsStreamDelta;
+	finishReason: JsFinishReason;
+}
+
+export interface JsStreamDelta {
+	role: string;
+	content: string;
+	toolCalls: Array<JsStreamToolCall>;
+	/** Deprecated legacy function_call delta; retained for API compatibility. */
+	functionCall: JsStreamFunctionCall;
+	refusal: string;
+}
+
+export interface JsStreamFunctionCall {
+	name: string;
+	arguments: string;
+}
+
+export interface JsStreamOptions {
+	includeUsage: boolean;
+}
+
+export interface JsStreamToolCall {
+	index: number;
+	id: string;
+	callType: JsToolType;
+	function: JsStreamFunctionCall;
+}
+
+export interface JsSystemMessage {
+	content: string;
+	name: string;
+}
+
+export interface JsToolCall {
+	id: string;
+	callType: JsToolType;
+	function: JsFunctionCall;
+}
+
+export declare enum JsToolChoice {
+	Mode = "Mode",
+	Specific = "Specific",
+}
+
+export declare enum JsToolChoiceMode {
+	Auto = "auto",
+	Required = "required",
+	None = "none",
+}
+
+export interface JsToolMessage {
+	content: string;
+	toolCallId: string;
+	name: string;
+}
+
+/**
+ * The type discriminator for tool/tool-call objects.
+ *
+ * Per the OpenAI spec this is always `"function"`. Using an enum enforces
+ * that constraint at the type level and rejects any other value on
+ * deserialization.
+ */
+export declare enum JsToolType {
+	Function = "function",
+}
+
+/** Response from a transcription request. */
+export interface JsTranscriptionResponse {
+	text: string;
+	language: string;
+	duration: number;
+	segments: Array<JsTranscriptionSegment>;
+}
+
+/** A segment of transcribed audio with timing information. */
+export interface JsTranscriptionSegment {
+	id: number;
+	start: number;
+	end: number;
+	text: string;
+}
+
+export interface JsUsage {
+	/** Prompt tokens used. Defaults to 0 when absent (some providers omit this). */
+	promptTokens: number;
+	/** Completion tokens used. Defaults to 0 when absent (e.g. embedding responses). */
+	completionTokens: number;
+	/** Total tokens used. Defaults to 0 when absent (some providers omit this). */
+	totalTokens: number;
+}
+
+export declare enum JsUserContent {
+	Text = "Text",
+	Parts = "Parts",
+}
+
+export interface JsUserMessage {
+	content: JsUserContent;
+	name: string;
+}
+
+/**
+ * Register a custom provider in the global runtime registry.
+ *
+ * The provider will be checked **before** all built-in providers during model
+ * detection. If a provider with the same `name` already exists it is replaced.
+ *
+ * # Errors
+ *
+ * Returns an error if the config is invalid (empty name, empty base_url, or
+ * no model prefixes).
+ */
+export declare function registerCustomProvider(
+	config: JsCustomProviderConfig,
+): void;
+
+/**
+ * Remove a previously registered custom provider by name.
+ *
+ * Returns `true` if a provider with the given name was found and removed,
+ * `false` if no such provider existed.
+ *
+ * # Errors
+ *
+ * Returns an error only if the internal lock is poisoned.
+ */
+export declare function unregisterCustomProvider(name: string): boolean;

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@kreuzberg/liter-llm-node",
+	"version": "1.4.0-rc.19",
+	"description": "Native NAPI-RS bindings for liter-llm \u2014 high-performance LLM client powered by Rust",
+	"main": "index.js",
+	"types": "index.d.ts",
+	"files": [
+		"index.js",
+		"index.d.ts",
+		"*.node"
+	],
+	"napi": {
+		"binaryName": "liter-llm-node",
+		"targets": [
+			"aarch64-apple-darwin",
+			"x86_64-unknown-linux-gnu",
+			"aarch64-unknown-linux-gnu",
+			"x86_64-pc-windows-msvc"
+		]
+	},
+	"engines": {
+		"node": ">= 22"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/kreuzberg-dev/liter-llm.git"
+	},
+	"homepage": "https://github.com/kreuzberg-dev/liter-llm",
+	"bugs": {
+		"url": "https://github.com/kreuzberg-dev/liter-llm/issues"
+	},
+	"license": "MIT",
+	"keywords": [
+		"llm",
+		"llm-client",
+		"openai",
+		"anthropic",
+		"streaming",
+		"tool-calling",
+		"napi",
+		"rust",
+		"native"
+	],
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
+	},
+	"scripts": {
+		"artifacts": "napi artifacts",
+		"build": "napi build --platform --release",
+		"prepublishOnly": "napi prepublish -t npm --skip-optional-publish"
+	},
+	"devDependencies": {
+		"@napi-rs/cli": "^3.6.2"
+	}
+}