@promptev/context-engine 0.0.0 → 0.0.2

package/dist/index.d.ts

@@ -1,91 +1,29 @@
 import { Pool } from 'pg';
-import { C as ContextEngineConfig, L as LLMConfig, R as RerankerConfig } from './config-Bt9bUQqU.js';
-export { a as ContextEngineConfigInit, E as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-Bt9bUQqU.js';
-import { H as Hooks, R as RedactionPolicy, U as UsageEvent, I as IngestReport } from './redaction-BmDSWJ7h.js';
-export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitToolCall, f as emitUsage, g as graphUnits, u as unitsForFile } from './redaction-BmDSWJ7h.js';
-import { E as Embedder, F as FetchImpl } from './embeddings-DaSdAZN3.js';
-export { a as EmbedKind, b as buildEmbedder } from './embeddings-DaSdAZN3.js';
-import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-XIScatRO.js';
-export { c as ToolKind, d as configSchema } from './governance-XIScatRO.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-CJrKgJeJ.js';
+export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-CJrKgJeJ.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';
 
-interface ChunkRow {
-    idx: number;
-    text: string;
-    lang?: string | null;
-    embedding?: number[] | null;
-    meta?: Record<string, unknown>;
-}
-interface SearchScope {
-    sourceIds?: string[] | null;
-    principals?: string[] | null;
-    limit?: number;
-}
-interface StorageBackend {
-    supportsFts: boolean;
-    supportsTrgm: boolean;
-    supportsAnn: boolean;
-    upsertChunks(documentId: string, sourceId: string | null, acl: string[] | null, chunks: readonly ChunkRow[]): Promise<number>;
-    deleteChunks(documentId: string): Promise<void>;
-    updateChunkEmbeddings(documentId: string, vectors: readonly number[][]): Promise<number>;
-    updateChunkAcl(documentId: string, acl: string[] | null): Promise<number>;
-    filterIds(chunkIds: readonly string[], scope: SearchScope): Promise<string[]>;
-    ftsSearch(query: string, scope: SearchScope): Promise<string[]>;
-    trgmSearch(query: string, scope: SearchScope): Promise<string[]>;
-    annSearch(vector: readonly number[], scope: SearchScope): Promise<string[]>;
-}
-declare class PostgresBackend implements StorageBackend {
-    supportsFts: boolean;
-    supportsTrgm: boolean;
-    supportsAnn: boolean;
-    private readonly pool;
-    private readonly exactThresholdOverride;
-    /** Tri-state: null = not yet checked. */
-    private iterativeScan;
-    constructor(pool: Pool, exactThreshold?: number | null);
-    private get exactThreshold();
-    /**
-     * Bind values for SCOPE + the row limit.
-     * `principals` is passed through UNCHANGED: null (trusted) and [] (anonymous)
-     * mean different things.
-     */
-    private scopeParams;
-    upsertChunks(documentId: string, sourceId: string | null, acl: string[] | null, chunks: readonly ChunkRow[]): Promise<number>;
-    deleteChunks(documentId: string): Promise<void>;
-    updateChunkEmbeddings(documentId: string, vectors: readonly number[][]): Promise<number>;
-    updateChunkAcl(documentId: string, acl: string[] | null): Promise<number>;
-    filterIds(chunkIds: readonly string[], scope: SearchScope): Promise<string[]>;
-    ftsSearch(query: string, scope: SearchScope): Promise<string[]>;
-    trgmSearch(query: string, scope: SearchScope): Promise<string[]>;
-    /**
-     * Set pg_trgm's similarity threshold for this query via the `set_limit()` /
-     * `show_limit()` FUNCTIONS — never the GUC `pg_trgm.similarity_threshold`.
-     *
-     * The GUC is registered lazily, only once pg_trgm's shared library is loaded
-     * into the backend process. On a fresh pooled connection that has not yet
-     * run any pg_trgm operation, `SHOW pg_trgm.similarity_threshold` raises
-     * "unrecognized configuration parameter" — and because that error aborts the
-     * surrounding transaction, a fallback issued on the same connection then
-     * fails with "current transaction is aborted". Every connection a pool hands
-     * out is fresh, so this is the common case, not an edge case. Calling
-     * `set_limit()` loads the library and does not depend on the GUC. This
-     * mirrors the Python backend, which was hardened against exactly this.
-     *
-     * `set_limit()` is connection-scoped and survives COMMIT and the return to
-     * the pool, so the previous value is captured here and restored by the
-     * caller.
-     */
-    private applyTrgmThreshold;
-    private restoreTrgmLimit;
-    annSearch(vector: readonly number[], scope: SearchScope): Promise<string[]>;
-    private eligibleIsSmall;
-    private tuneAnnScan;
-    private scanBudget;
-    private enableIterativeScan;
-    private supportsIterativeScan;
-}
+/**
+ * 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 {
@@ -191,6 +129,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
@@ -204,9 +149,57 @@ declare function compute(instruction: string, opts: {
     hooks: Hooks;
     sourceIds?: string[] | null;
     principals?: string[] | null;
-    docIds?: string[] | null;
+    documentIds?: string[] | null;
+    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>>;
 
 /**
@@ -317,6 +310,7 @@ interface RunSearchOpts {
     embedder: Embedder;
     pool: Pool;
     sourceIds?: string[] | null;
+    documentIds?: string[] | null;
     principals?: string[] | null;
     topK?: number;
     mode?: Mode;
@@ -392,25 +386,6 @@ declare function redactHits(hits: Hit[], policy: RedactionPolicy, opts: {
  */
 declare function runSearch(query: string, opts: RunSearchOpts): Promise<SearchResult>;
 
-/**
- * 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 class TrustedSentinel {
-    readonly [Symbol.toStringTag] = "TRUSTED";
-    toString(): string;
-    valueOf(): boolean;
-}
-declare const TRUSTED: TrustedSentinel;
-type Trusted = typeof TRUSTED;
-type Principals = string[] | null | typeof TRUSTED | undefined;
-declare function resolvePrincipals(value: Principals, method: string): string[] | null;
-
 /**
  * `ContextEngine` — the package's public object.
  *
@@ -439,6 +414,7 @@ declare class ContextEngine implements ToolEngine {
     constructor(config: ContextEngineConfig, opts?: {
         onUsage?: ((e: UsageEvent) => void) | null;
         onError?: ((e: unknown, ctx: Record<string, unknown>) => void) | null;
+        onProgress?: ((e: ProgressEvent) => void) | null;
     });
     private ensurePool;
     /** The embedding client, built on first use. */
@@ -486,6 +462,8 @@ declare class ContextEngine implements ToolEngine {
      */
     search(query: string, opts?: {
         sourceIds?: string[] | null;
+        /** Narrows WITHIN a source; INTERSECTS with `sourceIds`. */
+        documentIds?: string[] | null;
         principals?: Principals;
         topK?: number;
         mode?: "hybrid" | "graph";
@@ -539,7 +517,7 @@ declare class ContextEngine implements ToolEngine {
     compute(instruction: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
-        docIds?: string[] | null;
+        documentIds?: string[] | null;
         modelCfg?: LLMConfig | null;
         timeout?: number;
     }): Promise<Record<string, unknown>>;
@@ -566,6 +544,9 @@ declare class ContextEngine implements ToolEngine {
         principals?: Principals;
         actor?: Record<string, unknown> | null;
         source?: string;
+        /** Opaque claim scope for approvals (e.g. a run id) — separate from
+         * `sourceId`. See `governance.executeTool`. */
+        approvalScope?: string | null;
     }): Promise<Record<string, unknown>>;
 }
 
@@ -576,6 +557,23 @@ declare class ContextEngine implements ToolEngine {
  * reported via `hooks.onError` and degrade to whatever partial text was recovered.
  */
 
+/**
+ * WHY a document came back with less text than it has, when the answer is
+ * actionable. Mirrors the Python client's `Extracted.unreadable_reason` —
+ * that docstring is the canonical rationale; only the value semantics are
+ * restated here:
+ *
+ * - `needs_vision`  — pages had no usable text layer and no vision model was
+ *   configured. FIXABLE by configuring one (the OCR fallback may have tried
+ *   and read nothing; a vision model is still the actionable upgrade).
+ * - `vision_failed` — a vision model was configured and produced nothing for
+ *   those pages. An ops problem, not a configuration one.
+ *
+ * `null` means nothing was lost — a page a reader READ and found empty is
+ * blank, not unreadable. A closed set on purpose (callers branch on it), and
+ * NOT an error channel; `mediaOnly` stays set alongside it for whole files.
+ */
+type UnreadableReason = "needs_vision" | "vision_failed";
 declare class Extracted {
     text: string;
     pages: number | null;
@@ -584,6 +582,10 @@ declare class Extracted {
     providerTokens: Record<string, number>;
     llmPictures: number;
     isMarkdown: boolean;
+    /** See `UnreadableReason`. `mediaOnly` is the same idea for whole files and
+     *  stays set alongside this, so existing callers keep working. */
+    unreadableReason: UnreadableReason | null;
+    unreadablePages: number;
     constructor(init: {
         text: string;
         pages?: number | null;
@@ -592,6 +594,8 @@ declare class Extracted {
         providerTokens?: Record<string, number>;
         llmPictures?: number;
         isMarkdown?: boolean;
+        unreadableReason?: UnreadableReason | null;
+        unreadablePages?: number;
     });
 }
 /**
@@ -601,6 +605,7 @@ declare class Extracted {
 declare function extract(content: Buffer, filename: string, mime: string | null, opts: {
     visionLlm?: LLMConfig | null;
     hooks: Hooks;
+    extraction?: ExtractionConfig | null;
 }): Promise<Extracted>;
 
 declare const DEFAULT_LEG_WEIGHT = 1;
@@ -620,7 +625,8 @@ declare function rrfFuse(rankedLists: Record<string, string[]>, opts: {
  * `callLlm(cfg, { system, user, jsonMode, images, client })` is the single entry
  * point. Returns `[text, { input, output }]`.
  *
- * Images are always PNG. 30s timeout, no retries. Injectable `client` / `fetch`.
+ * Images are always PNG. 240s call timeout (every provider), no retries.
+ * Injectable `client` / `fetch`.
  * `callLlm` owns and closes the client it builds unless one is passed in.
  */
 
@@ -660,6 +666,17 @@ type LlmCallOpts = {
     user: string;
     jsonMode?: boolean;
     images?: ImageBytes[] | null;
+    maxTokens?: number | null;
+    /** Reasoning tokens are drawn from `maxTokens`, so a caller that wants
+     * transcription rather than deliberation must be able to spend the whole
+     * budget on output. Omitted = the provider's default. Applied per provider
+     * capability: gemini and anthropic take it directly (anthropic thinking is
+     * opt-in, so 0 sends nothing and a positive budget drops `temperature` —
+     * the API rejects the combination); bedrock forwards a positive budget as
+     * the anthropic-style passthrough; the openai family has no portable
+     * thinking control. */
+    thinkingBudget?: number | null;
+    temperature?: number | null;
 };
 type LLMClientOpts = {
     client?: ChatClient | null;
@@ -817,6 +834,7 @@ interface ApprovalRecord {
     toolName: string;
     toolArgsFrozen: Record<string, unknown>;
     sourceId: string | null;
+    approvalScope: string | null;
     principals: unknown;
     status: string;
     approver: string | null;
@@ -835,7 +853,7 @@ type EngineLike = {
 };
 declare function shouldRequireApproval(ct: Pick<CanonicalTool, "requiresApproval" | "approvalPolicy">, args: Record<string, unknown>): boolean;
 declare function resolveApproval(engine: EngineLike, approvalId: string, decision: "approved" | "rejected", approver: string, meta?: Record<string, unknown> | null, opts?: {
-    principals?: string[] | null;
+    principals?: string[] | null | Trusted;
 }): Promise<ApprovalRecord>;
 
 /**
@@ -848,4 +866,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, type ChunkRow, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, PostgresBackend, type Principals, RedactionPolicy, RerankerConfig, type SearchResult, type SearchScope, type 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, 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 };