@nirmos/sdk 0.3.2 → 0.3.3

package/dist/esm/memory/types.d.ts

@@ -65,6 +65,10 @@ export interface MemorySearchFilters {
 export interface MemorySearchRequest {
     memorySpaceId: string;
     query: string;
+    /** Default relevant: one bounded model check. Raw returns nearest neighbors without validation. */
+    relevance?: "relevant" | "raw";
+    /** Minimum normalized vector similarity (0–1), before ranking. Calibrate per embedding model. */
+    minScore?: number;
     limit?: number;
     filters?: MemorySearchFilters;
 }
@@ -75,14 +79,19 @@ export type MemoryResult = Pick<MemoryItem, "id" | "content" | "type" | "layer"
 export interface MemorySearchResponse {
     memories: Array<MemoryResult & {
         score: number;
+        similarityScore: number;
     }>;
+    relevance: "relevant" | "raw";
 }
-export interface MemoryContextResponse {
-    memories: Array<MemoryResult & {
-        score?: number;
-    }>;
-}
+export type MemoryContextResponse = MemorySearchResponse;
 export interface MemoryIndexingResult {
+    /** Safe stage/provider diagnostics for partial indexing failures. */
+    diagnostics?: Array<{
+        code: string;
+        status: number;
+        retryable: boolean;
+        details?: Record<string, unknown>;
+    }>;
     indexed: number;
     failed: number;
 }

package/dist/esm/memory/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/memory/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/examples/memory-quickstart.mjs

@@ -0,0 +1,199 @@
+// Generated from memory-quickstart.ts. Do not edit.
+import { APIError, Nirmos, } from "@nirmos/sdk";
+async function all(load) {
+    const items = [];
+    let cursor;
+    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, options) {
+    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 = {
+        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 = {
+        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/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": ["memory-quickstart.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nirmos/sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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.3";

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),
       },