@nirmos/sdk 0.3.4 → 0.3.6

package/README.md

@@ -1,6 +1,6 @@
 # Nirmos TypeScript SDK
 
-Documentation and offline checks target SDK **0.3.3**.
+Documentation and offline checks track the version in [package.json](./package.json).
 
 One client for Nirmos management and AI execution. Works in modern browsers and Node 18+ with ESM/CommonJS; no runtime dependencies.
 
@@ -12,8 +12,6 @@ pnpm add @nirmos/sdk
 import { Nirmos, NirmosError } from "@nirmos/sdk";
 
 const nirmos = new Nirmos({
-  apiBaseUrl: "http://localhost:4001",
-  runtimeBaseUrl: "http://localhost:4000",
   auth: { type: "api-key", key: process.env.NIRMOS_API_KEY! },
 });
 
@@ -28,6 +26,8 @@ const prompt = await nirmos.prompts.create({
 await nirmos.prompts.update(prompt.promptId, { name: "Support reply",slug:"support-reply",description: "Customer support" });
 ```
 
+Omitting `apiBaseUrl` and `runtimeBaseUrl` uses `https://api.nirmos.com` and `https://runtime.nirmos.com`, respectively. Set either option to override its default for local or private deployments.
+
 For an API-hosted Better Auth browser session:
 
 ```ts
@@ -379,6 +379,11 @@ pnpm docs:sdk:check
 node --test apps/web/scripts/sdk/docs-examples.test.mjs
 ```
 
+`pnpm --filter @nirmos/sdk pack` runs prepack: it builds the SDK, regenerates the
+reference from the current package version and public TypeScript inventory, and
+checks documentation before packing. Commit the generated reference with a release.
+The documentation check also rejects a package/reference version mismatch.
+
 These checks use local/injected responses, with no provider quota. See the public
 installation and evaluation guides for complete environment, run and cleanup
 instructions. `evaluations.traceCandidates()` exposes public request IDs and

package/dist/cjs/client.js

@@ -58,7 +58,7 @@ class Nirmos {
         const runtime = new transport_js_1.HttpTransport({
             ...common,
             runtime: true,
-            baseUrl: normalizeBaseUrl(options.runtimeBaseUrl ?? "https://gateway.nirmos.com"),
+            baseUrl: normalizeBaseUrl(options.runtimeBaseUrl ?? "https://runtime.nirmos.com"),
         });
         const resources = (0, resources_js_1.managementResources)(api);
         this.permissions = resources.permissions;

package/dist/cjs/core/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 // Generated from package.json by scripts/generate-version.mjs.
-exports.SDK_VERSION = "0.3.4";
+exports.SDK_VERSION = "0.3.6";
 //# sourceMappingURL=version.js.map

package/dist/esm/client.js

@@ -55,7 +55,7 @@ export class Nirmos {
         const runtime = new HttpTransport({
             ...common,
             runtime: true,
-            baseUrl: normalizeBaseUrl(options.runtimeBaseUrl ?? "https://gateway.nirmos.com"),
+            baseUrl: normalizeBaseUrl(options.runtimeBaseUrl ?? "https://runtime.nirmos.com"),
         });
         const resources = managementResources(api);
         this.permissions = resources.permissions;

package/dist/esm/core/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.3.4";
+export declare const SDK_VERSION = "0.3.6";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/core/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
-export const SDK_VERSION = "0.3.4";
+export const SDK_VERSION = "0.3.6";
 //# sourceMappingURL=version.js.map

package/examples/evaluation-offline.mjs

@@ -94,6 +94,7 @@ const sdk = new Nirmos({
         JSON.stringify({
           id: "run",
           status: ++polls === 1 ? "RUNNING" : "COMPLETED",
+          summary: polls === 1 ? null : { overallPassRate: 0.5, byEvaluator: { exact_match: { count: 2, passRate: 0.5, average: null } } },
         }),
       );
     if (path === "/v1/evaluations/runs/run/results") {
@@ -143,6 +144,7 @@ assert.deepEqual(
   result.results.data.map((trial) => trial.scores[0].passed),
   [true, false],
 );
+assert.equal(result.summary.overallPassRate, 0.5);
 assert.equal(archived.length, 3);
 console.log(
   "Offline workflow verified: two cases, pinned versions, mappings, polling, true/false scores and archive.",

package/examples/evaluation-quickstart.mjs

@@ -167,7 +167,12 @@ export async function evaluationQuickstart(client, options) {
                         trial.scores.some((score) => score.status !== "COMPLETED" || score.error))) {
                     throw new Error("Run ended with missing or failed trials/scores; inspect results");
                 }
-                return { runId, results }; // passed:false is a valid evaluation outcome.
+                // Runtime GET returns persisted aggregates after terminal processing.
+                const summary = run.summary;
+                if (!summary || typeof summary.overallPassRate !== "number")
+                    throw new Error("Missing aggregate scores; inspect the terminal run");
+                console.log({ overallPassRate: summary.overallPassRate, byEvaluator: summary.byEvaluator });
+                return { runId, results, summary }; // passed:false is a valid evaluation outcome.
             }
             await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? 2000));
         }

package/examples/evaluation-quickstart.ts

@@ -202,7 +202,12 @@ export async function evaluationQuickstart(
             "Run ended with missing or failed trials/scores; inspect results",
           );
         }
-        return { runId, results }; // passed:false is a valid evaluation outcome.
+        // Runtime GET returns persisted aggregates after terminal processing.
+        const summary = run.summary;
+        if (!summary || typeof summary.overallPassRate !== "number")
+          throw new Error("Missing aggregate scores; inspect the terminal run");
+        console.log({ overallPassRate: summary.overallPassRate, byEvaluator: summary.byEvaluator });
+        return { runId, results, summary }; // passed:false is a valid evaluation outcome.
       }
       await new Promise((resolve) =>
         setTimeout(resolve, options.pollMs ?? 2000),

package/examples/prompt-rollback.mjs

@@ -0,0 +1,65 @@
+// Generated from prompt-rollback.ts. Do not edit.
+import { Nirmos } from "@nirmos/sdk";
+/** Disposable management rollback example. No provider call is needed. */
+export async function promptRollback(nirmos) {
+    const suffix = `rollback-${Date.now()}`;
+    const prompt = await nirmos.prompts.create({ name: suffix, slug: suffix });
+    const save = async (text, parentVersionId) => {
+        const version = await nirmos.prompts.versions.create(prompt.promptId, {
+            branchId: prompt.branchId,
+            parentVersionId,
+            commitMessage: text,
+            temperature: 0,
+            maxTokens: 64,
+            topP: 1,
+            messages: [
+                {
+                    order: 0,
+                    role: "system",
+                    contentBlocks: [{ order: 0, type: "text", text }],
+                },
+            ],
+        });
+        if (!version.versionId)
+            throw new Error("Missing saved version ID");
+        return version.versionId;
+    };
+    const active = async (versionId, text) => {
+        const released = await nirmos.managedPrompts.retrieveActive(prompt.promptId, { cache: "reload" });
+        const rendered = await nirmos.managedPrompts.render(released, {});
+        if (released.version.id !== versionId ||
+            rendered.messages[0]?.content !== text)
+            throw new Error("Published content differs from the requested release");
+        console.log(rendered.messages[0].content);
+    };
+    try {
+        const v1 = await save("V1: Answer concisely.");
+        await nirmos.prompts.versions.publish(prompt.promptId, v1);
+        await active(v1, "V1: Answer concisely.");
+        const v2 = await save("V2: Include policy citations.", v1);
+        await nirmos.prompts.versions.publish(prompt.promptId, v2);
+        await active(v2, "V2: Include policy citations.");
+        const saved = await save("V3: Unpublished work.", v2);
+        await nirmos.prompts.versions.publish(prompt.promptId, v1);
+        await active(v1, "V1: Answer concisely.");
+        const branches = await nirmos.prompts.branches.list(prompt.promptId);
+        if (branches.items.find((branch) => branch.id === prompt.branchId)
+            ?.headVersionId !== saved)
+            throw new Error("Rollback changed the saved branch head");
+        await nirmos.prompts.versions.publish(prompt.promptId, v2);
+        await active(v2, "V2: Include policy citations.");
+        return { v1, v2, saved };
+    }
+    finally {
+        await nirmos.prompts.delete(prompt.promptId);
+    }
+}
+// NIRMOS_API_KEY=... node prompt-rollback.mjs (or run the .ts file with tsx).
+if (process.env.NIRMOS_API_KEY) {
+    await promptRollback(new Nirmos({
+        auth: { type: "api-key", key: process.env.NIRMOS_API_KEY },
+        apiBaseUrl: process.env.NIRMOS_API_URL ?? "http://localhost:4001",
+        runtimeBaseUrl: process.env.NIRMOS_RUNTIME_URL ?? "http://localhost:4000",
+        maxRetries: 0,
+    }));
+}

package/examples/prompt-rollback.ts

@@ -0,0 +1,76 @@
+import { Nirmos } from "@nirmos/sdk";
+
+/** Disposable management rollback example. No provider call is needed. */
+export async function promptRollback(nirmos: Nirmos) {
+  const suffix = `rollback-${Date.now()}`;
+  const prompt = await nirmos.prompts.create({ name: suffix, slug: suffix });
+  const save = async (text: string, parentVersionId?: string) => {
+    const version = await nirmos.prompts.versions.create(prompt.promptId, {
+      branchId: prompt.branchId,
+      parentVersionId,
+      commitMessage: text,
+      temperature: 0,
+      maxTokens: 64,
+      topP: 1,
+      messages: [
+        {
+          order: 0,
+          role: "system",
+          contentBlocks: [{ order: 0, type: "text", text }],
+        },
+      ],
+    });
+    if (!version.versionId) throw new Error("Missing saved version ID");
+    return version.versionId;
+  };
+  const active = async (versionId: string, text: string) => {
+    const released = await nirmos.managedPrompts.retrieveActive(
+      prompt.promptId,
+      { cache: "reload" },
+    );
+    const rendered = await nirmos.managedPrompts.render(released, {});
+    if (
+      released.version.id !== versionId ||
+      rendered.messages[0]?.content !== text
+    )
+      throw new Error("Published content differs from the requested release");
+    console.log(rendered.messages[0].content);
+  };
+  try {
+    const v1 = await save("V1: Answer concisely.");
+    await nirmos.prompts.versions.publish(prompt.promptId, v1);
+    await active(v1, "V1: Answer concisely.");
+    const v2 = await save("V2: Include policy citations.", v1);
+    await nirmos.prompts.versions.publish(prompt.promptId, v2);
+    await active(v2, "V2: Include policy citations.");
+    const saved = await save("V3: Unpublished work.", v2);
+    await nirmos.prompts.versions.publish(prompt.promptId, v1);
+    await active(v1, "V1: Answer concisely.");
+    const branches = await nirmos.prompts.branches.list(prompt.promptId);
+    if (
+      branches.items.find((branch) => branch.id === prompt.branchId)
+        ?.headVersionId !== saved
+    )
+      throw new Error("Rollback changed the saved branch head");
+    await nirmos.prompts.versions.publish(prompt.promptId, v2);
+    await active(v2, "V2: Include policy citations.");
+    return { v1, v2, saved };
+  } finally {
+    await nirmos.prompts.delete(prompt.promptId);
+  }
+}
+
+// This example remains type-checkable without Node type dependencies.
+declare const process: { env: Record<string, string | undefined> };
+
+// NIRMOS_API_KEY=... node prompt-rollback.mjs (or run the .ts file with tsx).
+if (process.env.NIRMOS_API_KEY) {
+  await promptRollback(
+    new Nirmos({
+      auth: { type: "api-key", key: process.env.NIRMOS_API_KEY },
+      apiBaseUrl: process.env.NIRMOS_API_URL ?? "http://localhost:4001",
+      runtimeBaseUrl: process.env.NIRMOS_RUNTIME_URL ?? "http://localhost:4000",
+      maxRetries: 0,
+    }),
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nirmos/sdk",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Official TypeScript SDK for the Nirmos AI platform.",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
     "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",
+    "prepack": "pnpm build && pnpm --dir ../.. docs:sdk && pnpm --dir ../.. docs:sdk:check",
     "test": "node ./scripts/ensure-built.mjs && tsc -p examples/tsconfig.json && tsc -p tests/tsconfig.json && node --test tests/*.test.mjs"
   },
   "engines": {

package/src/client.ts

@@ -138,7 +138,7 @@ export class Nirmos {
       ...common,
       runtime: true,
       baseUrl: normalizeBaseUrl(
-        options.runtimeBaseUrl ?? "https://gateway.nirmos.com",
+        options.runtimeBaseUrl ?? "https://runtime.nirmos.com",
       ),
     });
     const resources = managementResources(api);

package/src/core/version.ts

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