@nirmos/sdk 0.3.2 → 0.3.4

package/examples/memory-quickstart.ts

@@ -0,0 +1,240 @@
+import {
+  APIError,
+  Nirmos,
+  type MemoryIngestRequest,
+  type MemoryPolicyCreate,
+} from "@nirmos/sdk";
+
+declare const process: { env: Record<string, string | undefined> };
+
+async function all<T>(
+  load: (cursor?: string) => Promise<{ items: T[]; nextCursor: string | null }>,
+): Promise<T[]> {
+  const items: T[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await load(cursor);
+    items.push(...page.items);
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor);
+  return items;
+}
+
+/** Server-side only. Persist eventKey with the source event before first ingestion. */
+export async function memoryQuickstart(
+  client: Nirmos,
+  options: {
+    eventKey: string;
+    googleApiKey?: string;
+    cleanup?: boolean;
+    paceMs?: number;
+  },
+) {
+  const pause = () =>
+    new Promise((resolve) => setTimeout(resolve, options.paceMs ?? 20000));
+  const provider = (
+    await all((cursor) => client.providers.list({ cursor, limit: 100 }))
+  ).find((p) => p.slug === "google");
+  if (!provider)
+    throw new Error("Google provider missing from this deployment's catalog.");
+  // Optional SDK setup; dashboard Gateway Credentials → Add credential → Google is equivalent.
+  if (options.googleApiKey)
+    await client.providerCredentials.create({
+      name: "Memory quickstart Google",
+      providerId: provider.id,
+      credentialType: "api_key",
+      secretData: { apiKey: options.googleApiKey },
+      isDefault: true,
+    });
+  const models = await all((cursor) =>
+    client.models.list({ providerId: provider.id, limit: 100, cursor }),
+  );
+  const text = models.find(
+    (m) => m.slug === "google-gemini-2-5-flash-lite" && m.availability,
+  );
+  const embedding = models.find(
+    (m) => m.slug === "google-gemini-embedding-001" && m.availability,
+  );
+  if (!text || !embedding)
+    throw new Error(
+      "Configure an active Google credential and verify both models in models.list(). Availability does not guarantee provider quota.",
+    );
+  if (!embedding.knowledgeSupportedDimensions?.includes(768))
+    throw new Error(
+      "Selected embedding model does not support 768 dimensions in this deployment.",
+    );
+  const textModel = `${provider.slug}/${text.id}`;
+  const policyInput: MemoryPolicyCreate = {
+    policyKey: `${options.eventKey}-policy`,
+    name: "Memory quickstart",
+    version: 1,
+    status: "active",
+    captureTypes: [
+      "preference",
+      "fact",
+      "project_fact",
+      "decision",
+      "constraint",
+      "commitment",
+      "event",
+      "temporary_state",
+    ],
+    allowInferredMemories: false,
+    minimumConfidence: 0.7,
+    minimumFutureUtility: 0.5,
+    defaultMemoryTTLSeconds: 86400,
+    extractionConfig: {
+      model: textModel,
+      reconciliationModel: textModel,
+      profileModel: textModel,
+      observationModel: textModel,
+      indexing: {
+        model: `${provider.slug}/${embedding.id}`,
+        dimensions: 768,
+        distanceMetric: "cosine",
+      },
+    },
+    privacyConfig: {
+      allowPII: false,
+      allowedSensitivities: ["unclassified", "public", "internal"],
+    },
+    retentionConfig: {
+      episodeContent: "full",
+      evidenceExcerpts: true,
+      candidateContent: false,
+    },
+  };
+  const existing = await client.memory.policies.list({
+    policyKey: policyInput.policyKey,
+    limit: 100,
+  });
+  const policy =
+    existing.items.find((p) => p.version === 1) ??
+    (await client.memory.policies.create(policyInput));
+  const spaceKey = `${options.eventKey}/customer-123`;
+  const spaces = await all((cursor) =>
+    client.memory.spaces.list({
+      externalSubjectId: "customer-123",
+      cursor,
+      limit: 100,
+    }),
+  );
+  const space =
+    spaces.find((s) => s.spaceKey === spaceKey) ??
+    (await client.memory.spaces.create({
+      spaceKey,
+      name: "Disposable customer memory",
+      scopeType: "user",
+      scopeId: "customer-123",
+      externalSubjectId: "customer-123",
+      policyId: policy.id,
+    }));
+  const input: MemoryIngestRequest = {
+    memorySpaceId: space.id,
+    conversationId: options.eventKey,
+    idempotencyKey: options.eventKey,
+    messages: [
+      {
+        id: `${options.eventKey}-message`,
+        role: "user",
+        content:
+          "I prefer important notifications through email rather than WhatsApp.",
+      },
+    ],
+  };
+  let result;
+  try {
+    result = await client.memory.ingest(input, {
+      idempotencyKey: options.eventKey,
+      maxRetries: 0,
+    });
+  } catch (error) {
+    if (error instanceof APIError) {
+      // Safe identifiers/categories only; never print secrets, prompts or memory content.
+      console.error({
+        code: error.code,
+        status: error.status,
+        retryable: error.retryable,
+        retryAfterMs: error.retryAfterMs,
+        requestId: error.requestId,
+        diagnostics: error.details,
+      });
+    }
+    // After correcting configuration/quota, call ingest(input) with the SAME event identity.
+    // Do not blindly retry, mutate the input, or generate a fresh key.
+    throw error;
+  }
+  console.log({
+    runId: result.memoryRunId,
+    accepted: result.acceptedCount,
+    rejected: result.rejectedCount,
+    indexing: result.indexing,
+  });
+  const run = await client.memory.runs.get(result.memoryRunId);
+  if (result.indexing.failed)
+    throw new Error(
+      `Indexing incomplete for run ${run.id}; inspect diagnostics and repair through memory.reindex().`,
+    );
+  // A completed event replays without model execution or another memory write.
+  const replay = await client.memory.ingest(input, {
+    idempotencyKey: options.eventKey,
+    maxRetries: 0,
+  });
+  if (replay.memoryRunId !== result.memoryRunId || !replay.replayed)
+    throw new Error("Expected the original completed event to replay.");
+  console.log({ replayed: replay.replayed, runId: replay.memoryRunId });
+  await pause();
+  const search = await client.memory.search({
+    memorySpaceId: space.id,
+    query: "How should I send important notifications?",
+    relevance: "relevant",
+  });
+  console.log({ relevantMatches: search.memories.length });
+  await pause();
+  const context = await client.memory.context({
+    memorySpaceId: space.id,
+    messages: [{ role: "user", content: "How should you notify me?" }],
+  });
+  console.log({ contextMemories: context.memories.length });
+  await pause();
+  await client.memory.profiles.generate({ memorySpaceId: space.id });
+  const profile = await client.memory.profiles.get(space.id);
+  const items = await client.memory.items.list({
+    memorySpaceId: space.id,
+    limit: 25,
+  });
+  const first = items.items[0];
+  if (first) {
+    await client.memory.items.update(first.id, { importance: 0.8 });
+    await client.memory.items.evidence(first.id, { limit: 25 });
+    // Explicit cleanup only for this disposable example's space.
+    if (options.cleanup) await client.memory.items.delete(first.id);
+  }
+  if (options.cleanup) {
+    await client.memory.spaces.delete(space.id);
+    await client.memory.erase(space.id);
+    await client.memory.policies.delete(policy.id);
+  }
+  return { space, policy, result, search, context, profile };
+}
+
+if (process.env.NIRMOS_RUN_MEMORY_EXAMPLE === "1") {
+  const token = process.env.NIRMOS_API_KEY;
+  const eventKey = process.env.MEMORY_EVENT_KEY;
+  if (!token || !eventKey)
+    throw new Error("Set NIRMOS_API_KEY and a persisted MEMORY_EVENT_KEY.");
+  await memoryQuickstart(
+    new Nirmos({
+      auth: { type: "api-key", key: token },
+      apiBaseUrl: process.env.NIRMOS_API_BASE_URL ?? "http://localhost:4001",
+      runtimeBaseUrl:
+        process.env.NIRMOS_RUNTIME_BASE_URL ?? "http://localhost:4000",
+      maxRetries: 0,
+    }),
+    {
+      eventKey,
+      googleApiKey: process.env.GOOGLE_API_KEY,
+      cleanup: process.env.MEMORY_CLEANUP === "1",
+    },
+  );
+}

package/examples/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": { "noEmit": true, "rootDir": ".." },
+  "include": ["*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nirmos/sdk",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Official TypeScript SDK for the Nirmos AI platform.",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "examples"
   ],
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -21,11 +22,11 @@
     }
   },
   "scripts": {
-    "build": "node ./scripts/clean.mjs && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package.mjs",
+    "build": "node ./scripts/generate-version.mjs && node ./scripts/clean.mjs && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package.mjs && node ./scripts/generate-examples.mjs",
     "check-types": "tsc --noEmit",
     "lint": "eslint src tests --max-warnings 0",
     "prepack": "pnpm build",
-    "test": "node ./scripts/ensure-built.mjs && tsc -p tests/tsconfig.json && node --test tests/*.test.mjs"
+    "test": "node ./scripts/ensure-built.mjs && tsc -p examples/tsconfig.json && tsc -p tests/tsconfig.json && node --test tests/*.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/src/core/transport.ts

@@ -47,7 +47,7 @@ export interface TransportResponse<T> {
   response: Response;
 }
 
-const SDK_VERSION = "0.3.0";
+import { SDK_VERSION } from "./version.js";
 
 export class HttpTransport {
   readonly #config: TransportConfig;
@@ -95,7 +95,7 @@ export class HttpTransport {
         if (
           retryableMethod &&
           attempt < maxRetries &&
-          isRetryableStatus(response.status)
+          (await mayRetryResponse(response))
         ) {
           await response.body?.cancel();
           await waitBeforeRetry(response, attempt, request.options?.signal);
@@ -319,6 +319,18 @@ function isRetryableStatus(status: number): boolean {
   return status === 408 || status === 429 || status >= 500;
 }
 
+/** Server retryability overrides status defaults, including daily provider quota. */
+async function mayRetryResponse(response: Response): Promise<boolean> {
+  if (!isRetryableStatus(response.status)) return false;
+  try {
+    const payload = asUnknownRecord(await response.clone().json());
+    return readBoolean(asUnknownRecord(payload.error), "retryable") !== false;
+  } catch {
+    // Non-JSON legacy responses retain bounded status-based retry behavior.
+    return true;
+  }
+}
+
 function parseRetryAfter(value: string | null): number | undefined {
   if (!value) return undefined;
   const seconds = Number(value);

package/src/core/version.ts

@@ -0,0 +1,2 @@
+// Generated from package.json by scripts/generate-version.mjs.
+export const SDK_VERSION = "0.3.4";

package/src/evaluations/types.ts

@@ -0,0 +1,18 @@
+import type { Requests } from "../management/contracts.js";
+
+/** Built-in evaluator versions are discriminated by type. Configs follow the API schemas. */
+export type EvaluationEvaluatorVersion = Requests["createEvaluatorVersion"];
+export type EvaluationTargetConfig = NonNullable<
+  Requests["createEvaluationColumn"]["target"]
+>;
+export type EvaluationColumnCreate = Requests["createEvaluationColumn"];
+export type EvaluationInputBinding = NonNullable<
+  NonNullable<EvaluationColumnCreate["config"]>["inputMapping"]
+>[string];
+export type EvaluationSegmentCriteria = Requests["createSegment"]["criteria"];
+
+export type EvaluationEvaluatorType = EvaluationEvaluatorVersion["type"];
+export type EvaluationEvaluatorConfig<T extends EvaluationEvaluatorType> =
+  Extract<EvaluationEvaluatorVersion, { type: T }>["config"];
+export type EvaluationExpression =
+  EvaluationEvaluatorConfig<"custom_expression">["expression"];

package/src/gateway/chat-stream.ts

@@ -8,7 +8,7 @@ import {
   readString,
 } from "../core/metadata.js";
 import type { RequestMetadata, Usage } from "../core/types.js";
-import { normalizeToolCall, normalizeUsage } from "./mappers.js";
+import { mergeReasoningDetails, normalizeToolCall, normalizeUsage } from "./mappers.js";
 import type {
   ChatChoice,
   ChatCompletion,
@@ -21,6 +21,8 @@ type MutableChoice = {
   index: number;
   role: ChatMessage["role"];
   content: string;
+  reasoning?: string;
+  reasoningDetails?: ChatMessage["reasoningDetails"];
   finishReason: ChatChoice["finishReason"];
   toolCalls: Map<number, FunctionToolCall>;
 };
@@ -140,6 +142,13 @@ export class ChatStream implements AsyncIterable<ChatStreamEvent> {
                   : finishReason;
           }
 
+          const reasoning = readString(delta, "reasoning");
+          if (reasoning) {
+            mutable.reasoning = (mutable.reasoning ?? "") + reasoning;
+            yield { type: "reasoning.delta", id: this.#id, model: this.#model, choiceIndex: index, delta: reasoning, metadata: this.#metadata };
+          }
+          const details = readArray(delta, "reasoning_details", "reasoningDetails") as NonNullable<ChatMessage["reasoningDetails"]>;
+          if (details.length) mutable.reasoningDetails = mergeReasoningDetails(mutable.reasoningDetails ?? [], details);
           const content = readString(delta, "content");
           if (content) {
             mutable.content += content;
@@ -235,6 +244,8 @@ export class ChatStream implements AsyncIterable<ChatStreamEvent> {
         message: {
           role: choice.role,
           content: choice.content,
+          ...(choice.reasoning !== undefined ? { reasoning: choice.reasoning } : {}),
+          ...(choice.reasoningDetails ? { reasoningDetails: choice.reasoningDetails } : {}),
           ...(choice.toolCalls.size > 0
             ? { toolCalls: [...choice.toolCalls.values()] }
             : {}),

package/src/gateway/chat.ts

@@ -77,6 +77,7 @@ export class Chat {
       seed: params.seed,
       user: params.user,
       provider: params.provider,
+      provider_options: params.providerOptions,
       fallback_models: params.fallbackModels,
       routing_strategy: toWireRoutingStrategy(params.routingStrategy),
       metadata: params.metadata,

package/src/gateway/embeddings.ts

@@ -28,6 +28,7 @@ export class Embeddings {
         encoding_format: params.encoding,
         user: params.user,
         provider: params.provider,
+      provider_options: params.providerOptions,
         fallback_models: params.fallbackModels,
         routing_strategy: toWireRoutingStrategy(params.routingStrategy),
       },

package/src/gateway/mappers.ts

@@ -36,6 +36,12 @@ export function toWireMessage(message: ChatMessage): Record<string, unknown> {
               audio: { data: part.data, format: part.format },
             };
           }),
+    ...(message.reasoning !== undefined
+      ? { reasoning: message.reasoning }
+      : {}),
+    ...(message.reasoningDetails?.length
+      ? { reasoning_details: message.reasoningDetails }
+      : {}),
     ...(message.name ? { name: message.name } : {}),
     ...(message.toolCallId ? { tool_call_id: message.toolCallId } : {}),
     ...(message.toolCalls && message.toolCalls.length > 0
@@ -68,8 +74,15 @@ export function normalizeUsage(value: unknown): Usage {
     totalTokens:
       readNumber(usage, "total_tokens", "totalTokens") ??
       inputTokens + outputTokens,
-    cachedTokens: readNumber(usage, "cached_tokens", "cachedTokens"),
-    reasoningTokens: readNumber(usage, "reasoning_tokens", "reasoningTokens"),
+    cachedTokens:
+      readNumber(usage, "cached_tokens", "cachedTokens") ??
+      readNumber(asUnknownRecord(usage.prompt_tokens_details), "cached_tokens"),
+    reasoningTokens:
+      readNumber(usage, "reasoning_tokens", "reasoningTokens") ??
+      readNumber(
+        asUnknownRecord(usage.completion_tokens_details),
+        "reasoning_tokens",
+      ),
   };
 }
 
@@ -183,6 +196,12 @@ export function normalizeMessage(value: unknown): ChatMessage {
         ? content
         : "",
     name: readString(message, "name"),
+    reasoning: readString(message, "reasoning"),
+    reasoningDetails: readArray(
+      message,
+      "reasoning_details",
+      "reasoningDetails",
+    ) as ChatMessage["reasoningDetails"],
     toolCallId: readString(message, "tool_call_id", "toolCallId"),
     toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
   };
@@ -232,3 +251,37 @@ function normalizeFinishReason(
   if (value === "content_filter") return "contentFilter";
   return value;
 }
+
+/** Assemble indexed reasoning blocks without losing encrypted continuation data. */
+export function mergeReasoningDetails(
+  current: NonNullable<ChatMessage["reasoningDetails"]>,
+  incoming: NonNullable<ChatMessage["reasoningDetails"]>,
+): NonNullable<ChatMessage["reasoningDetails"]> {
+  const result = [...current];
+  for (const value of incoming) {
+    const detail = asUnknownRecord(value);
+    const position = result.findIndex((item) => {
+      const previous = asUnknownRecord(item);
+      return (
+        previous.type === detail.type &&
+        ((detail.index !== undefined && previous.index === detail.index) ||
+          (typeof detail.id === "string" && previous.id === detail.id))
+      );
+    });
+    if (position < 0) {
+      result.push(value);
+      continue;
+    }
+    const previous = asUnknownRecord(result[position]);
+    const merged = { ...previous, ...detail };
+    for (const field of ["text", "summary", "data", "signature"]) {
+      if (
+        typeof previous[field] === "string" &&
+        typeof detail[field] === "string"
+      )
+        merged[field] = previous[field] + detail[field];
+    }
+    result[position] = merged as (typeof result)[number];
+  }
+  return result;
+}

package/src/gateway/types.ts

@@ -45,6 +45,8 @@ export interface ChatMessage {
   role: ChatRole;
   content: string | readonly ChatContentPart[];
   name?: string;
+  reasoning?: string;
+  reasoningDetails?: readonly JsonValue[];
   toolCallId?: string;
   toolCalls?: readonly FunctionToolCall[];
 }
@@ -106,6 +108,8 @@ interface ChatCreateParamsBase {
   user?: string;
   /** Optional provider override. Omit to let the gateway select a provider. */
   provider?: string;
+  /** Options scoped to an upstream provider slug; other targets never receive them. */
+  providerOptions?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
   fallbackModels?: readonly string[];
   routingStrategy?: RoutingStrategy;
   metadata?: Readonly<Record<string, JsonValue>>;
@@ -167,6 +171,8 @@ export interface EmbeddingCreateParams {
   user?: string;
   /** Optional provider override. Omit to use the model's configured default provider. */
   provider?: string;
+  /** Options scoped to an upstream provider slug; other targets never receive them. */
+  providerOptions?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
   /** @deprecated Embeddings never fall back to another vector space. Requests with this option are rejected. */
   fallbackModels?: readonly string[];
   /** @deprecated Embeddings require direct model selection. */
@@ -204,6 +210,8 @@ export interface ImageGenerateParams {
   user?: string;
   /** Optional provider override. Omit to use the model's configured default provider. */
   provider?: string;
+  /** Options scoped to an upstream provider slug; other targets never receive them. */
+  providerOptions?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
   metadata?: Readonly<Record<string, JsonValue>>;
 }
 

package/src/index.ts

@@ -150,3 +150,14 @@ export {
   validatePromptVariableValues,
   validatePromptSettings,
 } from "./prompts/variables.js";
+
+export type {
+  EvaluationEvaluatorVersion,
+  EvaluationEvaluatorType,
+  EvaluationEvaluatorConfig,
+  EvaluationExpression,
+  EvaluationTargetConfig,
+  EvaluationColumnCreate,
+  EvaluationInputBinding,
+  EvaluationSegmentCriteria,
+} from "./evaluations/types.js";