@promptev/context-engine 0.0.1 → 0.0.3

package/dist/index.d.cts

@@ -1,30 +1,17 @@
 import { Pool } from 'pg';
-import { C as ContextEngineConfig, L as LLMConfig, E as ExtractionConfig, R as RerankerConfig } from './config-CNnASw5X.cjs';
-export { a as ContextEngineConfigInit, b as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-CNnASw5X.cjs';
+import { C as ContextEngineConfig, L as LLMConfig, E as ExtractionConfig, R as RerankerConfig } from './config-C5RZ00W6.cjs';
+export { a as ContextEngineConfigInit, b as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-C5RZ00W6.cjs';
 import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent, I as IngestReport } from './redaction-BqD_DEUQ.cjs';
 export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitProgress, f as emitToolCall, g as emitUsage, h as graphUnits, u as unitsForFile } from './redaction-BqD_DEUQ.cjs';
-import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-DU1JRno5.cjs';
-export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-DU1JRno5.cjs';
-import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-D8g6Wyvb.cjs';
-export { c as ToolKind, d as configSchema } from './governance-D8g6Wyvb.cjs';
-export { createMcpApp } from './mcp.cjs';
+import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-Dvpq2xAC.cjs';
+export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-Dvpq2xAC.cjs';
+import { P as Principals, U as Unset, S as ScopeInput, K as KnowledgeComputeFn, T as Trusted } from './mcp-BKSmxayM.cjs';
+export { a as KNOWLEDGE_ACTIONS, b as KNOWLEDGE_TOOL_DESCRIPTION, c as KnowledgeAction, d as Scope, e as TRUSTED, f as UNSCOPED, g as UNSET, h as callKnowledgeTool, i as createMcpApp, k as knowledgeToolDefinition, n as narrowToCeiling, r as resolvePrincipals, j as resolveScope } from './mcp-BKSmxayM.cjs';
+import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-P9pRb4Ol.cjs';
+export { c as ToolKind, d as configSchema } from './governance-P9pRb4Ol.cjs';
 import 'zod';
 import 'node:http';
 
-/**
- * Sentinels distinguishing omitted arguments from real values, including null.
- *
- * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
- * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
- * `if (principals)` does not treat a trusted caller as anonymous.
- */
-declare const UNSET: unique symbol;
-type Unset = typeof UNSET;
-declare const TRUSTED: unique symbol;
-type Trusted = typeof TRUSTED;
-type Principals = string[] | null | typeof TRUSTED | undefined;
-declare function resolvePrincipals(value: Principals, method: string): string[] | null;
-
 type Mode$1 = "hybrid" | "graph";
 interface IngestRequest {
     content?: Buffer | null;
@@ -79,17 +66,11 @@ declare function getDocumentText(documentId: string, opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<string>;
-/**
- * Page through documents in scope, newest first.
- *
- * `redaction` masks `documentType` — unconstrained free text an LLM wrote
- * after reading the document body. `name`/`description` remain
- * intentionally unmasked: both are CALLER-set at ingest time, not text the
- * pipeline derived from the document body.
- */
 declare function listDocuments(opts: {
     pool: Pool;
     sourceId?: string | null;
+    /** OR-of-many, ONE keyset-paged query across all of them; with `sourceId`, their union. */
+    sourceIds?: string[] | null;
     principals?: string[] | null;
     cursor?: unknown;
     limit?: number;
@@ -129,6 +110,13 @@ declare function queryStructured(question: string, opts: {
  * call, no sandbox run — when the flag is `false`. That flag, not the
  * isolate, is the actual security boundary.
  *
+ * Only the document half lives here: fetch the in-scope tabular documents
+ * and parse their stored text into `{sheet: rows[]}`. Everything after that
+ * — the guards, both redaction surfaces below, the prompt → code → sandbox
+ * path and the swept result — is `computeOverFrames`, the seam a host calls
+ * when it already holds the frames and has no document to point at; this
+ * function builds its frames from documents and delegates.
+ *
  * `config.redaction` is applied TWICE:
  * 1. Each document's raw `.text` is masked BEFORE it is parsed into a
  *    table, so the data the LLM-authored code runs against is built from
@@ -146,6 +134,54 @@ declare function compute(instruction: string, opts: {
     modelCfg?: LLMConfig | null;
     timeout?: number;
 }): Promise<Record<string, unknown>>;
+/** What `compute()` builds and `computeOverFrames` consumes: sheet name → rows. */
+type ComputeFrames = Record<string, Record<string, unknown>[]>;
+/** A source document behind a frame, as `compute()` reports it in `documentsUsed`. */
+interface ComputeDocument {
+    id: string;
+    name?: string | null;
+    sourceId?: string | null;
+}
+/**
+ * Compute an answer to `instruction` over caller-supplied tables.
+ *
+ * The frame-level seam under `compute()`: everything `compute()` does AFTER
+ * it has turned its documents into `{sheet: rows[]}` lives here, so a host
+ * that already holds the frames — an uploaded workbook, a connector's
+ * sheet, a query result — can run the same prompt → code → sandbox path
+ * without first ingesting a document to point at.
+ *
+ * `frames` keys are the sheet names the caller chose; the LLM sees them and
+ * each row's columns exactly as it sees a parsed document's.
+ *
+ * The guards are `compute()`'s, in the same order and all BEFORE any LLM
+ * call: `config.enableCodeExecution` off → `EngineActionError`; no LLM
+ * (`modelCfg` or `config.llm`) → `Error`; blank instruction or empty
+ * `frames` → `EngineActionError`; `timeout` clamped to 1..300 seconds.
+ *
+ * `config.redaction` is applied at the same two surfaces as `compute()`:
+ *
+ * 1. Every string cell and every column name is masked BEFORE the prompt is
+ *    built (`maskFrames`), so neither the schema summary the LLM reads nor
+ *    the rows its code runs against carry a raw value. Same intended
+ *    trade-off as `compute()`'s point 1 — a masked cell can change a
+ *    computed result, and that is correct.
+ * 2. The returned object is swept whole through `redactValueRecursive`,
+ *    `code` included — `compute()`'s point 2, deliberately blunt.
+ *
+ * `hooks`, `principals` and `documents` are how `compute()` threads its own
+ * context through; a host calling the seam directly normally leaves them at
+ * their defaults (no error hook, trusted-internal `unless` evaluation, no
+ * source documents — `documentsUsed` comes back empty).
+ */
+declare function computeOverFrames(frames: ComputeFrames, instruction: string, opts: {
+    config: ContextEngineConfig;
+    modelCfg?: LLMConfig | null;
+    timeout?: number;
+    hooks?: Hooks | null;
+    principals?: string[] | null;
+    documents?: ComputeDocument[] | null;
+}): Promise<Record<string, unknown>>;
 
 /**
  * AES-256-GCM crypto seam. Wire format is a compatibility promise with the
@@ -260,7 +296,9 @@ interface RunSearchOpts {
     topK?: number;
     mode?: Mode;
     compressToTokens?: number | null;
-    graphRanked?: string[] | null;
+    /** A list, or a promise of one: passing a promise lets the graph leg run
+     * BESIDE the hybrid legs instead of ahead of them. */
+    graphRanked?: string[] | Promise<string[] | null> | null;
     redaction?: RedactionPolicy | null;
 }
 /**
@@ -411,7 +449,13 @@ declare class ContextEngine implements ToolEngine {
         documentIds?: string[] | null;
         principals?: Principals;
         topK?: number;
-        mode?: "hybrid" | "graph";
+        /**
+         * Omit it (or pass null) and the mode is worked out from the documents
+         * in scope: the graph leg runs when this deployment has a graph AND
+         * something in scope was ingested with `mode: "graph"`. Naming one
+         * forces it. The graph leg ADDS to the hybrid legs, never replaces them.
+         */
+        mode?: "hybrid" | "graph" | null;
         compressToTokens?: number | null;
         redaction?: RedactionPolicy | null;
     }): Promise<SearchResult>;
@@ -421,8 +465,25 @@ declare class ContextEngine implements ToolEngine {
      * caller can never distinguish "doesn't exist" from "exists but you
      * can't see it").
      */
+    /**
+     * How long a failed graph probe is remembered. One refused connection must
+     * not become one refused connection per request, and must not be permanent
+     * either — the database may come back.
+     */
+    private static readonly GRAPH_PROBE_BACKOFF_MS;
+    private graphUnreachableUntil;
+    /**
+     * Is the graph database actually up?
+     *
+     * `graph.enabled` says the deployment is CONFIGURED, not that Neo4j is
+     * answering. Choosing the graph leg when it is unreachable buys a connection
+     * timeout on every search and no extra results, so a mode-less search checks
+     * first and remembers a failure briefly.
+     */
+    private graphIsReachable;
     getDocument(documentId: string, opts?: {
         principals?: Principals;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
     deleteDocument(documentId: string, opts?: {
         principals?: Principals;
@@ -447,17 +508,78 @@ declare class ContextEngine implements ToolEngine {
     getDocumentText(documentId: string, opts?: {
         principals?: Principals;
     }): Promise<string>;
+    /**
+     * The ONE knowledge tool, as a library call. See `knowledge-tool.ts`.
+     *
+     * The same function the MCP server serves — an application driving its own
+     * agent loop hands its model this one door to the corpus without speaking
+     * MCP at all, and cannot get a different answer, because there is one
+     * implementation behind both surfaces.
+     */
+    searchKnowledgeBase(args: {
+        action: string;
+        principals?: Principals;
+        scope: ScopeInput;
+        query?: string | null;
+        document_id?: string | null;
+        source_ids?: string[] | null;
+        document_ids?: string[] | null;
+        entity?: string | null;
+        depth?: number | null;
+        category?: string | null;
+        label?: string | null;
+        entity_type?: string | null;
+        top_k?: number | null;
+        mode?: string | null;
+        limit?: number | null;
+        cursor?: unknown;
+        redaction?: RedactionPolicy | null;
+        compute?: KnowledgeComputeFn | null;
+        map_reduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
+        start?: number | null;
+        end?: number | null;
+        max_chars?: number | null;
+    }): Promise<Record<string, unknown>>;
+    /** Read one document in order, a range of chunks at a time. */
+    getChunks(documentId: string, opts?: {
+        principals?: Principals;
+        start?: number | null;
+        end?: number | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Several whole documents at once, each ACL-checked. An id that is absent OR
+     * not visible is simply missing from the result, never an error — the same
+     * non-disclosure `getDocument` gives, which a batch read is the classic
+     * place to lose.
+     */
+    getDocuments(documentIds: string[], opts?: {
+        principals?: Principals;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Array<Record<string, unknown>>>;
+    /** Ask the same question of every document in scope. */
+    mapReduce(instruction: string, opts?: {
+        principals?: Principals;
+        sourceIds?: string[] | null;
+        documentIds?: string[] | null;
+        limit?: number | null;
+        maxConcurrency?: number | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, unknown>>;
     listDocuments(opts?: {
         sourceId?: string | null;
+        sourceIds?: string[] | null;
         principals?: Principals;
         cursor?: unknown;
         limit?: number;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
     queryStructured(question: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
         docType?: string | null;
         limit?: number;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
     compute(instruction: string, opts?: {
         sourceIds?: string[] | null;
@@ -811,4 +933,4 @@ declare function functionTool(fn: (...args: never[]) => unknown): CanonicalTool;
 /** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */
 declare const __version__ = "0.0.0";
 
-export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, type Principals, ProgressEvent, RedactionPolicy, RerankerConfig, type SearchResult, StorageBackend, TRUSTED, type TaskRunner, type TaskStatus, ToolConfig, type Trusted, UNSET, type Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, type ComputeDocument, type ComputeFrames, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, KnowledgeComputeFn, LLMClient, LLMConfig, Principals, ProgressEvent, RedactionPolicy, RerankerConfig, ScopeInput, type SearchResult, StorageBackend, type TaskRunner, type TaskStatus, ToolConfig, Trusted, Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, computeOverFrames, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };

package/dist/index.d.ts

@@ -1,30 +1,17 @@
 import { Pool } from 'pg';
-import { C as ContextEngineConfig, L as LLMConfig, E as ExtractionConfig, R as RerankerConfig } from './config-CdlSkKgV.js';
-export { a as ContextEngineConfigInit, b as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-CdlSkKgV.js';
+import { C as ContextEngineConfig, L as LLMConfig, E as ExtractionConfig, R as RerankerConfig } from './config-BODDdXJ7.js';
+export { a as ContextEngineConfigInit, b as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-BODDdXJ7.js';
 import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent, I as IngestReport } from './redaction-BqD_DEUQ.js';
 export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitProgress, f as emitToolCall, g as emitUsage, h as graphUnits, u as unitsForFile } from './redaction-BqD_DEUQ.js';
-import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-Dvt2ZxsV.js';
-export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-Dvt2ZxsV.js';
-import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-XFVgtEdV.js';
-export { c as ToolKind, d as configSchema } from './governance-XFVgtEdV.js';
-export { createMcpApp } from './mcp.js';
+import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-CJrKgJeJ.js';
+export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-CJrKgJeJ.js';
+import { P as Principals, U as Unset, S as ScopeInput, K as KnowledgeComputeFn, T as Trusted } from './mcp-BKSmxayM.js';
+export { a as KNOWLEDGE_ACTIONS, b as KNOWLEDGE_TOOL_DESCRIPTION, c as KnowledgeAction, d as Scope, e as TRUSTED, f as UNSCOPED, g as UNSET, h as callKnowledgeTool, i as createMcpApp, k as knowledgeToolDefinition, n as narrowToCeiling, r as resolvePrincipals, j as resolveScope } from './mcp-BKSmxayM.js';
+import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-BLPK7NMe.js';
+export { c as ToolKind, d as configSchema } from './governance-BLPK7NMe.js';
 import 'zod';
 import 'node:http';
 
-/**
- * Sentinels distinguishing omitted arguments from real values, including null.
- *
- * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
- * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
- * `if (principals)` does not treat a trusted caller as anonymous.
- */
-declare const UNSET: unique symbol;
-type Unset = typeof UNSET;
-declare const TRUSTED: unique symbol;
-type Trusted = typeof TRUSTED;
-type Principals = string[] | null | typeof TRUSTED | undefined;
-declare function resolvePrincipals(value: Principals, method: string): string[] | null;
-
 type Mode$1 = "hybrid" | "graph";
 interface IngestRequest {
     content?: Buffer | null;
@@ -79,17 +66,11 @@ declare function getDocumentText(documentId: string, opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<string>;
-/**
- * Page through documents in scope, newest first.
- *
- * `redaction` masks `documentType` — unconstrained free text an LLM wrote
- * after reading the document body. `name`/`description` remain
- * intentionally unmasked: both are CALLER-set at ingest time, not text the
- * pipeline derived from the document body.
- */
 declare function listDocuments(opts: {
     pool: Pool;
     sourceId?: string | null;
+    /** OR-of-many, ONE keyset-paged query across all of them; with `sourceId`, their union. */
+    sourceIds?: string[] | null;
     principals?: string[] | null;
     cursor?: unknown;
     limit?: number;
@@ -129,6 +110,13 @@ declare function queryStructured(question: string, opts: {
  * call, no sandbox run — when the flag is `false`. That flag, not the
  * isolate, is the actual security boundary.
  *
+ * Only the document half lives here: fetch the in-scope tabular documents
+ * and parse their stored text into `{sheet: rows[]}`. Everything after that
+ * — the guards, both redaction surfaces below, the prompt → code → sandbox
+ * path and the swept result — is `computeOverFrames`, the seam a host calls
+ * when it already holds the frames and has no document to point at; this
+ * function builds its frames from documents and delegates.
+ *
  * `config.redaction` is applied TWICE:
  * 1. Each document's raw `.text` is masked BEFORE it is parsed into a
  *    table, so the data the LLM-authored code runs against is built from
@@ -146,6 +134,54 @@ declare function compute(instruction: string, opts: {
     modelCfg?: LLMConfig | null;
     timeout?: number;
 }): Promise<Record<string, unknown>>;
+/** What `compute()` builds and `computeOverFrames` consumes: sheet name → rows. */
+type ComputeFrames = Record<string, Record<string, unknown>[]>;
+/** A source document behind a frame, as `compute()` reports it in `documentsUsed`. */
+interface ComputeDocument {
+    id: string;
+    name?: string | null;
+    sourceId?: string | null;
+}
+/**
+ * Compute an answer to `instruction` over caller-supplied tables.
+ *
+ * The frame-level seam under `compute()`: everything `compute()` does AFTER
+ * it has turned its documents into `{sheet: rows[]}` lives here, so a host
+ * that already holds the frames — an uploaded workbook, a connector's
+ * sheet, a query result — can run the same prompt → code → sandbox path
+ * without first ingesting a document to point at.
+ *
+ * `frames` keys are the sheet names the caller chose; the LLM sees them and
+ * each row's columns exactly as it sees a parsed document's.
+ *
+ * The guards are `compute()`'s, in the same order and all BEFORE any LLM
+ * call: `config.enableCodeExecution` off → `EngineActionError`; no LLM
+ * (`modelCfg` or `config.llm`) → `Error`; blank instruction or empty
+ * `frames` → `EngineActionError`; `timeout` clamped to 1..300 seconds.
+ *
+ * `config.redaction` is applied at the same two surfaces as `compute()`:
+ *
+ * 1. Every string cell and every column name is masked BEFORE the prompt is
+ *    built (`maskFrames`), so neither the schema summary the LLM reads nor
+ *    the rows its code runs against carry a raw value. Same intended
+ *    trade-off as `compute()`'s point 1 — a masked cell can change a
+ *    computed result, and that is correct.
+ * 2. The returned object is swept whole through `redactValueRecursive`,
+ *    `code` included — `compute()`'s point 2, deliberately blunt.
+ *
+ * `hooks`, `principals` and `documents` are how `compute()` threads its own
+ * context through; a host calling the seam directly normally leaves them at
+ * their defaults (no error hook, trusted-internal `unless` evaluation, no
+ * source documents — `documentsUsed` comes back empty).
+ */
+declare function computeOverFrames(frames: ComputeFrames, instruction: string, opts: {
+    config: ContextEngineConfig;
+    modelCfg?: LLMConfig | null;
+    timeout?: number;
+    hooks?: Hooks | null;
+    principals?: string[] | null;
+    documents?: ComputeDocument[] | null;
+}): Promise<Record<string, unknown>>;
 
 /**
  * AES-256-GCM crypto seam. Wire format is a compatibility promise with the
@@ -260,7 +296,9 @@ interface RunSearchOpts {
     topK?: number;
     mode?: Mode;
     compressToTokens?: number | null;
-    graphRanked?: string[] | null;
+    /** A list, or a promise of one: passing a promise lets the graph leg run
+     * BESIDE the hybrid legs instead of ahead of them. */
+    graphRanked?: string[] | Promise<string[] | null> | null;
     redaction?: RedactionPolicy | null;
 }
 /**
@@ -411,7 +449,13 @@ declare class ContextEngine implements ToolEngine {
         documentIds?: string[] | null;
         principals?: Principals;
         topK?: number;
-        mode?: "hybrid" | "graph";
+        /**
+         * Omit it (or pass null) and the mode is worked out from the documents
+         * in scope: the graph leg runs when this deployment has a graph AND
+         * something in scope was ingested with `mode: "graph"`. Naming one
+         * forces it. The graph leg ADDS to the hybrid legs, never replaces them.
+         */
+        mode?: "hybrid" | "graph" | null;
         compressToTokens?: number | null;
         redaction?: RedactionPolicy | null;
     }): Promise<SearchResult>;
@@ -421,8 +465,25 @@ declare class ContextEngine implements ToolEngine {
      * caller can never distinguish "doesn't exist" from "exists but you
      * can't see it").
      */
+    /**
+     * How long a failed graph probe is remembered. One refused connection must
+     * not become one refused connection per request, and must not be permanent
+     * either — the database may come back.
+     */
+    private static readonly GRAPH_PROBE_BACKOFF_MS;
+    private graphUnreachableUntil;
+    /**
+     * Is the graph database actually up?
+     *
+     * `graph.enabled` says the deployment is CONFIGURED, not that Neo4j is
+     * answering. Choosing the graph leg when it is unreachable buys a connection
+     * timeout on every search and no extra results, so a mode-less search checks
+     * first and remembers a failure briefly.
+     */
+    private graphIsReachable;
     getDocument(documentId: string, opts?: {
         principals?: Principals;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
     deleteDocument(documentId: string, opts?: {
         principals?: Principals;
@@ -447,17 +508,78 @@ declare class ContextEngine implements ToolEngine {
     getDocumentText(documentId: string, opts?: {
         principals?: Principals;
     }): Promise<string>;
+    /**
+     * The ONE knowledge tool, as a library call. See `knowledge-tool.ts`.
+     *
+     * The same function the MCP server serves — an application driving its own
+     * agent loop hands its model this one door to the corpus without speaking
+     * MCP at all, and cannot get a different answer, because there is one
+     * implementation behind both surfaces.
+     */
+    searchKnowledgeBase(args: {
+        action: string;
+        principals?: Principals;
+        scope: ScopeInput;
+        query?: string | null;
+        document_id?: string | null;
+        source_ids?: string[] | null;
+        document_ids?: string[] | null;
+        entity?: string | null;
+        depth?: number | null;
+        category?: string | null;
+        label?: string | null;
+        entity_type?: string | null;
+        top_k?: number | null;
+        mode?: string | null;
+        limit?: number | null;
+        cursor?: unknown;
+        redaction?: RedactionPolicy | null;
+        compute?: KnowledgeComputeFn | null;
+        map_reduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
+        start?: number | null;
+        end?: number | null;
+        max_chars?: number | null;
+    }): Promise<Record<string, unknown>>;
+    /** Read one document in order, a range of chunks at a time. */
+    getChunks(documentId: string, opts?: {
+        principals?: Principals;
+        start?: number | null;
+        end?: number | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Several whole documents at once, each ACL-checked. An id that is absent OR
+     * not visible is simply missing from the result, never an error — the same
+     * non-disclosure `getDocument` gives, which a batch read is the classic
+     * place to lose.
+     */
+    getDocuments(documentIds: string[], opts?: {
+        principals?: Principals;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Array<Record<string, unknown>>>;
+    /** Ask the same question of every document in scope. */
+    mapReduce(instruction: string, opts?: {
+        principals?: Principals;
+        sourceIds?: string[] | null;
+        documentIds?: string[] | null;
+        limit?: number | null;
+        maxConcurrency?: number | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, unknown>>;
     listDocuments(opts?: {
         sourceId?: string | null;
+        sourceIds?: string[] | null;
         principals?: Principals;
         cursor?: unknown;
         limit?: number;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
     queryStructured(question: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
         docType?: string | null;
         limit?: number;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
     compute(instruction: string, opts?: {
         sourceIds?: string[] | null;
@@ -811,4 +933,4 @@ declare function functionTool(fn: (...args: never[]) => unknown): CanonicalTool;
 /** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */
 declare const __version__ = "0.0.0";
 
-export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, type Principals, ProgressEvent, RedactionPolicy, RerankerConfig, type SearchResult, StorageBackend, TRUSTED, type TaskRunner, type TaskStatus, ToolConfig, type Trusted, UNSET, type Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, type ComputeDocument, type ComputeFrames, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, KnowledgeComputeFn, LLMClient, LLMConfig, Principals, ProgressEvent, RedactionPolicy, RerankerConfig, ScopeInput, type SearchResult, StorageBackend, type TaskRunner, type TaskStatus, ToolConfig, Trusted, Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, computeOverFrames, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };