@nirmos/sdk 0.1.0

package/src/gateway/chat.ts

@@ -0,0 +1,134 @@
+import { ValidationError } from "../core/errors.js";
+import type { RequestOptions } from "../core/types.js";
+import type { HttpTransport } from "../core/transport.js";
+import type { Prompts } from "../prompts/prompts.js";
+import { ChatStream } from "./chat-stream.js";
+import { normalizeChatCompletion, toWireMessage } from "./mappers.js";
+import type {
+  ChatCompletion,
+  ChatCreateParams,
+  ChatMessage,
+  ResponseFormat,
+  RoutingStrategy,
+} from "./types.js";
+
+export class Chat {
+  readonly #transport: HttpTransport;
+  readonly #prompts: Prompts;
+
+  constructor(transport: HttpTransport, prompts: Prompts) {
+    this.#transport = transport;
+    this.#prompts = prompts;
+  }
+
+  async create(
+    params: ChatCreateParams,
+    options?: RequestOptions,
+  ): Promise<ChatCompletion> {
+    const body = await this.#body(params, false);
+    const { data, response } = await this.#transport.request<unknown>({
+      method: "POST",
+      path: "/v1/chat/completions",
+      body,
+      options,
+    });
+    return normalizeChatCompletion(data, response);
+  }
+
+  async stream(
+    params: ChatCreateParams,
+    options?: RequestOptions,
+  ): Promise<ChatStream> {
+    const body = await this.#body(params, true);
+    const response = await this.#transport.fetch({
+      method: "POST",
+      path: "/v1/chat/completions",
+      body,
+      options,
+    });
+    return new ChatStream(await this.#transport.ensureSuccess(response));
+  }
+
+  async #body(
+    params: ChatCreateParams,
+    stream: boolean,
+  ): Promise<Record<string, unknown>> {
+    const messages = await this.#messages(params);
+    if (!params.model.trim()) {
+      throw localValidation("model", "Model is required.");
+    }
+    if (messages.length === 0) {
+      throw localValidation(
+        "messages",
+        "Provide messages, a managed prompt, or both.",
+      );
+    }
+
+    return {
+      model: params.model,
+      messages: messages.map(toWireMessage),
+      stream,
+      temperature: params.temperature,
+      top_p: params.topP,
+      max_tokens: params.maxOutputTokens,
+      stop: params.stop,
+      tools: params.tools,
+      tool_choice: params.toolChoice,
+      response_format: toWireResponseFormat(params.responseFormat),
+      seed: params.seed,
+      user: params.user,
+      provider: params.provider,
+      fallback_models: params.fallbackModels,
+      routing_strategy: toWireRoutingStrategy(params.routingStrategy),
+      metadata: params.metadata,
+    };
+  }
+
+  async #messages(params: ChatCreateParams): Promise<readonly ChatMessage[]> {
+    const requestMessages = params.messages ?? [];
+    if (!params.prompt) return requestMessages;
+
+    const rendered = await this.#prompts.render(
+      {
+        id: params.prompt.id,
+        version: params.prompt.version,
+        cache: params.prompt.cache,
+      },
+      params.prompt.variables,
+    );
+
+    return params.prompt.position === "after"
+      ? [...requestMessages, ...rendered.messages]
+      : [...rendered.messages, ...requestMessages];
+  }
+}
+
+function toWireResponseFormat(
+  format: ResponseFormat | undefined,
+): Record<string, unknown> | undefined {
+  if (!format) return undefined;
+  if (format.type === "text") return { type: "text" };
+  if (format.type === "jsonObject") return { type: "json_object" };
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: format.name,
+      schema: format.schema,
+      strict: format.strict,
+    },
+  };
+}
+
+function toWireRoutingStrategy(
+  strategy: RoutingStrategy | undefined,
+): string | undefined {
+  return strategy === "highestQuality" ? "highest_quality" : strategy;
+}
+
+function localValidation(field: string, message: string): ValidationError {
+  return new ValidationError(message, {
+    status: 400,
+    code: "SDK_VALIDATION_ERROR",
+    details: { field },
+  });
+}

package/src/gateway/embeddings.ts

@@ -0,0 +1,44 @@
+import type { HttpTransport } from "../core/transport.js";
+import type { RequestOptions } from "../core/types.js";
+import { normalizeEmbeddingResponse } from "./mappers.js";
+import type {
+  EmbeddingCreateParams,
+  EmbeddingResponse,
+  RoutingStrategy,
+} from "./types.js";
+
+export class Embeddings {
+  readonly #transport: HttpTransport;
+
+  constructor(transport: HttpTransport) {
+    this.#transport = transport;
+  }
+
+  async create(
+    params: EmbeddingCreateParams,
+    options?: RequestOptions,
+  ): Promise<EmbeddingResponse> {
+    const { data, response } = await this.#transport.request<unknown>({
+      method: "POST",
+      path: "/v1/embeddings",
+      body: {
+        model: params.model,
+        input: params.input,
+        dimensions: params.dimensions,
+        encoding_format: params.encoding,
+        user: params.user,
+        provider: params.provider,
+        fallback_models: params.fallbackModels,
+        routing_strategy: toWireRoutingStrategy(params.routingStrategy),
+      },
+      options,
+    });
+    return normalizeEmbeddingResponse(data, response);
+  }
+}
+
+function toWireRoutingStrategy(
+  strategy: RoutingStrategy | undefined,
+): string | undefined {
+  return strategy === "highestQuality" ? "highest_quality" : strategy;
+}

package/src/gateway/gateway.ts

@@ -0,0 +1,17 @@
+import type { HttpTransport } from "../core/transport.js";
+import type { Prompts } from "../prompts/prompts.js";
+import { Chat } from "./chat.js";
+import { Embeddings } from "./embeddings.js";
+import { Images } from "./images.js";
+
+export class Gateway {
+  readonly chat: Chat;
+  readonly embeddings: Embeddings;
+  readonly images: Images;
+
+  constructor(transport: HttpTransport, prompts: Prompts) {
+    this.chat = new Chat(transport, prompts);
+    this.embeddings = new Embeddings(transport);
+    this.images = new Images(transport);
+  }
+}

package/src/gateway/images.ts

@@ -0,0 +1,41 @@
+import type { HttpTransport } from "../core/transport.js";
+import type { RequestOptions } from "../core/types.js";
+import { normalizeImageGeneration } from "./mappers.js";
+import type { ImageGenerateParams, ImageGeneration } from "./types.js";
+
+export class Images {
+  readonly #transport: HttpTransport;
+
+  constructor(transport: HttpTransport) {
+    this.#transport = transport;
+  }
+
+  async generate(
+    params: ImageGenerateParams,
+    options?: RequestOptions,
+  ): Promise<ImageGeneration> {
+    const { data, response } = await this.#transport.request<unknown>({
+      method: "POST",
+      path: "/v1/images/generations",
+      body: {
+        model: params.model,
+        prompt: params.prompt,
+        n: params.count,
+        size: params.size,
+        quality: params.quality,
+        style: params.style,
+        output_format: params.format,
+        response_format:
+          params.responseFormat === "base64"
+            ? "b64_json"
+            : params.responseFormat,
+        background: params.background,
+        user: params.user,
+        provider: params.provider,
+        metadata: params.metadata,
+      },
+      options,
+    });
+    return normalizeImageGeneration(data, response);
+  }
+}

package/src/gateway/mappers.ts

@@ -0,0 +1,234 @@
+import {
+  asUnknownRecord,
+  compactMetadata,
+  extractMetadata,
+  readArray,
+  readNumber,
+  readString,
+} from "../core/metadata.js";
+import type { Usage } from "../core/types.js";
+import type {
+  ChatChoice,
+  ChatCompletion,
+  ChatContentPart,
+  ChatMessage,
+  EmbeddingResponse,
+  FunctionToolCall,
+  ImageGeneration,
+} from "./types.js";
+
+export function toWireMessage(message: ChatMessage): Record<string, unknown> {
+  return {
+    role: message.role,
+    content:
+      typeof message.content === "string"
+        ? message.content
+        : message.content.map((part) => {
+            if (part.type === "text") return { type: "text", text: part.text };
+            if (part.type === "image") {
+              return {
+                type: "image_url",
+                image_url: { url: part.url, detail: part.detail },
+              };
+            }
+            return {
+              type: "audio",
+              audio: { data: part.data, format: part.format },
+            };
+          }),
+    ...(message.name ? { name: message.name } : {}),
+    ...(message.toolCallId ? { tool_call_id: message.toolCallId } : {}),
+    ...(message.toolCalls && message.toolCalls.length > 0
+      ? { tool_calls: message.toolCalls }
+      : {}),
+  };
+}
+
+export function normalizeUsage(value: unknown): Usage {
+  const usage = asUnknownRecord(value);
+  const inputTokens =
+    readNumber(
+      usage,
+      "input_tokens",
+      "inputTokens",
+      "prompt_tokens",
+      "promptTokens",
+    ) ?? 0;
+  const outputTokens =
+    readNumber(
+      usage,
+      "output_tokens",
+      "outputTokens",
+      "completion_tokens",
+      "completionTokens",
+    ) ?? 0;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens:
+      readNumber(usage, "total_tokens", "totalTokens") ??
+      inputTokens + outputTokens,
+    cachedTokens: readNumber(usage, "cached_tokens", "cachedTokens"),
+    reasoningTokens: readNumber(usage, "reasoning_tokens", "reasoningTokens"),
+  };
+}
+
+export function normalizeChatCompletion(
+  payload: unknown,
+  response: Response,
+): ChatCompletion {
+  const root = asUnknownRecord(payload);
+  const choices = readArray(root, "choices").map(normalizeChoice);
+  const metadata = compactMetadata(extractMetadata(response, payload));
+
+  return {
+    id: readString(root, "id") ?? metadata.requestId ?? "",
+    createdAt: readNumber(root, "created", "created_at", "createdAt") ?? 0,
+    model: readString(root, "model") ?? metadata.model ?? "",
+    choices,
+    outputText: choices
+      .map((choice) =>
+        typeof choice.message.content === "string"
+          ? choice.message.content
+          : choice.message.content
+              .filter((part) => part.type === "text")
+              .map((part) => (part.type === "text" ? part.text : ""))
+              .join(""),
+      )
+      .join(""),
+    usage: normalizeUsage(root.usage),
+    metadata,
+  };
+}
+
+export function normalizeEmbeddingResponse(
+  payload: unknown,
+  response: Response,
+): EmbeddingResponse {
+  const root = asUnknownRecord(payload);
+  const metadata = compactMetadata(extractMetadata(response, payload));
+  return {
+    model: readString(root, "model") ?? metadata.model ?? "",
+    embeddings: readArray(root, "data", "embeddings").map((entry, position) => {
+      const item = asUnknownRecord(entry);
+      const index = readNumber(item, "index") ?? position;
+      const embedding = item.embedding ?? item.values ?? item.base64;
+      if (typeof embedding === "string") return { index, base64: embedding };
+      return {
+        index,
+        values: Array.isArray(embedding)
+          ? embedding.filter(
+              (value): value is number => typeof value === "number",
+            )
+          : [],
+      };
+    }),
+    usage: normalizeUsage(root.usage),
+    metadata,
+  };
+}
+
+export function normalizeImageGeneration(
+  payload: unknown,
+  response: Response,
+): ImageGeneration {
+  const root = asUnknownRecord(payload);
+  const metadata = compactMetadata(extractMetadata(response, payload));
+  const usage =
+    root.usage === undefined ? undefined : normalizeUsage(root.usage);
+
+  return {
+    id: readString(root, "id"),
+    createdAt: readNumber(root, "created", "created_at", "createdAt") ?? 0,
+    model: readString(root, "model") ?? metadata.model ?? "",
+    images: readArray(root, "data", "images").map((entry) => {
+      const image = asUnknownRecord(entry);
+      return {
+        url: readString(image, "url"),
+        base64: readString(image, "b64_json", "base64"),
+        revisedPrompt: readString(image, "revised_prompt", "revisedPrompt"),
+        mediaType: readString(image, "media_type", "mediaType"),
+        width: readNumber(image, "width"),
+        height: readNumber(image, "height"),
+      };
+    }),
+    usage,
+    metadata,
+  };
+}
+
+export function normalizeChoice(value: unknown): ChatChoice {
+  const choice = asUnknownRecord(value);
+  const message = asUnknownRecord(choice.message);
+  return {
+    index: readNumber(choice, "index") ?? 0,
+    message: normalizeMessage(message),
+    finishReason: normalizeFinishReason(
+      readString(choice, "finish_reason", "finishReason"),
+    ),
+  };
+}
+
+export function normalizeMessage(value: unknown): ChatMessage {
+  const message = asUnknownRecord(value);
+  const content = message.content;
+  const toolCalls = readArray(message, "tool_calls", "toolCalls").map(
+    normalizeToolCall,
+  );
+  return {
+    role: (readString(message, "role") ?? "assistant") as ChatMessage["role"],
+    content: Array.isArray(content)
+      ? content.map(normalizeContentPart)
+      : typeof content === "string"
+        ? content
+        : "",
+    name: readString(message, "name"),
+    toolCallId: readString(message, "tool_call_id", "toolCallId"),
+    toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+  };
+}
+
+export function normalizeToolCall(value: unknown): FunctionToolCall {
+  const call = asUnknownRecord(value);
+  const fn = asUnknownRecord(call.function);
+  return {
+    id: readString(call, "id") ?? "",
+    type: "function",
+    function: {
+      name: readString(fn, "name") ?? "",
+      arguments: readString(fn, "arguments") ?? "",
+    },
+  };
+}
+
+function normalizeContentPart(value: unknown): ChatContentPart {
+  const part = asUnknownRecord(value);
+  const type = readString(part, "type");
+  if (type === "image" || type === "image_url") {
+    const image = asUnknownRecord(part.image_url);
+    return {
+      type: "image",
+      url: readString(part, "url") ?? readString(image, "url") ?? "",
+      detail: (readString(part, "detail") ?? readString(image, "detail")) as
+        "auto" | "low" | "high" | undefined,
+    };
+  }
+  if (type === "audio" || type === "input_audio") {
+    const audio = asUnknownRecord(part.audio ?? part.input_audio);
+    return {
+      type: "audio",
+      data: readString(part, "data") ?? readString(audio, "data") ?? "",
+      format: readString(part, "format") ?? readString(audio, "format") ?? "",
+    };
+  }
+  return { type: "text", text: readString(part, "text") ?? "" };
+}
+
+function normalizeFinishReason(
+  value: string | undefined,
+): ChatChoice["finishReason"] {
+  if (!value) return null;
+  if (value === "tool_calls") return "toolCalls";
+  if (value === "content_filter") return "contentFilter";
+  return value;
+}

package/src/gateway/types.ts

@@ -0,0 +1,206 @@
+import type {
+  ExtensibleString,
+  JsonValue,
+  RequestMetadata,
+  Usage,
+} from "../core/types.js";
+import type {
+  PromptCacheMode,
+  PromptIdentifier,
+  PromptVariableValues,
+} from "../prompts/types.js";
+
+export type ChatRole = "system" | "developer" | "user" | "assistant" | "tool";
+
+export interface TextContentPart {
+  type: "text";
+  text: string;
+}
+
+export interface ImageContentPart {
+  type: "image";
+  url: string;
+  detail?: "auto" | "low" | "high";
+}
+
+export interface AudioContentPart {
+  type: "audio";
+  data: string;
+  format: string;
+}
+
+export type ChatContentPart =
+  TextContentPart | ImageContentPart | AudioContentPart;
+
+export interface FunctionToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+export interface ChatMessage {
+  role: ChatRole;
+  content: string | readonly ChatContentPart[];
+  name?: string;
+  toolCallId?: string;
+  toolCalls?: readonly FunctionToolCall[];
+}
+
+export interface FunctionTool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Readonly<Record<string, unknown>>;
+    strict?: boolean;
+  };
+}
+
+export type ToolChoice =
+  | "auto"
+  | "none"
+  | "required"
+  | {
+      type: "function";
+      function: { name: string };
+    };
+
+export type ResponseFormat =
+  | { type: "text" }
+  | { type: "jsonObject" }
+  | {
+      type: "jsonSchema";
+      name: string;
+      schema: Readonly<Record<string, unknown>>;
+      strict?: boolean;
+    };
+
+export type RoutingStrategy = ExtensibleString<
+  "auto" | "cheapest" | "fastest" | "highestQuality" | "reasoning" | "specific"
+>;
+
+export interface PromptReference {
+  id: PromptIdentifier;
+  version?: number | "active" | "latest";
+  variables?: PromptVariableValues;
+  cache?: PromptCacheMode;
+  /** Prompt messages are inserted before request messages by default. */
+  position?: "before" | "after";
+}
+
+export interface ChatCreateParams {
+  model: string;
+  messages?: readonly ChatMessage[];
+  /** Resolve and render a managed prompt before sending the gateway request. */
+  prompt?: PromptReference;
+  temperature?: number;
+  topP?: number;
+  maxOutputTokens?: number;
+  stop?: string | readonly string[];
+  tools?: readonly FunctionTool[];
+  toolChoice?: ToolChoice;
+  responseFormat?: ResponseFormat;
+  seed?: number;
+  user?: string;
+  provider?: string;
+  fallbackModels?: readonly string[];
+  routingStrategy?: RoutingStrategy;
+  metadata?: Readonly<Record<string, JsonValue>>;
+}
+
+export type FinishReason = ExtensibleString<
+  "stop" | "length" | "toolCalls" | "contentFilter"
+>;
+
+export interface ChatChoice {
+  index: number;
+  message: ChatMessage;
+  finishReason: FinishReason | null;
+}
+
+export interface ChatCompletion {
+  id: string;
+  createdAt: number;
+  model: string;
+  choices: readonly ChatChoice[];
+  outputText: string;
+  usage: Usage;
+  metadata: RequestMetadata;
+}
+
+export interface ChatStreamEvent {
+  type: ExtensibleString<
+    "content.delta" | "toolCall.delta" | "completion.completed"
+  >;
+  id: string;
+  model: string;
+  choiceIndex?: number;
+  delta?: string;
+  toolCall?: Partial<FunctionToolCall>;
+  completion?: ChatCompletion;
+  metadata: RequestMetadata;
+}
+
+export interface EmbeddingCreateParams {
+  model: string;
+  input: string | readonly string[];
+  dimensions?: number;
+  encoding?: "float" | "base64";
+  user?: string;
+  provider?: string;
+  fallbackModels?: readonly string[];
+  routingStrategy?: RoutingStrategy;
+}
+
+export type Embedding =
+  | { index: number; values: readonly number[]; base64?: never }
+  | { index: number; values?: never; base64: string };
+
+export interface EmbeddingResponse {
+  model: string;
+  embeddings: readonly Embedding[];
+  usage: Usage;
+  metadata: RequestMetadata;
+}
+
+export type ImageSize = ExtensibleString<
+  "256x256" | "512x512" | "1024x1024" | "1024x1792" | "1792x1024" | "auto"
+>;
+
+export interface ImageGenerateParams {
+  model: string;
+  prompt: string;
+  count?: number;
+  size?: ImageSize;
+  quality?: ExtensibleString<
+    "standard" | "hd" | "low" | "medium" | "high" | "auto"
+  >;
+  style?: ExtensibleString<"natural" | "vivid">;
+  format?: ExtensibleString<"png" | "jpeg" | "webp">;
+  responseFormat?: "url" | "base64";
+  background?: ExtensibleString<"transparent" | "opaque" | "auto">;
+  user?: string;
+  provider?: string;
+  metadata?: Readonly<Record<string, JsonValue>>;
+}
+
+export interface GeneratedImage {
+  url?: string;
+  base64?: string;
+  revisedPrompt?: string;
+  mediaType?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface ImageGeneration {
+  id?: string;
+  createdAt: number;
+  model: string;
+  images: readonly GeneratedImage[];
+  usage?: Usage;
+  metadata: RequestMetadata;
+}