@raisindb/client 0.5.3 → 0.5.4

package/dist/index.mjs

@@ -3,13 +3,13 @@ import {
   useConversation,
   useConversationList,
   useFlow
-} from "./chunk-QJKYNLT4.mjs";
+} from "./chunk-IFV4ECHC.mjs";
 import {
   RAISIN_CONTEXT_KEY,
   createConversationAdapter,
   createConversationListAdapter,
   createFlowAdapter
-} from "./chunk-P44XWTPA.mjs";
+} from "./chunk-ZUUSBLVP.mjs";
 import {
   FlowClient,
   RaisinAbortError,
@@ -20,10 +20,10 @@ import {
   RaisinTimeoutError,
   SSEClient,
   classifyHttpError
-} from "./chunk-Q4IBPW2W.mjs";
+} from "./chunk-AULHRX5C.mjs";
 import {
   createRaisinVue
-} from "./chunk-B6EFDYFS.mjs";
+} from "./chunk-VMUT6PIO.mjs";
 import {
   createAuthAdapter,
   createConnectionAdapter,
@@ -48,7 +48,7 @@ import {
   normalizeHomePath,
   projectPlansFromMessages,
   setLogLevel
-} from "./chunk-3KMOXRTK.mjs";
+} from "./chunk-765DLJMZ.mjs";
 
 // src/client.ts
 import { EventEmitter as EventEmitter2 } from "events";
@@ -3064,6 +3064,104 @@ var HttpFunctionsApi = class {
   }
 };
 
+// src/search-api.ts
+var ASK_FUNCTION = "ask";
+var DEFAULT_LIMIT = 8;
+var MAX_LIMIT = 50;
+var SearchApi = class {
+  constructor(runSql, runFunction) {
+    this.runSql = runSql;
+    this.runFunction = runFunction;
+  }
+  /**
+   * Find the passages that match a query, by meaning and by keyword at once.
+   *
+   * No model is involved, so this is the call for a search box, a "related
+   * content" list, or anything assembling its own context.
+   */
+  async search(query, options) {
+    if (!query || !query.trim()) {
+      throw new Error("search(query) requires a non-empty query");
+    }
+    if (!options || !options.workspaces || !options.workspaces.trim()) {
+      throw new Error(
+        "search() requires `workspaces` \u2014 name a workspace, a list, a glob, or 'ALL READABLE'. An unscoped search on a public site is how draft content reaches a visitor."
+      );
+    }
+    const limit = Math.min(
+      Math.max(Math.floor(options.limit ?? DEFAULT_LIMIT), 1),
+      MAX_LIMIT
+    );
+    const distance = Number.isFinite(options.maxDistance) ? `, max_distance => ${Number(options.maxDistance)}` : "";
+    const sql = `
+      SELECT node_id, path, name, score, chunk_index, chunk_text, chunk_text_source
+      FROM HYBRID_SEARCH($1, ${limit},
+                         workspaces => $2,
+                         granularity => 'chunk'${distance})
+    `;
+    const result = await this.runSql(sql, [query.trim(), options.workspaces.trim()]);
+    const rows = result?.rows ?? [];
+    return rows.map((row) => ({
+      path: String(row.path ?? ""),
+      nodeId: String(row.node_id ?? ""),
+      name: String(row.name ?? ""),
+      // `0` is a real chunk index — a document that was never split — so it
+      // must not be collapsed into "missing" by a falsy check.
+      chunkIndex: row.chunk_index == null ? 0 : Number(row.chunk_index),
+      text: String(row.chunk_text ?? ""),
+      textIsExact: row.chunk_text_source === "exact",
+      score: Number(row.score ?? 0)
+    })).filter((passage) => passage.text.length > 0);
+  }
+  /**
+   * Answer a question from the stored content, with citations.
+   *
+   * Retrieves, judges whether what came back answers the question, rewrites the
+   * query once if it does not, and answers from those passages only.
+   */
+  async ask(question, options) {
+    if (!question || !question.trim()) {
+      throw new Error("ask(question) requires a non-empty question");
+    }
+    if (!options || !options.workspaces || !options.workspaces.trim()) {
+      throw new Error(
+        "ask() requires `workspaces` \u2014 name a workspace, a list, a glob, or 'ALL READABLE'. An answer is quoted back to whoever asked, so the corpus it may be drawn from is stated, never assumed."
+      );
+    }
+    const raw = await this.runFunction(ASK_FUNCTION, {
+      question: question.trim(),
+      workspaces: options.workspaces.trim(),
+      limit: options.limit,
+      model: options.model,
+      use_graph: options.useGraph
+    });
+    if (raw && typeof raw === "object" && "error" in raw && raw.error) {
+      throw new Error(`ask failed: ${String(raw.error)}`);
+    }
+    const citations = Array.isArray(raw?.citations) ? raw.citations : [];
+    return {
+      answer: String(raw?.answer ?? ""),
+      // Absent counts as NOT grounded. This flag is the one a caller branches
+      // on before showing an answer, so an unexpected response shape must fail
+      // towards "we found nothing", never towards "trust this".
+      grounded: raw?.grounded === true,
+      citations: citations.map((c) => ({
+        marker: Number(c.marker ?? 0),
+        path: String(c.path ?? ""),
+        nodeId: String(c.node_id ?? ""),
+        name: String(c.title ?? ""),
+        chunkIndex: c.chunk_index == null ? 0 : Number(c.chunk_index),
+        textIsExact: c.text_is_exact === true
+      })),
+      attempts: Array.isArray(raw?.attempts) ? raw.attempts.map((a) => ({
+        query: String(a.query ?? ""),
+        passages: Number(a.passages ?? 0)
+      })) : [],
+      model: String(raw?.model ?? "")
+    };
+  }
+};
+
 // src/conversations.ts
 var DEFAULT_SEND_MESSAGE_INACTIVITY_TIMEOUT_MS = 12e4;
 var ConversationManager = class {
@@ -3571,7 +3669,17 @@ var ConversationManager = class {
         tasks.push({
           id: row.id,
           title: row.properties?.title ?? row.name,
-          status: row.properties?.status ?? "pending"
+          status: row.properties?.status ?? "pending",
+          delegation: row.properties?.delegation_id ? {
+            id: row.properties.delegation_id,
+            status: row.properties.delegation_status ?? "unknown",
+            agentRef: row.properties.delegated_agent_ref?.["raisin:path"] ?? row.properties.delegated_agent_ref?.["raisin:ref"] ?? (typeof row.properties.delegated_agent_ref === "string" ? row.properties.delegated_agent_ref : void 0),
+            flowInstanceId: row.properties.delegation_flow_instance_id ?? void 0,
+            branch: row.properties.delegation_branch ?? void 0,
+            baseBranch: row.properties.delegation_base_branch ?? void 0,
+            result: row.properties.delegation_result,
+            error: row.properties.delegation_error ?? void 0
+          } : void 0
         });
         tasksByPlan.set(planPath, tasks);
         continue;
@@ -4185,6 +4293,73 @@ var Database = class _Database {
     }
     return this._functionsApi;
   }
+  /**
+   * The retrieval implementation behind {@link search} and {@link ask}.
+   *
+   * Private: callers get the two verbs, not the object, so how retrieval is
+   * served stays ours to change.
+   */
+  searchApi() {
+    if (!this._searchApi) {
+      this._searchApi = new SearchApi(
+        (sql, params) => this.executeSql(sql, params),
+        async (name, input) => {
+          const run = await this.functions().invoke(name, input, {
+            waitForResult: true
+          });
+          return run?.result ?? run;
+        }
+      );
+    }
+    return this._searchApi;
+  }
+  /**
+   * Find the passages matching a query, by meaning and by keyword at once.
+   *
+   * No model is involved — this is the call for a search box or for assembling
+   * your own context. Returns one entry per PASSAGE, so several may come from
+   * one document.
+   *
+   * @example
+   * ```typescript
+   * const passages = await db.search('how much notice to terminate', {
+   *   workspaces: 'stories',
+   * });
+   * passages[0].text;        // the passage itself
+   * passages[0].chunkIndex;  // where in the document it came from
+   * ```
+   */
+  async search(query, options) {
+    return this.searchApi().search(query, options);
+  }
+  /**
+   * Answer a question from the stored content, with citations.
+   *
+   * Retrieves, judges whether what came back answers the question, rewrites the
+   * query once if it does not, and answers from those passages only. Check
+   * `grounded` before showing the answer: when it is false nothing relevant was
+   * found and the model was never asked.
+   *
+   * `workspaces` is required, the same as on {@link search}: an answer is
+   * quoted back to whoever asked, so the corpus it may be drawn from is stated
+   * rather than assumed. One name, a comma-separated list, a glob, or
+   * `'ALL READABLE'`.
+   *
+   * A method rather than `functions().invoke('ask', ...)` on purpose — see the
+   * note at the top of `search-api.ts`. `invoke` is the escape hatch for
+   * functions YOU wrote.
+   *
+   * @example
+   * ```typescript
+   * const { answer, citations, grounded } = await db.ask(
+   *   'How much notice do we have to give?',
+   *   { workspaces: 'stories, handbook' },   // one name, a list, a glob, or 'ALL READABLE'
+   * );
+   * ```
+   */
+  async ask(question, options) {
+    return this.searchApi().ask(question, options);
+  }
   /**
    * Get a pre-configured ConversationManager for managing conversations.
    *