@codefionn/llmleaf-client 0.1.2

package/src/index.ts

@@ -0,0 +1,77 @@
+// @codefionn/llmleaf-client — official TypeScript/JavaScript client for the llmleaf LLM proxy.
+//
+// The wire is OpenAI/OpenRouter-shaped JSON over HTTP (see clients/SPEC.md). The proto
+// (clients/proto/llmleaf/v1/llmleaf.proto) is the typed source of truth; the protobuf-es
+// codegen artifact lives under ./gen and the hand-written transport here maps the public
+// model to/from the wire JSON.
+
+export { LlmleafClient } from "./client.js";
+export type {
+  LlmleafClientOptions,
+  FetchLike,
+  TranscriptionFile,
+} from "./client.js";
+
+export { ApiError } from "./error.js";
+
+// Enums (re-exported straight from the generated descriptor file) + the generic
+// wire-token mapping helpers.
+export {
+  Role,
+  FinishReason,
+  BatchStatus,
+  enumToWire,
+  enumFromWire,
+} from "./enums.js";
+
+// The public typed model.
+export type {
+  Usage,
+  TextPart,
+  ImageUrlPart,
+  ContentPart,
+  MessageContent,
+  FunctionCall,
+  ToolCall,
+  ChatMessage,
+  FunctionDef,
+  ToolDef,
+  ToolChoice,
+  ResponseFormat,
+  ChatRequest,
+  Choice,
+  ChatResponse,
+  FunctionCallDelta,
+  ToolCallDelta,
+  Delta,
+  ChunkChoice,
+  ChatCompletionChunk,
+  EmbeddingRequest,
+  Embedding,
+  EmbeddingResponse,
+  SpeechRequest,
+  SpeechResult,
+  Voice,
+  VoicesResponse,
+  TranscriptionRequest,
+  TranscriptionResponse,
+  Architecture,
+  Pricing,
+  TopProvider,
+  ModelEndpoint,
+  ModelEntry,
+  ListModelsResponse,
+  ModelType,
+  ListModelsOptions,
+  BatchRequestItem,
+  BatchCreateRequest,
+  BatchCounts,
+  BatchHandle,
+  BatchResponse,
+  BatchError,
+  BatchResultLine,
+} from "./types.js";
+
+// The generated protobuf-es descriptors/types remain importable for advanced users
+// who want the codegen artifact directly (e.g. binary/JSON reflection via @bufbuild/protobuf).
+export * as gen from "./gen/llmleaf/v1/llmleaf_pb.js";

package/src/stream.ts

@@ -0,0 +1,82 @@
+// Streaming helpers: decode the response body's ReadableStream into lines, then
+// surface SSE `data:` frames (chat streaming) or NDJSON objects (batch results).
+//
+// These are runtime-agnostic: they only use the WHATWG ReadableStream + TextDecoder
+// that Node 20+, Deno, Bun and browsers all provide.
+
+/** Yield decoded text lines from a byte stream, handling \n / \r\n splits across chunks. */
+async function* iterLines(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<string, void, unknown> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let nl: number;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        let line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (line.endsWith("\r")) line = line.slice(0, -1);
+        yield line;
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.endsWith("\r")) buffer = buffer.slice(0, -1);
+    if (buffer.length > 0) yield buffer;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Parse a `text/event-stream` body into the raw JSON payload of each `data:` frame.
+ *
+ * Stops (returns) on the sentinel line `data: [DONE]` WITHOUT yielding it — callers
+ * must not JSON-parse the sentinel (SPEC.md). Blank lines (frame separators) and any
+ * non-`data:` SSE fields (`event:`, `id:`, comments) are ignored. Multi-line `data:`
+ * frames are concatenated with newlines per the SSE spec.
+ */
+export async function* parseSseData(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<string, void, unknown> {
+  let dataLines: string[] = [];
+  for await (const line of iterLines(body)) {
+    if (line === "") {
+      // Dispatch the accumulated event.
+      if (dataLines.length > 0) {
+        yield dataLines.join("\n");
+        dataLines = [];
+      }
+      continue;
+    }
+    if (line.startsWith(":")) continue; // comment
+    if (!line.startsWith("data:")) continue; // ignore event:/id:/retry:
+    // Strip "data:" and a single optional leading space.
+    let value = line.slice(5);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (value === "[DONE]") return;
+    dataLines.push(value);
+  }
+  // Flush a trailing event that wasn't followed by a blank line.
+  if (dataLines.length > 0) {
+    const payload = dataLines.join("\n");
+    if (payload !== "[DONE]") yield payload;
+  }
+}
+
+/**
+ * Parse an `application/x-ndjson` body into one parsed JSON value per non-empty line.
+ */
+export async function* parseNdjson(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<unknown, void, unknown> {
+  for await (const line of iterLines(body)) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    yield JSON.parse(trimmed);
+  }
+}

package/src/types.ts

@@ -0,0 +1,384 @@
+// Public, hand-written TypeScript surface mirroring proto/llmleaf/v1/llmleaf.proto.
+//
+// Why interfaces and not the generated protobuf-es classes directly? protobuf-es's
+// own JSON codec emits camelCase keys and STRING enum NAMES (e.g. "ASSISTANT"), which
+// do NOT match the OpenAI/OpenRouter wire (snake_case keys + lowercase tokens like
+// "assistant"), and it has no notion of the "free-form JSON carried as a raw string"
+// or "content is string-or-array" conventions in SPEC.md. So these plain interfaces
+// are the ergonomic public model; src/wire.ts maps them to/from the actual wire JSON.
+//
+// The generated descriptors/enums remain the committed codegen artifact (src/gen) and
+// are the single source of truth these shapes track. The three closed-set enums are
+// re-used straight from the generated file via src/enums.ts.
+
+import type { Role, FinishReason, BatchStatus } from "./enums.js";
+
+export type { Role, FinishReason, BatchStatus };
+
+// ---------------------------------------------------------------------------
+// Common
+// ---------------------------------------------------------------------------
+
+export interface Usage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  /** llmleaf addition; absent when the model has no known price. */
+  costUsd?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Chat
+// ---------------------------------------------------------------------------
+
+export interface TextPart {
+  type: "text";
+  text: string;
+}
+
+export interface ImageUrlPart {
+  type: "image_url";
+  imageUrl: {
+    url: string;
+    /** "auto" | "low" | "high" */
+    detail?: string;
+  };
+}
+
+export type ContentPart = TextPart | ImageUrlPart;
+
+/** Wire `content` is either a plain string or an array of content parts. */
+export type MessageContent = string | ContentPart[];
+
+export interface FunctionCall {
+  name: string;
+  /** JSON-encoded arguments string (OpenAI shape). */
+  arguments: string;
+}
+
+export interface ToolCall {
+  id: string;
+  /** always "function" today */
+  type: string;
+  function: FunctionCall;
+}
+
+export interface ChatMessage {
+  role: Role;
+  content?: MessageContent;
+  name?: string;
+  toolCalls?: ToolCall[];
+  /** set when role == TOOL */
+  toolCallId?: string;
+}
+
+export interface FunctionDef {
+  name: string;
+  description?: string;
+  /** raw JSON Schema object, as a JSON string. */
+  parameters?: string;
+}
+
+export interface ToolDef {
+  /** "function" */
+  type: string;
+  function: FunctionDef;
+}
+
+/** "auto" | "none" | "required", or a named-function object. */
+export type ToolChoice =
+  | string
+  | {
+      type: "function";
+      function: { name: string };
+    };
+
+export interface ResponseFormat {
+  /** "text" | "json_object" | "json_schema" */
+  type: string;
+  /** raw JSON object as a JSON string when type == "json_schema". */
+  jsonSchema?: string;
+}
+
+export interface ChatRequest {
+  model: string;
+  messages: ChatMessage[];
+  stream?: boolean;
+  temperature?: number;
+  topP?: number;
+  /** legacy name */
+  maxTokens?: number;
+  /** modern name (takes precedence) */
+  maxCompletionTokens?: number;
+  stop?: string[];
+  n?: number;
+  seed?: number;
+  frequencyPenalty?: number;
+  presencePenalty?: number;
+  tools?: ToolDef[];
+  toolChoice?: ToolChoice;
+  responseFormat?: ResponseFormat;
+  /** "low" | "medium" | "high" */
+  reasoningEffort?: string;
+  /** dialect-specific passthrough, raw JSON object as a JSON string, merged at the top level. */
+  extra?: string;
+}
+
+export interface Choice {
+  index: number;
+  message: ChatMessage;
+  finishReason?: FinishReason;
+}
+
+export interface ChatResponse {
+  id: string;
+  /** "chat.completion" */
+  object: string;
+  /** unix seconds */
+  created: number;
+  model: string;
+  choices: Choice[];
+  usage?: Usage;
+}
+
+// Streaming
+
+export interface FunctionCallDelta {
+  name?: string;
+  arguments?: string;
+}
+
+export interface ToolCallDelta {
+  index: number;
+  id?: string;
+  type?: string;
+  function?: FunctionCallDelta;
+}
+
+export interface Delta {
+  /** first chunk only */
+  role?: Role;
+  /** incremental text */
+  content?: string;
+  toolCalls?: ToolCallDelta[];
+}
+
+export interface ChunkChoice {
+  index: number;
+  delta: Delta;
+  finishReason?: FinishReason;
+}
+
+export interface ChatCompletionChunk {
+  id: string;
+  /** "chat.completion.chunk" */
+  object: string;
+  created: number;
+  model: string;
+  choices: ChunkChoice[];
+  /** terminal chunk only */
+  usage?: Usage;
+}
+
+// ---------------------------------------------------------------------------
+// Embeddings
+// ---------------------------------------------------------------------------
+
+export interface EmbeddingRequest {
+  model: string;
+  /** wire accepts string or array of strings. */
+  input: string[];
+  dimensions?: number;
+  /** "float" | "base64" */
+  encodingFormat?: string;
+  /** raw JSON object passthrough as a JSON string. */
+  extra?: string;
+}
+
+export interface Embedding {
+  /** "embedding" */
+  object: string;
+  index: number;
+  /** Always decoded to floats, even when encoding_format == "base64". */
+  embedding: number[];
+}
+
+export interface EmbeddingResponse {
+  /** "list" */
+  object: string;
+  data: Embedding[];
+  model: string;
+  usage?: Usage;
+}
+
+// ---------------------------------------------------------------------------
+// Audio
+// ---------------------------------------------------------------------------
+
+export interface SpeechRequest {
+  model: string;
+  input: string;
+  voice: string;
+  /** mp3|opus|aac|flac|wav|pcm */
+  responseFormat?: string;
+  speed?: number;
+  /** raw JSON object passthrough as a JSON string. */
+  extra?: string;
+}
+
+/** Raw audio bytes plus the Content-Type the server reported. */
+export interface SpeechResult {
+  bytes: Uint8Array;
+  contentType: string;
+}
+
+export interface Voice {
+  /** value to put in SpeechRequest.voice */
+  id: string;
+  name?: string;
+  /** BCP-47 tags */
+  languages: string[];
+}
+
+export interface VoicesResponse {
+  model: string;
+  voices: Voice[];
+}
+
+export interface TranscriptionRequest {
+  model: string;
+  /** ISO-639-1 hint */
+  language?: string;
+  /** decoding bias */
+  prompt?: string;
+  /** json|text|verbose_json|srt|vtt */
+  responseFormat?: string;
+  temperature?: number;
+}
+
+export interface TranscriptionResponse {
+  text: string;
+  /** "transcribe" (verbose_json) */
+  task?: string;
+  language?: string;
+  duration?: number;
+  usage?: Usage;
+}
+
+// ---------------------------------------------------------------------------
+// Model catalog
+// ---------------------------------------------------------------------------
+
+export interface Architecture {
+  inputModalities: string[];
+  outputModalities: string[];
+  /** "text->text" | "text->audio" | ... */
+  modality?: string;
+  tokenizer: string;
+  instructType?: string;
+}
+
+export interface Pricing {
+  /** USD per token, decimal string */
+  prompt: string;
+  completion: string;
+}
+
+export interface TopProvider {
+  contextLength?: number;
+  maxCompletionTokens?: number;
+  isModerated: boolean;
+  /** llmleaf extension */
+  maxThinkingTokens?: number;
+}
+
+/** Admin-only fallback-chain entry (present only with a valid admin token). */
+export interface ModelEndpoint {
+  provider: string;
+  model: string;
+  down: boolean;
+  /** "route" | "prefix" */
+  source: string;
+}
+
+export interface ModelEntry {
+  id: string;
+  canonicalSlug: string;
+  name: string;
+  created: number;
+  description: string;
+  contextLength?: number;
+  architecture?: Architecture;
+  pricing?: Pricing;
+  topProvider?: TopProvider;
+  supportedParameters: string[];
+  unsupportedParameters: string[];
+  /** raw JSON object as a JSON string. */
+  defaultParameters?: string;
+  /** admin-only */
+  endpoints: ModelEndpoint[];
+}
+
+export interface ListModelsResponse {
+  data: ModelEntry[];
+}
+
+/** Filter for {@link "./client".LlmleafClient.listModels}. */
+export type ModelType = "all" | "llm" | "tts" | "stt" | "embedding";
+
+export interface ListModelsOptions {
+  type?: ModelType;
+  /** substring search */
+  search?: string;
+  /** when true, send the admin token so per-model `endpoints` are included. */
+  admin?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Batches
+// ---------------------------------------------------------------------------
+
+export interface BatchRequestItem {
+  customId: string;
+  body: ChatRequest;
+}
+
+export interface BatchCreateRequest {
+  requests: BatchRequestItem[];
+}
+
+export interface BatchCounts {
+  total: number;
+  processing: number;
+  succeeded: number;
+  errored: number;
+  canceled: number;
+  expired: number;
+}
+
+export interface BatchHandle {
+  id: string;
+  status: BatchStatus;
+  counts?: BatchCounts;
+  createdAt?: number;
+  expiresAt?: number;
+  endedAt?: number;
+  /** e.g. "/v1/chat/completions" */
+  endpoint?: string;
+}
+
+export interface BatchResponse {
+  statusCode: number;
+  body: ChatResponse;
+}
+
+export interface BatchError {
+  code: string;
+  message: string;
+}
+
+export interface BatchResultLine {
+  customId: string;
+  response?: BatchResponse;
+  error?: BatchError;
+}