@autorag/librarian 2.7.0 → 2.8.0

package/dist/agent/query-decomposition.d.ts

@@ -0,0 +1,25 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+/** Hard cap on search queries one question may decompose into. */
+export declare const MAX_DECOMPOSED_QUERIES = 5;
+/** Prompt in, raw completion text out. The seam the decomposer calls. */
+export type DecompositionCompleter = (prompt: string) => Promise<string>;
+/** A pi-ai model plus the credential used only for decomposition calls. */
+export interface DecompositionModel {
+    readonly model: Model<Api>;
+    readonly apiKey?: string;
+}
+export declare function buildDecompositionPrompt(query: string): string;
+/**
+ * Parse the model's reply into at most {@link MAX_DECOMPOSED_QUERIES} unique,
+ * non-empty queries. Accepts `{"queries": [...]}`, a bare array (optionally
+ * fenced or wrapped in prose), or one query per line as a last resort.
+ */
+export declare function parseDecomposedQueries(text: string): string[];
+/**
+ * Decompose one question into up to {@link MAX_DECOMPOSED_QUERIES} search
+ * queries. A reply with no usable query falls back to the original question,
+ * so the caller always has something to search.
+ */
+export declare function decomposeQuery(complete: DecompositionCompleter, query: string): Promise<string[]>;
+/** Completer over a pi-ai model: one user turn, thinking off, short output. */
+export declare function createModelDecompositionCompleter(target: DecompositionModel, signal?: AbortSignal): DecompositionCompleter;

package/dist/agent/query-routing.d.ts

@@ -0,0 +1,54 @@
+import type { JevJudge } from "./jev-extension.js";
+/**
+ * Where a user question is answered from:
+ * - `local`: information only the user can reach (their files, chats, mail).
+ * - `web`: public information one internet search would answer.
+ * - `direct`: general knowledge or small talk the model answers on its own.
+ */
+export type QueryRoute = "local" | "web" | "direct";
+/** Jev question id of the three-way branch. */
+export declare const QUERY_ROUTE_QUESTION_ID = "route";
+/** Jev question id of the "does this need decomposition?" check. */
+export declare const DECOMPOSE_QUESTION_ID = "decompose";
+/** Jev question id of the post-fast-answer "needs follow-up?" check. */
+export declare const FOLLOW_UP_QUESTION_ID = "follow_up";
+/** Route used whenever Jev gives no usable branch: today's local search. */
+export declare const FALLBACK_QUERY_ROUTE: QueryRoute;
+/** A `noul` probability at or above this asks for question decomposition. */
+export declare const DECOMPOSE_PROBABILITY_THRESHOLD = 0.5;
+/** A `noul` probability at or above this sends the fast answer on to verification. */
+export declare const FOLLOW_UP_PROBABILITY_THRESHOLD = 0.5;
+export interface FollowUpDecision {
+    /** True when the run continues into the verification phase. */
+    readonly followUp: boolean;
+    /** Jev's P(follow-up needed), when it answered. */
+    readonly probability?: number;
+    /** Why the check fell back to verifying instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Ask Jev whether the fast answer needs correction, clarification, or further
+ * research. Never throws: a missing credential, an unreachable backend, or a
+ * verdict with no probability keeps verifying, because ending early on an
+ * unchecked answer is the costlier mistake.
+ */
+export declare function needsFollowUp(judge: JevJudge, query: string, answer: string): Promise<FollowUpDecision>;
+export interface QueryRouteDecision {
+    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none. */
+    readonly route: QueryRoute;
+    /** True when Jev judged the question needs decomposition (never for `direct`). */
+    readonly decompose: boolean;
+    /** Probability Jev gave the chosen branch, when it reported a distribution. */
+    readonly routeProbability?: number;
+    /** Jev's P(decomposition needed), when it answered. */
+    readonly decomposeProbability?: number;
+    /** Why the decision fell back instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Ask Jev, in one batched call about the user question, which branch answers
+ * it and whether it needs decomposition. Never throws: a missing credential,
+ * an unreachable backend, or an unusable verdict falls back to a single local
+ * search, with the reason recorded.
+ */
+export declare function routeQuery(judge: JevJudge, query: string): Promise<QueryRouteDecision>;

package/dist/agent/search-documents.d.ts

@@ -10,7 +10,7 @@ export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
  * (#21/#22) does not require another source-breaking type change; codes not yet
  * emitted are still valid members.
  */
-export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "minsync-staging-excluded" | "minsync-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit" | "model-request-failed";
+export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "minsync-staging-excluded" | "minsync-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit" | "model-request-failed" | "query-routed" | "query-route-fallback" | "query-decomposition-failed" | "follow-up-skipped" | "follow-up-check-fallback" | "citation-without-result";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;
@@ -107,5 +107,5 @@ export declare function createEmptySearchDocumentsResponse(sessionId: string, qu
 export declare function recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails, sessions: SearchSessions, memory: RetrievalMemory, componentDiagnostics?: readonly SearchDocumentDiagnostic[], options?: {
     readonly isolateMemory?: boolean;
 }): SearchDocumentsResponse;
-export declare function recordNumberedFeedback(sessions: ReadonlySearchSessions, memory: RetrievalMemory, sessionId: string, usefulNumbers: readonly number[], notUsefulNumbers: readonly number[]): void;
+export declare function recordNumberedFeedback(sessions: ReadonlySearchSessions, memory: RetrievalMemory, sessionId: string, usefulNumbers: readonly number[], notUsefulNumbers: readonly number[]): boolean;
 export {};

package/dist/agent/system-prompt.d.ts

@@ -9,5 +9,6 @@ export interface SystemPromptConfig {
     jikjiIndexingEnabled?: boolean;
     datasourceSkills?: readonly Skill[];
     retrievedContentGuard?: boolean;
+    remoteSession?: boolean;
 }
 export declare function buildSystemPrompt(config: SystemPromptConfig): string;

package/dist/cli/commands/evidence.d.ts

@@ -1,3 +1,25 @@
+import type { MemorySchemaV4 } from "../../memory/memory.js";
 import type { CommandContext } from "./types.js";
+interface EvidenceView {
+    readonly stableEvidenceId: string;
+    readonly method: string;
+    readonly source: string;
+    readonly excerpt?: string;
+    readonly content?: string;
+    readonly retrievalResultId?: string;
+    readonly chunkIndex?: number;
+    readonly lineNumber?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+export declare function evidenceFor(schema: MemorySchemaV4, sessionId: string, resultNumber?: number): {
+    sessionId: string;
+    results: {
+        number: number;
+        title: string;
+        summary: string;
+        chunks: EvidenceView[];
+    }[];
+};
 /** Show the persisted source/chunk evidence attached to a search session. */
 export declare function runEvidence(ctx: CommandContext): Promise<number>;
+export {};

package/dist/cli/commands/init.d.ts

@@ -4,6 +4,7 @@ import type { CommandContext } from "./types.js";
  * Model flags are folded into the generated config. A legacy
  * `autorag.config.json` in the current working directory may be migrated
  * non-destructively. An existing home config is not overwritten without
- * `--force`.
+ * `--force`, and `--force` only replaces an existing config when the caller
+ * selected the path explicitly (`--config` or `AUTORAG_CONFIG`).
  */
 export declare function runInit(ctx: CommandContext): Promise<number>;

package/dist/cli/commands/update-check.d.ts

@@ -0,0 +1,8 @@
+import { type AutoRAGUpdateResult } from "../update-check.js";
+import type { CommandContext } from "./types.js";
+export interface UpdateCheckDeps {
+    readonly currentVersion?: string;
+    readonly check?: (currentVersion: string) => Promise<AutoRAGUpdateResult>;
+}
+/** `autorag update-check`: compare the running package against the npm registry. */
+export declare function runUpdateCheck(ctx: CommandContext, deps?: UpdateCheckDeps): Promise<number>;

package/dist/cli/config.d.ts

@@ -1,7 +1,9 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { AutoRAGAgentOptions, AutoRAGRetrievalLimits } from "../agent/agent.js";
+import type { JevBackendName } from "../agent/jev-extension.js";
 import { type LoadLocalAutoRAGModelOptions } from "../agent/local-model.js";
+import type { DecompositionModel } from "../agent/query-decomposition.js";
 import type { DatasourceAccessContextOptions } from "../datasource/access-context.js";
 import { type DatasourcesConfig } from "../datasource/skills/factory.js";
 import type { EnsureMinSyncBinaryOptions, MinSyncEmbedderConfig } from "../minsync/index.js";
@@ -51,6 +53,26 @@ export interface WebSearchCliConfig {
         timeoutSeconds?: number;
     } | false;
 }
+/**
+ * Jev decision-tool config. Absent disables the tool; `enabled: false` disables
+ * it explicitly. Secrets never appear here: the `jev-use` engine reads the
+ * backend credential from its own environment variable (`TYPESAFE_API_KEY`,
+ * `OPENROUTER_API_KEY`, or `AI_GATEWAY_API_KEY`).
+ */
+export interface JevCliConfig {
+    enabled?: boolean;
+    /** Force one backend; omit to let the first credential present win. */
+    backend?: JevBackendName;
+    /** Model id sent with every call, e.g. `jev-latest`. */
+    model?: string;
+    /** Escalate verdicts below this confidence (0-1). Default: per-source thresholds. */
+    confidenceThreshold?: number;
+}
+/** Question-decomposition config. Secrets stay in env/pi auth like the main model. */
+export interface QueryDecompositionConfig {
+    /** Dedicated decomposition model; same shape and auth rules as the top-level `model`. */
+    model?: AgentModelConfig;
+}
 /**
  * Post-merge reranking config. Routes merged evidence through a dedicated
  * rerank model. `provider` is `openrouter` today; `model` is the OpenRouter
@@ -68,7 +90,7 @@ export interface RerankConfig {
     apiKeyEnv?: string;
     /** Override the provider base URL (e.g. a gateway). */
     baseUrl?: string;
-    /** Return only the top N merged results. Omitted ⇒ all distinct results are reordered. */
+    /** Return only the top N merged results. @default 25 (DEFAULT_RERANK_TOP_N) */
     topN?: number;
     /** Per-request timeout in milliseconds. */
     timeoutMs?: number;
@@ -145,6 +167,21 @@ export interface CliConfig {
         watch?: boolean;
     } | false;
     webSearch?: WebSearchCliConfig;
+    /**
+     * Jev query routing (local / web / direct), the decomposition check, the
+     * post-fast-answer follow-up check, and the `jev` tool. On by default with
+     * the OpenRouter backend; `false` or `enabled: false` disables it. Secrets
+     * never appear here: `jev-use` reads the backend key from its own
+     * environment variable.
+     */
+    jev?: JevCliConfig | false;
+    /**
+     * Question decomposition for the Jev query pipeline. `model` names the LLM
+     * that splits one question into at most five search queries; absent or `{}`
+     * uses {@link DEFAULT_QUERY_DECOMPOSITION_MODEL}, and `false` lets the
+     * agent's own model decompose.
+     */
+    queryDecomposition?: QueryDecompositionConfig | false;
     /** Post-merge reranking. Absent ⇒ reranking disabled. `false` disables it. */
     rerank?: RerankConfig | false;
     parserOptions?: Record<string, unknown>;
@@ -205,6 +242,19 @@ export declare function resolveConfig(input: ResolveConfigInput): CliConfig;
  * would resolve them but never copied into `~/.autorag/config.json`.
  */
 export declare function resolveConfigReadOnly(input: ResolveConfigInput): CliConfig;
+/** Validate and normalize the `jev` config section. */
+export declare function normalizeJevConfig(raw: unknown): JevCliConfig;
+/** Jev backend used when the config names none (absent section or `{}`). */
+export declare const DEFAULT_JEV_BACKEND: JevBackendName;
+/**
+ * Question-decomposition model used when the config names none. Picked from a
+ * live OpenRouter bench (6 questions incl. Korean, 2 runs each): 12/12 valid,
+ * covering, language-preserving decompositions at ~0.9s p50, about 3.5x
+ * cheaper per call than google/gemini-2.5-flash-lite at equal quality.
+ */
+export declare const DEFAULT_QUERY_DECOMPOSITION_MODEL: AgentModelConfig;
+/** Validate the `queryDecomposition` config section (`false` = decompose with the session model). */
+export declare function normalizeQueryDecompositionConfig(raw: unknown): QueryDecompositionConfig | false;
 /** Normalize and validate the `rerank` config section, filling in defaults. */
 export declare function normalizeRerankConfig(raw: unknown, path: string): RerankConfig | false;
 export declare function buildAgentOptions(config: CliConfig): Omit<AutoRAGAgentOptions, "model">;
@@ -253,6 +303,13 @@ export interface ResolvedAgentModelDetailed {
     readonly role: ResolvedAgentModelRole;
 }
 export declare function resolveAgentModel(config: CliConfig, options?: ResolveAgentModelOptions): Promise<ResolvedAgentModel>;
+/**
+ * Resolve the question-decomposition model and its credential through the same
+ * chain as the agent model. An absent section or `{}` uses
+ * {@link DEFAULT_QUERY_DECOMPOSITION_MODEL}; `queryDecomposition: false`
+ * returns undefined so the agent's own model decomposes.
+ */
+export declare function resolveQueryDecompositionModel(config: CliConfig, options?: ResolveAgentModelOptions): Promise<DecompositionModel | undefined>;
 export declare function resolveAgentModelDetailed(config: CliConfig, options?: ResolveAgentModelOptions): Promise<ResolvedAgentModelDetailed>;
 export declare function readRawConfigObject(path: string): Record<string, unknown>;
 /** Atomically replace a config file, preserving the caller's JSON object. */
@@ -262,4 +319,12 @@ export declare function writeDefaultConfig(path: string, partial: Partial<CliCon
     atomicCreate?: boolean;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Whether the target path was selected explicitly by the caller
+     * (`--config` / `AUTORAG_CONFIG`). When `false`, `force` refuses to
+     * replace an existing file: an implicit home config may only be
+     * replaced through an explicit config path. `undefined` (callers that
+     * do not distinguish) keeps the historical force semantics.
+     */
+    explicit?: boolean;
 }): void;

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const COMMANDS: readonly ["init", "setup", "refresh", "status", "search", "feedback", "evidence", "memory", "index", "watch", "health", "duplicates", "tui", "serve", "p2p", "lite", "models", "gateway"];
+declare const COMMANDS: readonly ["init", "setup", "refresh", "status", "search", "feedback", "evidence", "memory", "index", "watch", "health", "duplicates", "tui", "serve", "p2p", "lite", "models", "gateway", "update-check"];
 type CommandName = (typeof COMMANDS)[number];
 export type { CommandName };
 interface ParsedArgs {