@codefionn/llmleaf-client 0.1.7 → 0.1.8

package/src/index.ts

@@ -31,6 +31,7 @@ export { cachedTokens } from "./types.js";
 export type {
   Usage,
   PromptTokensDetails,
+  ErrorBody,
   TextPart,
   ImageUrlPart,
   ContentPart,
@@ -51,6 +52,29 @@ export type {
   Delta,
   ChunkChoice,
   ChatCompletionChunk,
+  // Responses dialect (POST /v1/responses)
+  ResponseInputTextPart,
+  ResponseInputImagePart,
+  ResponseOutputTextPart,
+  ResponseContentPart,
+  ResponseMessageContent,
+  ResponseMessageItem,
+  ResponseFunctionCallItem,
+  ResponseFunctionCallOutputItem,
+  ResponseReasoningText,
+  ResponseReasoningItem,
+  ResponseItem,
+  ResponsesInput,
+  ResponsesToolDef,
+  ResponsesToolChoice,
+  ResponsesReasoning,
+  ResponsesRequest,
+  ResponsesInputTokensDetails,
+  ResponsesOutputTokensDetails,
+  ResponsesUsage,
+  ResponsesIncompleteDetails,
+  ResponsesResponse,
+  ResponsesStreamEvent,
   EmbeddingRequest,
   Embedding,
   EmbeddingResponse,

package/src/types.ts

@@ -55,6 +55,18 @@ export function cachedTokens(usage: Usage): number {
   return usage.promptTokensDetails?.cachedTokens ?? 0;
 }
 
+/**
+ * The canonical error envelope body (`{"error":{"message":...}}`). Any non-2xx HTTP
+ * response is raised as an {@link "./error".ApiError}; this typed shape is the `error`
+ * carried *inside* a `failed` {@link ResponsesResponse} snapshot.
+ */
+export interface ErrorBody {
+  message: string;
+  /** present on some dialects; absent on the llmleaf core envelope. */
+  type?: string;
+  code?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Chat
 // ---------------------------------------------------------------------------
@@ -456,3 +468,248 @@ export interface BatchResultLine {
   response?: BatchResponse;
   error?: BatchError;
 }
+
+// ---------------------------------------------------------------------------
+// Responses (POST /v1/responses) — the OpenAI Responses dialect
+// ---------------------------------------------------------------------------
+//
+// llmleaf serves this dialect statelessly: `store` is accepted but always answered
+// `false`, `previousResponseId`/`background:true` are rejected (400), and there is no
+// retrieval call (`GET /v1/responses/{id}` is an explained 404). Dialect vocabulary
+// that would collide with the chat enums (statuses "completed"/"in_progress"/…, roles
+// incl. "developer") stays a plain wire string here rather than an enum.
+
+/** `{"type":"input_text","text":...}` */
+export interface ResponseInputTextPart {
+  type: "input_text";
+  text: string;
+}
+
+/**
+ * `{"type":"input_image","image_url":"<url>","detail":...}`. Unlike the chat dialect's
+ * nested `{url}` object, {@link imageUrl} is a plain string here.
+ */
+export interface ResponseInputImagePart {
+  type: "input_image";
+  imageUrl: string;
+  /** "auto" | "low" | "high" */
+  detail?: string;
+}
+
+/** `{"type":"output_text","text":...,"annotations":[]}` (annotations emitted as `[]`). */
+export interface ResponseOutputTextPart {
+  type: "output_text";
+  text: string;
+}
+
+export type ResponseContentPart =
+  | ResponseInputTextPart
+  | ResponseInputImagePart
+  | ResponseOutputTextPart;
+
+/** A message item's `content`: a bare string or an array of content parts. */
+export type ResponseMessageContent = string | ResponseContentPart[];
+
+/**
+ * A conversation message item. On input, {@link role} is "user" | "system" |
+ * "developer" | "assistant" and serialises as a bare role-keyed object (no `"type"`);
+ * on output, role is "assistant" with `output_text` parts and {@link status}/{@link id}.
+ */
+export interface ResponseMessageItem {
+  type: "message";
+  id?: string;
+  /** "user" | "system" | "developer" | "assistant" */
+  role: string;
+  content?: ResponseMessageContent;
+  /** output only: "in_progress" | "completed" */
+  status?: string;
+}
+
+/**
+ * A function call the model made. {@link callId} pairs it with its
+ * {@link ResponseFunctionCallOutputItem}; {@link arguments} is the raw JSON string.
+ */
+export interface ResponseFunctionCallItem {
+  type: "function_call";
+  id?: string;
+  callId: string;
+  name: string;
+  arguments: string;
+  status?: string;
+}
+
+/** The caller's answer to a function call, replayed on the next turn. */
+export interface ResponseFunctionCallOutputItem {
+  type: "function_call_output";
+  id?: string;
+  callId: string;
+  output: string;
+}
+
+/** One entry of a reasoning item's `summary[]` or `content[]` list. */
+export interface ResponseReasoningText {
+  text: string;
+}
+
+/**
+ * A reasoning ("thinking") item. {@link summary} entries serialise as
+ * `{"type":"summary_text","text"}`, {@link content} entries as
+ * `{"type":"reasoning_text","text"}` — the list decides the wire token.
+ * {@link encryptedContent} is opaque and MUST be echoed back verbatim in the next
+ * request's input to continue an encrypted reasoning turn.
+ */
+export interface ResponseReasoningItem {
+  type: "reasoning";
+  id?: string;
+  summary?: ResponseReasoningText[];
+  content?: ResponseReasoningText[];
+  encryptedContent?: string;
+}
+
+/**
+ * One item of the request `input` array or the response `output` array. The `type`
+ * field is the discriminator (a message item serialises without one — see
+ * {@link ResponseMessageItem}).
+ */
+export type ResponseItem =
+  | ResponseMessageItem
+  | ResponseFunctionCallItem
+  | ResponseFunctionCallOutputItem
+  | ResponseReasoningItem;
+
+/** `input`: a bare string (one user message) or an array of items. */
+export type ResponsesInput = string | ResponseItem[];
+
+/**
+ * A tool the model MAY call — FLAT in this dialect (`type`/`name`/`parameters` at the
+ * top level, no nested `function` object).
+ */
+export interface ResponsesToolDef {
+  /** "function" */
+  type: string;
+  name: string;
+  description?: string;
+  /** raw JSON Schema object, as a JSON string. */
+  parameters?: string;
+  /** defaults TRUE upstream; llmleaf's own edge pins false. */
+  strict?: boolean;
+}
+
+/**
+ * "auto" | "none" | "required", or the FLAT named object `{type:"function",name}`
+ * (no nested `function`, unlike the chat dialect).
+ */
+export type ResponsesToolChoice =
+  | string
+  | {
+      type: "function";
+      name: string;
+    };
+
+/** `reasoning`: `{"effort":...,"summary":...}`. */
+export interface ResponsesReasoning {
+  /** "minimal" | "low" | "medium" | "high" | ... */
+  effort?: string;
+  summary?: string;
+}
+
+export interface ResponsesRequest {
+  model: string;
+  input: ResponsesInput;
+  /** becomes a leading system message */
+  instructions?: string;
+  stream?: boolean;
+  temperature?: number;
+  topP?: number;
+  maxOutputTokens?: number;
+  tools?: ResponsesToolDef[];
+  toolChoice?: ResponsesToolChoice;
+  reasoning?: ResponsesReasoning;
+  /** accepted, but llmleaf stores nothing and always answers `false`. */
+  store?: boolean;
+  /** dialect-specific passthrough, raw JSON object as a JSON string, merged at the top level. */
+  extra?: string;
+}
+
+export interface ResponsesInputTokensDetails {
+  cachedTokens?: number;
+}
+
+export interface ResponsesOutputTokensDetails {
+  reasoningTokens?: number;
+}
+
+/**
+ * Token accounting in the Responses dialect's own names (`input_tokens`/`output_tokens`,
+ * not the chat dialect's `prompt_tokens`/`completion_tokens`).
+ */
+export interface ResponsesUsage {
+  inputTokens: number;
+  inputTokensDetails?: ResponsesInputTokensDetails;
+  outputTokens: number;
+  outputTokensDetails?: ResponsesOutputTokensDetails;
+  totalTokens: number;
+}
+
+/** `status:"incomplete"` refinement: "max_output_tokens" | "content_filter". */
+export interface ResponsesIncompleteDetails {
+  reason: string;
+}
+
+/**
+ * The response object (`"object":"response"`), also the snapshot carried by the
+ * `response.created` / `response.in_progress` / `response.completed` stream events.
+ */
+export interface ResponsesResponse {
+  id: string;
+  /** "response" */
+  object: string;
+  /** unix seconds */
+  createdAt: number;
+  /** "completed" | "in_progress" | "incomplete" | "failed" */
+  status: string;
+  incompleteDetails?: ResponsesIncompleteDetails;
+  /** carried by a `failed` snapshot */
+  error?: ErrorBody;
+  model: string;
+  output: ResponseItem[];
+  /** null on in-flight snapshots */
+  usage?: ResponsesUsage;
+  /** llmleaf always answers `false`. */
+  store?: boolean;
+  instructions?: string;
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  reasoning?: ResponsesReasoning;
+}
+
+/**
+ * One streaming SSE event. Unlike chat streaming there is NO `data: [DONE]` sentinel —
+ * the stream ends after the terminal `response.completed` / `response.incomplete` /
+ * `response.failed` event. This is a flat superset of every event's fields; {@link type}
+ * says which are meaningful. {@link "./client".LlmleafClient.responsesStream} skips event
+ * types it doesn't recognise (the dialect grows by adding types).
+ */
+export interface ResponsesStreamEvent {
+  /** "response.created", "response.output_text.delta", "error", ... */
+  type: string;
+  sequenceNumber: number;
+  /** response.created / in_progress / completed / incomplete / failed */
+  response?: ResponsesResponse;
+  outputIndex?: number;
+  itemId?: string;
+  contentIndex?: number;
+  /** response.output_item.added / done */
+  item?: ResponseItem;
+  /** response.content_part.added / done */
+  part?: ResponseContentPart;
+  /** *.delta events (text / reasoning / arguments) */
+  delta?: string;
+  /** response.output_text.done / reasoning_text.done */
+  text?: string;
+  /** response.function_call_arguments.done */
+  arguments?: string;
+  /** "error" event */
+  message?: string;
+}