@promptev/context-engine 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,851 @@
+import { Pool } from 'pg';
+import { C as ContextEngineConfig, L as LLMConfig, R as RerankerConfig } from './config-Bl9U789m.cjs';
+export { a as ContextEngineConfigInit, E as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-Bl9U789m.cjs';
+import { H as Hooks, R as RedactionPolicy, U as UsageEvent, I as IngestReport } from './redaction-BmDSWJ7h.cjs';
+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.cjs';
+import { E as Embedder, F as FetchImpl } from './embeddings-B-jZ42mk.cjs';
+export { a as EmbedKind, b as buildEmbedder } from './embeddings-B-jZ42mk.cjs';
+import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-BDkcv4qZ.cjs';
+export { c as ToolKind, d as configSchema } from './governance-BDkcv4qZ.cjs';
+export { createMcpApp } from './mcp.cjs';
+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;
+}
+
+type Mode$1 = "hybrid" | "graph";
+interface IngestRequest {
+    content?: Buffer | null;
+    filename?: string | null;
+    text?: string | null;
+    name?: string | null;
+    description?: string | null;
+    sourceId?: string | null;
+    externalId?: string | null;
+    metaData?: Record<string, unknown> | null;
+    acl?: string[] | null;
+    mode?: Mode$1;
+    batch?: boolean;
+    extractStructured?: boolean;
+    fieldHints?: Record<string, unknown>[] | null;
+}
+
+/**
+ * CPSE action surface — document access, structured query, compute.
+ *
+ * **ACL/source scoping.** Every read here goes through `scopeDocumentsSql`,
+ * the Document-table equivalent of storage's chunk-table predicate:
+ * `sourceIds=null` means the whole corpus, a list scopes to it;
+ * `principals=null` means a trusted internal caller (no ACL filtering),
+ * `principals=[]` means an anonymous caller and matches only `acl IS NULL`
+ * documents. Same non-interchangeable pair as `search()` — see that
+ * module's docstring.
+ *
+ * Missing vs forbidden documents raise `DocumentNotFoundError` with the
+ * identical message `document not found: ${id}` so a caller can never
+ * distinguish "doesn't exist" from "exists but you can't see it".
+ */
+
+/**
+ * Return one document's full text, ACL-checked.
+ *
+ * Unlike an LLM-tool payload helper, this returns the WHOLE text
+ * untruncated — token-budget policy belongs to whatever calls this.
+ *
+ * Raises `EngineActionError` for an unparseable id and
+ * `DocumentNotFoundError` for a missing document or one the caller's
+ * `principals` can't see — the same message for the last two, deliberately.
+ *
+ * `redaction` (an `apply_at="output"` policy) masks the fetched text
+ * before it is returned. This is the ONLY protection for a corpus ingested
+ * WITHOUT an `apply_at="ingest"` policy.
+ */
+declare function getDocumentText(documentId: string, opts: {
+    pool: Pool;
+    principals?: string[] | null;
+    redaction?: RedactionPolicy | null;
+    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;
+    principals?: string[] | null;
+    cursor?: unknown;
+    limit?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<Record<string, unknown>>;
+/**
+ * Answer a natural-language question against documents' `structuredData`.
+ *
+ * When NOTHING resolves — every candidate fell below the similarity floor
+ * and had no exact/synonym match either — this returns ZERO documents, not
+ * the whole in-scope corpus. An off-topic question has no business getting
+ * an invoice back just because the invoice happens to have SOME structured
+ * fields.
+ *
+ * `redaction` masks each result's `documentType` and the STRING VALUES of
+ * `structuredData`. KEYS are left unredacted — they are the canonical
+ * field names this function's `resolveFields` matching keys off of.
+ */
+declare function queryStructured(question: string, opts: {
+    pool: Pool;
+    embedder: Embedder;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    docType?: string | null;
+    limit?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<Record<string, unknown>>;
+/**
+ * Compute an answer to `instruction` over in-scope spreadsheet documents.
+ *
+ * **Disabled by default** (`config.enableCodeExecution`): this executes
+ * LLM-GENERATED code. Raises `EngineActionError` before ANY work — no LLM
+ * call, no sandbox run — when the flag is `false`. That flag, not the
+ * isolate, is the actual security boundary.
+ *
+ * `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
+ *    masked cells.
+ * 2. The final returned dict is swept whole through `redactValueRecursive`
+ *    — including `code`.
+ */
+declare function compute(instruction: string, opts: {
+    pool: Pool;
+    config: ContextEngineConfig;
+    hooks: Hooks;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    docIds?: string[] | null;
+    modelCfg?: LLMConfig | null;
+    timeout?: number;
+}): Promise<Record<string, unknown>>;
+
+/**
+ * AES-256-GCM crypto seam. Wire format is a compatibility promise with the
+ * Python library and promptev-connectors:
+ *   base64(nonce[12] || AES-256-GCM ciphertext+tag)
+ */
+declare function encryptDict(data: Record<string, unknown>, key: Buffer): string;
+declare function decryptDict(token: string, key: Buffer): Record<string, unknown>;
+declare function getSecretKey(config: {
+    secretKey?: string | null;
+}): Buffer;
+
+declare function runMigrate(databaseUrl: string, opts?: {
+    dim?: number;
+    graph?: boolean;
+}): Promise<void>;
+
+/** Action-surface errors — user-facing / data-dependent failures (not found, ACL, bad input).
+ *  Config/programming errors stay as TypeError / RangeError / Error.
+ */
+declare class EngineActionError extends Error {
+    constructor(message: string);
+}
+/** Missing vs forbidden document: identical message so callers cannot distinguish. */
+declare class DocumentNotFoundError extends Error {
+    constructor(documentId: string);
+}
+declare class GraphLegUnavailable extends Error {
+    constructor(message?: string);
+}
+declare class ApprovalNotPending extends Error {
+    constructor(message?: string);
+}
+declare class ApprovalExpired extends Error {
+    constructor(message?: string);
+}
+declare class CodeExecutionError extends Error {
+    constructor(message: string);
+}
+declare class CodeExecutionTimeout extends Error {
+    constructor(message?: string);
+}
+declare class ExtraMissingError extends Error {
+    constructor(extra: string, pkg: string, what: string);
+}
+
+/**
+ * Hybrid retrieval: run the legs, fuse, (rerank), hydrate, (compress).
+ *
+ * `ContextEngine.search()` is a thin shell over `runSearch()` here. One call
+ * goes through these stages:
+ *
+ *     embed query → run supported legs concurrently → RRF fuse →
+ *     hydrate candidates → redact BEFORE rerank → optional rerank →
+ *     cut to top_k → optional compression → usage event
+ *
+ * **ACL semantics — read before touching the scope.** `principals=null` means
+ * an internal, fully-trusted caller and disables ACL filtering completely;
+ * `principals=[]` means an anonymous caller and matches only chunks whose
+ * `acl IS NULL`. Those are not interchangeable. The HTTP router ALWAYS
+ * passes a list — never `null`, never a `null` that leaked out of an
+ * absent auth header — so an unauthenticated request can never be mistaken
+ * for a trusted one. `sourceIds=null` likewise means "the whole corpus".
+ *
+ * Failure policy: retrieval degrades rather than dies. A query that can't be
+ * embedded (provider down) reports through `emitError` and continues with
+ * the lexical legs; one leg raising reports and continues with the others; a
+ * reranker or compression failure reports and falls back to the fused order.
+ * Only a search where EVERY attempted leg failed raises — at that point there
+ * is no result to degrade to, and returning an empty list would look like
+ * "nothing matched".
+ */
+
+type Mode = "hybrid" | "graph";
+/**
+ * One retrieved chunk, hydrated with its document's identity.
+ *
+ * **`score` is provenance, not the ranking key.** It is always the RRF
+ * fusion score. When a reranker runs, the reranker decides the ORDER while
+ * the score keeps its fusion value — `providers.reranker.rerank()` returns
+ * positions only, never scores, so there is no reranker score to put here
+ * and inventing one would misrepresent a number no provider gave us.
+ * Consequence for consumers: **the list order is authoritative — re-sorting
+ * hits by `score` silently discards the reranker's ordering.** Check
+ * `SearchResult.usage.reranked` if you need to know which applies.
+ */
+interface Hit {
+    documentId: string;
+    documentName: string | null;
+    description: string | null;
+    sourceId: string | null;
+    chunkText: string;
+    idx: number | null;
+    lang: string | null;
+    score: number;
+    chunkId: string;
+    meta: Record<string, unknown>;
+}
+interface SearchResult {
+    hits: Hit[];
+    usage: Record<string, unknown>;
+}
+interface RunSearchOpts {
+    config: ContextEngineConfig;
+    hooks: Hooks;
+    backend: StorageBackend;
+    embedder: Embedder;
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    topK?: number;
+    mode?: Mode;
+    compressToTokens?: number | null;
+    graphRanked?: string[] | null;
+    redaction?: RedactionPolicy | null;
+}
+/**
+ * Redact every hit's `chunkText`, and any string `meta` values, in
+ * place-by-copy.
+ *
+ * `meta` is in scope for the same reason the ingest-side fix
+ * (`redactChunkMeta`) exists: `Hit.meta` (`section_title`, `sheet_title`,
+ * ...) is extracted verbatim from the same raw document text as
+ * `chunkText` and is returned to the caller right alongside it. Ingest-time
+ * redaction only masks `meta` for corpora ingested UNDER a policy with
+ * ingest-phase rules; an output-phase policy is the ONLY protection for a
+ * corpus ingested WITHOUT one — which is the main use case output rules
+ * exist for. Skipping `meta` here would leave that corpus's PII reachable
+ * through a field sitting right next to the text we just masked, repeating
+ * the exact gap the ingest fix closed. `documentName`/`description` are
+ * left untouched: they are uploader/admin-set Document columns, not text
+ * the chunker derived from the document body, so they are out of scope for
+ * a chunk-content redaction pass.
+ *
+ * Returns `[hits, note]`; `note` is `{}` when nothing fired. Aggregates
+ * `rules_fired` (union, order preserved) and `spans` (sum) across hits and
+ * across `chunkText` + `meta`.
+ *
+ * `runSearch` calls this BEFORE maybeRerank/maybeCompress by design (see the
+ * call site), so when a policy is active the reranker scores MASKED text
+ * and the compressor counts MASKED tokens, not the original — this can
+ * shift relevance ordering and token-budget decisions versus the no-policy
+ * case. That is the correct, intended trade-off (redaction is not optional
+ * just because it might reorder results), but it is worth stating
+ * explicitly: a later "reranking got worse" or "compression drops the
+ * wrong hit" report on a redacted corpus may be this, not a
+ * reranker/compressor regression.
+ *
+ * FLAT walk, deliberately — not the recursive walker
+ * `governance.redactToolResult`/`actions.redactValueRecursive` use. Every
+ * `chunk_metas` producer in `chunkers.ts` emits a flat
+ * `{str: str | int | bool}` dict today (`section_title`, `sheet_title`,
+ * `rows_range`, `total_rows`, ...), so a one-level walk covers every string
+ * leaf that actually exists. Final review flagged this as a silent-bypass
+ * risk if a FUTURE chunker ever nests `meta` — reviewed and accepted
+ * rather than switched to a recursive walk, because threading
+ * `fired`/`failed` aggregation through a shared recursive primitive across
+ * three call sites with different existing note shapes was judged
+ * higher-risk than the flat assumption it would replace.
+ */
+declare function redactHits(hits: Hit[], policy: RedactionPolicy, opts: {
+    principals: string[] | null;
+    secretKey: string | Buffer | null;
+    hooks?: Hooks | null;
+}): [Hit[], Record<string, unknown>];
+/**
+ * Hybrid retrieval over one Context Engine database.
+ *
+ * `graphRanked` is the Task 14 seam: when the graph stage exists it
+ * passes its own ranked chunk-id list here and fusion picks it up as a
+ * fourth leg (weight `fusion.weights.graph`), which is also what flips
+ * the billing to `UNITS_PER_SCOPE_GRAPH`. Those ids are re-filtered through
+ * `backend.filterIds` first — they come from Neo4j, not from a leg's WHERE
+ * clause, so they carry no ACL or source guarantee of their own.
+ *
+ * `mode="graph"` therefore runs the hybrid legs and reports
+ * `usage.graphLeg = false` with `usage.degraded = "graph_leg_unavailable"`
+ * (plus one `emitError`), rather than letting `mode` alone imply a leg
+ * that never ran. `graphLeg` is the truth of whether the graph leg
+ * CONTRIBUTED, not merely whether it was attempted — `filterIds` may have
+ * emptied the list (every id ACL/source-filtered out).
+ */
+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.
+ *
+ * Construction is cheap and side-effect free: no database connection is
+ * opened and no provider client is built until the first call that needs
+ * one (the embedder in particular is built lazily, so an engine used only
+ * for `getDocument`/`stats` never constructs an LLM/embedding HTTP client).
+ *
+ * Graph mode is gated behind `GraphConfig.enabled` and the optional graph
+ * extra. A graph-retrieval error at query time degrades to hybrid-only
+ * results (visible via `usage.degraded`) rather than failing the search.
+ */
+
+declare class ContextEngine implements ToolEngine {
+    config: ContextEngineConfig;
+    hooks: Hooks;
+    pool: Pool;
+    backend: StorageBackend | null;
+    /** In-memory function-tool registry. Function tools are NOT persisted. */
+    _functionTools: Record<string, CanonicalTool>;
+    _toolHttpClient: ToolHttpClient | null;
+    private _pool;
+    private _embedder;
+    /** Built lazily on first graph use so constructing an engine never pulls neo4j. */
+    private _graphStore;
+    constructor(config: ContextEngineConfig, opts?: {
+        onUsage?: ((e: UsageEvent) => void) | null;
+        onError?: ((e: unknown, ctx: Record<string, unknown>) => void) | null;
+    });
+    private ensurePool;
+    /** The embedding client, built on first use. */
+    get embedder(): Embedder;
+    private getGraphStore;
+    private runGraphStage;
+    /**
+     * Release everything this engine opened. Safe to call more than once.
+     *
+     * Construction is lazy, so this only tears down what was actually built.
+     * Also usable via `await using engine = new ContextEngine(config)`.
+     */
+    aclose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Ingest one document. Returns its `IngestReport` (never raises for
+     * per-document failures — those come back as `status="failed"`).
+     *
+     * Exactly one of `file` / `content` / `text` must be given. `text=`
+     * skips extraction. `mode=null` uses `config.defaultMode`; `"graph"`
+     * requires `config.graph.enabled`.
+     */
+    ingest(opts?: IngestRequest & {
+        file?: unknown;
+        content?: Buffer | null;
+        filename?: string | null;
+        text?: string | null;
+    }): Promise<IngestReport>;
+    /**
+     * Poll every `batch_pending` document; fill embeddings for finished jobs.
+     *
+     * There is NO background daemon — `ingest({ batch: true })` submits the
+     * embedding job and returns immediately; something has to call this
+     * method afterwards. Returns the number of documents flipped to
+     * `completed` in this call.
+     */
+    resumeBatches(): Promise<number>;
+    /**
+     * Retrieve the `top_k` chunks most relevant to `query`.
+     *
+     * `principals` is the ACL contract and the two "empty" values are NOT
+     * the same: `null`/`TRUSTED` means an internal, fully-trusted caller and
+     * skips ACL filtering entirely, while `[]` means an anonymous caller and
+     * matches only chunks with no ACL.
+     */
+    search(query: string, opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        topK?: number;
+        mode?: "hybrid" | "graph";
+        compressToTokens?: number | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<SearchResult>;
+    /**
+     * Return one document as a plain dict (raises `DocumentNotFoundError` if
+     * absent OR not visible under `principals` — identical message, so a
+     * caller can never distinguish "doesn't exist" from "exists but you
+     * can't see it").
+     */
+    getDocument(documentId: string, opts?: {
+        principals?: Principals;
+    }): Promise<Record<string, unknown>>;
+    deleteDocument(documentId: string, opts?: {
+        principals?: Principals;
+    }): Promise<void>;
+    /**
+     * Update caller-declared attributes WITHOUT re-sending content.
+     *
+     * PATCH semantics: only the fields actually passed change. `acl=null`
+     * UNRESTRICTS — it can never mean "leave alone"; omit the argument
+     * entirely for that (the `UNSET` sentinel is what makes the two
+     * distinguishable). A PATCH that includes `acl` always re-syncs the
+     * chunk plane, even when the value matches what's already stored.
+     */
+    updateDocument(documentId: string, opts?: {
+        acl?: string[] | null | Unset;
+        name?: string | null | Unset;
+        description?: string | null | Unset;
+        metaData?: Record<string, unknown> | null | Unset;
+        principals?: Principals;
+    }): Promise<string[]>;
+    stats(sourceId?: string | null): Promise<Record<string, unknown>>;
+    getDocumentText(documentId: string, opts?: {
+        principals?: Principals;
+    }): Promise<string>;
+    listDocuments(opts?: {
+        sourceId?: string | null;
+        principals?: Principals;
+        cursor?: unknown;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    queryStructured(question: string, opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        docType?: string | null;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    compute(instruction: string, opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        docIds?: string[] | null;
+        modelCfg?: LLMConfig | null;
+        timeout?: number;
+    }): Promise<Record<string, unknown>>;
+    registerTool(tc: ToolConfig): Promise<string>;
+    registerFunctionTool(fn: (...args: never[]) => unknown): string;
+    updateTool(id: string, opts?: Record<string, unknown> & {
+        principals?: Principals;
+    }): Promise<ToolConfig>;
+    deleteTool(id: string, opts?: {
+        principals?: Principals;
+    }): Promise<void>;
+    listTools(opts?: {
+        sourceId?: string | null;
+        principals?: Principals;
+    }): Promise<Record<string, unknown>[]>;
+    searchTools(query: string, opts?: {
+        sourceId?: string | null;
+        principals?: Principals;
+        limit?: number;
+    }): Promise<Record<string, unknown>[]>;
+    testTool(tc: ToolConfig): Promise<Record<string, unknown>>;
+    executeTool(callName: string, args: Record<string, unknown> | null, opts?: {
+        sourceId?: string | null;
+        principals?: Principals;
+        actor?: Record<string, unknown> | null;
+        source?: string;
+    }): Promise<Record<string, unknown>>;
+}
+
+/**
+ * File -> text extraction. `extract()` is the single public entry point.
+ *
+ * Never throws for extraction failures internal to a single file — those are
+ * reported via `hooks.onError` and degrade to whatever partial text was recovered.
+ */
+
+declare class Extracted {
+    text: string;
+    pages: number | null;
+    slides: number | null;
+    mediaOnly: boolean;
+    providerTokens: Record<string, number>;
+    llmPictures: number;
+    isMarkdown: boolean;
+    constructor(init: {
+        text: string;
+        pages?: number | null;
+        slides?: number | null;
+        mediaOnly?: boolean;
+        providerTokens?: Record<string, number>;
+        llmPictures?: number;
+        isMarkdown?: boolean;
+    });
+}
+/**
+ * Extract text from `content` (raw file bytes). Never throws for per-file
+ * extraction failures — those go through `hooks.onError` and degrade.
+ */
+declare function extract(content: Buffer, filename: string, mime: string | null, opts: {
+    visionLlm?: LLMConfig | null;
+    hooks: Hooks;
+}): Promise<Extracted>;
+
+declare const DEFAULT_LEG_WEIGHT = 1;
+/**
+ * Reciprocal Rank Fusion. score(id) = Σ weight/(k+rank) with 1-based rank.
+ * Missing weight → 1.0; explicit 0.0 skips the leg; first occurrence wins;
+ * ties broken by chunk id ascending.
+ */
+declare function rrfFuse(rankedLists: Record<string, string[]>, opts: {
+    k: number;
+    weights: Record<string, number>;
+}): Array<[string, number]>;
+
+/**
+ * Pluggable LLM provider.
+ *
+ * `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`.
+ * `callLlm` owns and closes the client it builds unless one is passed in.
+ */
+
+type TokenUsage = {
+    input: number;
+    output: number;
+};
+type ImageBytes = Uint8Array;
+type ChatClient = {
+    chat: {
+        completions: {
+            create(body: {
+                model: string;
+                messages: unknown[];
+                response_format?: {
+                    type: string;
+                };
+            }): Promise<{
+                choices: Array<{
+                    message?: {
+                        content?: string | null;
+                    };
+                }>;
+                usage?: {
+                    prompt_tokens?: number;
+                    completion_tokens?: number;
+                } | null;
+            }>;
+        };
+    };
+    close?: () => void | Promise<void>;
+    timeout?: number;
+    baseURL?: string;
+};
+type LlmCallOpts = {
+    system: string;
+    user: string;
+    jsonMode?: boolean;
+    images?: ImageBytes[] | null;
+};
+type LLMClientOpts = {
+    client?: ChatClient | null;
+    fetch?: FetchImpl | null;
+    fetchImpl?: FetchImpl | null;
+};
+declare class LLMClient {
+    cfg: LLMConfig;
+    provider: LLMConfig["provider"];
+    model: string;
+    client: ChatClient | null;
+    fetchImpl: FetchImpl | null;
+    private genaiClient;
+    constructor(cfg: LLMConfig, opts?: LLMClientOpts);
+    aclose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    call(opts: LlmCallOpts): Promise<[string, TokenUsage]>;
+    private callAnthropic;
+    private callOpenAI;
+    private callGemini;
+    private callBedrock;
+}
+declare function buildLlmClient(cfg: LLMConfig, opts?: LLMClientOpts): LLMClient;
+/**
+ * Call the LLM configured by `cfg`. Returns `[text, tokenUsage]`.
+ *
+ * With no `client`, one is built for this call and CLOSED afterwards,
+ * success or failure. Pass `client` to reuse a connection across many calls;
+ * the caller then owns `aclose()`.
+ */
+declare function callLlm(cfg: LLMConfig, opts: LlmCallOpts & {
+    client?: LLMClient | null;
+}): Promise<[string, TokenUsage]>;
+
+/**
+ * Pluggable reranker provider.
+ *
+ * Returns indices into `docs`, sorted most-relevant-first (re-sorted by score
+ * descending rather than trusting API order). 30s timeout, no retries.
+ * Injectable `fetch` for tests.
+ *
+ * custom POSTs `{ query, texts }` to `{baseUrl}/rerank`.
+ */
+
+/**
+ * Rerank `docs` against `query`. Returns indices into `docs`, most-relevant-first.
+ * Raises if `cfg.enabled` is false.
+ */
+declare function rerank(cfg: RerankerConfig, query: string, docs: string[], opts?: {
+    fetch?: FetchImpl | null;
+    fetchImpl?: FetchImpl | null;
+}): Promise<number[]>;
+
+interface TaskStatus {
+    state: "running" | "done" | "failed" | string;
+    error: string | null;
+    result: unknown;
+}
+interface TaskRunner {
+    /** Schedule `factory()` to run, returning a task id. Takes a zero-argument CALLABLE — not a bare Promise — because some runners need to construct it lazily. */
+    submit(factory: () => Promise<unknown>): string;
+    /** Return `{state, error, result}`. Throws for an unknown task id. */
+    status(id: string): TaskStatus;
+}
+declare class InProcessRunner implements TaskRunner {
+    private readonly registry;
+    /** Kept so the Promise isn't garbage-collected mid-flight. */
+    private readonly tasks;
+    submit(factory: () => Promise<unknown>): string;
+    status(id: string): TaskStatus;
+}
+/**
+ * Adapter seam for callers who already run a distributed task queue —
+ * NOT a working integration. `submit()`/`status()` throw so nobody
+ * mistakes this stub for something that works out of the box.
+ */
+declare class CeleryRunner implements TaskRunner {
+    celeryApp: unknown;
+    taskName: string;
+    constructor(celeryApp: unknown, taskName: string);
+    submit(_factory?: () => Promise<unknown>): string;
+    status(_id?: string): TaskStatus;
+}
+
+/** Extraction schema version stamped on `documents.extraction_version`. */
+declare const EXTRACTION_VERSION = "ce-structured-v1";
+interface ExtractionResult {
+    documentType: string | null;
+    structuredDataRaw: Record<string, unknown>;
+    structuredData: Record<string, unknown>;
+    keysRaw: string[];
+    keysNormalized: string[];
+    quality: "high" | "medium" | "low" | "failed" | string;
+    error: string | null;
+    providerTokens: Record<string, number>;
+}
+/**
+ * Extract structured key/value data from already-extracted document text.
+ *
+ * Never throws — an LLM failure or unparseable response comes back as
+ * `ExtractionResult(quality="failed", error=...)` so ingest can complete
+ * the rest of ingestion instead of losing already-computed chunks.
+ *
+ * Tokens are tracked CUMULATIVELY across every attempt whose `callLlm`
+ * actually completed, even one whose response then failed to parse —
+ * that attempt still consumed real, billable provider tokens.
+ */
+declare function extractStructuredData(text: string, opts: {
+    llmCfg: LLMConfig;
+    fieldHints?: Record<string, unknown>[] | null;
+    maxChars?: number;
+    maxRetries?: number;
+}): Promise<ExtractionResult>;
+/**
+ * Upsert `structuredData`'s keys into the field registry.
+ *
+ * Generates a field-name embedding (`Embedder.embed(..., kind="document")`)
+ * for any NEW field, or one whose synonym set changed, or one that somehow
+ * has no embedding yet — batched into one `embed()` call per ingest rather
+ * than one per field.
+ *
+ * Returns the embedding provider's token count (0 if nothing needed embedding).
+ */
+declare function upsertRegistry(opts: {
+    pool: Pool;
+    embedder: Embedder;
+    sourceId: string | null;
+    docType: string;
+    structuredData: Record<string, unknown>;
+    keysRaw: string[];
+    keysNormalized: string[];
+}): Promise<number>;
+/**
+ * Resolve free-text field-name candidates to canonical registry keys.
+ *
+ * Cheapest-first: normalize → exact `key_norm` match → synonym-array
+ * match → nearest registry embedding (cosine, gated by
+ * FIELD_RESOLUTION_SIMILARITY_FLOOR). Unresolved candidates are simply
+ * absent from the returned `{candidate: canonicalKey}` mapping.
+ *
+ * All still-unresolved candidates are embedded in ONE batched `embed()` call.
+ *
+ * No ACL: registry rows are field NAMES, not document content, so source_id
+ * scoping is enough.
+ */
+declare function resolveFields(candidates: readonly string[], opts: {
+    pool: Pool;
+    embedder: Embedder;
+    sourceIds?: string[] | null;
+    docType?: string | null;
+}): Promise<Record<string, string>>;
+
+interface ApprovalRecord {
+    id: string;
+    toolName: string;
+    toolArgsFrozen: Record<string, unknown>;
+    sourceId: string | null;
+    principals: unknown;
+    status: string;
+    approver: string | null;
+    approverMeta: Record<string, unknown> | null;
+    expiresAt: Date | null;
+    resolvedAt: Date | null;
+    createdAt: Date | null;
+}
+type EngineLike = {
+    pool: {
+        query: (sql: string, params?: unknown[]) => Promise<{
+            rows: Array<Record<string, unknown>>;
+            rowCount?: number | null;
+        }>;
+    };
+};
+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;
+}): Promise<ApprovalRecord>;
+
+/**
+ * Derive a CanonicalTool from a plain function's name and arity.
+ * `fn.length` is the count of required positional parameters (JS omits
+ * defaults from `.length`); parameter names are parsed from source.
+ */
+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 };