mindgraph 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -30,6 +30,29 @@ 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 `/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 +352,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 +1067,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;

package/dist/index.d.ts

@@ -30,6 +30,29 @@ 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 `/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 +352,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 +1067,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;

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",

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",

package/package.json

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