@autorag/librarian 2.13.7 → 2.13.9

package/dist/find/groups.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The group runners behind `autorag lite find`: one model-free search per
+ * surface — the platform file-name index, local document content, and each
+ * connected datasource, each asked on its own so a slow one never blocks the
+ * rest.
+ */
+import type { RetrievalResult } from "../retrieval/types.js";
+import type { FindGroupDescriptor, FindGroupStatus, FindHit, FindJudge, FindRuntime } from "./types.js";
+/** The result of running one group. */
+export interface FindGroupOutcome {
+    readonly status: FindGroupStatus;
+    readonly hits: readonly FindHit[];
+    readonly error: string | null;
+}
+export interface FindGroupRunner {
+    readonly key: string;
+    readonly descriptor: FindGroupDescriptor;
+    run(): Promise<FindGroupOutcome>;
+}
+export interface BuildGroupRunnersOptions {
+    readonly query: string;
+    readonly topK: number;
+    readonly runtime: FindRuntime;
+    readonly judge?: FindJudge;
+    readonly platform?: NodeJS.Platform;
+    /** Whether the platform file-name index is enabled in config (default true). */
+    readonly fileSearchEnabled?: boolean;
+    /** Whether local semantic search is enabled in config (default true). */
+    readonly semanticEnabled?: boolean;
+    /** The enabled, registered datasources, in config order. */
+    readonly datasources?: readonly FindGroupDescriptor[];
+}
+/** A retrieval result as a datasource hit; exported for tests. */
+export declare function sourceHit(result: RetrievalResult, query: string): FindHit;
+export declare function buildGroupRunners(options: BuildGroupRunnersOptions): FindGroupRunner[];

package/dist/find/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `autorag lite find`: a model-free whole search across the platform file-name
+ * index, local document content, and every connected datasource. Pure and
+ * injectable (runtime, judge); the CLI wires the real ones and prints NDJSON.
+ */
+export { type BuildGroupRunnersOptions, buildGroupRunners, type FindGroupOutcome, type FindGroupRunner, sourceHit, } from "./groups.js";
+export { createRelevanceGate, JEV_RELEVANCE_THRESHOLD, type RelevanceCandidate, type RelevanceGateDeps, type SearchRelevanceGate, } from "./relevance.js";
+export { type FindRunOptions, runFind } from "./run.js";
+export { capContent, contentSnippet, escapeSearchRegex, everythingRegexQuery, fsearchRegexQuery, matchesQueryLexically, SEARCH_HIT_CONTENT_LIMIT, } from "./text.js";
+export type { FindDoneLine, FindGroupDescriptor, FindGroupLine, FindGroupStatus, FindGroupsLine, FindHit, FindJudge, FindJudgment, FindKind, FindLine, FindRuntime, FindSearchAnswer, FindVerdict, } from "./types.js";

package/dist/find/relevance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The relevance gate for the `content` and `source:*` groups.
+ *
+ * A deterministic lexical pass auto-keeps obvious hits; everything else goes to
+ * the decision model as batched `noul` questions, and only candidates with
+ * P(relevant) at or above {@link JEV_RELEVANCE_THRESHOLD} survive, ordered by
+ * probability. When no decision model can answer — the judge throws, or returns
+ * no numeric verdicts — every candidate is kept unfiltered (fail open).
+ */
+import type { FindJudge } from "./types.js";
+/** Minimum judged probability `P(relevant)` required for a non-lexical hit to be shown. */
+export declare const JEV_RELEVANCE_THRESHOLD = 0.5;
+export interface RelevanceCandidate {
+    readonly id: string;
+    readonly sourceLabel: string;
+    readonly title?: string | null;
+    readonly subtitle?: string | null;
+    readonly content: string;
+}
+export interface SearchRelevanceGate {
+    filter<T extends RelevanceCandidate>(query: string, candidates: readonly T[]): Promise<T[]>;
+}
+export interface RelevanceGateDeps {
+    readonly judge: FindJudge;
+    readonly threshold?: number;
+    readonly maxQuestionsPerBatch?: number;
+    readonly maxConcurrentBatches?: number;
+}
+export declare function createRelevanceGate(deps: RelevanceGateDeps): SearchRelevanceGate;

package/dist/find/run.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Orchestrates a whole search: emit the group list immediately, run every group
+ * in parallel, stream one group line per group in completion order, and finish
+ * with the done line. One group throwing never affects the others.
+ */
+import type { FindGroupDescriptor, FindJudge, FindLine, FindRuntime } from "./types.js";
+export interface FindRunOptions {
+    readonly query: string;
+    readonly topK: number;
+    readonly runtime: FindRuntime;
+    readonly judge?: FindJudge;
+    readonly platform?: NodeJS.Platform;
+    readonly fileSearchEnabled?: boolean;
+    readonly semanticEnabled?: boolean;
+    /** The enabled, registered datasources, in config order. */
+    readonly datasources?: readonly FindGroupDescriptor[];
+    /** `--groups` narrowing: run only these keys. */
+    readonly groups?: readonly string[];
+    /** Emit the `groups` line before running. Pass false when the caller already announced it. */
+    readonly announce?: boolean;
+    readonly emit: (line: FindLine) => void;
+    readonly now?: () => number;
+}
+export declare function runFind(options: FindRunOptions): Promise<void>;

package/dist/find/text.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Text helpers for the whole-search groups: the relevance gate's deterministic
+ * lexical pass, the one-line snippet, and the platform file-name regexes.
+ *
+ * The lexical pass is ported from the Finder's `matchesQueryLexicallyOrApprox`
+ * with the approximate edit-distance step dropped, so it stays dependency-free.
+ */
+/** Passed text a hit carries, capped at this many characters. */
+export declare const SEARCH_HIT_CONTENT_LIMIT = 2000;
+/** The passage as one line, cut to {@link SNIPPET_LENGTH} around the first query term that appears in it. */
+export declare function contentSnippet(text: string, query: string): string;
+/** The passage flattened to one line and capped at {@link SEARCH_HIT_CONTENT_LIMIT} characters. */
+export declare function capContent(text: string): string;
+/**
+ * Fast deterministic pass-through before Jev: exact query word match (NFKC
+ * case-folded, ASCII boundary-aware so `_`/`-`/Hangul neighbors work while
+ * partial stems like `art` in `start` do not, plus Korean postposition
+ * stripping like `비행기를` → `비행기`). The approximate edit-distance step the
+ * Finder had is intentionally dropped: this is dependency-free.
+ */
+export declare function matchesQueryLexically(query: string, candidateText: string): boolean;
+/** Escape a literal query so an index's regex mode matches it as a substring. */
+export declare function escapeSearchRegex(text: string): string;
+/**
+ * Regex for the fsearch index. macOS stores Hangul file names decomposed (NFD)
+ * while typed queries are composed (NFC), and the index compares bytes, so a
+ * name matches only when the query uses the same form. Sending both forms as an
+ * alternation finds either spelling; a query that has one form (ASCII) stays the
+ * plain escaped substring.
+ */
+export declare function fsearchRegexQuery(text: string): string;
+/**
+ * Everything's `regex:` search function is the working regex surface on the
+ * bundled ES build. A bare space ends the function's argument, so spaces become
+ * `\x20` to keep a literal substring.
+ */
+export declare function everythingRegexQuery(text: string): string;

package/dist/find/types.d.ts

@@ -0,0 +1,86 @@
+import type { Question } from "jev-use";
+import type { EverythingSearchRequest, EverythingSearchResult } from "../everything/index.js";
+import type { FSearchSearchRequest, FSearchSearchResult } from "../fsearch/index.js";
+import type { RetrievalSelection } from "../retrieval/selection.js";
+import type { RetrievalDiagnostic, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } from "../retrieval/types.js";
+/** What a whole-search hit is: a file name, document content, or a datasource message. */
+export type FindKind = "file" | "content" | "message";
+/** One hit on one group, shared by the filename, content, and datasource surfaces. */
+export interface FindHit {
+    readonly id: string;
+    readonly kind: FindKind;
+    readonly title: string;
+    readonly author: string | null;
+    readonly snippet: string;
+    /** Passed text, capped at {@link SEARCH_HIT_CONTENT_LIMIT} characters. */
+    readonly content: string;
+    /** Absolute local path for file and content hits; null for datasource messages. */
+    readonly path: string | null;
+    readonly line: number | null;
+    /** Epoch milliseconds, when the source states one. */
+    readonly timestamp: number | null;
+    readonly url: string | null;
+    readonly score: number | null;
+}
+/** The group list line, printed before any group runs. */
+export interface FindGroupDescriptor {
+    readonly key: string;
+    readonly datasourceId?: string;
+    readonly datasourceType?: string;
+}
+/** `off` = the surface is disabled in config; `unavailable` = its index is not built. */
+export type FindGroupStatus = "ready" | "error" | "off" | "unavailable";
+export interface FindGroupsLine {
+    readonly type: "groups";
+    readonly groups: readonly FindGroupDescriptor[];
+}
+export interface FindGroupLine {
+    readonly type: "group";
+    readonly key: string;
+    readonly status: FindGroupStatus;
+    readonly hits: readonly FindHit[];
+    /** The group's own failure text verbatim, or null. */
+    readonly error: string | null;
+    readonly elapsedMs: number;
+}
+export interface FindDoneLine {
+    readonly type: "done";
+    readonly elapsedMs: number;
+}
+export type FindLine = FindGroupsLine | FindGroupLine | FindDoneLine;
+/** The answer shape `searchSelected` returns; a structural subset of the retrieval engine's. */
+export interface FindSearchAnswer {
+    readonly results: readonly RetrievalResult[];
+    readonly diagnostics: readonly RetrievalDiagnostic[];
+    readonly unsearched: readonly RetrievalUnsearchedSurface[];
+}
+/**
+ * The model-free runtime a whole search drives. `AutoRAGLite` satisfies it
+ * structurally; tests inject a fake. Only these methods are touched, so a
+ * search never enters the model-backed agent loop.
+ */
+export interface FindRuntime {
+    listDatasources(): readonly {
+        readonly datasourceId: string;
+    }[];
+    searchSelected(query: string, selection?: RetrievalSelection, options?: RetrievalOptions): Promise<FindSearchAnswer>;
+    searchFsearch(request: FSearchSearchRequest): Promise<FSearchSearchResult>;
+    searchEverything(request: EverythingSearchRequest): Promise<EverythingSearchResult>;
+}
+/**
+ * One batched `noul` judgment over relevance questions. The real implementation
+ * is `createDecisionModels(...).judge`; a thrown error means "no decision model
+ * can answer", and the gate fails open.
+ */
+export type FindJudge = (state: string, questions: Question[]) => Promise<FindJudgment>;
+/** The verdicts the gate reads; a structural subset of `jev-use`'s `JudgeResult`. */
+export interface FindJudgment {
+    readonly verdicts: readonly FindVerdict[];
+}
+export interface FindVerdict {
+    readonly id: string;
+    readonly type?: string;
+    readonly answer: number | string | null;
+    readonly confidence?: number;
+    readonly escalate?: boolean;
+}