mindgraph 0.8.0 → 0.10.0

package/dist/index.d.mts

@@ -81,12 +81,20 @@ interface EnrichedSearchResponse {
     chunks: SearchChunk[];
 }
 interface PathStep {
-    uid: string;
+    node_uid: string;
     label: string;
     node_type: string;
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
+    /** Min-plus cost of the returned BFS path from the start node
+     * (sum of -ln(weight), weights clamped to (1e-9, 1]); cost of the path
+     * the traversal returned, not the cheapest path. 0 at the start node. */
+    path_cost?: number;
+    /** Product of edge confidences along the returned BFS path (clamped to
+     * (1e-9, 1]); a ranking signal, not a calibrated probability. 1 at the
+     * start node. */
+    path_confidence?: number;
 }
 interface PersonProps {
     canonical_name: string;
@@ -395,13 +403,19 @@ interface RetrieveRequest {
     created_before?: number;
 }
 interface TraverseRequest {
-    action: "chain" | "neighborhood" | "path" | "subgraph";
+    action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
     start_uid: string;
     end_uid?: string;
     max_depth?: number;
     direction?: "outgoing" | "incoming" | "both";
     edge_types?: string[];
     weight_threshold?: number;
+    /** `top_k_paths` only: number of cheapest paths to return (default 3, cap 25). */
+    k?: number;
+    /** `top_k_paths` only: max edges per path (default 8, cap 16). */
+    max_hops?: number;
+    /** `top_k_paths` only: prune paths whose min-plus cost exceeds this. */
+    max_cost?: number;
 }
 interface EvolveRequest {
     action: "update" | "tombstone" | "restore" | "decay" | "history" | "snapshot" | "tombstone_edge" | "restore_edge" | "tombstone_cascade";
@@ -503,6 +517,11 @@ interface RetrieveContextRequest {
     layer?: string;
     include_graph?: boolean;
     min_similarity?: number;
+    /**
+     * M3 as-of (valid time): ISO-8601 date to judge validity windows against.
+     * Windowed nodes then carry `valid_at_time` instead of `currently_valid`.
+     */
+    valid_at?: string;
 }
 interface ArticleResult {
     uid: string;
@@ -577,6 +596,18 @@ interface RetrieveContextResponse {
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
+            /** This node has been replaced by a newer value (Supersedes edge). */
+            superseded?: boolean;
+            /** UID of the node that superseded this one. */
+            superseded_by?: string;
+            /**
+             * Whether the node's valid-time window (`props.valid_from`/`valid_until`)
+             * contains today. Absent when the node carries no window — unknown is
+             * not false.
+             */
+            currently_valid?: boolean;
+            /** As-of variant of `currently_valid` when the request set `valid_at`. */
+            valid_at_time?: boolean;
         })[];
         edges: Record<string, unknown>[];
     };
@@ -1042,6 +1073,16 @@ declare class MindGraph {
         status: string;
     }>;
     stats(): Promise<Record<string, unknown>>;
+    /**
+     * Schema fill-rate report (measure-first tiering): per live node type,
+     * the exact live count and sampled per-field fill rates; near-empty
+     * fields flagged below 5%. `sample` caps per-type sampling (default
+     * 1000); `layer` restricts (e.g. "epistemic").
+     */
+    schemaFillStats(params?: {
+        sample?: number;
+        layer?: string;
+    }): Promise<unknown>;
     capture(req: CaptureRequest): Promise<unknown>;
     entity(req: EntityRequest): Promise<unknown>;
     /** Convenience: create or find an entity by label. */
@@ -1296,6 +1337,14 @@ declare class MindGraph {
     getAliases(uid: string): Promise<unknown>;
     resolveAlias(text: string): Promise<unknown>;
     exportGraph(): Promise<unknown>;
+    /**
+     * Export one document's extraction provenance as JSON-LD: PROV-O
+     * entities/agents, CiTO relations between extracted claims, and the
+     * citation anchors as W3C Web Annotations (TextQuoteSelector +
+     * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+     * flagged via `mg:offsetUnit`).
+     */
+    exportProvenance(documentUid: string): Promise<unknown>;
     importGraph(data: unknown): Promise<unknown>;
     decay(req: DecayRequest): Promise<unknown>;
     purge(req?: PurgeRequest): Promise<unknown>;

package/dist/index.d.ts

@@ -81,12 +81,20 @@ interface EnrichedSearchResponse {
     chunks: SearchChunk[];
 }
 interface PathStep {
-    uid: string;
+    node_uid: string;
     label: string;
     node_type: string;
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
+    /** Min-plus cost of the returned BFS path from the start node
+     * (sum of -ln(weight), weights clamped to (1e-9, 1]); cost of the path
+     * the traversal returned, not the cheapest path. 0 at the start node. */
+    path_cost?: number;
+    /** Product of edge confidences along the returned BFS path (clamped to
+     * (1e-9, 1]); a ranking signal, not a calibrated probability. 1 at the
+     * start node. */
+    path_confidence?: number;
 }
 interface PersonProps {
     canonical_name: string;
@@ -395,13 +403,19 @@ interface RetrieveRequest {
     created_before?: number;
 }
 interface TraverseRequest {
-    action: "chain" | "neighborhood" | "path" | "subgraph";
+    action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
     start_uid: string;
     end_uid?: string;
     max_depth?: number;
     direction?: "outgoing" | "incoming" | "both";
     edge_types?: string[];
     weight_threshold?: number;
+    /** `top_k_paths` only: number of cheapest paths to return (default 3, cap 25). */
+    k?: number;
+    /** `top_k_paths` only: max edges per path (default 8, cap 16). */
+    max_hops?: number;
+    /** `top_k_paths` only: prune paths whose min-plus cost exceeds this. */
+    max_cost?: number;
 }
 interface EvolveRequest {
     action: "update" | "tombstone" | "restore" | "decay" | "history" | "snapshot" | "tombstone_edge" | "restore_edge" | "tombstone_cascade";
@@ -503,6 +517,11 @@ interface RetrieveContextRequest {
     layer?: string;
     include_graph?: boolean;
     min_similarity?: number;
+    /**
+     * M3 as-of (valid time): ISO-8601 date to judge validity windows against.
+     * Windowed nodes then carry `valid_at_time` instead of `currently_valid`.
+     */
+    valid_at?: string;
 }
 interface ArticleResult {
     uid: string;
@@ -577,6 +596,18 @@ interface RetrieveContextResponse {
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
+            /** This node has been replaced by a newer value (Supersedes edge). */
+            superseded?: boolean;
+            /** UID of the node that superseded this one. */
+            superseded_by?: string;
+            /**
+             * Whether the node's valid-time window (`props.valid_from`/`valid_until`)
+             * contains today. Absent when the node carries no window — unknown is
+             * not false.
+             */
+            currently_valid?: boolean;
+            /** As-of variant of `currently_valid` when the request set `valid_at`. */
+            valid_at_time?: boolean;
         })[];
         edges: Record<string, unknown>[];
     };
@@ -1042,6 +1073,16 @@ declare class MindGraph {
         status: string;
     }>;
     stats(): Promise<Record<string, unknown>>;
+    /**
+     * Schema fill-rate report (measure-first tiering): per live node type,
+     * the exact live count and sampled per-field fill rates; near-empty
+     * fields flagged below 5%. `sample` caps per-type sampling (default
+     * 1000); `layer` restricts (e.g. "epistemic").
+     */
+    schemaFillStats(params?: {
+        sample?: number;
+        layer?: string;
+    }): Promise<unknown>;
     capture(req: CaptureRequest): Promise<unknown>;
     entity(req: EntityRequest): Promise<unknown>;
     /** Convenience: create or find an entity by label. */
@@ -1296,6 +1337,14 @@ declare class MindGraph {
     getAliases(uid: string): Promise<unknown>;
     resolveAlias(text: string): Promise<unknown>;
     exportGraph(): Promise<unknown>;
+    /**
+     * Export one document's extraction provenance as JSON-LD: PROV-O
+     * entities/agents, CiTO relations between extracted claims, and the
+     * citation anchors as W3C Web Annotations (TextQuoteSelector +
+     * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+     * flagged via `mg:offsetUnit`).
+     */
+    exportProvenance(documentUid: string): Promise<unknown>;
     importGraph(data: unknown): Promise<unknown>;
     decay(req: DecayRequest): Promise<unknown>;
     purge(req?: PurgeRequest): Promise<unknown>;

package/dist/index.js

@@ -108,6 +108,19 @@ var MindGraph = class {
   async stats() {
     return this.get("/stats");
   }
+  /**
+   * Schema fill-rate report (measure-first tiering): per live node type,
+   * the exact live count and sampled per-field fill rates; near-empty
+   * fields flagged below 5%. `sample` caps per-type sampling (default
+   * 1000); `layer` restricts (e.g. "epistemic").
+   */
+  async schemaFillStats(params) {
+    const q = new URLSearchParams();
+    if (params?.sample !== void 0) q.set("sample", String(params.sample));
+    if (params?.layer) q.set("layer", params.layer);
+    const qs = q.toString();
+    return this.get(`/stats/schema-fill${qs ? `?${qs}` : ""}`);
+  }
   // ---- Reality Layer ----
   async capture(req) {
     return this.post("/reality/capture", req);
@@ -469,6 +482,18 @@ var MindGraph = class {
   async exportGraph() {
     return this.get("/export");
   }
+  /**
+   * Export one document's extraction provenance as JSON-LD: PROV-O
+   * entities/agents, CiTO relations between extracted claims, and the
+   * citation anchors as W3C Web Annotations (TextQuoteSelector +
+   * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+   * flagged via `mg:offsetUnit`).
+   */
+  async exportProvenance(documentUid) {
+    return this.get(
+      `/export/prov?document_uid=${encodeURIComponent(documentUid)}`
+    );
+  }
   async importGraph(data) {
     return this.post("/import", data);
   }

package/dist/index.mjs

@@ -81,6 +81,19 @@ var MindGraph = class {
   async stats() {
     return this.get("/stats");
   }
+  /**
+   * Schema fill-rate report (measure-first tiering): per live node type,
+   * the exact live count and sampled per-field fill rates; near-empty
+   * fields flagged below 5%. `sample` caps per-type sampling (default
+   * 1000); `layer` restricts (e.g. "epistemic").
+   */
+  async schemaFillStats(params) {
+    const q = new URLSearchParams();
+    if (params?.sample !== void 0) q.set("sample", String(params.sample));
+    if (params?.layer) q.set("layer", params.layer);
+    const qs = q.toString();
+    return this.get(`/stats/schema-fill${qs ? `?${qs}` : ""}`);
+  }
   // ---- Reality Layer ----
   async capture(req) {
     return this.post("/reality/capture", req);
@@ -442,6 +455,18 @@ var MindGraph = class {
   async exportGraph() {
     return this.get("/export");
   }
+  /**
+   * Export one document's extraction provenance as JSON-LD: PROV-O
+   * entities/agents, CiTO relations between extracted claims, and the
+   * citation anchors as W3C Web Annotations (TextQuoteSelector +
+   * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+   * flagged via `mg:offsetUnit`).
+   */
+  async exportProvenance(documentUid) {
+    return this.get(
+      `/export/prov?document_uid=${encodeURIComponent(documentUid)}`
+    );
+  }
   async importGraph(data) {
     return this.post("/import", data);
   }

package/package.json

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