mindgraph 0.1.9 → 0.2.1

package/README.md

@@ -52,7 +52,27 @@ new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
 |--------|-------------|
 | `capture(req)` | Capture a source, snippet, or observation |
 | `entity(req)` | Create, alias, resolve, or merge entities |
-| `findOrCreateEntity(label, entityType?, agentId?)` | Convenience: create or find an entity by label |
+| `findOrCreateEntity(label, entityType?, agentId?)` | Convenience: create or find an entity by label (generic fallback) |
+| `findOrCreatePerson(label, props?, agentId?)` | Find or create a Person entity |
+| `findOrCreateOrganization(label, props?, agentId?)` | Find or create an Organization entity |
+| `findOrCreateNation(label, props?, agentId?)` | Find or create a Nation entity |
+| `findOrCreateEvent(label, props?, agentId?)` | Find or create an Event entity |
+| `findOrCreatePlace(label, props?, agentId?)` | Find or create a Place entity |
+| `findOrCreateConcept(label, props?, agentId?)` | Find or create a Concept entity |
+| `addClaim(label, props?, agentId?)` | Add a Claim node |
+| `addEvidence(label, props?, agentId?)` | Add an Evidence node |
+| `addObservation(label, props?, agentId?)` | Add an Observation node |
+
+**Typed entity example:**
+
+```typescript
+const person = await graph.findOrCreatePerson("Marie Curie", { nationality: "Polish" });
+const org = await graph.findOrCreateOrganization("CERN", { org_type: "intergovernmental" });
+const concept = await graph.findOrCreateConcept("Nuclear Physics");
+
+// findOrCreateEntity() still works as a generic fallback for any entity type
+const entity = await graph.findOrCreateEntity("Some Entity");
+```
 
 ### Epistemic Layer
 

package/dist/index.d.mts

@@ -38,6 +38,59 @@ interface PathStep {
     depth: number;
     parent_uid: string | null;
 }
+interface PersonProps {
+    canonical_name: string;
+    description?: string;
+    birth_date?: string;
+    death_date?: string;
+    nationality?: string;
+    occupation?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface OrganizationProps {
+    canonical_name: string;
+    description?: string;
+    org_type: string;
+    founded_date?: string;
+    dissolved_date?: string;
+    headquarters?: string;
+    sector?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface NationProps {
+    canonical_name: string;
+    description?: string;
+    iso_code?: string;
+    capital?: string;
+    government_type?: string;
+    region?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface EventProps {
+    canonical_name: string;
+    description?: string;
+    event_type: string;
+    event_date?: string;
+    end_date?: string;
+    location?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface PlaceProps {
+    canonical_name: string;
+    description?: string;
+    place_type: string;
+    coordinates?: {
+        lat: number;
+        lon: number;
+    };
+    parent_location?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
 interface CaptureRequest {
     action: "source" | "snippet" | "observation";
     label: string;
@@ -445,6 +498,30 @@ declare class MindGraph {
     findOrCreateEntity(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
         created: boolean;
     }>;
+    /** Convenience: create or find a Person entity by label. */
+    findOrCreatePerson(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find an Organization entity by label. */
+    findOrCreateOrganization(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find a Nation entity by label. */
+    findOrCreateNation(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find an Event entity by label. */
+    findOrCreateEvent(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find a Place entity by label. */
+    findOrCreatePlace(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find a Concept entity by label. */
+    findOrCreateConcept(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
     /**
      * Resolve text to an existing entity via alias matching.
      * Returns `{ uid: string | null }`.
@@ -466,6 +543,18 @@ declare class MindGraph {
     argue(req: ArgumentRequest): Promise<unknown>;
     inquire(req: InquiryRequest): Promise<unknown>;
     structure(req: StructureRequest): Promise<unknown>;
+    /**
+     * Convenience: create a Claim node via the argument endpoint.
+     * Returns the full argument response including `claim_uid`.
+     */
+    addClaim(label: string, content: string, confidence?: number, agentId?: string): Promise<unknown>;
+    /**
+     * Convenience: create an Evidence node attached to a claim via the argument endpoint.
+     * If `claimLabel` and `claimConfidence` are provided, also creates the claim.
+     */
+    addEvidence(label: string, description: string, agentId?: string): Promise<unknown>;
+    /** Convenience: create an Observation node via the reality capture endpoint. */
+    addObservation(label: string, description: string, agentId?: string): Promise<unknown>;
     commit(req: CommitmentRequest): Promise<unknown>;
     deliberate(req: DeliberationRequest): Promise<unknown>;
     /** Open a new decision for deliberation. Returns the Decision node. */
@@ -530,6 +619,25 @@ declare class MindGraph {
         agent_id?: string;
     }): Promise<GraphNode>;
     deleteNode(uid: string): Promise<void>;
+    batchDeleteNodes(params: {
+        uids?: string[];
+        agentId?: string;
+        filter?: {
+            nodeType?: string;
+            nodeTypes?: string[];
+            layer?: string;
+            labelContains?: string;
+            propEquals?: [string, string];
+        };
+        reason?: string;
+        by?: string;
+        hardPurge?: boolean;
+    }): Promise<{
+        nodes_tombstoned: number;
+        edges_tombstoned: number;
+        nodes_purged: number;
+        edges_purged: number;
+    }>;
     getNodeHistory(uid: string): Promise<unknown[]>;
     getNodeAtVersion(uid: string, version: number): Promise<GraphNode>;
     addLink(body: {
@@ -675,4 +783,4 @@ declare class MindGraph {
     clearGraph(): Promise<ClearResponse>;
 }
 
-export { type ArgumentRequest, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type PathStep, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };
+export { type ArgumentRequest, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };

package/dist/index.d.ts

@@ -38,6 +38,59 @@ interface PathStep {
     depth: number;
     parent_uid: string | null;
 }
+interface PersonProps {
+    canonical_name: string;
+    description?: string;
+    birth_date?: string;
+    death_date?: string;
+    nationality?: string;
+    occupation?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface OrganizationProps {
+    canonical_name: string;
+    description?: string;
+    org_type: string;
+    founded_date?: string;
+    dissolved_date?: string;
+    headquarters?: string;
+    sector?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface NationProps {
+    canonical_name: string;
+    description?: string;
+    iso_code?: string;
+    capital?: string;
+    government_type?: string;
+    region?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface EventProps {
+    canonical_name: string;
+    description?: string;
+    event_type: string;
+    event_date?: string;
+    end_date?: string;
+    location?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
+interface PlaceProps {
+    canonical_name: string;
+    description?: string;
+    place_type: string;
+    coordinates?: {
+        lat: number;
+        lon: number;
+    };
+    parent_location?: string;
+    identifiers?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+}
 interface CaptureRequest {
     action: "source" | "snippet" | "observation";
     label: string;
@@ -445,6 +498,30 @@ declare class MindGraph {
     findOrCreateEntity(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
         created: boolean;
     }>;
+    /** Convenience: create or find a Person entity by label. */
+    findOrCreatePerson(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find an Organization entity by label. */
+    findOrCreateOrganization(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find a Nation entity by label. */
+    findOrCreateNation(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find an Event entity by label. */
+    findOrCreateEvent(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find a Place entity by label. */
+    findOrCreatePlace(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
+    /** Convenience: create or find a Concept entity by label. */
+    findOrCreateConcept(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
+        created: boolean;
+    }>;
     /**
      * Resolve text to an existing entity via alias matching.
      * Returns `{ uid: string | null }`.
@@ -466,6 +543,18 @@ declare class MindGraph {
     argue(req: ArgumentRequest): Promise<unknown>;
     inquire(req: InquiryRequest): Promise<unknown>;
     structure(req: StructureRequest): Promise<unknown>;
+    /**
+     * Convenience: create a Claim node via the argument endpoint.
+     * Returns the full argument response including `claim_uid`.
+     */
+    addClaim(label: string, content: string, confidence?: number, agentId?: string): Promise<unknown>;
+    /**
+     * Convenience: create an Evidence node attached to a claim via the argument endpoint.
+     * If `claimLabel` and `claimConfidence` are provided, also creates the claim.
+     */
+    addEvidence(label: string, description: string, agentId?: string): Promise<unknown>;
+    /** Convenience: create an Observation node via the reality capture endpoint. */
+    addObservation(label: string, description: string, agentId?: string): Promise<unknown>;
     commit(req: CommitmentRequest): Promise<unknown>;
     deliberate(req: DeliberationRequest): Promise<unknown>;
     /** Open a new decision for deliberation. Returns the Decision node. */
@@ -530,6 +619,25 @@ declare class MindGraph {
         agent_id?: string;
     }): Promise<GraphNode>;
     deleteNode(uid: string): Promise<void>;
+    batchDeleteNodes(params: {
+        uids?: string[];
+        agentId?: string;
+        filter?: {
+            nodeType?: string;
+            nodeTypes?: string[];
+            layer?: string;
+            labelContains?: string;
+            propEquals?: [string, string];
+        };
+        reason?: string;
+        by?: string;
+        hardPurge?: boolean;
+    }): Promise<{
+        nodes_tombstoned: number;
+        edges_tombstoned: number;
+        nodes_purged: number;
+        edges_purged: number;
+    }>;
     getNodeHistory(uid: string): Promise<unknown[]>;
     getNodeAtVersion(uid: string, version: number): Promise<GraphNode>;
     addLink(body: {
@@ -675,4 +783,4 @@ declare class MindGraph {
     clearGraph(): Promise<ClearResponse>;
 }
 
-export { type ArgumentRequest, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type PathStep, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };
+export { type ArgumentRequest, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };

package/dist/index.js

@@ -121,6 +121,30 @@ var MindGraph = class {
       agent_id: agentId
     });
   }
+  /** Convenience: create or find a Person entity by label. */
+  async findOrCreatePerson(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "person", ...props }, agentId);
+  }
+  /** Convenience: create or find an Organization entity by label. */
+  async findOrCreateOrganization(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "organization", ...props }, agentId);
+  }
+  /** Convenience: create or find a Nation entity by label. */
+  async findOrCreateNation(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "nation", ...props }, agentId);
+  }
+  /** Convenience: create or find an Event entity by label. */
+  async findOrCreateEvent(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "event", ...props }, agentId);
+  }
+  /** Convenience: create or find a Place entity by label. */
+  async findOrCreatePlace(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "place", ...props }, agentId);
+  }
+  /** Convenience: create or find a Concept entity by label. */
+  async findOrCreateConcept(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "concept", ...props }, agentId);
+  }
   /**
    * Resolve text to an existing entity via alias matching.
    * Returns `{ uid: string | null }`.
@@ -154,6 +178,40 @@ var MindGraph = class {
   async structure(req) {
     return this.post("/epistemic/structure", req);
   }
+  /**
+   * Convenience: create a Claim node via the argument endpoint.
+   * Returns the full argument response including `claim_uid`.
+   */
+  async addClaim(label, content, confidence, agentId) {
+    return this.post("/epistemic/argument", {
+      claim: {
+        label,
+        confidence,
+        props: { content }
+      },
+      agent_id: agentId
+    });
+  }
+  /**
+   * Convenience: create an Evidence node attached to a claim via the argument endpoint.
+   * If `claimLabel` and `claimConfidence` are provided, also creates the claim.
+   */
+  async addEvidence(label, description, agentId) {
+    return this.post("/epistemic/argument", {
+      claim: { label: `Claim for: ${label}` },
+      evidence: [{ label, props: { description } }],
+      agent_id: agentId
+    });
+  }
+  /** Convenience: create an Observation node via the reality capture endpoint. */
+  async addObservation(label, description, agentId) {
+    return this.post("/reality/capture", {
+      action: "observation",
+      label,
+      summary: description,
+      agent_id: agentId
+    });
+  }
   // ---- Intent Layer ----
   async commit(req) {
     return this.post("/intent/commitment", req);
@@ -260,6 +318,24 @@ var MindGraph = class {
   async deleteNode(uid) {
     await this.del(`/node/${uid}`);
   }
+  async batchDeleteNodes(params) {
+    const body = {};
+    if (params.uids) body.uids = params.uids;
+    if (params.agentId) body.agent_id = params.agentId;
+    if (params.filter) {
+      body.filter = {
+        node_type: params.filter.nodeType,
+        node_types: params.filter.nodeTypes,
+        layer: params.filter.layer,
+        label_contains: params.filter.labelContains,
+        prop_equals: params.filter.propEquals
+      };
+    }
+    if (params.reason) body.reason = params.reason;
+    if (params.by) body.by = params.by;
+    if (params.hardPurge) body.hard_purge = params.hardPurge;
+    return this.post("/nodes/delete", body);
+  }
   async getNodeHistory(uid) {
     return this.get(`/node/${uid}/history`);
   }

package/dist/index.mjs

@@ -94,6 +94,30 @@ var MindGraph = class {
       agent_id: agentId
     });
   }
+  /** Convenience: create or find a Person entity by label. */
+  async findOrCreatePerson(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "person", ...props }, agentId);
+  }
+  /** Convenience: create or find an Organization entity by label. */
+  async findOrCreateOrganization(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "organization", ...props }, agentId);
+  }
+  /** Convenience: create or find a Nation entity by label. */
+  async findOrCreateNation(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "nation", ...props }, agentId);
+  }
+  /** Convenience: create or find an Event entity by label. */
+  async findOrCreateEvent(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "event", ...props }, agentId);
+  }
+  /** Convenience: create or find a Place entity by label. */
+  async findOrCreatePlace(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "place", ...props }, agentId);
+  }
+  /** Convenience: create or find a Concept entity by label. */
+  async findOrCreateConcept(label, props, agentId) {
+    return this.findOrCreateEntity(label, { entity_type: "concept", ...props }, agentId);
+  }
   /**
    * Resolve text to an existing entity via alias matching.
    * Returns `{ uid: string | null }`.
@@ -127,6 +151,40 @@ var MindGraph = class {
   async structure(req) {
     return this.post("/epistemic/structure", req);
   }
+  /**
+   * Convenience: create a Claim node via the argument endpoint.
+   * Returns the full argument response including `claim_uid`.
+   */
+  async addClaim(label, content, confidence, agentId) {
+    return this.post("/epistemic/argument", {
+      claim: {
+        label,
+        confidence,
+        props: { content }
+      },
+      agent_id: agentId
+    });
+  }
+  /**
+   * Convenience: create an Evidence node attached to a claim via the argument endpoint.
+   * If `claimLabel` and `claimConfidence` are provided, also creates the claim.
+   */
+  async addEvidence(label, description, agentId) {
+    return this.post("/epistemic/argument", {
+      claim: { label: `Claim for: ${label}` },
+      evidence: [{ label, props: { description } }],
+      agent_id: agentId
+    });
+  }
+  /** Convenience: create an Observation node via the reality capture endpoint. */
+  async addObservation(label, description, agentId) {
+    return this.post("/reality/capture", {
+      action: "observation",
+      label,
+      summary: description,
+      agent_id: agentId
+    });
+  }
   // ---- Intent Layer ----
   async commit(req) {
     return this.post("/intent/commitment", req);
@@ -233,6 +291,24 @@ var MindGraph = class {
   async deleteNode(uid) {
     await this.del(`/node/${uid}`);
   }
+  async batchDeleteNodes(params) {
+    const body = {};
+    if (params.uids) body.uids = params.uids;
+    if (params.agentId) body.agent_id = params.agentId;
+    if (params.filter) {
+      body.filter = {
+        node_type: params.filter.nodeType,
+        node_types: params.filter.nodeTypes,
+        layer: params.filter.layer,
+        label_contains: params.filter.labelContains,
+        prop_equals: params.filter.propEquals
+      };
+    }
+    if (params.reason) body.reason = params.reason;
+    if (params.by) body.by = params.by;
+    if (params.hardPurge) body.hard_purge = params.hardPurge;
+    return this.post("/nodes/delete", body);
+  }
   async getNodeHistory(uid) {
     return this.get(`/node/${uid}/history`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",