@nirmos/sdk 0.3.1 → 0.3.3

package/src/management/manifest.ts

@@ -1216,6 +1216,22 @@ export const managementManifest = [
     "permission": "observability:read",
     "plane": "api"
   },
+  {
+    "method": "POST",
+    "path": "/v1/knowledge-bases/:id/search",
+    "operationId": "searchKnowledgeBase",
+    "sdk": "knowledge.search",
+    "permission": "knowledge:search",
+    "plane": "api"
+  },
+  {
+    "method": "GET",
+    "path": "/v1/knowledge-bases/:id/search-status",
+    "operationId": "getKnowledgeSearchStatus",
+    "sdk": "knowledge.searchStatus",
+    "permission": "knowledge:read",
+    "plane": "api"
+  },
   {
     "method": "GET",
     "path": "/v1/knowledge-bases",

package/src/management/resources.ts

@@ -154,7 +154,9 @@ get: (id: string, options?: RequestOptions) => transport.data<Responses["getTrac
 observability: { gatewayOverview: (options?: RequestOptions) => transport.data<Responses["gatewayOverview"]>({ method: "GET", path: `/v1/gateway/overview`, options }),
 overview: (query: Queries["observabilityOverview"] = {}, options?: RequestOptions) => transport.data<Responses["observabilityOverview"]>({ method: "GET", path: `/v1/observability/overview`, query, options }),
 metrics: (query: Queries["metrics"] = {}, options?: RequestOptions) => transport.data<Responses["metrics"]>({ method: "GET", path: `/v1/metrics`, query, options }) },
-knowledge: { list: (query: Queries["listKnowledgeBases"] = {}, options?: RequestOptions) => transport.data<Responses["listKnowledgeBases"]>({ method: "GET", path: `/v1/knowledge-bases`, query, options }),
+knowledge: { search: (id: string, body: Requests["searchKnowledgeBase"], options?: RequestOptions) => transport.data<Responses["searchKnowledgeBase"]>({ method: "POST", path: `/v1/knowledge-bases/${encodeURIComponent(id)}/search`, body, options }),
+searchStatus: (id: string, options?: RequestOptions) => transport.data<Responses["getKnowledgeSearchStatus"]>({ method: "GET", path: `/v1/knowledge-bases/${encodeURIComponent(id)}/search-status`, options }),
+list: (query: Queries["listKnowledgeBases"] = {}, options?: RequestOptions) => transport.data<Responses["listKnowledgeBases"]>({ method: "GET", path: `/v1/knowledge-bases`, query, options }),
 get: (id: string, options?: RequestOptions) => transport.data<Responses["getKnowledgeBase"]>({ method: "GET", path: `/v1/knowledge-bases/${encodeURIComponent(id)}`, options }),
 create: (body: Requests["createKnowledgeBase"], options?: RequestOptions) => transport.data<Responses["createKnowledgeBase"]>({ method: "POST", path: `/v1/knowledge-bases`, body, options }),
 update: (id: string, body: Requests["updateKnowledgeBase"], options?: RequestOptions) => transport.data<Responses["updateKnowledgeBase"]>({ method: "PATCH", path: `/v1/knowledge-bases/${encodeURIComponent(id)}`, body, options }),

package/src/memory/types.ts

@@ -79,6 +79,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;
 }
@@ -100,12 +104,19 @@ export type MemoryResult = Pick<
   | "confidence"
 >;
 export interface MemorySearchResponse {
-  memories: Array<MemoryResult & { score: number }>;
-}
-export interface MemoryContextResponse {
-  memories: Array<MemoryResult & { score?: number }>;
+  memories: Array<MemoryResult & { score: number; similarityScore: number }>;
+  relevance: "relevant" | "raw";
 }
+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/src/prompts/render.ts

@@ -9,7 +9,7 @@ import type {
   RenderedPrompt,
 } from "./types.js";
 
-const PLACEHOLDER = /\{\{\s*([a-zA-Z][a-zA-Z0-9_.-]*)\s*\}\}/g;
+import { PROMPT_VARIABLE_PATTERN as PLACEHOLDER, promptVariableValue, validatePromptTemplate, validatePromptVariableValues } from "./variables.js";
 
 export function renderPrompt(
   prompt: Prompt,
@@ -65,7 +65,8 @@ function resolveVariables(
   const missing: string[] = [];
 
   for (const variable of definitions) {
-    const value = resolved[variable.name];
+    const value = promptVariableValue(resolved, variable.name);
+    if (value !== undefined) resolved[variable.name] = value as JsonValue;
     if (value === undefined && variable.default !== undefined) {
       resolved[variable.name] = variable.default;
     } else if (value === undefined && variable.required) {
@@ -79,6 +80,8 @@ function resolveVariables(
       missing,
     );
   }
+  const errors = validatePromptVariableValues(definitions, resolved);
+  if (Object.keys(errors).length) throw new PromptRenderError(Object.entries(errors).map(([name, error]) => `${name}: ${error}`).join(" "), Object.keys(errors));
   return resolved;
 }
 
@@ -87,14 +90,16 @@ function interpolate(
   values: PromptVariableValues,
   options: PromptRenderOptions,
 ): string {
+  const syntaxErrors = validatePromptTemplate(template);
+  if (syntaxErrors.length) throw new PromptRenderError(syntaxErrors.join(" "), []);
   const unresolved = new Set<string>();
   const result = template.replace(PLACEHOLDER, (placeholder, name: string) => {
-    const value = values[name];
+    const value = promptVariableValue(values, name);
     if (value === undefined) {
       unresolved.add(name);
       return placeholder;
     }
-    return stringify(value);
+    return stringify(value as JsonValue);
   });
 
   if (unresolved.size > 0 && !options.allowUnresolved) {

package/src/prompts/variables.ts

@@ -0,0 +1,156 @@
+/** 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: Array<string | null | undefined>
+): string[] {
+  return [
+    ...new Set(
+      values.flatMap((value) =>
+        [...(value ?? "").matchAll(PROMPT_VARIABLE_PATTERN)].map(
+          (match) => match[1]!,
+        ),
+      ),
+    ),
+  ];
+}
+export function promptVariableValue(
+  values: Record<string, unknown>,
+  name: string,
+): unknown {
+  if (Object.hasOwn(values, name)) return values[name];
+  let current: unknown = 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 as Record<string, unknown>)[key];
+  }
+  return current;
+}
+export function interpolatePromptVariables(
+  text: string,
+  values: Record<string, unknown>,
+): string {
+  return text.replace(PROMPT_VARIABLE_PATTERN, (token, name: string) => {
+    const value = promptVariableValue(values, name);
+    return value === undefined
+      ? token
+      : typeof value === "string"
+        ? value
+        : JSON.stringify(value);
+  });
+}
+export function validatePromptTemplate(text: string): string[] {
+  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 type VariableDefinition = {
+  name: string;
+  type: string;
+  required?: boolean;
+  default?: unknown;
+  enum?: readonly string[];
+  values?: readonly string[];
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  min_length?: number;
+  max_length?: number;
+  itemType?: string;
+  item_type?: string;
+};
+export function validatePromptVariableValues(
+  definitions: readonly VariableDefinition[],
+  values: Record<string, unknown>,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  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: {
+  temperature: unknown;
+  topP: unknown;
+  maxTokens: unknown;
+}): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const [field, label, min, max] of [
+    ["temperature", "Temperature", 0, 2],
+    ["topP", "Top P", 0, 1],
+    ["maxTokens", "Max tokens", 1, 200000],
+  ] as const) {
+    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;
+}