mindgraph 0.1.8 → 0.2.0

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;
@@ -413,6 +466,10 @@ interface MindGraphConfig {
     baseUrl: string;
     apiKey?: string;
     jwt?: string;
+    /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
+    maxRetries?: number;
+    /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
+    retryBackoffMs?: number;
 }
 
 declare class MindGraphError extends Error {
@@ -423,6 +480,8 @@ declare class MindGraphError extends Error {
 declare class MindGraph {
     private baseUrl;
     private headers;
+    private maxRetries;
+    private retryBackoffMs;
     constructor(config: MindGraphConfig);
     private request;
     private get;
@@ -439,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 }`.
@@ -460,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. */
@@ -669,4 +764,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;
@@ -413,6 +466,10 @@ interface MindGraphConfig {
     baseUrl: string;
     apiKey?: string;
     jwt?: string;
+    /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
+    maxRetries?: number;
+    /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
+    retryBackoffMs?: number;
 }
 
 declare class MindGraphError extends Error {
@@ -423,6 +480,8 @@ declare class MindGraphError extends Error {
 declare class MindGraph {
     private baseUrl;
     private headers;
+    private maxRetries;
+    private retryBackoffMs;
     constructor(config: MindGraphConfig);
     private request;
     private get;
@@ -439,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 }`.
@@ -460,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. */
@@ -669,4 +764,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

@@ -43,6 +43,8 @@ var MindGraph = class {
     } else if (config.jwt) {
       this.headers["Authorization"] = `Bearer ${config.jwt}`;
     }
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
@@ -54,24 +56,35 @@ var MindGraph = class {
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
-    const res = await fetch(url, init);
-    if (!res.ok) {
-      const text2 = await res.text().catch(() => "");
-      let parsed;
-      try {
-        parsed = JSON.parse(text2);
-      } catch {
-        parsed = text2;
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const res = await fetch(url, init);
+      if (!res.ok) {
+        const text2 = await res.text().catch(() => "");
+        let parsed;
+        try {
+          parsed = JSON.parse(text2);
+        } catch {
+          parsed = text2;
+        }
+        const err = new MindGraphError(
+          `${method} ${path} failed: ${res.status}`,
+          res.status,
+          parsed
+        );
+        if (res.status === 503 && attempt < this.maxRetries) {
+          lastError = err;
+          const delay = this.retryBackoffMs * 2 ** attempt;
+          await new Promise((r) => setTimeout(r, delay));
+          continue;
+        }
+        throw err;
       }
-      throw new MindGraphError(
-        `${method} ${path} failed: ${res.status}`,
-        res.status,
-        parsed
-      );
+      const text = await res.text();
+      if (!text) return void 0;
+      return JSON.parse(text);
     }
-    const text = await res.text();
-    if (!text) return void 0;
-    return JSON.parse(text);
+    throw lastError;
   }
   get(path) {
     return this.request("GET", path);
@@ -108,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 }`.
@@ -141,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);

package/dist/index.mjs

@@ -16,6 +16,8 @@ var MindGraph = class {
     } else if (config.jwt) {
       this.headers["Authorization"] = `Bearer ${config.jwt}`;
     }
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
@@ -27,24 +29,35 @@ var MindGraph = class {
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
-    const res = await fetch(url, init);
-    if (!res.ok) {
-      const text2 = await res.text().catch(() => "");
-      let parsed;
-      try {
-        parsed = JSON.parse(text2);
-      } catch {
-        parsed = text2;
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const res = await fetch(url, init);
+      if (!res.ok) {
+        const text2 = await res.text().catch(() => "");
+        let parsed;
+        try {
+          parsed = JSON.parse(text2);
+        } catch {
+          parsed = text2;
+        }
+        const err = new MindGraphError(
+          `${method} ${path} failed: ${res.status}`,
+          res.status,
+          parsed
+        );
+        if (res.status === 503 && attempt < this.maxRetries) {
+          lastError = err;
+          const delay = this.retryBackoffMs * 2 ** attempt;
+          await new Promise((r) => setTimeout(r, delay));
+          continue;
+        }
+        throw err;
       }
-      throw new MindGraphError(
-        `${method} ${path} failed: ${res.status}`,
-        res.status,
-        parsed
-      );
+      const text = await res.text();
+      if (!text) return void 0;
+      return JSON.parse(text);
     }
-    const text = await res.text();
-    if (!text) return void 0;
-    return JSON.parse(text);
+    throw lastError;
   }
   get(path) {
     return this.request("GET", path);
@@ -81,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 }`.
@@ -114,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);

package/package.json

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