@promptev/context-engine 0.0.2 → 0.0.4

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-uirRbluA.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-uirRbluA.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,18 @@ 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;
+    /**
+     * Narrows to specific documents IN SQL, not after the page is built: three
+     * named documents that happen to sit on page four would otherwise come back
+     * as an empty page rather than as themselves. An empty array means nothing
+     * is in scope and stays empty.
+     */
+    documentIds?: string[] | null;
     principals?: string[] | null;
     cursor?: unknown;
     limit?: number;
@@ -97,6 +85,167 @@ declare function listDocuments(opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<Record<string, unknown>>;
+type SpreadsheetDescription = {
+    document_id: string;
+    name: unknown;
+    source_id: unknown;
+    sheets: SheetSchema[] | null;
+    schema_unavailable?: string;
+};
+/**
+ * Sheet names, column headers and row counts for the named spreadsheets.
+ *
+ * `documentIds` comes from a listing the caller has already been shown, but
+ * the ACL and the source scope are applied AGAIN here: "we already filtered
+ * the list" is exactly how a batch read ends up reading one row it should
+ * not have. A document that is not visible, is not in scope, or is not
+ * tabular simply does not appear in the result.
+ *
+ * Reading document bodies is the cost, so it is bounded twice: the caller
+ * passes only the page it is describing, and `budget` caps the total
+ * characters of stored text this will pull. Documents past the budget are
+ * still LISTED, with `sheets: null` and a reason — a silently shortened
+ * schema would read as "that workbook has no sheets".
+ *
+ * `redaction` masks sheet names and column headers, which are derived from
+ * the document body exactly like `search`'s chunk text. The document `name`
+ * is not masked, matching `listDocuments`: it is caller-set at ingest.
+ */
+declare function spreadsheetSchema(opts: {
+    pool: Pool;
+    documentIds: string[];
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    budget?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<SpreadsheetDescription[]>;
+type DocumentStructure = Record<string, unknown>;
+/**
+ * What is INSIDE each of the named documents, whatever its type.
+ *
+ * Returns `{documentId: structure}`. The shape of `structure` follows the
+ * document, because the thing a model needs to know differs by type:
+ *
+ * | document | structure |
+ * |---|---|
+ * | CSV / XLSX / TSV | `sheets: [{name, columns, row_count}]` |
+ * | markdown, Word, HTML, a transcribed PDF | `sections: [...]`, `last_page` |
+ * | JSON | `keys: [...]` |
+ * | anything else | just `chunks` |
+ *
+ * `chunks` is on every one of them, and is the floor: a plain `.txt` has no
+ * headings to report, but a model still has to know whether `get_chunks` is
+ * worth calling. A document that is present but described by nothing at all
+ * reads as an empty document, which is why there is no "no structure" case.
+ *
+ * Everything but the spreadsheet columns comes from `meta_data` on the chunk
+ * rows, which the chunkers already wrote at ingest (`section_title`, `page`,
+ * `top_level_key`) — one grouped query over small rows, no document body read
+ * and no LLM. Columns are the exception: the header row is not in chunk
+ * metadata, so the tabular half still parses stored text, under the same
+ * budget (see `spreadsheetSchema`).
+ */
+declare function documentStructure(opts: {
+    pool: Pool;
+    documentIds: string[];
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    budget?: number;
+    /**
+     * Cap every list at `MAX_STRUCTURE_ITEMS` and report the remainder as a
+     * count. One rule decides it, and the caller above applies it: **the cap is
+     * for the call that did NOT name its documents.** A `discover` describing a
+     * whole page has a context budget to keep; a caller that asked about one
+     * document asked for all of it, exactly like `spreadsheetSchema`.
+     */
+    bounded?: boolean;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<Record<string, DocumentStructure>>;
+type DocumentTypeCount = {
+    kind: "spreadsheet" | "text";
+    type: string | null;
+    documents: number;
+    with_fields: number;
+};
+/**
+ * The corpus census: `[{kind, type, documents, with_fields}]`.
+ *
+ * Keyed by TWO things, because only one of them is always known:
+ *
+ * - `kind` is derived from the mime (`isTabularMime`, the same predicate
+ *   `compute` selects on), so it is known for every document ever ingested.
+ * - `type` is the document's `document_type`, which is unconstrained free
+ *   text an LLM wrote during structured extraction — and extraction is
+ *   opt-in (`extractStructured`, off by default). On a deployment that never
+ *   enabled it, `type` is null on every row. A census keyed on `type` alone
+ *   would therefore be a single null bucket, which tells a model nothing
+ *   about a corpus it is about to query.
+ *
+ * `with_fields` counts documents whose `structured_data` is a non-empty
+ * object. Extraction that ran and legitimately found nothing stores `{}`, and
+ * counting that as coverage would point a model at `query_meta` for a type
+ * that has nothing to filter on.
+ */
+declare function documentTypes(opts: {
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    documentIds?: string[] | null;
+    limit?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<DocumentTypeCount[]>;
+type FieldDescription = {
+    field: string;
+    type: string;
+    documents: number;
+};
+type FieldGroup = {
+    kind: "spreadsheet" | "text";
+    type: string | null;
+    fields: FieldDescription[];
+    more_fields?: string[];
+};
+/**
+ * Extracted structured field names grouped by document kind AND type.
+ *
+ * Returns `[{kind, type, fields: [{field, type, documents}], more_fields}]` —
+ * one row per group, keyed by the SAME pair `documentTypes` is keyed by. That
+ * pairing is the point: `document_type` is a label an LLM wrote, so two
+ * different kinds can share one ("invoice" for both a PDF and a CSV of
+ * invoice rows). Keyed on the label alone, their fields merge into one group
+ * and a model reads a spreadsheet's columns as a PDF's extracted fields.
+ *
+ * `more_fields` holds the NAMES the per-group detail cap left out, not a
+ * count: nothing is dropped silently, and a name is all a caller needs to
+ * reach a field through `query_meta`. It is absent when nothing was left out.
+ *
+ * Counted over the documents the CALLER can see, not over the learned field
+ * registry (`context_engine_structured_keys`), which carries no ACL: a
+ * registry-wide answer would tell an anonymous caller the field names of
+ * every restricted document in the corpus. Counting from `structured_data`
+ * also makes `documents` mean what it says — how many in-scope documents
+ * actually carry the field.
+ *
+ * The type is `inferDataType`, the same function that labelled the registry,
+ * so the vocabulary a model reads here is the one the rest of the engine
+ * uses.
+ */
+declare function fieldSummary(opts: {
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    documentIds?: string[] | null;
+    maxFieldsPerType?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<FieldGroup[]>;
 /**
  * Answer a natural-language question against documents' `structuredData`.
  *
@@ -121,6 +270,24 @@ declare function queryStructured(question: string, opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<Record<string, unknown>>;
+type SheetSchema = {
+    name: string;
+    columns: string[];
+    row_count: number;
+};
+/**
+ * The schema of one stored spreadsheet: `[{name, columns, row_count}]`.
+ *
+ * Header row and row count per SHEET, not unioned across the workbook — two
+ * sheets that both have an `amount` column are two different frames to
+ * `compute`, and a union would hide which one has the column a question
+ * needs. `row_count` counts DATA rows (the header is not one of them).
+ *
+ * Needs no danfo: `discover` must stay callable on an install that never
+ * enabled code execution, which is exactly the install where a model most
+ * needs the columns before it writes a query.
+ */
+declare function spreadsheetSchemaFromText(text: string | null | undefined): SheetSchema[];
 /**
  * Compute an answer to `instruction` over in-scope spreadsheet documents.
  *
@@ -315,7 +482,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 +635,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 +651,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 +694,133 @@ 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;
+        documentIds?: string[] | null;
         principals?: Principals;
         cursor?: unknown;
         limit?: number;
+        redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Sheet names, columns and row counts for the named spreadsheets.
+     *
+     * See `actions.spreadsheetSchema`. This is the half of `discover` that lets
+     * a model write ONE `compute` call: sheet names here are the keys it will
+     * index `dfs` by, and columns are the names it will use inside the code it
+     * writes.
+     */
+    spreadsheetSchema(opts: {
+        documentIds: string[];
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        redaction?: RedactionPolicy | null;
+    }): Promise<SpreadsheetDescription[]>;
+    /**
+     * What is inside each of the named documents, whatever its type.
+     *
+     * See `actions.documentStructure`. Sheets and columns for a workbook,
+     * sections and the last page for a document with headings, top-level keys
+     * for JSON, and a chunk count for everything — so `discover` describes the
+     * whole corpus rather than only the spreadsheets in it.
+     */
+    documentStructure(opts: {
+        documentIds: string[];
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        bounded?: boolean;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, DocumentStructure>>;
+    /**
+     * The corpus census — `[{kind, type, documents, with_fields}]`.
+     *
+     * See `actions.documentTypes`. `kind` comes from the mime and is always
+     * known; `type` is the LLM-written document type and exists only where
+     * structured extraction was opted into.
+     */
+    documentTypes(opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        documentIds?: string[] | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<DocumentTypeCount[]>;
+    /**
+     * Extracted structured field names grouped by document kind and type.
+     *
+     * See `actions.fieldSummary`. One row per group, keyed by the same
+     * `(kind, type)` pair `documentTypes` uses.
+     */
+    fieldSummary(opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        documentIds?: string[] | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<FieldGroup[]>;
     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 +1174,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, documentStructure, documentTypes, encryptDict, extract, extractStructuredData, fieldSummary, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rrfFuse, runMigrate, runSearch, shouldRequireApproval, spreadsheetSchema, spreadsheetSchemaFromText, upsertRegistry };