mindgraph 0.1.1 → 0.1.7

package/dist/index.js

@@ -93,18 +93,41 @@ var MindGraph = class {
     return this.get("/stats");
   }
   // ---- Reality Layer ----
-  async ingest(req) {
-    return this.post("/reality/ingest", req);
+  async capture(req) {
+    return this.post("/reality/capture", req);
   }
   async entity(req) {
     return this.post("/reality/entity", req);
   }
   /** Convenience: create or find an entity by label. */
-  async findOrCreateEntity(label, entityType = "other", agentId) {
+  async findOrCreateEntity(label, props, agentId) {
     return this.post("/reality/entity", {
       action: "create",
       label,
-      entity_type: entityType,
+      props: { entity_type: "other", ...props },
+      agent_id: agentId
+    });
+  }
+  /**
+   * Resolve text to an existing entity via alias matching.
+   * Returns `{ uid: string | null }`.
+   */
+  async resolveEntity(text, agentId) {
+    return this.post("/reality/entity", {
+      action: "resolve",
+      text,
+      agent_id: agentId
+    });
+  }
+  /**
+   * Fuzzy-match text against existing entities.
+   * Returns `{ matches: [{ uid, label, score }] }`.
+   */
+  async fuzzyResolveEntity(text, limit = 5, agentId) {
+    return this.post("/reality/entity", {
+      action: "fuzzy_resolve",
+      text,
+      limit,
       agent_id: agentId
     });
   }
@@ -125,6 +148,35 @@ var MindGraph = class {
   async deliberate(req) {
     return this.post("/intent/deliberation", req);
   }
+  /** Open a new decision for deliberation. Returns the Decision node. */
+  async openDecision(label, opts) {
+    return this.post("/intent/deliberation", {
+      action: "open_decision",
+      label,
+      ...opts
+    });
+  }
+  /** Add an option to an open decision. Returns the Option node. */
+  async addOption(decisionUid, label, opts) {
+    return this.post("/intent/deliberation", {
+      action: "add_option",
+      decision_uid: decisionUid,
+      label,
+      ...opts
+    });
+  }
+  /**
+   * Resolve a decision by choosing an option.
+   * `chosenOptionUid` must be the uid of an option added via `addOption()`.
+   */
+  async resolveDecision(decisionUid, chosenOptionUid, opts) {
+    return this.post("/intent/deliberation", {
+      action: "resolve",
+      decision_uid: decisionUid,
+      chosen_option_uid: chosenOptionUid,
+      ...opts
+    });
+  }
   // ---- Action Layer ----
   async procedure(req) {
     return this.post("/action/procedure", req);
@@ -136,11 +188,11 @@ var MindGraph = class {
   async session(req) {
     return this.post("/memory/session", req);
   }
-  async journal(label, content, options) {
+  async journal(label, props, options) {
     return this.post("/memory/session", {
       action: "journal",
       label,
-      content,
+      props,
       ...options
     });
   }
@@ -161,6 +213,7 @@ var MindGraph = class {
     return this.post("/agent/execution", req);
   }
   // ---- Cross-cutting ----
+  /** Returns an array of results. Shape varies by action. */
   async retrieve(req) {
     return this.post("/retrieve", req);
   }
@@ -174,8 +227,19 @@ var MindGraph = class {
   async getNode(uid) {
     return this.get(`/node/${uid}`);
   }
+  /**
+   * Create a node via the low-level CRUD endpoint.
+   *
+   * The server requires `props._type` to determine the node variant.
+   * If `node_type` is provided and `_type` is not already in `props`,
+   * it is injected automatically.
+   */
   async addNode(body) {
-    return this.post("/node", body);
+    const props = { ...body.props };
+    if (body.node_type && !("_type" in props)) {
+      props._type = body.node_type;
+    }
+    return this.post("/node", { ...body, props });
   }
   async updateNode(uid, body) {
     return this.patch(`/node/${uid}`, body);
@@ -183,16 +247,60 @@ var MindGraph = class {
   async deleteNode(uid) {
     await this.del(`/node/${uid}`);
   }
+  async getNodeHistory(uid) {
+    return this.get(`/node/${uid}/history`);
+  }
+  async getNodeAtVersion(uid, version) {
+    return this.get(`/node/${uid}/history/${version}`);
+  }
   // ---- Edge CRUD ----
   async addLink(body) {
     return this.post("/link", body);
   }
+  /**
+   * Create an edge via the low-level CRUD endpoint.
+   *
+   * The server requires `props._type` to determine the edge variant.
+   * If `edge_type` is provided and `_type` is not already in `props`,
+   * it is injected automatically.
+   */
+  async addEdge(body) {
+    const props = { ...body.props };
+    if (body.edge_type && !("_type" in props)) {
+      props._type = body.edge_type;
+    }
+    return this.post("/edge", { ...body, props });
+  }
+  async updateEdge(uid, body) {
+    return this.patch(`/edge/${uid}`, body);
+  }
+  async deleteEdge(uid) {
+    await this.del(`/edge/${uid}`);
+  }
+  async getEdgeHistory(uid) {
+    return this.get(`/edge/${uid}/history`);
+  }
+  /**
+   * List edges filtered by source and/or target node.
+   * At least one of `from_uid` or `to_uid` is **required** —
+   * the server returns 400 if neither is provided.
+   */
   async getEdges(params) {
+    if (!params.from_uid && !params.to_uid) {
+      throw new Error("at least one of from_uid or to_uid is required");
+    }
     const qs = new URLSearchParams();
     if (params.from_uid) qs.set("from_uid", params.from_uid);
     if (params.to_uid) qs.set("to_uid", params.to_uid);
     return this.get(`/edges?${qs}`);
   }
+  async getEdgeBetween(params) {
+    const qs = new URLSearchParams();
+    qs.set("from_uid", params.from_uid);
+    qs.set("to_uid", params.to_uid);
+    if (params.edge_type) qs.set("edge_type", params.edge_type);
+    return this.get(`/edge/between?${qs}`);
+  }
   // ---- Search ----
   async search(query, opts) {
     return this.post("/search", { query, ...opts });
@@ -205,20 +313,87 @@ var MindGraph = class {
       ...opts
     });
   }
+  // ---- Nodes listing ----
+  async getNodes(params) {
+    const qs = new URLSearchParams();
+    if (params?.node_type) qs.set("node_type", params.node_type);
+    if (params?.layer) qs.set("layer", params.layer);
+    if (params?.limit != null) qs.set("limit", String(params.limit));
+    if (params?.offset != null) qs.set("offset", String(params.offset));
+    return this.get(`/nodes?${qs}`);
+  }
+  async getAgentNodes(agentId) {
+    return this.get(`/agent/${agentId}/nodes`);
+  }
+  // ---- Batch ----
+  async batch(req) {
+    return this.post("/batch", req);
+  }
+  // ---- Embeddings ----
+  async configureEmbeddings(body) {
+    return this.post("/embeddings/configure", body);
+  }
+  async embeddingSearch(body) {
+    return this.post("/embeddings/search", body);
+  }
+  async embeddingSearchText(body) {
+    return this.post("/embeddings/search-text", body);
+  }
+  async getEmbedding(uid) {
+    return this.get(`/node/${uid}/embedding`);
+  }
+  async setEmbedding(uid, vector) {
+    await this.request("PUT", `/node/${uid}/embedding`, { vector });
+  }
+  async deleteEmbedding(uid) {
+    await this.del(`/node/${uid}/embedding`);
+  }
+  // ---- Entity resolution ----
+  async mergeEntities(body) {
+    return this.post("/entities/merge", body);
+  }
+  async addAlias(body) {
+    return this.post("/alias", body);
+  }
+  async getAliases(uid) {
+    return this.get(`/aliases/${uid}`);
+  }
+  async resolveAlias(text) {
+    return this.get(`/resolve?text=${encodeURIComponent(text)}`);
+  }
+  // ---- Export / Import ----
+  async exportGraph() {
+    return this.get("/export");
+  }
+  async importGraph(data) {
+    return this.post("/import", data);
+  }
+  // ---- Lifecycle ----
+  async decay(req) {
+    return this.post("/decay", req);
+  }
+  async purge(req) {
+    return this.post("/purge", req ?? {});
+  }
   // ---- Traversal shortcuts ----
   async reasoningChain(uid, maxDepth = 5) {
-    return this.post("/traverse", {
+    const r = await this.post("/traverse", {
       action: "chain",
       start_uid: uid,
       max_depth: maxDepth
     });
+    return r?.steps ?? r;
   }
   async neighborhood(uid, maxDepth = 1) {
-    return this.post("/traverse", {
+    const r = await this.post("/traverse", {
       action: "neighborhood",
       start_uid: uid,
       max_depth: maxDepth
     });
+    return r?.steps ?? r;
+  }
+  async subgraph(uid, opts) {
+    return this.post("/subgraph", { start_uids: [uid], ...opts });
   }
   // ---- Lifecycle shortcuts ----
   async tombstone(uid, reason, agentId) {
@@ -236,24 +411,55 @@ var MindGraph = class {
       agent_id: agentId
     });
   }
-  // ---- Management (Cloud only) ----
-  async signup(email, password) {
-    return this.post("/v1/auth/signup", { email, password });
+  // ---- Epistemic queries ----
+  async getGoals() {
+    return this.get("/goals");
+  }
+  async getOpenDecisions() {
+    return this.get("/decisions");
+  }
+  async getOpenQuestions() {
+    return this.get("/questions");
+  }
+  async getWeakClaims() {
+    return this.get("/claims/weak");
+  }
+  async getContradictions() {
+    return this.get("/contradictions");
+  }
+  async getPendingApprovals() {
+    return this.get("/approvals/pending");
+  }
+  // ---- Ingestion & Retrieval ----
+  async ingestChunk(req) {
+    return this.post("/ingest/chunk", req);
+  }
+  async ingestDocument(req) {
+    return this.post("/ingest/document", req);
+  }
+  async ingestSession(req) {
+    return this.post("/ingest/session", req);
+  }
+  async retrieveContext(req) {
+    return this.post("/retrieve/context", req);
+  }
+  async listJobs() {
+    return this.get("/jobs");
   }
-  async login(email, password) {
-    return this.post("/v1/auth/login", { email, password });
+  async getJob(id) {
+    return this.get(`/jobs/${id}`);
   }
-  async createApiKey(name = "default") {
-    return this.post("/v1/api-keys", { name });
+  async cancelJob(id) {
+    return this.post(`/jobs/${id}/cancel`, {});
   }
-  async listApiKeys() {
-    return this.get("/v1/api-keys");
+  async cleanupOrphans() {
+    return this.post("/ingest/cleanup", {});
   }
-  async revokeApiKey(id) {
-    await this.del(`/v1/api-keys/${id}`);
+  async embedAll() {
+    return this.post("/ingest/embed-all", {});
   }
-  async getUsage() {
-    return this.get("/v1/usage");
+  async clearGraph() {
+    return this.post("/clear", {});
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -66,18 +66,41 @@ var MindGraph = class {
     return this.get("/stats");
   }
   // ---- Reality Layer ----
-  async ingest(req) {
-    return this.post("/reality/ingest", req);
+  async capture(req) {
+    return this.post("/reality/capture", req);
   }
   async entity(req) {
     return this.post("/reality/entity", req);
   }
   /** Convenience: create or find an entity by label. */
-  async findOrCreateEntity(label, entityType = "other", agentId) {
+  async findOrCreateEntity(label, props, agentId) {
     return this.post("/reality/entity", {
       action: "create",
       label,
-      entity_type: entityType,
+      props: { entity_type: "other", ...props },
+      agent_id: agentId
+    });
+  }
+  /**
+   * Resolve text to an existing entity via alias matching.
+   * Returns `{ uid: string | null }`.
+   */
+  async resolveEntity(text, agentId) {
+    return this.post("/reality/entity", {
+      action: "resolve",
+      text,
+      agent_id: agentId
+    });
+  }
+  /**
+   * Fuzzy-match text against existing entities.
+   * Returns `{ matches: [{ uid, label, score }] }`.
+   */
+  async fuzzyResolveEntity(text, limit = 5, agentId) {
+    return this.post("/reality/entity", {
+      action: "fuzzy_resolve",
+      text,
+      limit,
       agent_id: agentId
     });
   }
@@ -98,6 +121,35 @@ var MindGraph = class {
   async deliberate(req) {
     return this.post("/intent/deliberation", req);
   }
+  /** Open a new decision for deliberation. Returns the Decision node. */
+  async openDecision(label, opts) {
+    return this.post("/intent/deliberation", {
+      action: "open_decision",
+      label,
+      ...opts
+    });
+  }
+  /** Add an option to an open decision. Returns the Option node. */
+  async addOption(decisionUid, label, opts) {
+    return this.post("/intent/deliberation", {
+      action: "add_option",
+      decision_uid: decisionUid,
+      label,
+      ...opts
+    });
+  }
+  /**
+   * Resolve a decision by choosing an option.
+   * `chosenOptionUid` must be the uid of an option added via `addOption()`.
+   */
+  async resolveDecision(decisionUid, chosenOptionUid, opts) {
+    return this.post("/intent/deliberation", {
+      action: "resolve",
+      decision_uid: decisionUid,
+      chosen_option_uid: chosenOptionUid,
+      ...opts
+    });
+  }
   // ---- Action Layer ----
   async procedure(req) {
     return this.post("/action/procedure", req);
@@ -109,11 +161,11 @@ var MindGraph = class {
   async session(req) {
     return this.post("/memory/session", req);
   }
-  async journal(label, content, options) {
+  async journal(label, props, options) {
     return this.post("/memory/session", {
       action: "journal",
       label,
-      content,
+      props,
       ...options
     });
   }
@@ -134,6 +186,7 @@ var MindGraph = class {
     return this.post("/agent/execution", req);
   }
   // ---- Cross-cutting ----
+  /** Returns an array of results. Shape varies by action. */
   async retrieve(req) {
     return this.post("/retrieve", req);
   }
@@ -147,8 +200,19 @@ var MindGraph = class {
   async getNode(uid) {
     return this.get(`/node/${uid}`);
   }
+  /**
+   * Create a node via the low-level CRUD endpoint.
+   *
+   * The server requires `props._type` to determine the node variant.
+   * If `node_type` is provided and `_type` is not already in `props`,
+   * it is injected automatically.
+   */
   async addNode(body) {
-    return this.post("/node", body);
+    const props = { ...body.props };
+    if (body.node_type && !("_type" in props)) {
+      props._type = body.node_type;
+    }
+    return this.post("/node", { ...body, props });
   }
   async updateNode(uid, body) {
     return this.patch(`/node/${uid}`, body);
@@ -156,16 +220,60 @@ var MindGraph = class {
   async deleteNode(uid) {
     await this.del(`/node/${uid}`);
   }
+  async getNodeHistory(uid) {
+    return this.get(`/node/${uid}/history`);
+  }
+  async getNodeAtVersion(uid, version) {
+    return this.get(`/node/${uid}/history/${version}`);
+  }
   // ---- Edge CRUD ----
   async addLink(body) {
     return this.post("/link", body);
   }
+  /**
+   * Create an edge via the low-level CRUD endpoint.
+   *
+   * The server requires `props._type` to determine the edge variant.
+   * If `edge_type` is provided and `_type` is not already in `props`,
+   * it is injected automatically.
+   */
+  async addEdge(body) {
+    const props = { ...body.props };
+    if (body.edge_type && !("_type" in props)) {
+      props._type = body.edge_type;
+    }
+    return this.post("/edge", { ...body, props });
+  }
+  async updateEdge(uid, body) {
+    return this.patch(`/edge/${uid}`, body);
+  }
+  async deleteEdge(uid) {
+    await this.del(`/edge/${uid}`);
+  }
+  async getEdgeHistory(uid) {
+    return this.get(`/edge/${uid}/history`);
+  }
+  /**
+   * List edges filtered by source and/or target node.
+   * At least one of `from_uid` or `to_uid` is **required** —
+   * the server returns 400 if neither is provided.
+   */
   async getEdges(params) {
+    if (!params.from_uid && !params.to_uid) {
+      throw new Error("at least one of from_uid or to_uid is required");
+    }
     const qs = new URLSearchParams();
     if (params.from_uid) qs.set("from_uid", params.from_uid);
     if (params.to_uid) qs.set("to_uid", params.to_uid);
     return this.get(`/edges?${qs}`);
   }
+  async getEdgeBetween(params) {
+    const qs = new URLSearchParams();
+    qs.set("from_uid", params.from_uid);
+    qs.set("to_uid", params.to_uid);
+    if (params.edge_type) qs.set("edge_type", params.edge_type);
+    return this.get(`/edge/between?${qs}`);
+  }
   // ---- Search ----
   async search(query, opts) {
     return this.post("/search", { query, ...opts });
@@ -178,20 +286,87 @@ var MindGraph = class {
       ...opts
     });
   }
+  // ---- Nodes listing ----
+  async getNodes(params) {
+    const qs = new URLSearchParams();
+    if (params?.node_type) qs.set("node_type", params.node_type);
+    if (params?.layer) qs.set("layer", params.layer);
+    if (params?.limit != null) qs.set("limit", String(params.limit));
+    if (params?.offset != null) qs.set("offset", String(params.offset));
+    return this.get(`/nodes?${qs}`);
+  }
+  async getAgentNodes(agentId) {
+    return this.get(`/agent/${agentId}/nodes`);
+  }
+  // ---- Batch ----
+  async batch(req) {
+    return this.post("/batch", req);
+  }
+  // ---- Embeddings ----
+  async configureEmbeddings(body) {
+    return this.post("/embeddings/configure", body);
+  }
+  async embeddingSearch(body) {
+    return this.post("/embeddings/search", body);
+  }
+  async embeddingSearchText(body) {
+    return this.post("/embeddings/search-text", body);
+  }
+  async getEmbedding(uid) {
+    return this.get(`/node/${uid}/embedding`);
+  }
+  async setEmbedding(uid, vector) {
+    await this.request("PUT", `/node/${uid}/embedding`, { vector });
+  }
+  async deleteEmbedding(uid) {
+    await this.del(`/node/${uid}/embedding`);
+  }
+  // ---- Entity resolution ----
+  async mergeEntities(body) {
+    return this.post("/entities/merge", body);
+  }
+  async addAlias(body) {
+    return this.post("/alias", body);
+  }
+  async getAliases(uid) {
+    return this.get(`/aliases/${uid}`);
+  }
+  async resolveAlias(text) {
+    return this.get(`/resolve?text=${encodeURIComponent(text)}`);
+  }
+  // ---- Export / Import ----
+  async exportGraph() {
+    return this.get("/export");
+  }
+  async importGraph(data) {
+    return this.post("/import", data);
+  }
+  // ---- Lifecycle ----
+  async decay(req) {
+    return this.post("/decay", req);
+  }
+  async purge(req) {
+    return this.post("/purge", req ?? {});
+  }
   // ---- Traversal shortcuts ----
   async reasoningChain(uid, maxDepth = 5) {
-    return this.post("/traverse", {
+    const r = await this.post("/traverse", {
       action: "chain",
       start_uid: uid,
       max_depth: maxDepth
     });
+    return r?.steps ?? r;
   }
   async neighborhood(uid, maxDepth = 1) {
-    return this.post("/traverse", {
+    const r = await this.post("/traverse", {
       action: "neighborhood",
       start_uid: uid,
       max_depth: maxDepth
     });
+    return r?.steps ?? r;
+  }
+  async subgraph(uid, opts) {
+    return this.post("/subgraph", { start_uids: [uid], ...opts });
   }
   // ---- Lifecycle shortcuts ----
   async tombstone(uid, reason, agentId) {
@@ -209,24 +384,55 @@ var MindGraph = class {
       agent_id: agentId
     });
   }
-  // ---- Management (Cloud only) ----
-  async signup(email, password) {
-    return this.post("/v1/auth/signup", { email, password });
+  // ---- Epistemic queries ----
+  async getGoals() {
+    return this.get("/goals");
+  }
+  async getOpenDecisions() {
+    return this.get("/decisions");
+  }
+  async getOpenQuestions() {
+    return this.get("/questions");
+  }
+  async getWeakClaims() {
+    return this.get("/claims/weak");
+  }
+  async getContradictions() {
+    return this.get("/contradictions");
+  }
+  async getPendingApprovals() {
+    return this.get("/approvals/pending");
+  }
+  // ---- Ingestion & Retrieval ----
+  async ingestChunk(req) {
+    return this.post("/ingest/chunk", req);
+  }
+  async ingestDocument(req) {
+    return this.post("/ingest/document", req);
+  }
+  async ingestSession(req) {
+    return this.post("/ingest/session", req);
+  }
+  async retrieveContext(req) {
+    return this.post("/retrieve/context", req);
+  }
+  async listJobs() {
+    return this.get("/jobs");
   }
-  async login(email, password) {
-    return this.post("/v1/auth/login", { email, password });
+  async getJob(id) {
+    return this.get(`/jobs/${id}`);
   }
-  async createApiKey(name = "default") {
-    return this.post("/v1/api-keys", { name });
+  async cancelJob(id) {
+    return this.post(`/jobs/${id}/cancel`, {});
   }
-  async listApiKeys() {
-    return this.get("/v1/api-keys");
+  async cleanupOrphans() {
+    return this.post("/ingest/cleanup", {});
   }
-  async revokeApiKey(id) {
-    await this.del(`/v1/api-keys/${id}`);
+  async embedAll() {
+    return this.post("/ingest/embed-all", {});
   }
-  async getUsage() {
-    return this.get("/v1/usage");
+  async clearGraph() {
+    return this.post("/clear", {});
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.1.1",
+  "version": "0.1.7",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,6 +14,7 @@
   "keywords": ["mindgraph", "knowledge-graph", "cognitive", "ai", "agent"],
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^25.4.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"