mindgraph 0.1.2 → 0.1.7

package/dist/index.d.ts

@@ -38,7 +38,7 @@ interface PathStep {
     depth: number;
     parent_uid: string | null;
 }
-interface IngestRequest {
+interface CaptureRequest {
     action: "source" | "snippet" | "observation";
     label: string;
     summary?: string;
@@ -250,6 +250,10 @@ interface ExecutionRequest {
     agent_id?: string;
 }
 interface RetrieveRequest {
+    /**
+     * Retrieval action. Note: `"semantic"` requires a configured embedding
+     * provider on the server; for semantic search use `retrieveContext()` instead.
+     */
     action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "layer" | "recent";
     query?: string;
     k?: number;
@@ -286,26 +290,114 @@ interface EvolveRequest {
     version?: number;
     agent_id?: string;
 }
-interface SignupRequest {
-    email: string;
-    password: string;
+interface IngestChunkRequest {
+    content: string;
+    chunk_type?: string;
+    document_uid?: string;
+    chunk_index?: number;
+    label?: string;
+    layers?: string[];
+    agent_id?: string;
+}
+interface IngestChunkResponse {
+    chunk_uid: string;
+    nodes_created: number;
+    nodes_deduplicated: number;
+    edges_created: number;
+    extracted_node_uids: string[];
+    errors: string[];
+}
+interface IngestDocumentRequest {
+    content: string;
+    title?: string;
+    document_type?: string;
+    /** Semantic content type: "article" (default), "meeting_notes", "journal". Drives default extraction layers. */
+    content_type?: string;
+    source_uri?: string;
+    chunk_size?: number;
+    chunk_overlap?: number;
+    layers?: string[];
+    agent_id?: string;
 }
-interface LoginRequest {
-    email: string;
-    password: string;
+interface IngestDocumentResponse {
+    job_id: string;
+    document_uid: string;
 }
-interface CreateOrgRequest {
-    name: string;
-    slug?: string;
+interface IngestSessionRequest {
+    content: string;
+    title?: string;
+    session_uid?: string;
+    chunk_size?: number;
+    chunk_overlap?: number;
+    layers?: string[];
+    agent_id?: string;
+}
+interface RetrieveContextRequest {
+    query: string;
+    k?: number;
+    depth?: number;
+    node_types?: string[];
+    layer?: string;
+    include_chunks?: boolean;
+    include_graph?: boolean;
+    min_similarity?: number;
 }
-interface CreateApiKeyRequest {
-    name?: string;
+interface RetrieveContextResponse {
+    chunks: {
+        chunk_uid: string;
+        content: string;
+        score: number;
+        document_uid: string | null;
+        chunk_index: number | null;
+    }[];
+    graph: {
+        nodes: Record<string, unknown>[];
+        edges: Record<string, unknown>[];
+    };
 }
-interface ApiKeyResponse {
+interface Job {
     id: string;
-    key: string;
-    name: string;
-    prefix: string;
+    title: string;
+    status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+    progress: {
+        total_chunks: number;
+        processed_chunks: number;
+        nodes_created: number;
+        edges_created: number;
+    };
+    result: Record<string, unknown> | null;
+    error: string | null;
+    created_at: number;
+    queue_position?: number;
+}
+interface ClearResponse {
+    cleared: boolean;
+    nodes_removed: number;
+    edges_removed: number;
+    versions_removed: number;
+    aliases_removed: number;
+    embeddings_removed: number;
+}
+interface BatchRequest {
+    nodes?: {
+        label: string;
+        node_type?: string;
+        props?: Record<string, unknown>;
+    }[];
+    edges?: {
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+    }[];
+    agent_id?: string;
+}
+interface DecayRequest {
+    half_life_secs: number;
+    min_salience?: number;
+    min_age_secs?: number;
+}
+interface PurgeRequest {
+    before?: number;
 }
 interface MindGraphConfig {
     baseUrl: string;
@@ -331,17 +423,55 @@ declare class MindGraph {
         status: string;
     }>;
     stats(): Promise<Record<string, unknown>>;
-    ingest(req: IngestRequest): Promise<unknown>;
+    capture(req: CaptureRequest): Promise<unknown>;
     entity(req: EntityRequest): Promise<unknown>;
     /** Convenience: create or find an entity by label. */
     findOrCreateEntity(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 }`.
+     */
+    resolveEntity(text: string, agentId?: string): Promise<{
+        uid: string | null;
+    }>;
+    /**
+     * Fuzzy-match text against existing entities.
+     * Returns `{ matches: [{ uid, label, score }] }`.
+     */
+    fuzzyResolveEntity(text: string, limit?: number, agentId?: string): Promise<{
+        matches: {
+            uid: string;
+            label: string;
+            score: number;
+        }[];
+    }>;
     argue(req: ArgumentRequest): Promise<unknown>;
     inquire(req: InquiryRequest): Promise<unknown>;
     structure(req: StructureRequest): Promise<unknown>;
     commit(req: CommitmentRequest): Promise<unknown>;
     deliberate(req: DeliberationRequest): Promise<unknown>;
+    /** Open a new decision for deliberation. Returns the Decision node. */
+    openDecision(label: string, opts?: {
+        summary?: string;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    /** Add an option to an open decision. Returns the Option node. */
+    addOption(decisionUid: string, label: string, opts?: {
+        summary?: string;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    /**
+     * Resolve a decision by choosing an option.
+     * `chosenOptionUid` must be the uid of an option added via `addOption()`.
+     */
+    resolveDecision(decisionUid: string, chosenOptionUid: string, opts?: {
+        summary?: string;
+        agent_id?: string;
+    }): Promise<unknown>;
     procedure(req: ProcedureRequest): Promise<unknown>;
     risk(req: RiskRequest): Promise<unknown>;
     session(req: SessionRequest): Promise<unknown>;
@@ -358,10 +488,18 @@ declare class MindGraph {
     plan(req: PlanRequest): Promise<unknown>;
     governance(req: GovernanceRequest): Promise<unknown>;
     execution(req: ExecutionRequest): Promise<unknown>;
-    retrieve(req: RetrieveRequest): Promise<unknown>;
+    /** Returns an array of results. Shape varies by action. */
+    retrieve(req: RetrieveRequest): Promise<unknown[]>;
     traverse(req: TraverseRequest): Promise<unknown>;
     evolve(req: EvolveRequest): Promise<unknown>;
     getNode(uid: string): Promise<GraphNode>;
+    /**
+     * 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.
+     */
     addNode(body: {
         label: string;
         node_type?: string;
@@ -376,16 +514,50 @@ declare class MindGraph {
         agent_id?: string;
     }): Promise<GraphNode>;
     deleteNode(uid: string): Promise<void>;
+    getNodeHistory(uid: string): Promise<unknown[]>;
+    getNodeAtVersion(uid: string, version: number): Promise<GraphNode>;
     addLink(body: {
         from_uid: string;
         to_uid: string;
         edge_type: string;
         agent_id?: string;
     }): Promise<unknown>;
+    /**
+     * 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.
+     */
+    addEdge(body: {
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+        weight?: number;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    updateEdge(uid: string, body: {
+        weight?: number;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    deleteEdge(uid: string): Promise<void>;
+    getEdgeHistory(uid: string): Promise<unknown[]>;
+    /**
+     * 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.
+     */
     getEdges(params: {
         from_uid?: string;
         to_uid?: string;
     }): Promise<GraphEdge[]>;
+    getEdgeBetween(params: {
+        from_uid: string;
+        to_uid: string;
+        edge_type?: string;
+    }): Promise<GraphEdge[]>;
     search(query: string, opts?: {
         node_type?: string;
         layer?: string;
@@ -397,18 +569,79 @@ declare class MindGraph {
         node_types?: string[];
         layer?: string;
     }): Promise<SearchResult[]>;
+    getNodes(params?: {
+        node_type?: string;
+        layer?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    getAgentNodes(agentId: string): Promise<GraphNode[]>;
+    batch(req: BatchRequest): Promise<unknown>;
+    configureEmbeddings(body: {
+        model: string;
+        dimensions: number;
+        distance_metric?: string;
+    }): Promise<unknown>;
+    embeddingSearch(body: {
+        vector: number[];
+        k?: number;
+        node_types?: string[];
+        threshold?: number;
+    }): Promise<unknown>;
+    embeddingSearchText(body: {
+        text: string;
+        k?: number;
+        node_types?: string[];
+        threshold?: number;
+    }): Promise<unknown>;
+    getEmbedding(uid: string): Promise<unknown>;
+    setEmbedding(uid: string, vector: number[]): Promise<void>;
+    deleteEmbedding(uid: string): Promise<void>;
+    mergeEntities(body: {
+        keep_uid: string;
+        merge_uid: string;
+        agent_id?: string;
+    }): Promise<unknown>;
+    addAlias(body: {
+        text: string;
+        canonical_uid: string;
+        score?: number;
+    }): Promise<unknown>;
+    getAliases(uid: string): Promise<unknown>;
+    resolveAlias(text: string): Promise<unknown>;
+    exportGraph(): Promise<unknown>;
+    importGraph(data: unknown): Promise<unknown>;
+    decay(req: DecayRequest): Promise<unknown>;
+    purge(req?: PurgeRequest): Promise<unknown>;
     reasoningChain(uid: string, maxDepth?: number): Promise<PathStep[]>;
     neighborhood(uid: string, maxDepth?: number): Promise<PathStep[]>;
+    subgraph(uid: string, opts?: {
+        max_depth?: number;
+        direction?: "outgoing" | "incoming" | "both";
+        edge_types?: string[];
+        weight_threshold?: number;
+    }): Promise<{
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    }>;
     tombstone(uid: string, reason?: string, agentId?: string): Promise<unknown>;
     restore(uid: string, agentId?: string): Promise<unknown>;
-    signup(email: string, password: string): Promise<unknown>;
-    login(email: string, password: string): Promise<unknown>;
-    createApiKey(name?: string): Promise<ApiKeyResponse>;
-    listApiKeys(): Promise<{
-        api_keys: unknown[];
-    }>;
-    revokeApiKey(id: string): Promise<void>;
-    getUsage(): Promise<unknown>;
+    getGoals(): Promise<GraphNode[]>;
+    getOpenDecisions(): Promise<GraphNode[]>;
+    getOpenQuestions(): Promise<GraphNode[]>;
+    getWeakClaims(): Promise<GraphNode[]>;
+    getContradictions(): Promise<unknown[]>;
+    getPendingApprovals(): Promise<GraphNode[]>;
+    ingestChunk(req: IngestChunkRequest): Promise<IngestChunkResponse>;
+    ingestDocument(req: IngestDocumentRequest): Promise<IngestDocumentResponse>;
+    ingestSession(req: IngestSessionRequest): Promise<IngestDocumentResponse>;
+    retrieveContext(req: RetrieveContextRequest): Promise<RetrieveContextResponse>;
+    listJobs(): Promise<Job[]>;
+    getJob(id: string): Promise<Job>;
+    cancelJob(id: string): Promise<unknown>;
+    cleanupOrphans(): Promise<unknown>;
+    embedAll(): Promise<unknown>;
+    clearGraph(): Promise<ClearResponse>;
 }
 
-export { type ApiKeyResponse, type ArgumentRequest, type CommitmentRequest, type CreateApiKeyRequest, type CreateOrgRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestRequest, type InquiryRequest, type LoginRequest, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type PathStep, type PlanRequest, type ProcedureRequest, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type SignupRequest, type StructureRequest, type TraverseRequest };
+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 };

package/dist/index.js

@@ -93,8 +93,8 @@ 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);
@@ -108,6 +108,29 @@ var MindGraph = class {
       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
+    });
+  }
   // ---- Epistemic Layer ----
   async argue(req) {
     return this.post("/epistemic/argument", req);
@@ -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);
@@ -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: