mindgraph 0.5.0 → 0.6.1

package/dist/index.d.mts

@@ -30,6 +30,44 @@ interface SearchResult {
     node_type: string;
     score: number;
 }
+/**
+ * One retrieval leg's contribution to a fused hybrid result — the
+ * "why retrieved" detail. The fused score reconstructs exactly as
+ * `Σ 1/(60 + rank)` over a result's legs.
+ */
+interface LegContribution {
+    /** Which leg surfaced the result: `"fts"` (keyword/BM25) or `"vec"` (vector). */
+    leg: string;
+    /** 1-based within-leg rank the fusion used. */
+    rank: number;
+    /**
+     * The leg's raw score (BM25 relevance for `fts`, cosine similarity for
+     * `vec`). Not comparable across legs — RRF fuses by rank, not score.
+     */
+    score: number;
+}
+/** A suspected duplicate pair awaiting human review (pending PossibleDuplicate edge). */
+interface MergeCandidate {
+    edge_uid: string;
+    node_a_uid: string;
+    node_a_label: string;
+    node_a_summary: string;
+    node_b_uid: string;
+    node_b_label: string;
+    node_b_summary: string;
+    node_type: string;
+    /** Similarity score that triggered the candidate (e.g. cosine), if known. */
+    similarity: number | null;
+    /** How the candidate was found: "exact" | "fuzzy" | "semantic" | "llm". */
+    method: string | null;
+}
+/** A `/retrieve` hybrid result: the full node plus the fused RRF score. */
+interface HybridSearchResult {
+    node: GraphNode;
+    score: number;
+    /** Per-leg contributions; present only when the request set `explain: true`. */
+    legs?: LegContribution[];
+}
 interface SearchChunk {
     chunk_uid: string;
     content: string;
@@ -329,6 +367,12 @@ interface RetrieveRequest {
     salience_min?: number;
     limit?: number;
     offset?: number;
+    /**
+     * Hybrid action only: attach per-leg contributions (`legs`) to each
+     * result — the "why retrieved" detail. Requires server ≥ 1.2.0; older
+     * servers ignore the field.
+     */
+    explain?: boolean;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph";
@@ -1038,12 +1082,17 @@ declare class MindGraph {
         include_edges?: boolean;
         include_chunks?: boolean;
     }): Promise<SearchResult[] | EnrichedSearchResponse>;
-    /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+    /**
+     * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+     * `explain: true` to get per-leg contributions (`legs`) on each result —
+     * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+     */
     hybridSearch(query: string, opts?: {
         k?: number;
         node_types?: string[];
         layer?: string;
-    }): Promise<SearchResult[]>;
+        explain?: boolean;
+    }): Promise<HybridSearchResult[]>;
     getNodes(params?: {
         node_type?: string;
         layer?: string;
@@ -1110,6 +1159,12 @@ declare class MindGraph {
     getOpenQuestions(): Promise<GraphNode[]>;
     getWeakClaims(): Promise<GraphNode[]>;
     getContradictions(): Promise<unknown[]>;
+    /**
+     * Pending merge candidates: suspected duplicate pairs recorded by the dedup
+     * pipeline's ambiguous zone as PossibleDuplicate edges, awaiting a human
+     * merge/dismiss decision (server >= 1.3).
+     */
+    getMergeCandidates(): Promise<MergeCandidate[]>;
     getPendingApprovals(): Promise<GraphNode[]>;
     ingestChunk(req: IngestChunkRequest): Promise<IngestChunkResponse>;
     ingestDocument(req: IngestDocumentRequest): Promise<IngestDocumentResponse>;

package/dist/index.d.ts

@@ -30,6 +30,44 @@ interface SearchResult {
     node_type: string;
     score: number;
 }
+/**
+ * One retrieval leg's contribution to a fused hybrid result — the
+ * "why retrieved" detail. The fused score reconstructs exactly as
+ * `Σ 1/(60 + rank)` over a result's legs.
+ */
+interface LegContribution {
+    /** Which leg surfaced the result: `"fts"` (keyword/BM25) or `"vec"` (vector). */
+    leg: string;
+    /** 1-based within-leg rank the fusion used. */
+    rank: number;
+    /**
+     * The leg's raw score (BM25 relevance for `fts`, cosine similarity for
+     * `vec`). Not comparable across legs — RRF fuses by rank, not score.
+     */
+    score: number;
+}
+/** A suspected duplicate pair awaiting human review (pending PossibleDuplicate edge). */
+interface MergeCandidate {
+    edge_uid: string;
+    node_a_uid: string;
+    node_a_label: string;
+    node_a_summary: string;
+    node_b_uid: string;
+    node_b_label: string;
+    node_b_summary: string;
+    node_type: string;
+    /** Similarity score that triggered the candidate (e.g. cosine), if known. */
+    similarity: number | null;
+    /** How the candidate was found: "exact" | "fuzzy" | "semantic" | "llm". */
+    method: string | null;
+}
+/** A `/retrieve` hybrid result: the full node plus the fused RRF score. */
+interface HybridSearchResult {
+    node: GraphNode;
+    score: number;
+    /** Per-leg contributions; present only when the request set `explain: true`. */
+    legs?: LegContribution[];
+}
 interface SearchChunk {
     chunk_uid: string;
     content: string;
@@ -329,6 +367,12 @@ interface RetrieveRequest {
     salience_min?: number;
     limit?: number;
     offset?: number;
+    /**
+     * Hybrid action only: attach per-leg contributions (`legs`) to each
+     * result — the "why retrieved" detail. Requires server ≥ 1.2.0; older
+     * servers ignore the field.
+     */
+    explain?: boolean;
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph";
@@ -1038,12 +1082,17 @@ declare class MindGraph {
         include_edges?: boolean;
         include_chunks?: boolean;
     }): Promise<SearchResult[] | EnrichedSearchResponse>;
-    /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+    /**
+     * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+     * `explain: true` to get per-leg contributions (`legs`) on each result —
+     * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+     */
     hybridSearch(query: string, opts?: {
         k?: number;
         node_types?: string[];
         layer?: string;
-    }): Promise<SearchResult[]>;
+        explain?: boolean;
+    }): Promise<HybridSearchResult[]>;
     getNodes(params?: {
         node_type?: string;
         layer?: string;
@@ -1110,6 +1159,12 @@ declare class MindGraph {
     getOpenQuestions(): Promise<GraphNode[]>;
     getWeakClaims(): Promise<GraphNode[]>;
     getContradictions(): Promise<unknown[]>;
+    /**
+     * Pending merge candidates: suspected duplicate pairs recorded by the dedup
+     * pipeline's ambiguous zone as PossibleDuplicate edges, awaiting a human
+     * merge/dismiss decision (server >= 1.3).
+     */
+    getMergeCandidates(): Promise<MergeCandidate[]>;
     getPendingApprovals(): Promise<GraphNode[]>;
     ingestChunk(req: IngestChunkRequest): Promise<IngestChunkResponse>;
     ingestDocument(req: IngestDocumentRequest): Promise<IngestDocumentResponse>;

package/dist/index.js

@@ -397,7 +397,11 @@ var MindGraph = class {
   async search(query, opts) {
     return this.post("/search", { query, ...opts });
   }
-  /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+  /**
+   * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+   * `explain: true` to get per-leg contributions (`legs`) on each result —
+   * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+   */
   async hybridSearch(query, opts) {
     return this.post("/retrieve", {
       action: "hybrid",
@@ -527,6 +531,14 @@ var MindGraph = class {
   async getContradictions() {
     return this.get("/contradictions");
   }
+  /**
+   * Pending merge candidates: suspected duplicate pairs recorded by the dedup
+   * pipeline's ambiguous zone as PossibleDuplicate edges, awaiting a human
+   * merge/dismiss decision (server >= 1.3).
+   */
+  async getMergeCandidates() {
+    return this.post("/retrieve", { action: "merge_candidates" });
+  }
   async getPendingApprovals() {
     return this.get("/approvals/pending");
   }

package/dist/index.mjs

@@ -370,7 +370,11 @@ var MindGraph = class {
   async search(query, opts) {
     return this.post("/search", { query, ...opts });
   }
-  /** Hybrid BM25 + vector search with reciprocal rank fusion. */
+  /**
+   * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+   * `explain: true` to get per-leg contributions (`legs`) on each result —
+   * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+   */
   async hybridSearch(query, opts) {
     return this.post("/retrieve", {
       action: "hybrid",
@@ -500,6 +504,14 @@ var MindGraph = class {
   async getContradictions() {
     return this.get("/contradictions");
   }
+  /**
+   * Pending merge candidates: suspected duplicate pairs recorded by the dedup
+   * pipeline's ambiguous zone as PossibleDuplicate edges, awaiting a human
+   * merge/dismiss decision (server >= 1.3).
+   */
+  async getMergeCandidates() {
+    return this.post("/retrieve", { action: "merge_candidates" });
+  }
   async getPendingApprovals() {
     return this.get("/approvals/pending");
   }

package/package.json

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