@neo4j-labs/agent-memory 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,6 +1,6 @@
-import { extractRequestId, supportsUserAgentHeader, defaultUserAgent, BridgeTransport } from './chunk-TGBKROHO.js';
-export { VERSION } from './chunk-TGBKROHO.js';
-import { ConnectionError, AuthenticationError, NotSupportedError, TransportError, ValidationError } from './chunk-ASQMU7YC.js';
+import { extractRequestId, supportsUserAgentHeader, defaultUserAgent, BridgeTransport } from './chunk-E752ALCR.js';
+export { VERSION } from './chunk-E752ALCR.js';
+import { ValidationError, NotSupportedError, ConnectionError, AuthenticationError, TransportError } from './chunk-ASQMU7YC.js';
 export { AuthenticationError, ConnectionError, MemoryError, NotFoundError, NotSupportedError, TransportError, ValidationError } from './chunk-ASQMU7YC.js';
 
 // src/auth/index.ts
@@ -165,6 +165,59 @@ var LongTermMemory = class {
     });
     return wire.map(toEntity);
   }
+  /**
+   * Poll entity search until async extraction has caught up, or time out.
+   *
+   * NAMS extracts entities in a background pipeline, so writes return before
+   * the entities are searchable. This helper lets application and test code
+   * await consistency explicitly instead of racing a fixed delay.
+   *
+   * Provide one of:
+   * - `predicate` — called with the current results; return true when satisfied.
+   * - `expectedNames` — succeed once every name appears (case-insensitive).
+   *   **Recommended**: NAMS entity search is vector/nearest-neighbor, so a
+   *   `minResults` threshold is satisfied almost immediately on a non-empty
+   *   workspace; prefer `expectedNames`/`predicate` to confirm a *specific*
+   *   extraction landed.
+   * - otherwise — succeed once at least `minResults` entities match.
+   *
+   * Returns `true` if satisfied within `timeoutMs`, `false` otherwise (it does
+   * not throw, so callers can branch or skip gracefully).
+   */
+  async waitForExtraction(options) {
+    const {
+      query,
+      expectedNames,
+      minResults = 1,
+      predicate,
+      timeoutMs = 3e4,
+      intervalMs = 1e3
+    } = options;
+    const q = query ?? (expectedNames && expectedNames.length > 0 ? expectedNames[0] : void 0);
+    if (q === void 0 && predicate === void 0) {
+      throw new ValidationError(
+        "waitForExtraction requires one of: query, expectedNames, or predicate."
+      );
+    }
+    const want = (expectedNames ?? []).map((n) => n.toLowerCase());
+    const fetch2 = Math.max(minResults, want.length, options.limit ?? 10);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const results = await this.searchEntities(q ?? "", { limit: fetch2 });
+      let ok;
+      if (predicate !== void 0) {
+        ok = predicate(results);
+      } else if (want.length > 0) {
+        const found = new Set(results.map((e) => e.name.toLowerCase()));
+        ok = want.every((n) => found.has(n));
+      } else {
+        ok = results.length >= minResults;
+      }
+      if (ok) return true;
+      if (Date.now() >= deadline) return false;
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
   async searchPreferences(query, options) {
     const wire = await this.transport.request("search_preferences", {
       query,
@@ -286,6 +339,172 @@ var LongTermMemory = class {
   }
 };
 
+// src/ontology/index.ts
+function toDocument(raw) {
+  if (!raw || typeof raw !== "object" || !raw.domain) return void 0;
+  return {
+    domain: raw.domain,
+    entityTypes: (raw.entity_types ?? []).map((e) => ({
+      label: e.label,
+      poleType: e.pole_type,
+      subtype: e.subtype,
+      color: e.color,
+      icon: e.icon,
+      properties: (e.properties ?? []).map((p) => ({
+        name: p.name,
+        type: p.type,
+        required: p.required,
+        unique: p.unique,
+        enum: p.enum ?? void 0
+      }))
+    })),
+    relationships: raw.relationships ?? []
+  };
+}
+function toDocumentFromJson(schemaJson) {
+  if (schemaJson == null) return void 0;
+  try {
+    return toDocument(JSON.parse(schemaJson));
+  } catch {
+    return void 0;
+  }
+}
+function toVersion(raw) {
+  return {
+    id: raw.id,
+    ontologyId: raw.ontology_id,
+    revision: raw.revision,
+    validationMode: raw.validation_mode,
+    document: toDocumentFromJson(raw.schema_json),
+    schemaHash: raw.schema_hash,
+    createdAt: raw.created_at,
+    message: raw.message
+  };
+}
+function toSummary(raw) {
+  return {
+    id: raw.id,
+    name: raw.name,
+    displayName: raw.display_name,
+    description: raw.description,
+    emoji: raw.emoji,
+    tagline: raw.tagline,
+    isSystem: raw.is_system ?? false,
+    currentRevision: raw.current_revision,
+    isActive: raw.is_active ?? false
+  };
+}
+function docToWire(doc) {
+  return {
+    domain: doc.domain,
+    entity_types: doc.entityTypes.map((e) => ({
+      label: e.label,
+      pole_type: e.poleType,
+      subtype: e.subtype,
+      color: e.color,
+      icon: e.icon,
+      properties: (e.properties ?? []).map((p) => ({
+        name: p.name,
+        type: p.type,
+        required: p.required,
+        unique: p.unique,
+        enum: p.enum
+      }))
+    })),
+    relationships: doc.relationships
+  };
+}
+var OntologyClient = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async list() {
+    const raw = await this.transport.request(
+      "list_ontologies",
+      {}
+    );
+    return (raw.ontologies ?? []).map(toSummary);
+  }
+  async get(id) {
+    const raw = await this.transport.request(
+      "get_ontology",
+      { id }
+    );
+    const r = raw.record ?? {};
+    return {
+      record: {
+        id: r.id,
+        name: r.name,
+        description: r.description,
+        workspaceId: r.workspace_id,
+        isSystem: r.is_system ?? false,
+        createdAt: r.created_at
+      },
+      versions: (raw.versions ?? []).map(toVersion)
+    };
+  }
+  async getActive() {
+    const raw = await this.transport.request(
+      "get_active_ontology",
+      {}
+    );
+    const document = toDocument(raw.ontology);
+    if (!document) {
+      throw new NotSupportedError("No active ontology bound for this workspace.");
+    }
+    const active = { document };
+    const summaries = await this.list();
+    const match = summaries.find((s) => s.isActive) ?? summaries.find((s) => s.name === document.domain.id);
+    if (match) {
+      active.ontologyId = match.id;
+      const detail = await this.get(match.id);
+      const current = currentVersion(detail, match.currentRevision);
+      if (current) {
+        active.validationMode = current.validationMode;
+        active.revision = current.revision;
+        active.versionId = current.id;
+      }
+    }
+    return active;
+  }
+  async clone(templateName) {
+    const raw = await this.transport.request("clone_ontology", { name: templateName });
+    return toVersion(raw);
+  }
+  async create(options) {
+    const body = { ontology: docToWire(options.schema) };
+    if (options.validationMode !== void 0) body.validation_mode = options.validationMode;
+    const raw = await this.transport.request("create_ontology", { body });
+    return toVersion(raw);
+  }
+  async update(options) {
+    const body = { ontology: docToWire(options.schema) };
+    if (options.validationMode !== void 0) body.validation_mode = options.validationMode;
+    const raw = await this.transport.request("update_ontology", {
+      id: options.id,
+      body
+    });
+    return toVersion(raw);
+  }
+  async activate(versionId) {
+    const raw = await this.transport.request("activate_ontology", {
+      body: { version_id: versionId }
+    });
+    return toVersion(raw);
+  }
+  async delete(id) {
+    await this.transport.request("delete_ontology", { id });
+  }
+};
+function currentVersion(ontology, revision) {
+  if (ontology.versions.length === 0) return void 0;
+  if (revision !== void 0) {
+    const exact = ontology.versions.find((v) => v.revision === revision);
+    if (exact) return exact;
+  }
+  return ontology.versions.reduce((a, b) => b.revision > a.revision ? b : a);
+}
+
 // src/query/index.ts
 var QueryConsole = class {
   constructor(transport) {
@@ -509,6 +728,15 @@ var ReasoningMemory = class {
 };
 
 // src/short-term/index.ts
+function resolveConversationId(sessionId, conversationId, method) {
+  const resolved = sessionId ?? conversationId;
+  if (resolved === void 0) {
+    throw new ValidationError(
+      `${method} requires sessionId (alias: conversationId) \u2014 the NAMS API is conversation-scoped.`
+    );
+  }
+  return resolved;
+}
 function toMessage(w) {
   return {
     id: w.id,
@@ -566,8 +794,9 @@ var ShortTermMemory = class {
   }
   // ---- Bronze tier (bridge) ----------------------------------------------
   async addMessage(sessionId, role, content, options) {
+    const conv = resolveConversationId(sessionId, options?.conversationId, "addMessage");
     const wire = await this.transport.request("add_message", {
-      session_id: sessionId,
+      session_id: conv,
       role,
       content,
       metadata: options?.metadata
@@ -575,16 +804,18 @@ var ShortTermMemory = class {
     return toMessage(wire);
   }
   async getConversation(sessionId, options) {
+    const conv = resolveConversationId(sessionId, options?.conversationId, "getConversation");
     const wire = await this.transport.request("get_conversation", {
-      session_id: sessionId,
+      session_id: conv,
       limit: options?.limit
     });
     return toConversation(wire);
   }
   async searchMessages(query, options) {
+    const conv = options?.sessionId ?? options?.conversationId;
     const wire = await this.transport.request("search_messages", {
       query,
-      session_id: options?.sessionId,
+      session_id: conv,
       limit: options?.limit ?? 10,
       threshold: options?.threshold ?? 0.7
     });
@@ -602,8 +833,9 @@ var ShortTermMemory = class {
     });
     return result.deleted;
   }
-  async clearSession(sessionId) {
-    await this.transport.request("clear_session", { session_id: sessionId });
+  async clearSession(sessionId, options) {
+    const conv = resolveConversationId(sessionId, options?.conversationId, "clearSession");
+    await this.transport.request("clear_session", { session_id: conv });
   }
   // ---- Volume 5 / hosted-native methods -----------------------------------
   /** Create a new conversation (hosted service). */
@@ -969,7 +1201,32 @@ var ROUTES = {
     method: "POST",
     path: "/auth/refresh",
     hasBody: true
-  }
+  },
+  // Ontologies — snake_case sub-API (verified against staging; absent from the
+  // OpenAPI spec). Bodies are sent verbatim via `snakeBody`.
+  list_ontologies: { method: "GET", path: "/ontologies" },
+  get_ontology: { method: "GET", path: "/ontologies/{id}", pathParams: ["id"] },
+  get_active_ontology: { method: "GET", path: "/ontologies/active" },
+  clone_ontology: {
+    method: "POST",
+    path: "/ontologies/{name}/clone",
+    pathParams: ["name"]
+  },
+  create_ontology: { method: "POST", path: "/ontologies", hasBody: true, snakeBody: true },
+  update_ontology: {
+    method: "PUT",
+    path: "/ontologies/{id}",
+    pathParams: ["id"],
+    hasBody: true,
+    snakeBody: true
+  },
+  activate_ontology: {
+    method: "POST",
+    path: "/ontologies/active",
+    hasBody: true,
+    snakeBody: true
+  },
+  delete_ontology: { method: "DELETE", path: "/ontologies/{id}", pathParams: ["id"] }
 };
 var RestTransport = class {
   endpoint;
@@ -1107,13 +1364,17 @@ var RestTransport = class {
     const query = queryEntries.length ? "?" + queryEntries.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&") : "";
     let body;
     if (route.hasBody) {
-      const bodyObj = {};
-      for (const [k, v] of Object.entries(camelParams)) {
-        if (!consumed.has(k) && v !== void 0 && v !== null) {
-          bodyObj[k] = v;
+      if (route.snakeBody) {
+        body = JSON.stringify(original.body ?? {});
+      } else {
+        const bodyObj = {};
+        for (const [k, v] of Object.entries(camelParams)) {
+          if (!consumed.has(k) && v !== void 0 && v !== null) {
+            bodyObj[k] = v;
+          }
         }
+        body = JSON.stringify(bodyObj);
       }
-      body = JSON.stringify(bodyObj);
     }
     const url = `${this.endpoint}${path}${query}`;
     const start = nowMs();
@@ -1229,6 +1490,8 @@ var MemoryClient = class {
   query;
   /** API-key & OAuth management (hosted service only). */
   auth;
+  /** Ontology lifecycle — typed domain schemas (hosted service only). */
+  ontology;
   transport;
   constructor(optionsOrTransport = {}) {
     if (isTransport(optionsOrTransport)) {
@@ -1241,6 +1504,7 @@ var MemoryClient = class {
     this.reasoning = new ReasoningMemory(this.transport);
     this.query = new QueryConsole(this.transport);
     this.auth = new AuthClient(this.transport);
+    this.ontology = new OntologyClient(this.transport);
   }
   async connect() {
     await this.transport.connect();
@@ -1261,9 +1525,22 @@ function resolveApiKey(option) {
   if (typeof process === "undefined" || !process.env) return void 0;
   return process.env.MEMORY_API_KEY;
 }
+function resolveWorkspaceId(option) {
+  if (option !== void 0) return option;
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env.MEMORY_WORKSPACE_ID;
+}
+function withWorkspaceHeader(headers, workspaceId) {
+  if (!workspaceId) return headers;
+  const hasExplicit = headers !== void 0 && Object.keys(headers).some((k) => k.toLowerCase() === "x-workspace-id");
+  if (hasExplicit) return headers;
+  return { ...headers ?? {}, "X-Workspace-Id": workspaceId };
+}
 function createTransport(options) {
   const endpoint = options.endpoint;
   const apiKey = resolveApiKey(options.apiKey);
+  const workspaceId = resolveWorkspaceId(options.workspaceId);
+  const headers = withWorkspaceHeader(options.headers, workspaceId);
   const choice = pickTransport(endpoint ?? DEFAULT_ENDPOINT, options.transport);
   if (choice === "rest") {
     return new RestTransport({
@@ -1271,7 +1548,7 @@ function createTransport(options) {
       apiKey,
       tokenProvider: options.tokenProvider,
       timeout: options.timeout,
-      headers: options.headers,
+      headers,
       logger: options.logger
     });
   }
@@ -1282,7 +1559,7 @@ function createTransport(options) {
     endpoint,
     apiKey,
     timeout: options.timeout,
-    headers: options.headers,
+    headers,
     logger: options.logger
   });
 }
@@ -1308,6 +1585,6 @@ var LazyConnectTransport = class {
   }
 };
 
-export { AuthClient, LongTermMemory, MemoryClient, QueryConsole, ReasoningMemory, RestTransport, ShortTermMemory };
+export { AuthClient, LongTermMemory, MemoryClient, OntologyClient, QueryConsole, ReasoningMemory, RestTransport, ShortTermMemory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map