@nirmos/sdk 0.3.2 → 0.3.4

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

@@ -0,0 +1,35 @@
+export type MemoryIngestResponse = {
+    "memoryRunId": string;
+    "memories": Array<{
+        "id": string;
+        "content": string;
+        "type": "preference" | "fact" | "relationship" | "decision" | "constraint" | "commitment" | "procedure" | "event" | "project_fact" | "temporary_state" | "observation" | "custom";
+        "layer": "atomic" | "observation";
+        "status": "active" | "superseded" | "expired" | "archived" | "deleted";
+        "validFrom": string | null;
+        "validUntil": string | null;
+        "confidence": number | null;
+    }>;
+    "candidateCount": number;
+    "acceptedCount": number;
+    "rejectedCount": number;
+    "insertedCount": number;
+    "mergedCount": number;
+    "reinforcedCount": number;
+    "supersededCount": number;
+    "ignoredCount": number;
+    "indexing": {
+        "indexed": number;
+        "failed": number;
+        "diagnostics"?: Array<{
+            "code": string;
+            "status": number;
+            "retryable": boolean;
+            "details"?: {
+                [key: string]: unknown;
+            };
+        }>;
+    };
+    "replayed": boolean;
+};
+//# sourceMappingURL=execution-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execution-types.d.ts","sourceRoot":"","sources":["../../../src/memory/execution-types.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,oBAAoB,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,cAAc,GAAG,iBAAiB,GAAG,aAAa,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,QAAQ,GAAG,aAAa,CAAC;QAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAAE,CAAC,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,OAAO,CAAC;YAAC,SAAS,CAAC,EAAE;gBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;aAAE,CAAC;SAAE,CAAC,CAAC;KAAE,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;CAAE,CAAC"}

package/dist/esm/memory/execution-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=execution-types.js.map

package/dist/esm/memory/execution-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-types.js","sourceRoot":"","sources":["../../../src/memory/execution-types.ts"],"names":[],"mappings":""}

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,31 +79,13 @@ 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 interface MemoryIndexingResult {
-    indexed: number;
-    failed: number;
-}
-export interface MemoryIngestResponse {
-    memoryRunId: string;
-    memories: MemoryResult[];
-    candidateCount: number;
-    acceptedCount: number;
-    rejectedCount: number;
-    insertedCount: number;
-    mergedCount: number;
-    reinforcedCount: number;
-    supersededCount: number;
-    ignoredCount: number;
-    indexing: MemoryIndexingResult;
-    replayed?: boolean;
-}
+export type MemoryContextResponse = MemorySearchResponse;
+export type { MemoryIngestResponse } from "./execution-types.js";
+export type MemoryIndexingResult = import("./execution-types.js").MemoryIngestResponse["indexing"];
 export interface MemoryManualRequest {
     memorySpaceId: string;
     content: string;

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/evaluation-offline.mjs

@@ -0,0 +1,149 @@
+// Deterministic SDK workflow fixture. No network, credentials, database or provider calls.
+// Run: node packages/sdk/examples/evaluation-offline.mjs (after pnpm --filter @nirmos/sdk build).
+// The live workflow uses the same public SDK function; this transport simulates service responses.
+import assert from "node:assert/strict";
+import { Nirmos } from "@nirmos/sdk";
+if (process.env.NIRMOS_RUN_EVALUATION_EXAMPLE === "1") {
+  throw new Error("Unset NIRMOS_RUN_EVALUATION_EXAMPLE before running the offline fixture.");
+}
+const { evaluationQuickstart } = await import("./evaluation-quickstart.mjs");
+
+const cases = [];
+const archived = [];
+let frozen = false;
+let polls = 0;
+let bindings;
+const json = (data) =>
+  new Response(JSON.stringify({ data }), {
+    headers: { "content-type": "application/json" },
+  });
+const sdk = new Nirmos({
+  auth: { type: "api-key", key: "offline-fixture" },
+  apiBaseUrl: "https://api.example.test",
+  runtimeBaseUrl: "https://runtime.example.test",
+  maxRetries: 0,
+  fetch: async (url, init) => {
+    const path = new URL(url).pathname;
+    const body = init.body ? JSON.parse(init.body) : {};
+    if (path.endsWith("/archive")) {
+      archived.push(path);
+      return json({ id: "archived" });
+    }
+    if (path === "/v1/evaluations/datasets")
+      return json({
+        dataset: { id: "dataset", name: body.name },
+        initialVersion: { id: "dataset-v1", version: 1, status: "draft" },
+      });
+    if (path === "/v1/evaluations/datasets/dataset/columns")
+      return json({ id: body.key });
+    if (path === "/v1/evaluations/datasets/dataset/cases") {
+      assert.equal(frozen, false);
+      cases.push(body.data);
+      return json({ id: `case-${cases.length}` });
+    }
+    if (path.endsWith("/freeze")) {
+      frozen = true;
+      return json({ id: "dataset-v1" });
+    }
+    if (path === "/v1/evaluations/suites") {
+      assert.ok(frozen);
+      return json({ id: "suite" });
+    }
+    if (path === "/v1/evaluations/columns") {
+      if (body.category === "target") {
+        assert.deepEqual(body.target.inputMapping, {
+          user_message: "dataset.question",
+        });
+        return json({
+          target: { id: "target" },
+          targetVersion: {
+            id: "target-v1",
+            version: 1,
+            columns: [{ id: "target-column" }],
+          },
+          column: { id: "target-column" },
+        });
+      }
+      bindings = body.config.inputMapping;
+      return json({ id: "evaluator-column", key: body.key, position: 1 });
+    }
+    if (path === "/v1/evaluations/evaluators") {
+      assert.equal(body.version.type, "exact_match");
+      assert.deepEqual(body.version.config, {
+        caseSensitive: true,
+        trimWhitespace: true,
+        normalizeWhitespace: false,
+      });
+      return json({
+        evaluator: { id: "evaluator", name: body.name },
+        version: { id: "evaluator-v1", version: 1 },
+      });
+    }
+    if (path === "/v1/evaluations/experiments/prepare") {
+      assert.deepEqual(body.targetVersionIds, ["target-v1"]);
+      return json({ id: "experiment" });
+    }
+    if (path === "/v1/evaluations/runs") {
+      assert.deepEqual(body.targetIds, ["target-v1"]);
+      return new Response(JSON.stringify({ id: "run", status: "QUEUED" }), {
+        status: 202,
+      });
+    }
+    if (path === "/v1/evaluations/runs/run")
+      return new Response(
+        JSON.stringify({
+          id: "run",
+          status: ++polls === 1 ? "RUNNING" : "COMPLETED",
+        }),
+      );
+    if (path === "/v1/evaluations/runs/run/results") {
+      assert.deepEqual(bindings, {
+        actual: { source: "target", path: "output" },
+        expected: { source: "dataset", key: "expected" },
+      });
+      // Fixed target outputs deliberately demonstrate both passing and failing scores.
+      return new Response(
+        JSON.stringify({
+          data: cases.map((row, i) => {
+            const output = ["Paris", "Kyoto"][i];
+            const passed = output === row.expected;
+            return {
+              id: `trial-${i}`,
+              caseId: `case-${i}`,
+              status: "COMPLETED",
+              output,
+              error: null,
+              scores: [
+                {
+                  evaluatorVersionId: "evaluator-v1",
+                  status: "COMPLETED",
+                  value: passed,
+                  passed,
+                  error: null,
+                },
+              ],
+            };
+          }),
+          total: cases.length,
+          page: 1,
+          pageSize: 25,
+        }),
+      );
+    }
+    throw new Error(`Unexpected fixture request: ${init.method} ${path}`);
+  },
+});
+const result = await evaluationQuickstart(sdk, {
+  providerId: "fixture-provider",
+  modelId: "fixture-model",
+  cleanup: true,
+  pollMs: 0,
+});
+assert.deepEqual(
+  result.results.data.map((trial) => trial.scores[0].passed),
+  [true, false],
+);
+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

@@ -0,0 +1,205 @@
+// Generated from evaluation-quickstart.ts. Do not edit.
+import { Nirmos } from "@nirmos/sdk";
+function requireId(value, label) {
+    if (typeof value !== "string" || !value)
+        throw new Error(`Missing ${label}`);
+    return value;
+}
+export async function evaluationQuickstart(client, options) {
+    let datasetId;
+    let suiteId;
+    let evaluatorId;
+    let runId;
+    let terminal = false;
+    let submissionStarted = false;
+    try {
+        const dataset = await client.evaluations.datasets.create({
+            name: "SDK two-case demo",
+        });
+        datasetId = requireId(dataset.dataset.id, "dataset ID");
+        const datasetVersionId = requireId(dataset.initialVersion?.id, "dataset version ID");
+        console.log({ datasetId, datasetVersionId });
+        for (const column of [
+            { key: "question", name: "Question", role: "input" },
+            { key: "expected", name: "Expected", role: "expected" },
+            { key: "topic", name: "Topic", role: "metadata" },
+        ]) {
+            await client.evaluations.datasets.columns.create(datasetId, {
+                datasetVersionId,
+                ...column,
+                dataType: "text",
+                required: true,
+            });
+        }
+        for (const data of [
+            {
+                question: "Reply with exactly Paris and nothing else.",
+                expected: "Paris",
+                topic: "cities",
+            },
+            {
+                question: "Reply with exactly Tokyo and nothing else.",
+                expected: "Tokyo",
+                topic: "cities",
+            },
+        ]) {
+            await client.evaluations.datasets.cases.create(datasetId, {
+                datasetVersionId,
+                data,
+                tags: ["sdk-demo"],
+            });
+        }
+        await client.evaluations.datasets.versions.freeze(datasetId, datasetVersionId);
+        const suite = await client.evaluations.suites.create({
+            name: "SDK exact-match demo",
+            datasetVersionId,
+        });
+        suiteId = requireId(suite.id, "suite ID");
+        console.log({ suiteId });
+        const target = await client.evaluations.columns.create({
+            suiteId,
+            key: "candidate",
+            name: "Candidate",
+            category: "target",
+            enabled: true,
+            config: { role: "candidate", dataType: "output" },
+            target: {
+                type: "model",
+                name: "Demo model",
+                providerId: options.providerId,
+                modelId: options.modelId,
+                inputMapping: { user_message: "dataset.question" },
+            },
+        });
+        // The target's logical ID is distinct from the immutable version used in runs.
+        const targetId = requireId(target.target?.id, "target ID");
+        const targetVersionId = requireId(target.targetVersion?.id, "target version ID");
+        const evaluator = await client.evaluations.evaluators.create({
+            name: "SDK exact match",
+            version: {
+                type: "exact_match",
+                category: "deterministic",
+                scope: "output",
+                inputSchema: [
+                    { key: "actual", type: "any", required: true },
+                    { key: "expected", type: "any", required: true },
+                ],
+                config: {
+                    caseSensitive: true,
+                    trimWhitespace: true,
+                    normalizeWhitespace: false,
+                },
+                outputType: "boolean",
+                scoreDirection: "none",
+            },
+        });
+        evaluatorId = requireId(evaluator.evaluator.id, "evaluator ID");
+        const evaluatorVersionId = requireId(evaluator.version?.id, "evaluator version ID");
+        console.log({ evaluatorId, targetVersionId, evaluatorVersionId });
+        await client.evaluations.columns.create({
+            suiteId,
+            key: "exact_match",
+            name: "Exact match",
+            category: "evaluator",
+            enabled: true,
+            evaluatorVersionId,
+            config: {
+                inputMapping: {
+                    actual: { source: "target", path: "output" },
+                    expected: { source: "dataset", key: "expected" },
+                },
+            },
+        });
+        const experiment = await client.evaluations.experiments.prepare({
+            suiteId,
+            datasetVersionId,
+            targetVersionIds: [targetVersionId],
+            evaluatorVersionIds: [evaluatorVersionId],
+            trialCount: 1,
+        });
+        const experimentId = requireId(experiment.id, "experiment ID");
+        // Persist this input and submissionId if implementing replay across process restarts.
+        const submissionId = crypto.randomUUID();
+        console.log({ experimentId, submissionId });
+        submissionStarted = true;
+        const created = await client.evaluations.runs.create({
+            experimentId,
+            cases: "all",
+            targetIds: [targetVersionId],
+            evaluatorIds: [evaluatorVersionId],
+            trialCount: 1,
+        }, { idempotencyKey: submissionId, maxRetries: 0 });
+        runId = created.id;
+        console.log({ runId });
+        for (let attempt = 0; attempt < (options.maxPolls ?? 60); attempt++) {
+            const run = await client.evaluations.runs.get(runId, {
+                timeoutMs: 10_000,
+                maxRetries: 0,
+            });
+            if (["COMPLETED", "FAILED", "CANCELLED"].includes(run.status)) {
+                terminal = true;
+                const results = await client.evaluations.runs.results(runId, {
+                    page: 1,
+                    pageSize: 25,
+                });
+                for (const trial of results.data) {
+                    console.log({
+                        caseId: trial.caseId,
+                        trialStatus: trial.status,
+                        error: trial.error,
+                    });
+                    for (const score of trial.scores) {
+                        console.log({
+                            evaluatorVersionId: score.evaluatorVersionId,
+                            status: score.status,
+                            value: score.value,
+                            passed: score.passed,
+                            error: score.error,
+                        });
+                    }
+                }
+                // Two cases × one target × one trial fit on one page.
+                if (run.status !== "COMPLETED")
+                    throw new Error(`Run ${runId}: ${run.status}`);
+                if (results.data.length !== 2 ||
+                    results.data.some((trial) => trial.status !== "COMPLETED" ||
+                        trial.scores.length !== 1 ||
+                        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.
+            }
+            await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? 2000));
+        }
+        await client.evaluations.runs.cancel(runId);
+        throw new Error(`Polling limit reached; cancellation requested for ${runId}. Confirm terminal state before cleanup.`);
+    }
+    finally {
+        // Never archive inputs while background execution might still use them.
+        if (options.cleanup && (!submissionStarted || terminal)) {
+            const cleanup = await Promise.allSettled([
+                ...(suiteId ? [client.evaluations.suites.archive(suiteId)] : []),
+                ...(evaluatorId
+                    ? [client.evaluations.evaluators.archive(evaluatorId)]
+                    : []),
+                ...(datasetId ? [client.evaluations.datasets.archive(datasetId)] : []),
+            ]);
+            for (const result of cleanup)
+                if (result.status === "rejected")
+                    console.error("Archive failed:", result.reason);
+        }
+    }
+}
+if (process.env.NIRMOS_RUN_EVALUATION_EXAMPLE === "1") {
+    const key = requireId(process.env.NIRMOS_API_KEY, "NIRMOS_API_KEY");
+    await evaluationQuickstart(new Nirmos({
+        auth: { type: "api-key", key },
+        apiBaseUrl: process.env.NIRMOS_API_URL,
+        runtimeBaseUrl: process.env.NIRMOS_RUNTIME_URL,
+        maxRetries: 0,
+    }), {
+        providerId: requireId(process.env.NIRMOS_PROVIDER_ID, "NIRMOS_PROVIDER_ID"),
+        modelId: requireId(process.env.NIRMOS_MODEL_ID, "NIRMOS_MODEL_ID"),
+        cleanup: process.env.EVALUATION_CLEANUP === "1",
+    });
+}