@promptev/context-engine 0.0.2 → 0.0.3

package/dist/index.d.cts

@@ -5,26 +5,13 @@ import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent,
 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-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';
-export { createMcpApp } from './mcp.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;
@@ -315,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;
 }
 /**
@@ -466,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>;
@@ -476,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;
@@ -502,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;
@@ -866,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, 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, 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, computeOverFrames, 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

@@ -5,26 +5,13 @@ import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent,
 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-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';
-export { createMcpApp } from './mcp.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;
@@ -315,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;
 }
 /**
@@ -466,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>;
@@ -476,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;
@@ -502,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;
@@ -866,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, 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, 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, computeOverFrames, 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 };