@nirmos/sdk 0.3.1 → 0.3.3

package/dist/esm/prompts/variables.js

@@ -0,0 +1,108 @@
+/** Shared placeholder semantics for managed prompts, the dashboard and execution. */
+export const PROMPT_VARIABLE_PATTERN = /\{\{\s*([a-zA-Z][a-zA-Z0-9_.-]*)\s*\}\}/g;
+export function extractPromptVariableNames(...values) {
+    return [
+        ...new Set(values.flatMap((value) => [...(value ?? "").matchAll(PROMPT_VARIABLE_PATTERN)].map((match) => match[1]))),
+    ];
+}
+export function promptVariableValue(values, name) {
+    if (Object.hasOwn(values, name))
+        return values[name];
+    let current = values;
+    for (const key of name.split(".")) {
+        if (["__proto__", "prototype", "constructor"].includes(key) ||
+            !current ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, key))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+export function interpolatePromptVariables(text, values) {
+    return text.replace(PROMPT_VARIABLE_PATTERN, (token, name) => {
+        const value = promptVariableValue(values, name);
+        return value === undefined
+            ? token
+            : typeof value === "string"
+                ? value
+                : JSON.stringify(value);
+    });
+}
+export function validatePromptTemplate(text) {
+    const remaining = text.replace(PROMPT_VARIABLE_PATTERN, "");
+    return /\{\{|\{%/.test(remaining)
+        ? [
+            "Unsupported variable syntax. Use {{name}}, {{ spaced }}, or {{user.name}}. Expressions, filters and template blocks cannot run as managed prompt variables.",
+        ]
+        : [];
+}
+export function validatePromptVariableValues(definitions, values) {
+    const errors = {};
+    for (const definition of definitions) {
+        const supplied = promptVariableValue(values, definition.name);
+        const value = supplied === undefined ? definition.default : supplied;
+        let error = "";
+        if (value === undefined || value === "") {
+            if (definition.required)
+                error = "A value is required.";
+        }
+        else {
+            const type = definition.type;
+            if (type === "number" &&
+                (typeof value !== "number" || !Number.isFinite(value)))
+                error = "Enter a valid number.";
+            if (type === "boolean" && typeof value !== "boolean")
+                error = "Choose true or false.";
+            if (type === "string" && typeof value !== "string")
+                error = "Enter text.";
+            if (type === "enum" &&
+                !(definition.enum ?? definition.values)?.includes(String(value)))
+                error = "Choose one of the allowed values.";
+            if (type === "array" && !Array.isArray(value))
+                error = "Enter a valid array.";
+            if (typeof value === "number" &&
+                ((definition.min !== undefined && value < definition.min) ||
+                    (definition.max !== undefined && value > definition.max)))
+                error = `Enter a number between ${definition.min ?? "−∞"} and ${definition.max ?? "∞"}.`;
+            const minLength = definition.minLength ?? definition.min_length;
+            const maxLength = definition.maxLength ?? definition.max_length;
+            if (typeof value === "string" &&
+                ((minLength !== undefined && value.length < minLength) ||
+                    (maxLength !== undefined && value.length > maxLength)))
+                error = `Use ${minLength ?? 0} to ${maxLength ?? "any number of"} characters.`;
+            const itemType = definition.itemType ?? definition.item_type;
+            if (Array.isArray(value) &&
+                itemType &&
+                value.some((item) => itemType === "array"
+                    ? !Array.isArray(item)
+                    : itemType !== "enum" && typeof item !== itemType))
+                error = `Every item must be ${itemType}.`;
+        }
+        if (error)
+            errors[definition.name] = error;
+    }
+    return errors;
+}
+export function validatePromptSettings(settings) {
+    const errors = {};
+    for (const [field, label, min, max] of [
+        ["temperature", "Temperature", 0, 2],
+        ["topP", "Top P", 0, 1],
+        ["maxTokens", "Max tokens", 1, 200000],
+    ]) {
+        const raw = settings[field];
+        const value = Number(raw);
+        if (raw === "" ||
+            raw === null ||
+            raw === undefined ||
+            !Number.isFinite(value) ||
+            value < min ||
+            value > max ||
+            (field === "maxTokens" && !Number.isInteger(value)))
+            errors[field] =
+                `${label} must be ${field === "maxTokens" ? "a whole number" : "a number"} between ${min} and ${max}.`;
+    }
+    return errors;
+}
+//# sourceMappingURL=variables.js.map

package/dist/esm/prompts/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../../src/prompts/variables.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.1",
+  "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/client.ts

@@ -72,18 +72,7 @@ export class Nirmos {
     ) => Promise<EndpointExecution>;
   };
   readonly memory: Memory;
-  readonly knowledge: ManagementResources["knowledge"] & {
-    search: (
-      id: string,
-      body: {
-        query: string;
-        topK?: number;
-        minScore?: number;
-        filters?: Record<string, string | number | boolean>;
-      },
-      options?: RequestOptions,
-    ) => Promise<KnowledgeMatch[]>;
-  };
+  readonly knowledge: ManagementResources["knowledge"];
   readonly evaluations: Omit<ManagementResources["evaluations"], "runs"> & {
     runs: ManagementResources["evaluations"]["runs"] & {
       create: (
@@ -193,16 +182,7 @@ export class Nirmos {
           })
         ).data,
     };
-    this.knowledge = {
-      ...resources.knowledge,
-      search: (id, body, options) =>
-        runtime.data<KnowledgeMatch[]>({
-          method: "POST",
-          path: `/v1/knowledge-bases/${encodeURIComponent(id)}/search`,
-          body,
-          options,
-        }),
-    };
+    this.knowledge = resources.knowledge;
     const runPath = (id: string) =>
       `/v1/evaluations/runs/${encodeURIComponent(id)}`;
     const command = async (
@@ -260,14 +240,14 @@ export class Nirmos {
   }
 }
 
-export interface KnowledgeMatch {
-  chunkId: string;
-  documentId: string;
-  content: string;
-  score: number;
-  metadata: Record<string, string | number | boolean> | null;
-  source: { title: string; uri: string | null; type: string };
-}
+export type KnowledgeSearchRequest =
+  import("./management/contracts.js").Requests["searchKnowledgeBase"];
+export type KnowledgeSearchResponse =
+  import("./management/contracts.js").Responses["searchKnowledgeBase"];
+export type KnowledgeSearchMode = KnowledgeSearchResponse["mode"];
+export type KnowledgeMatch = KnowledgeSearchResponse["items"][number];
+export type KnowledgeSearchStatus =
+  import("./management/contracts.js").Responses["getKnowledgeSearchStatus"];
 export interface EndpointExecution {
   success: boolean;
   data: {