@autorag/librarian 2.8.0 → 2.10.0

package/dist/memory/check-memory-tool.d.ts

@@ -1,14 +1,18 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
+import { type MemoryContextOptions } from "./context.js";
 import type { RetrievalMemory } from "./memory.js";
 declare const checkMemorySchema: Type.TObject<{
     query: Type.TString;
 }>;
 export interface CheckMemoryDetails {
-    signalCount: number;
-    topMethod: string | null;
+    currentCount: number;
+    similarCount: number;
     insightCount: number;
-    contextHintCount: number;
 }
-export declare function createCheckMemoryTool(memory: RetrievalMemory): AgentTool<typeof checkMemorySchema, CheckMemoryDetails>;
+/**
+ * `options` returns undefined when this session must not read retrieval memory
+ * (remote P2P peers); the tool then answers as if memory were empty.
+ */
+export declare function createCheckMemoryTool(memory: RetrievalMemory, options: () => MemoryContextOptions | undefined): AgentTool<typeof checkMemorySchema, CheckMemoryDetails>;
 export {};

package/dist/memory/context.d.ts

@@ -0,0 +1,51 @@
+import type { Embedder } from "../embedding-runtime/gateway-embedder.js";
+import type { JudgedEvidenceRecord } from "./judged-evidence.js";
+import type { RetrievalInsight, RetrievalMemory } from "./memory.js";
+import { type SimilarQuestion } from "./similar-queries.js";
+export interface MemoryContextOptions {
+    readonly conversationId: string;
+    /**
+     * Per-record gate applied to both the current conversation's evidence and
+     * the past evidence considered for similarity. Memory is shared across
+     * workspaces, so the agent uses this to drop evidence from datasources that
+     * are not configured for the current run.
+     */
+    readonly isVisible?: (record: JudgedEvidenceRecord) => boolean;
+    /**
+     * Per-insight gate applied to the matching long-term insights. Insights name
+     * sources and methods, so the same datasource-scope filter drops the ones
+     * whose sources the current run cannot read.
+     */
+    readonly isInsightVisible?: (insight: RetrievalInsight) => boolean;
+    readonly embedder?: Embedder;
+    readonly vectorStorePath?: string;
+}
+export interface MemoryContext {
+    /** The advisory markdown the librarian agent receives. */
+    readonly text: string;
+    /** True when there is nothing to show. */
+    readonly empty: boolean;
+    /** Current-conversation evidence after {@link MemoryContextOptions.isVisible}, before the render cap; reusable by the caller. */
+    readonly current: readonly JudgedEvidenceRecord[];
+    /**
+     * The same similarity search kept unfiltered, including questions from the
+     * current conversation. The agent uses it to hint at datasources, so a
+     * follow-up in the same session still finds the earlier question.
+     */
+    readonly related: readonly SimilarQuestion[];
+    /** Similar questions from other conversations only (current-conversation records removed); what is rendered. */
+    readonly similar: readonly SimilarQuestion[];
+    /** Records rendered from the current conversation (capped at {@link CURRENT_CONVERSATION_RECORD_LIMIT}). */
+    readonly currentCount: number;
+    /** Similar past questions found. */
+    readonly similarCount: number;
+    readonly insightCount: number;
+    /** Why semantic matching was skipped, verbatim from {@link findSimilarQuestions}. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Gathers this conversation's judged evidence, similar past questions, and
+ * matching long-term insights into one advisory context. Never throws:
+ * {@link findSimilarQuestions} degrades to keywords and reports why.
+ */
+export declare function loadMemoryContext(memory: RetrievalMemory, query: string, options: MemoryContextOptions): Promise<MemoryContext>;

package/dist/memory/index.d.ts

@@ -1,5 +1,12 @@
 export type { CheckMemoryDetails } from "./check-memory-tool.js";
 export { createCheckMemoryTool } from "./check-memory-tool.js";
-export type { ContextValueHint, EvidenceContext, FeedbackIdInput, MemoryEntry, ResultFeedback, RetrievalContextHints, RetrievalInsight, RetrievalMemoryOptions, SearchAttempt, } from "./memory.js";
+export type { MemoryContext, MemoryContextOptions } from "./context.js";
+export { loadMemoryContext } from "./context.js";
+export type { JudgedEvidenceRecord } from "./judged-evidence.js";
+export { EVIDENCE_SUPPORT_THRESHOLD } from "./judged-evidence.js";
+export type { CuratedResultRecord, EvidenceChunkRecord, EvidenceContext, InsightExtractor, MemorySchema, RetrievalInsight, RetrievalMemoryOptions, SessionEvidenceRef, } from "./memory.js";
 export { normalizeSessionEvidenceRef, RetrievalMemory } from "./memory.js";
+export type { MemoryContextSections } from "./renderer.js";
 export { renderMemoryContext } from "./renderer.js";
+export type { SimilarQuestion } from "./similar-queries.js";
+export { findSimilarQuestions, SIMILAR_QUESTION_LIMIT } from "./similar-queries.js";

package/dist/memory/judged-evidence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Evidence the final answer cited and Jev judged to support the user's
+ * question. This is the unit retrieval memory stores: a question, the search
+ * query and method that surfaced the evidence, and the evidence itself.
+ */
+export interface JudgedEvidenceRecord {
+    /** `<sessionId>:<stableEvidenceId>`; unique per search run and evidence. */
+    readonly id: string;
+    /** The search run (one `searchDocuments` call) that produced the evidence. */
+    readonly sessionId: string;
+    /** The agent conversation the run belonged to; "current session" memory is keyed on it. */
+    readonly conversationId: string;
+    /** The user's original question. */
+    readonly question: string;
+    /** The search query that surfaced the evidence (the question itself when no sub-query is known). */
+    readonly searchQuery: string;
+    /** Retrieval method or tool that surfaced the evidence. */
+    readonly method: string;
+    /** Opaque source identifier of the evidence. */
+    readonly source: string;
+    readonly stableEvidenceId: string;
+    /** Number and title of the curated result the evidence backs. */
+    readonly resultNumber: number;
+    readonly title: string;
+    /** Bounded evidence text. */
+    readonly excerpt: string;
+    /** Jev's P(this evidence supports the question), at or above {@link EVIDENCE_SUPPORT_THRESHOLD}. */
+    readonly probability: number;
+    readonly createdAt: number;
+}
+/** Evidence is kept in memory only when Jev's P(supports the question) reaches this. */
+export declare const EVIDENCE_SUPPORT_THRESHOLD = 0.7;

package/dist/memory/memory.d.ts

@@ -1,13 +1,5 @@
 import { type NormalizedEvidenceRef } from "../retrieval/evidence-id.js";
-export type FeedbackOutcome = "pending" | "useful" | "not_useful";
-export type FeedbackSentiment = "useful" | "not_useful";
-export type FeedbackSignalSource = "explicit" | "followup" | "retry";
-export interface SignalDefaults {
-    readonly explicitWeight: number;
-    readonly followupWeight: number;
-    readonly retryWeight: number;
-    readonly implicitCap: number;
-}
+import type { JudgedEvidenceRecord } from "./judged-evidence.js";
 export interface EvidenceContext {
     readonly retrieverMix?: readonly string[];
     readonly parserType?: string;
@@ -35,46 +27,7 @@ export interface CuratedResultRecord {
     readonly confidence?: number;
     readonly createdAt: number;
 }
-export interface FeedbackSignal {
-    readonly id: string;
-    readonly target: {
-        readonly type: "curated_result";
-        readonly resultId: string;
-    } | {
-        readonly type: "evidence_chunk";
-        readonly stableEvidenceId: string;
-    } | {
-        readonly type: "method";
-        readonly method: string;
-    };
-    readonly query: string;
-    readonly method?: string;
-    readonly sentiment: FeedbackSentiment;
-    readonly source: FeedbackSignalSource;
-    readonly weight: number;
-    readonly confidenceCap: number;
-    readonly eventId: string;
-    readonly timestamp: number;
-}
-export interface MethodHint {
-    readonly method: string;
-    readonly score: number;
-    readonly confidence: number;
-    readonly reason: string;
-}
-export interface ContextValueHint {
-    readonly value: string;
-    readonly score: number;
-    readonly confidence: number;
-}
-export interface RetrievalContextHints {
-    readonly documentAreas: readonly ContextValueHint[];
-    readonly documentTypes: readonly ContextValueHint[];
-    readonly evidenceTypes: readonly ContextValueHint[];
-    readonly evidenceLocations: readonly ContextValueHint[];
-    readonly parserTypes: readonly ContextValueHint[];
-    readonly retrieverMix: readonly ContextValueHint[];
-}
+/** A long-term lesson summarized from a batch of judged evidence about one kind of question. */
 export interface RetrievalInsight {
     readonly id: string;
     readonly clusterKey: string;
@@ -82,52 +35,32 @@ export interface RetrievalInsight {
     readonly recommendedSources: string[];
     readonly recommendedMethods: string[];
     readonly rationale: string;
-    supportingSignalCount: number;
+    supportingEvidenceCount: number;
     confidence: number;
     readonly createdAt: number;
     updatedAt: number;
 }
-export interface InsightExtractionSignal {
-    readonly signal: FeedbackSignal;
-    readonly method?: string;
-    readonly source?: string;
-}
-export type InsightExtractor = (signals: readonly InsightExtractionSignal[], now: number) => RetrievalInsight[];
+/** Summarizes one batch of judged evidence into insights. */
+export type InsightExtractor = (records: readonly JudgedEvidenceRecord[], now: number) => RetrievalInsight[];
 export interface MemoryWarning {
     readonly code: string;
     readonly message: string;
     readonly timestamp: number;
 }
-export interface MemorySchemaV4 {
-    readonly version: 4;
+export interface MemorySchema {
+    readonly version: 5;
     curatedResults: CuratedResultRecord[];
     evidenceChunks: EvidenceChunkRecord[];
-    feedbackSignals: FeedbackSignal[];
-    readonly signalDefaults: SignalDefaults;
+    /** Every piece of evidence Jev judged to support the question it was cited for. Never evicted. */
+    judgedEvidence: JudgedEvidenceRecord[];
     warnings: MemoryWarning[];
     insights: RetrievalInsight[];
-    pendingInsightSignals: InsightExtractionSignal[];
-}
-export interface MemoryEntry {
-    id: string;
-    query: string;
-    method: string;
-    outcome: FeedbackOutcome;
-    timestamp: number;
-    metadata?: {
-        resultCount?: number;
-    };
-}
-export interface SearchAttempt {
-    id: string;
-    query: string;
-    method: string;
-    sources: string[];
-    timestamp: number;
+    /** Ids of judged evidence not yet summarized into insights; summarized 100 at a time. */
+    pendingInsightEntries: string[];
 }
-export interface ResultFeedback {
-    source: string;
-    useful: boolean;
+export interface RetrievalMemoryOptions {
+    storagePath: string;
+    insightExtractor?: InsightExtractor;
 }
 export interface SessionEvidenceRef extends NormalizedEvidenceRef, EvidenceContext {
     readonly metadata?: Record<string, unknown>;
@@ -147,61 +80,44 @@ export interface SessionRecordInput {
     readonly query: string;
     readonly results: readonly SessionCuratedResultInput[];
 }
-export interface NumberedFeedbackInput {
-    readonly sessionId: string;
-    readonly query: string;
-    readonly feedback: readonly {
-        readonly number: number;
-        readonly useful: boolean;
-    }[];
-}
-export interface FeedbackIdInput {
-    readonly feedbackId: string;
-    readonly useful: boolean;
-}
-export interface RetrievalMemoryOptions {
-    storagePath: string;
-    insightExtractor?: InsightExtractor;
-}
+/**
+ * Long-term retrieval memory: the evidence Jev judged to genuinely support the
+ * question it was cited for, plus the curated results and evidence chunks of
+ * past searches. Nothing is evicted; every 100 judged records are summarized
+ * into long-term insights.
+ */
 export declare class RetrievalMemory {
     private readonly storagePath;
     private readonly insightExtractor;
     private data;
     private persistedData;
-    private legacyEntries;
-    private legacySourceToAttemptId;
     constructor(options: RetrievalMemoryOptions);
     load(): void;
     save(): void;
-    getSchema(): MemorySchemaV4;
-    getSignalCount(): number;
+    getSchema(): MemorySchema;
+    getJudgedEvidence(): readonly JudgedEvidenceRecord[];
+    /** Everything judged during one conversation, oldest first. */
+    getConversationEvidence(conversationId: string): JudgedEvidenceRecord[];
     recordCuratedResultsSession(input: SessionRecordInput): void;
-    recordNumberedFeedback(input: NumberedFeedbackInput): boolean;
-    recordFeedbackByIds(feedback: readonly FeedbackIdInput[]): boolean;
-    recordWeakSignal(query: string, method: string, source: "followup" | "retry"): void;
-    getMethodHints(_query: string): MethodHint[];
-    getContextHints(_query: string): RetrievalContextHints;
+    /** Remember judged evidence. A record already stored under the same id is left as it was. */
+    recordJudgedEvidence(records: readonly JudgedEvidenceRecord[]): void;
     getInsights(query: string): RetrievalInsight[];
-    getMethodPriority(query: string): Array<{
-        method: string;
-        score: number;
-    }>;
-    append(entry: Omit<MemoryEntry, "id" | "timestamp">): MemoryEntry;
-    getEntries(): readonly MemoryEntry[];
-    registerAttempt(attempt: SearchAttempt): void;
-    recordResultFeedback(feedback: ResultFeedback[]): void;
-    resolvePendingEntries(query: string, method: string | null, outcome: "useful" | "not_useful"): void;
-    recordFeedback(query: string, methodName: string, satisfied: boolean): void;
     private readPersistedData;
     private incompatibleMemory;
     private acquireLock;
+    /**
+     * Fold what this instance added since it last loaded or saved into the file
+     * as it is now, so processes saving independently never overwrite each other.
+     */
     private mergeWithPersisted;
-    private capData;
-    private extractInsightsFromEvictedSignals;
+    /**
+     * Every full group of 100 pending judged records is summarized into
+     * insights; the remainder waits for the next batch. A failing extractor never
+     * blocks the save, and the batch it failed on is not retried.
+     */
+    private summarizeCompleteBatches;
     private mergeInsights;
     private upsertEvidence;
-    private methodForSignal;
-    private sourceForSignal;
 }
 export declare function normalizeSessionEvidenceRef(input: Omit<SessionEvidenceRef, "stableEvidenceId"> & {
     readonly stableEvidenceId?: string;

package/dist/memory/renderer.d.ts

@@ -1,7 +1,16 @@
-import type { MethodHint, RetrievalContextHints, RetrievalInsight } from "./memory.js";
-export declare function renderMemoryContext(hints: readonly MethodHint[], opts?: {
-    maxHints?: number;
-    insights?: readonly RetrievalInsight[];
-    maxInsights?: number;
-    contextHints?: RetrievalContextHints;
-}): string;
+import type { JudgedEvidenceRecord } from "./judged-evidence.js";
+import type { RetrievalInsight } from "./memory.js";
+import type { SimilarQuestion } from "./similar-queries.js";
+/** Most recent judged records shown verbatim from one conversation; older ones are summarized. */
+export declare const CURRENT_CONVERSATION_RECORD_LIMIT = 50;
+export interface MemoryContextSections {
+    readonly current: readonly JudgedEvidenceRecord[];
+    readonly similar: readonly SimilarQuestion[];
+    readonly insights: readonly RetrievalInsight[];
+}
+/**
+ * Renders retrieval memory as advisory markdown for the librarian agent. Empty
+ * sections are omitted. Questions and evidence are JSON-quoted; insight table
+ * cells escape backslashes, pipes, and newlines to preserve the table structure.
+ */
+export declare function renderMemoryContext(sections: MemoryContextSections): string;

package/dist/memory/similar-queries.d.ts

@@ -0,0 +1,40 @@
+import type { Embedder } from "../embedding-runtime/gateway-embedder.js";
+import type { JudgedEvidenceRecord } from "./judged-evidence.js";
+/** How many similar past questions memory brings back for one question. */
+export declare const SIMILAR_QUESTION_LIMIT = 25;
+/**
+ * Cosine similarity below this is not a semantic match. Embedding models give
+ * unrelated short texts a clearly positive cosine, so a bare "top N by
+ * cosine" would always return something.
+ */
+export declare const VECTOR_MIN_SIMILARITY = 0.5;
+/** A past question and the evidence Jev kept for it, best evidence first. */
+export interface SimilarQuestion {
+    readonly question: string;
+    /** Fused BM25 + vector rank score; only meaningful for ordering. */
+    readonly score: number;
+    readonly records: readonly JudgedEvidenceRecord[];
+}
+export interface SimilarQuestionsOptions {
+    readonly limit?: number;
+    /** Adds semantic matching; without it only BM25 ranks. */
+    readonly embedder?: Embedder;
+    /** Where question vectors are cached; unset keeps them in memory for this call only. */
+    readonly vectorStorePath?: string;
+}
+export interface SimilarQuestionsResult {
+    readonly questions: readonly SimilarQuestion[];
+    /** Why semantic matching was skipped (verbatim error); absent when it ran or no embedder was given. */
+    readonly fallbackReason?: string;
+}
+/** The vector cache lives beside the memory file it indexes. */
+export declare function memoryVectorStorePath(memoryPath: string): string;
+/**
+ * Past questions that resemble `query`, with the evidence Jev judged to
+ * support each. Keyword (BM25) and semantic (vector) rankings are fused by
+ * reciprocal rank, so a question found by both outranks one found by either
+ * alone, and a rephrasing that shares no word with the query is still found
+ * semantically. Never throws: a failed embedder degrades to keywords only and
+ * says why.
+ */
+export declare function findSimilarQuestions(records: readonly JudgedEvidenceRecord[], query: string, options?: SimilarQuestionsOptions): Promise<SimilarQuestionsResult>;

package/dist/minsync/client.d.ts

@@ -14,7 +14,7 @@ export interface MinSyncClientOptions {
     readonly maxChunkSize?: number;
     readonly runtime?: MinSyncRuntime;
 }
-/** MinSync v0.4.5 supports native vector, BM25, and hybrid query modes. */
+/** MinSync v0.4.6 supports native vector, BM25, and hybrid query modes. */
 export type MinSyncQueryMode = "vector" | "bm25" | "hybrid";
 export declare class MinSyncQueryError extends Error {
     readonly code: number | null;

package/dist/minsync/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MinSync is the only retrieval method that searches document content
+ * semantically, so AutoRAG treats it as required: when it cannot be used there
+ * is no degraded mode that answers from other retrieval paths. This error is
+ * the one failure that is never swallowed per-method; it ends the operation and
+ * reaches the operator with the reason attached.
+ */
+export declare class MinSyncRequiredError extends Error {
+    constructor(message: string);
+}
+/** Raised when the `minsync` executable cannot be resolved. Path-free on purpose. */
+export declare function minSyncBinaryMissingError(): MinSyncRequiredError;
+/** Raised when auto-install ran and failed; carries the installer's own message. */
+export declare function minSyncInstallFailedError(cause: unknown): MinSyncRequiredError;

package/dist/minsync/index.d.ts

@@ -1,5 +1,6 @@
 export { MINSYNC_OLLAMA_MIGRATION_MESSAGE, MinSyncClient, type MinSyncClientOptions, MinSyncQueryError, type MinSyncQueryMode, } from "./client.js";
 export { configuredVectorDimension, DEFAULT_MINSYNC_EMBEDDER_CONFIG, DEFAULT_MINSYNC_EMBEDDER_DIMENSION, DEFAULT_MINSYNC_EMBEDDER_ID, MINSYNC_CONFIG_DIR, MINSYNC_CONFIG_FILE, type MinSyncEmbeddingIdentity, minSyncConfigPath, minSyncEmbeddingIdentityPath, rewriteEmbedderConfig, } from "./embedder-config.js";
+export { MinSyncRequiredError } from "./errors.js";
 export { type EnsureMinSyncBinaryOptions, ensureMinSyncBinary, executableName, fetchLatestMinSyncRelease, type InstalledMinSyncBinary, MINSYNC_VERSION, type MinSyncRelease, type MinSyncReleaseAsset, MinSyncReleaseError, selectReleaseAsset, } from "./installer.js";
 export { ensureLocalEmbedder, LocalEmbedderError, type LocalEmbedderPreflightOptions, } from "./local-embedder.js";
 export { MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";

package/dist/minsync/installer.d.ts

@@ -1,4 +1,4 @@
-export declare const MINSYNC_VERSION = "0.4.5";
+export declare const MINSYNC_VERSION = "0.4.6";
 export declare const MINSYNC_CARGO_INSTALL_TIMEOUT_MS: number;
 export interface MinSyncReleaseAsset {
     readonly name: string;

package/dist/minsync/method.d.ts

@@ -50,12 +50,12 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
      * auto-install runs only for `sync` (refresh); queries pass
      * `install: false` so a user's turn never waits on `cargo install`.
      *
-     * Returns: string path on success, undefined for missing-binary, or a MinSyncSyncResult
-     * for install-failed.
+     * Returns the executable path, or throws {@link MinSyncRequiredError}:
+     * MinSync is required, so there is no "no binary" value to degrade on.
      */
     protected resolveBinary(options?: {
         readonly install?: boolean;
-    }): Promise<string | undefined | MinSyncSyncResult>;
+    }): Promise<string>;
 }
 export declare class MinSyncHybridMethod extends MinSyncVectorMethod {
     constructor(options: MinSyncHybridMethodOptions);

package/dist/mirror/sync.d.ts

@@ -15,8 +15,11 @@ export interface ParsedMirrorSyncOptions {
     /** Absolute source paths or directories omitted by the user. */
     readonly userExcludedSourcePaths?: ReadonlySet<string>;
 }
-export type ParsedMirrorDiagnosticCode = "unsupported-file" | "parser-skipped" | "parser-failed" | "duplicate-excluded" | "deleted-mirror" | "stale-index" | "pdf-extract-thin" | "parser-warning";
-/** Path-opaque refresh diagnostic. `source` is an opaque virtual path, never a real fs path. */
+export type ParsedMirrorDiagnosticCode = "unsupported-file" | "parser-skipped" | "parser-failed" | "source-vanished" | "source-unreadable" | "duplicate-excluded" | "deleted-mirror" | "stale-index" | "pdf-extract-thin" | "parser-warning";
+/**
+ * Refresh diagnostic. `source` is an opaque virtual path, never a real filesystem path.
+ * `message` keeps the underlying error text, which may include a filesystem path.
+ */
 export interface ParsedMirrorDiagnostic {
     readonly code: ParsedMirrorDiagnosticCode;
     readonly severity: "info" | "warning";

package/dist/observability/run-log.d.ts

@@ -9,7 +9,7 @@ export type AutoRAGRunEvent = {
     timestamp: string;
     sessionId: string;
     resultCount: number;
-    /** True when the run ended without emit_autorag_results and fell back to a degraded response. */
+    /** True when the run ended without a final answer message and fell back to a degraded response. */
     degraded?: boolean;
 } | {
     event: "search_failed";

package/dist/parser/defaults.d.ts

@@ -1,16 +1,27 @@
 import { type LanguageTag } from "../language.js";
 import { type KordocParserOptions } from "./kordoc.js";
-import { type OcrParserOptions } from "./ocr.js";
+import { type OcrOptions } from "./ocr-engines.js";
 import { ParserRegistry } from "./registry.js";
 export interface DefaultParserRegistryOptions {
-    readonly ocr?: OcrParserOptions;
+    readonly ocr?: OcrOptions;
     readonly kordoc?: KordocParserOptions;
-    /** Global document languages; drives OCR engine selection. */
+    /** Global document languages; selects the OCR engine when OCR is enabled. */
     readonly languages?: readonly LanguageTag[];
 }
+/** Workspace-relative directory for Tesseract traineddata, so models never land in the process working directory. */
+export declare function tesseractCachePathFor(workspacePath: string): string;
 /**
  * Merges the globally configured document languages into registry options.
- * An explicit `parserOptions.languages` wins over the global setting.
+ * An explicit `parserOptions.languages` wins over the global setting. When a
+ * workspace is known, Tesseract's model cache is pinned under it unless the
+ * caller set `ocr.cachePath`.
+ */
+export declare function resolveParserOptions(parserOptions: DefaultParserRegistryOptions | undefined, languages: readonly LanguageTag[], workspacePath?: string): DefaultParserRegistryOptions;
+/**
+ * `ocr.enabled` is the single opt-in. Off: image files are not parsed and
+ * scanned pages are left unrecognized. On: kordoc owns both, and the
+ * configured languages pick the engine. kordoc's built-in PP-OCRv5 model is
+ * used only when every language is one it reads reliably; otherwise Tesseract
+ * is injected as kordoc's OCR provider. An explicit `kordoc.ocr` always wins.
  */
-export declare function resolveParserOptions(parserOptions: DefaultParserRegistryOptions | undefined, languages: readonly LanguageTag[]): DefaultParserRegistryOptions;
 export declare function createDefaultParserRegistry(options?: DefaultParserRegistryOptions): ParserRegistry;

package/dist/parser/index.d.ts

@@ -2,7 +2,7 @@ export { createDefaultParserRegistry, type DefaultParserRegistryOptions, resolve
 export { EmlParser } from "./eml.js";
 export { ParseError } from "./errors.js";
 export { KORDOC_EXTENSIONS, type KordocOcrProvider, type KordocParseFn, KordocParser, type KordocParserOptions, } from "./kordoc.js";
-export { ImageOcrParser, type OcrEngine, type OcrEngineInput, type OcrParserOptions } from "./ocr.js";
+export { BUILTIN_OCR_LANGUAGES, createTesseractOcrProvider, type OcrOptions, type OcrProvider, } from "./ocr-engines.js";
 export { PptxParser } from "./office.js";
 export { PlainTextParser } from "./plain-text.js";
 export { ParserRegistry } from "./registry.js";

package/dist/parser/kordoc.d.ts

@@ -33,10 +33,17 @@ export type KordocParseFn = (bytes: Uint8Array, options: KordocParseCallOptions)
 export interface KordocParserOptions {
     /** OCR mode handed to kordoc: off, built-in engine, or an injected provider. */
     readonly ocr?: boolean | "force" | KordocOcrProvider;
+    /** Also claim standalone image files; kordoc OCRs them whenever it parses them, so this follows the OCR switch. */
+    readonly images?: boolean;
     readonly parse?: KordocParseFn;
 }
 /** Document extensions kordoc parses. `.pptx` and `.eml` stay on their own parsers. */
 export declare const KORDOC_EXTENSIONS: readonly [".hwp", ".hwpx", ".hml", ".hwpml", ".pdf", ".docx", ".xlsx", ".xls"];
+/**
+ * Standalone image formats kordoc OCRs directly. `.bmp` and `.tiff` return
+ * `UNSUPPORTED_FORMAT` from kordoc, so they are deliberately not claimed.
+ */
+export declare const KORDOC_IMAGE_EXTENSIONS: readonly [".png", ".jpg", ".jpeg", ".webp"];
 /**
  * Parses HWP/HWPX/HWPML, PDF, DOCX and XLSX/XLS through the kordoc library.
  *
@@ -47,7 +54,7 @@ export declare const KORDOC_EXTENSIONS: readonly [".hwp", ".hwpx", ".hml", ".hwp
 export declare class KordocParser extends Parser {
     #private;
     readonly name = "kordoc";
-    readonly extensions: readonly [".hwp", ".hwpx", ".hml", ".hwpml", ".pdf", ".docx", ".xlsx", ".xls"];
+    readonly extensions: readonly string[];
     constructor(options?: KordocParserOptions);
     parse(input: ParseInput): Promise<ParseOutput>;
 }

package/dist/parser/ocr-engines.d.ts

@@ -1,9 +1,28 @@
 import type { LanguageTag } from "../language.js";
+/**
+ * Languages kordoc's built-in PP-OCRv5 model reads reliably. Its recognizer
+ * dictionary is Korean plus basic Latin: it has no kana, han, Cyrillic, Thai,
+ * Arabic or Devanagari, and on rendered text it drops diacritics (accented
+ * character recall fr 0.64, de 0.82, es 0.45 versus Tesseract 1.00, 0.91, 1.00).
+ * Any configured language outside this set switches OCR to Tesseract.
+ */
+export declare const BUILTIN_OCR_LANGUAGES: ReadonlySet<LanguageTag>;
+/** OCR switch and Tesseract settings. `enabled` is the single opt-in for image files and scanned pages. */
+export interface OcrOptions {
+    readonly enabled: boolean;
+    readonly timeoutMs?: number;
+    /**
+     * Directory where Tesseract stores downloaded traineddata. tesseract.js
+     * falls back to the process working directory when unset.
+     */
+    readonly cachePath?: string;
+}
 export type OcrProvider = (pageImage: Uint8Array, pageNumber: number, mimeType: "image/png" | "image/jpeg" | "image/webp") => Promise<string>;
 export type TesseractOcrEngine = (language: string, pageImage: Uint8Array, pageNumber: number, mimeType: "image/png" | "image/jpeg" | "image/webp") => Promise<string>;
 export interface TesseractOcrProviderOptions {
     readonly languages: readonly LanguageTag[];
     readonly timeoutMs?: number;
+    readonly cachePath?: string;
     readonly engine?: TesseractOcrEngine;
 }
 /** Traineddata codes for the configured languages, order preserved and deduplicated. */

package/dist/retrieval/bm25.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lightweight BM25-style lexical scorer shared by retrieval surfaces.
+ *
+ * Terms match document tokens exactly or as a prefix (min 2 chars), so
+ * agglutinative suffixes — Korean particles/endings (인증서 → 인증서를) and
+ * English inflections (index → indexing) — still rank. Prefix hits are
+ * slightly discounted against exact hits (0.75 weight).
+ */
+/**
+ * Lowercase `text` and split on anything that is not a letter, digit, or
+ * Hangul syllable, discarding empty tokens.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Score each entry of `documents` against `query` with a BM25-style formula.
+ * Returns one score per document, in the same order; unmatched documents
+ * score 0. Empty query terms or zero documents yield an array of zeros.
+ */
+export declare function bm25Scores(query: string, documents: readonly string[]): number[];