@autorag/librarian 2.6.3 → 2.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/NOTICE +6 -0
- package/README.md +76 -25
- package/dist/agent/agent.d.ts +135 -27
- package/dist/agent/answer-guidelines.d.ts +19 -0
- package/dist/agent/citations.d.ts +20 -0
- package/dist/agent/index.d.ts +1 -0
- package/dist/agent/jev-extension.d.ts +68 -0
- package/dist/agent/pi-session.d.ts +55 -0
- package/dist/agent/query-decomposition.d.ts +25 -0
- package/dist/agent/query-routing.d.ts +54 -0
- package/dist/agent/search-documents.d.ts +2 -2
- package/dist/agent/system-prompt.d.ts +1 -0
- package/dist/cli/commands/evidence.d.ts +22 -0
- package/dist/cli/commands/health.d.ts +2 -3
- package/dist/cli/commands/init.d.ts +2 -1
- package/dist/cli/commands/models.d.ts +20 -0
- package/dist/cli/commands/search.d.ts +2 -2
- package/dist/cli/commands/serve.d.ts +2 -2
- package/dist/cli/commands/tui.d.ts +12 -35
- package/dist/cli/commands/update-check.d.ts +8 -0
- package/dist/cli/config.d.ts +82 -5
- package/dist/cli/index.d.ts +1 -1
- package/dist/cli/index.js +9802 -9324
- package/dist/cli/update-check.d.ts +34 -0
- package/dist/cli/version.d.ts +5 -0
- package/dist/core.d.ts +34 -2
- package/dist/core.js +9848 -8977
- package/dist/everything/bundle.d.ts +15 -3
- package/dist/everything/client.d.ts +22 -5
- package/dist/everything/index.d.ts +1 -1
- package/dist/filesystem/name-search.d.ts +57 -0
- package/dist/fsearch/client.d.ts +7 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +11181 -9015
- package/dist/jikji/client.d.ts +6 -1
- package/dist/mcp/index.d.ts +2 -0
- package/dist/mcp/index.js +29949 -0
- package/dist/mcp/server.d.ts +9 -0
- package/dist/minsync/method.d.ts +6 -3
- package/dist/mirror/index.d.ts +1 -1
- package/dist/mirror/paths.d.ts +6 -0
- package/dist/retrieval/engine.d.ts +32 -1
- package/dist/retrieval/index.d.ts +2 -1
- package/dist/retrieval/rerank.d.ts +8 -3
- package/dist/retrieval/selection.d.ts +97 -0
- package/package.json +10 -3
- package/skills/autorag/SKILL.md +25 -4
- package/skills/autorag-doctor/SKILL.md +27 -18
- package/skills/autorag-lite-setup/SKILL.md +115 -59
- package/skills/autorag-setup/SKILL.md +99 -16
- package/dist/agent/bash-tool.d.ts +0 -32
- package/dist/cli/tui-commands.d.ts +0 -16
- package/dist/cli/tui-session-store.d.ts +0 -16
- package/skills/autorag-lite-search/SKILL.md +0 -245
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/server";
|
|
2
|
+
import type { AutoRAGLite } from "../core.js";
|
|
3
|
+
export interface AutoRAGMcpServerOptions {
|
|
4
|
+
readonly readOnly?: boolean;
|
|
5
|
+
readonly tools?: readonly string[];
|
|
6
|
+
/** Test/embedded override; defaults to the current Node platform. */
|
|
7
|
+
readonly platform?: NodeJS.Platform;
|
|
8
|
+
}
|
|
9
|
+
export declare function createAutoRAGMcpServer(lite: AutoRAGLite, options?: AutoRAGMcpServerOptions): McpServer;
|
package/dist/minsync/method.d.ts
CHANGED
|
@@ -32,7 +32,6 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
|
|
|
32
32
|
private readonly runtime;
|
|
33
33
|
private readonly defaultTopK;
|
|
34
34
|
private readonly scopedTopK;
|
|
35
|
-
private installFailed;
|
|
36
35
|
constructor(options: MinSyncVectorMethodOptions);
|
|
37
36
|
describe(): RetrievalMethodDescriptor;
|
|
38
37
|
sync(force?: boolean): Promise<MinSyncSyncResult>;
|
|
@@ -47,12 +46,16 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
|
|
|
47
46
|
private retrieveUnlocked;
|
|
48
47
|
/**
|
|
49
48
|
* Resolve the MinSync CLI from the user's global PATH first, then the
|
|
50
|
-
* workspace cache, and finally the verified auto-install fallback.
|
|
49
|
+
* workspace cache, and finally the verified auto-install fallback. The
|
|
50
|
+
* auto-install runs only for `sync` (refresh); queries pass
|
|
51
|
+
* `install: false` so a user's turn never waits on `cargo install`.
|
|
51
52
|
*
|
|
52
53
|
* Returns: string path on success, undefined for missing-binary, or a MinSyncSyncResult
|
|
53
54
|
* for install-failed.
|
|
54
55
|
*/
|
|
55
|
-
protected resolveBinary(
|
|
56
|
+
protected resolveBinary(options?: {
|
|
57
|
+
readonly install?: boolean;
|
|
58
|
+
}): Promise<string | undefined | MinSyncSyncResult>;
|
|
56
59
|
}
|
|
57
60
|
export declare class MinSyncHybridMethod extends MinSyncVectorMethod {
|
|
58
61
|
constructor(options: MinSyncHybridMethodOptions);
|
package/dist/mirror/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export type { ParsedMirrorEntry, ParsedMirrorIndex } from "./index-store.js";
|
|
2
2
|
export { emptyMirrorIndex, loadMirrorIndex, saveMirrorIndex } from "./index-store.js";
|
|
3
|
-
export { parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath } from "./paths.js";
|
|
3
|
+
export { isParsedRefreshComplete, parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath, } from "./paths.js";
|
|
4
4
|
export type { ParsedMirrorDiagnostic, ParsedMirrorDiagnosticCode, ParsedMirrorSyncOptions, ParsedMirrorSyncResult, } from "./sync.js";
|
|
5
5
|
export { DEFAULT_MAX_SOURCE_BYTES, detectMirrorStaleness, isPathExcluded, syncParsedMirrors } from "./sync.js";
|
package/dist/mirror/paths.d.ts
CHANGED
|
@@ -8,3 +8,9 @@ export declare function parsedMirrorIndexPath(root: string): string;
|
|
|
8
8
|
export declare function parsedOutputPath(root: string, virtualPath: string): string;
|
|
9
9
|
export declare function refreshReadinessPath(root: string): string;
|
|
10
10
|
export declare function refreshProgressPath(root: string): string;
|
|
11
|
+
/**
|
|
12
|
+
* Whether a parsed-mirror refresh has completed at least once for the given
|
|
13
|
+
* workspace. Reads the persisted readiness marker so a separate process (CLI,
|
|
14
|
+
* MCP server) reaches the same verdict as the process that ran the refresh.
|
|
15
|
+
*/
|
|
16
|
+
export declare function isParsedRefreshComplete(workspacePath: string): boolean;
|
|
@@ -15,7 +15,8 @@
|
|
|
15
15
|
*/
|
|
16
16
|
import { DatasourceAccessContext, type DatasourceAccessContextOptions } from "../datasource/access-context.js";
|
|
17
17
|
import { RetrievalMethodRegistry } from "./registry.js";
|
|
18
|
-
import type
|
|
18
|
+
import { type Reranker } from "./rerank.js";
|
|
19
|
+
import { type RetrievalSelection } from "./selection.js";
|
|
19
20
|
import type { RetrievalDiagnostic, RetrievalMethod, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } from "./types.js";
|
|
20
21
|
/** Options for constructing a standalone {@link RetrievalEngine}. */
|
|
21
22
|
export interface RetrievalEngineOptions {
|
|
@@ -41,6 +42,14 @@ export interface RetrievalEngineOptions {
|
|
|
41
42
|
* preservation — matching the existing {@link AutoRAGAgent} behavior.
|
|
42
43
|
*/
|
|
43
44
|
readonly isMinSyncBinaryMissing?: () => boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Authorized datasource ids from the skill catalog, including datasources
|
|
47
|
+
* that expose no retrieval methods. {@link retrieveSelected} uses this to
|
|
48
|
+
* tell an unknown datasource id from an unauthorized one. When omitted, the
|
|
49
|
+
* engine derives ids from its authorized registered methods; method-less
|
|
50
|
+
* datasources are then treated as unknown.
|
|
51
|
+
*/
|
|
52
|
+
readonly authorizedDatasourceIds?: () => readonly string[];
|
|
44
53
|
/**
|
|
45
54
|
* Optional post-merge reranker. When set, merged results are reordered by
|
|
46
55
|
* the reranker after dedup and score normalization. A reranker failure is
|
|
@@ -48,6 +57,11 @@ export interface RetrievalEngineOptions {
|
|
|
48
57
|
* the engine never silently drops evidence because a reranker was down.
|
|
49
58
|
*/
|
|
50
59
|
readonly reranker?: Reranker;
|
|
60
|
+
/**
|
|
61
|
+
* Number of merged results kept after reranking when the caller omits `topK`.
|
|
62
|
+
* Only applies when {@link reranker} is set. @default DEFAULT_RERANK_TOP_N
|
|
63
|
+
*/
|
|
64
|
+
readonly rerankTopN?: number;
|
|
51
65
|
}
|
|
52
66
|
/**
|
|
53
67
|
* Model-free retrieval pipeline.
|
|
@@ -79,7 +93,9 @@ export declare class RetrievalEngine {
|
|
|
79
93
|
private readonly defaultTopK;
|
|
80
94
|
private readonly defaultDedup;
|
|
81
95
|
private readonly isMinSyncBinaryMissing;
|
|
96
|
+
private readonly authorizedDatasourceIdsProvider;
|
|
82
97
|
private readonly reranker;
|
|
98
|
+
private readonly rerankTopN;
|
|
83
99
|
constructor(options?: RetrievalEngineOptions);
|
|
84
100
|
/** The underlying method registry. Intentionally public for tooling. */
|
|
85
101
|
getMethodRegistry(): RetrievalMethodRegistry;
|
|
@@ -124,6 +140,21 @@ export declare class RetrievalEngine {
|
|
|
124
140
|
diagnostics: RetrievalDiagnostic[];
|
|
125
141
|
unsearched: RetrievalUnsearchedSurface[];
|
|
126
142
|
}>;
|
|
143
|
+
/**
|
|
144
|
+
* Run a selected subset of the registered methods — parallel retrieve,
|
|
145
|
+
* datasource filter, merge — and return merged results with diagnostics.
|
|
146
|
+
*
|
|
147
|
+
* Unlike {@link retrieve}, selection happens BEFORE any backend is invoked:
|
|
148
|
+
* the eligible method list is reduced first, so an unselected or
|
|
149
|
+
* unauthorized datasource backend is never spawned. Unknown or unauthorized
|
|
150
|
+
* method/datasource selections throw {@link RetrievalSelectionError}. The
|
|
151
|
+
* trusted access context still narrows results/tags/scopes after retrieval.
|
|
152
|
+
*/
|
|
153
|
+
retrieveSelected(query: string, selection?: RetrievalSelection, options?: RetrievalOptions): Promise<{
|
|
154
|
+
results: RetrievalResult[];
|
|
155
|
+
diagnostics: RetrievalDiagnostic[];
|
|
156
|
+
unsearched: RetrievalUnsearchedSurface[];
|
|
157
|
+
}>;
|
|
127
158
|
/**
|
|
128
159
|
* Post-check for MinSync binary-missing diagnostic.
|
|
129
160
|
*
|
|
@@ -2,7 +2,8 @@ export { RetrievalEngine, type RetrievalEngineOptions } from "./engine.js";
|
|
|
2
2
|
export type { MergeOptions } from "./merger.js";
|
|
3
3
|
export { ParallelRetriever, ResultMerger } from "./merger.js";
|
|
4
4
|
export { RetrievalMethodRegistry } from "./registry.js";
|
|
5
|
-
export { type CreateRerankerOptions, createReranker, DEFAULT_RERANK_API_KEY_ENV, DEFAULT_RERANK_MODEL, DEFAULT_RERANK_PROVIDER, OpenRouterReranker, type OpenRouterRerankerOptions, type Reranker, type RerankerDescriptor, type RerankOptions, } from "./rerank.js";
|
|
5
|
+
export { type CreateRerankerOptions, createReranker, DEFAULT_RERANK_API_KEY_ENV, DEFAULT_RERANK_MODEL, DEFAULT_RERANK_PROVIDER, DEFAULT_RERANK_TOP_N, OpenRouterReranker, type OpenRouterRerankerOptions, type Reranker, type RerankerDescriptor, type RerankOptions, SUPPORTED_RERANK_PROVIDERS, } from "./rerank.js";
|
|
6
6
|
export { matchesVirtualPathScope, normalizeVirtualPath, normalizeVirtualPathScope, virtualPathScopeToRegExp, } from "./scope.js";
|
|
7
|
+
export { type DatasourceCatalogEntry, derivedAuthorizedDatasourceIds, type RetrievalSelection, RetrievalSelectionError, type RetrievalSelectionErrorCode, resolveSelectedMethods, } from "./selection.js";
|
|
7
8
|
export { describeRetrievalError, groupUnsearchedSurfaces, MINSYNC_SURFACE, type RetrievalSkip, retrievalSurfaceFor, } from "./skip.js";
|
|
8
9
|
export type { CuratedResult, NumberedResult, RetrievalDiagnostic, RetrievalDiagnosticCode, RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface, RetrievalWithDiagnostics, } from "./types.js";
|
|
@@ -18,6 +18,10 @@ export declare const DEFAULT_RERANK_MODEL = "voyageai/rerank-3-lite";
|
|
|
18
18
|
export declare const DEFAULT_RERANK_PROVIDER = "openrouter";
|
|
19
19
|
/** Default environment variable holding the OpenRouter API key. */
|
|
20
20
|
export declare const DEFAULT_RERANK_API_KEY_ENV = "OPENROUTER_API_KEY";
|
|
21
|
+
/** Default number of merged chunks kept after reranking. */
|
|
22
|
+
export declare const DEFAULT_RERANK_TOP_N = 25;
|
|
23
|
+
/** Rerank providers {@link createReranker} can build. */
|
|
24
|
+
export declare const SUPPORTED_RERANK_PROVIDERS: readonly string[];
|
|
21
25
|
/** Static description of a reranker, used for diagnostics and inspection. */
|
|
22
26
|
export interface RerankerDescriptor {
|
|
23
27
|
/** Stable label (e.g. `openrouter`). */
|
|
@@ -57,6 +61,8 @@ export interface RerankClient {
|
|
|
57
61
|
documents: string[];
|
|
58
62
|
topN?: number;
|
|
59
63
|
};
|
|
64
|
+
}, options?: {
|
|
65
|
+
signal?: AbortSignal;
|
|
60
66
|
}): Promise<RerankResponse>;
|
|
61
67
|
}
|
|
62
68
|
/** Response body returned by OpenRouter's rerank router. */
|
|
@@ -92,9 +98,8 @@ export interface CreateRerankerOptions extends OpenRouterRerankerOptions {
|
|
|
92
98
|
}
|
|
93
99
|
/**
|
|
94
100
|
* Build the configured reranker. Returns `undefined` when reranking is disabled
|
|
95
|
-
* or absent
|
|
96
|
-
*
|
|
97
|
-
* touching the retrieval pipeline.
|
|
101
|
+
* or absent. Throws for a provider AutoRAG cannot build (an unsupported
|
|
102
|
+
* `provider` id is a configuration error, not a silent no-op).
|
|
98
103
|
*/
|
|
99
104
|
export declare function createReranker(config: CreateRerankerOptions | false | undefined): Reranker | undefined;
|
|
100
105
|
/**
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Selection gating for the retrieval pipeline.
|
|
3
|
+
*
|
|
4
|
+
* `searchSelected` lets a caller narrow a search to specific datasources,
|
|
5
|
+
* specific methods, or the local (non-datasource) surfaces *before* any backend
|
|
6
|
+
* is invoked. This module owns that narrowing so the engine can reuse its
|
|
7
|
+
* existing parallel-retrieve / datasource-filter / merge chain on the reduced
|
|
8
|
+
* method list instead of fanning out to every backend and filtering afterwards.
|
|
9
|
+
*
|
|
10
|
+
* Security invariants:
|
|
11
|
+
* - Unauthorized datasource methods are never selected, whether or not the
|
|
12
|
+
* caller passed a selection — an unselected search still excludes them, so
|
|
13
|
+
* no denied backend is executed.
|
|
14
|
+
* - A caller-supplied selection can only *narrow* the trusted method set; it
|
|
15
|
+
* can never widen it. Unknown or unauthorized method/datasource names are
|
|
16
|
+
* rejected with a typed error, never silently resolved.
|
|
17
|
+
* - The trusted {@link DatasourceAccessContext} remains the sole authority:
|
|
18
|
+
* the `authorizedDatasourceIds` catalog is itself built from that context.
|
|
19
|
+
*/
|
|
20
|
+
import type { DatasourceAccessContext } from "../datasource/access-context.js";
|
|
21
|
+
import type { RetrievalMethod } from "./types.js";
|
|
22
|
+
/**
|
|
23
|
+
* Model-free, credential-free descriptor of one authorized configured
|
|
24
|
+
* datasource, for catalog/listing surfaces. Carries no credentials, config
|
|
25
|
+
* paths, or raw instance metadata — only the identity, capability tags, and
|
|
26
|
+
* the opaque source scope strings the access context authorizes.
|
|
27
|
+
*/
|
|
28
|
+
export interface DatasourceCatalogEntry {
|
|
29
|
+
/** Stable datasource id, e.g. `"kakao"`. */
|
|
30
|
+
readonly datasourceId: string;
|
|
31
|
+
/** Skill name, e.g. `"kakao"`. */
|
|
32
|
+
readonly name: string;
|
|
33
|
+
/** Skill kind, e.g. `"chat"` or `"chat-export"`. */
|
|
34
|
+
readonly type: string;
|
|
35
|
+
/** Human-readable description. */
|
|
36
|
+
readonly description: string;
|
|
37
|
+
/** Authorization tags that made this datasource accessible. */
|
|
38
|
+
readonly tags: readonly string[];
|
|
39
|
+
/** Capability names such as `"keyword"`, `"scoped"`, `"polling"`. */
|
|
40
|
+
readonly capabilities: readonly string[];
|
|
41
|
+
readonly status: "active" | "stub";
|
|
42
|
+
/**
|
|
43
|
+
* Authorized slash-hierarchical source scope strings discovered for this
|
|
44
|
+
* datasource. Scope-capable datasources expose only sources allowed by the
|
|
45
|
+
* trusted scope predicate; unscoped datasources expose their opaque sources.
|
|
46
|
+
*/
|
|
47
|
+
readonly sourceScopes: readonly string[];
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Caller request narrowing which retrieval methods run.
|
|
51
|
+
*
|
|
52
|
+
* Semantics (unambiguous, deny-widening):
|
|
53
|
+
* - `datasourceIds` omitted ⇒ every authorized datasource method is eligible.
|
|
54
|
+
* - `datasourceIds` present ⇒ ONLY methods of those datasources are eligible,
|
|
55
|
+
* plus the local (non-datasource) methods only when `local === true`.
|
|
56
|
+
* - `local === false` ⇒ no local method is ever eligible.
|
|
57
|
+
* - `methods` present ⇒ intersected with the eligible set; every named method
|
|
58
|
+
* must exist and (for datasource methods) be authorized.
|
|
59
|
+
*/
|
|
60
|
+
export interface RetrievalSelection {
|
|
61
|
+
/** Datasource ids to run. Omit to run all authorized datasources. */
|
|
62
|
+
readonly datasourceIds?: readonly string[];
|
|
63
|
+
/** Method names to run, intersected with the datasource/local selection. */
|
|
64
|
+
readonly methods?: readonly string[];
|
|
65
|
+
/** Whether local (non-datasource) methods run. See the semantics above. */
|
|
66
|
+
readonly local?: boolean;
|
|
67
|
+
}
|
|
68
|
+
export type RetrievalSelectionErrorCode = "unknown-method" | "unauthorized-method" | "unknown-datasource" | "unauthorized-datasource";
|
|
69
|
+
/** Thrown when a caller selection names an unknown or unauthorized target. */
|
|
70
|
+
export declare class RetrievalSelectionError extends Error {
|
|
71
|
+
readonly code: RetrievalSelectionErrorCode;
|
|
72
|
+
constructor(code: RetrievalSelectionErrorCode, message: string);
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Reduce the registered methods to the ones a selection authorizes to run.
|
|
76
|
+
*
|
|
77
|
+
* The returned list is built entirely from `methods`; a caller cannot conjure a
|
|
78
|
+
* method that is not registered. Datasource methods denied by `ctx` are dropped
|
|
79
|
+
* from the eligible set unconditionally, so they are never invoked. Explicit
|
|
80
|
+
* selections that name an unknown method or an unauthorized/unknown datasource
|
|
81
|
+
* throw {@link RetrievalSelectionError} rather than degrading silently.
|
|
82
|
+
*
|
|
83
|
+
* @param methods Every registered retrieval method.
|
|
84
|
+
* @param ctx Trusted, server-supplied access context.
|
|
85
|
+
* @param selection Caller narrowing request.
|
|
86
|
+
* @param authorizedDatasourceIds Authorized datasource ids from the catalog;
|
|
87
|
+
* used to distinguish an unknown id from an unauthorized one. Method-less
|
|
88
|
+
* authorized datasources belong here and select cleanly (yielding nothing).
|
|
89
|
+
*/
|
|
90
|
+
export declare function resolveSelectedMethods(methods: readonly RetrievalMethod[], ctx: DatasourceAccessContext, selection: RetrievalSelection, authorizedDatasourceIds: readonly string[]): RetrievalMethod[];
|
|
91
|
+
/**
|
|
92
|
+
* Authorized datasource ids derived directly from a method set and access
|
|
93
|
+
* context. Used as the fallback catalog for a standalone engine that has no
|
|
94
|
+
* datasource-skill catalog wired in; method-less datasources are unknowable
|
|
95
|
+
* here and therefore treated as unknown.
|
|
96
|
+
*/
|
|
97
|
+
export declare function derivedAuthorizedDatasourceIds(methods: readonly RetrievalMethod[], ctx: DatasourceAccessContext): string[];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@autorag/librarian",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.8.0",
|
|
4
4
|
"description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
}
|
|
22
22
|
},
|
|
23
23
|
"bin": {
|
|
24
|
-
"autorag": "dist/cli/index.js"
|
|
24
|
+
"autorag": "dist/cli/index.js",
|
|
25
|
+
"autorag-mcp": "dist/mcp/index.js"
|
|
25
26
|
},
|
|
26
27
|
"files": [
|
|
27
28
|
"dist",
|
|
@@ -35,7 +36,7 @@
|
|
|
35
36
|
"access": "public"
|
|
36
37
|
},
|
|
37
38
|
"scripts": {
|
|
38
|
-
"build": "bun build src/index.ts src/core.ts src/cli/index.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
|
|
39
|
+
"build": "bun build src/index.ts src/core.ts src/cli/index.ts src/mcp/index.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
|
|
39
40
|
"prepublishOnly": "bun run typecheck && bun run build",
|
|
40
41
|
"prepare": "bun run build",
|
|
41
42
|
"test": "node scripts/run-test-files.mjs",
|
|
@@ -54,10 +55,12 @@
|
|
|
54
55
|
"@earendil-works/pi-ai": "^0.86.1",
|
|
55
56
|
"@earendil-works/pi-coding-agent": "0.86.1",
|
|
56
57
|
"@earendil-works/pi-tui": "0.86.1",
|
|
58
|
+
"@modelcontextprotocol/server": "^2.3.0",
|
|
57
59
|
"@openrouter/sdk": "^1.4.21",
|
|
58
60
|
"chardet": "^2.2.0",
|
|
59
61
|
"fast-xml-parser": "^5.11.1",
|
|
60
62
|
"iconv-lite": "^0.7.3",
|
|
63
|
+
"jev-use": "^0.8.0",
|
|
61
64
|
"jszip": "^3.10.1",
|
|
62
65
|
"kordoc": "^4.15.7",
|
|
63
66
|
"mailparser": "^3.9.20",
|
|
@@ -71,11 +74,15 @@
|
|
|
71
74
|
},
|
|
72
75
|
"devDependencies": {
|
|
73
76
|
"@biomejs/biome": "2.5.14",
|
|
77
|
+
"@modelcontextprotocol/client": "^2.3.0",
|
|
74
78
|
"@types/mailparser": "^3.4.6",
|
|
75
79
|
"@types/node": "^26.4.1",
|
|
76
80
|
"@types/ws": "^8.18.1",
|
|
77
81
|
"typescript": "^7.0.2",
|
|
78
82
|
"vitest": "^5.0.0",
|
|
79
83
|
"xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
|
|
84
|
+
},
|
|
85
|
+
"overrides": {
|
|
86
|
+
"zod": "3.25.76"
|
|
80
87
|
}
|
|
81
88
|
}
|
package/skills/autorag/SKILL.md
CHANGED
|
@@ -47,15 +47,20 @@ refresh is enabled by default and can be disabled with
|
|
|
47
47
|
to `workspacePath`) that refresh keeps out of the parsed mirror and MinSync.
|
|
48
48
|
A folder entry excludes everything under it. Removing an entry and running
|
|
49
49
|
`autorag refresh --method minsync` indexes the file again. Excluded sources are
|
|
50
|
-
recorded as `user-excluded` skips, so they are not reported as stale.
|
|
50
|
+
recorded as `user-excluded` skips, so they are not reported as stale. Jikji
|
|
51
|
+
indexes the source folders directly and is not refreshed here, so AutoRAG also
|
|
52
|
+
drops excluded paths from the `jikji_find` answer pack and the baseline prefetch
|
|
53
|
+
at retrieval time; the on-disk `.jikji_agent_map.md` stays complete, and direct
|
|
54
|
+
file reads remain available.
|
|
51
55
|
|
|
52
56
|
`status` is model-free and path-opaque. `health` resolves the single model,
|
|
53
57
|
checks credential presence, and normally probes one live completion. If the
|
|
54
58
|
model, authentication, configuration, or indexes are unhealthy, use
|
|
55
59
|
`autorag-setup` rather than guessing private provider details.
|
|
56
60
|
|
|
57
|
-
MinSync and Jikji should normally be healthy.
|
|
58
|
-
|
|
61
|
+
MinSync and Jikji should normally be healthy. Answering a question never
|
|
62
|
+
builds or installs them: `autorag refresh` auto-installs both by default and
|
|
63
|
+
builds their indexes incrementally. If they are missing or stale, run a full
|
|
59
64
|
`autorag refresh` or return to setup rather than silently degrading to
|
|
60
65
|
lexical-only search.
|
|
61
66
|
|
|
@@ -71,7 +76,10 @@ autorag search "what were the key findings in the Q3 report" --top-k 5 --json --
|
|
|
71
76
|
|
|
72
77
|
`--json --debug` includes `answer`, numbered `results` (`number`, `title`,
|
|
73
78
|
`summary`, optional `source`), and `sessionId`. Use that `sessionId` for
|
|
74
|
-
feedback. `--json` without `--debug` is only `answer` plus `results`.
|
|
79
|
+
feedback. `--json` without `--debug` is only `answer` plus `results`. Every
|
|
80
|
+
bracketed `[n]` citation in `answer` resolves to a `results[].number` of the
|
|
81
|
+
same response; an unmatched citation is removed and reported as a
|
|
82
|
+
`citation-without-result` diagnostic.
|
|
75
83
|
|
|
76
84
|
To inspect the exact persisted evidence behind numbered results, use:
|
|
77
85
|
|
|
@@ -98,6 +106,19 @@ AutoRAG. The search loop can use Jikji, MinSync lexical/vector/hybrid retrieval,
|
|
|
98
106
|
direct source reading as appropriate. If search fails because of model,
|
|
99
107
|
provider, auth, or timeout problems, diagnose with `autorag health --json`.
|
|
100
108
|
|
|
109
|
+
Every search is two-phase: a fast answer, then verification. With Jev on (the
|
|
110
|
+
default, OpenRouter), Jev first routes the question:
|
|
111
|
+
|
|
112
|
+
- General knowledge or small talk is answered directly.
|
|
113
|
+
- Private-data questions use local search; public current facts use web search.
|
|
114
|
+
- A multi-part question is split into up to five parallel search queries.
|
|
115
|
+
|
|
116
|
+
After the fast answer, Jev ends the run if the answer is complete and
|
|
117
|
+
evidence-backed. So `results` may come straight from the fast answer, with no
|
|
118
|
+
verification phase. `--debug` diagnostics show the decision: `query-routed`
|
|
119
|
+
(branch and queries), `follow-up-skipped` (fast answer final), or
|
|
120
|
+
`query-route-fallback` (Jev unavailable, single local search).
|
|
121
|
+
|
|
101
122
|
Record feedback so retrieval memory can learn. Numbers refer to the returned
|
|
102
123
|
knowledge units. Supply at least one feedback list:
|
|
103
124
|
|
|
@@ -87,36 +87,41 @@ Rules:
|
|
|
87
87
|
|
|
88
88
|
## 3. Prove searchability
|
|
89
89
|
|
|
90
|
-
Indexing without retrieval is a failed run. Probe retrieval per datasource
|
|
91
|
-
the model-free
|
|
90
|
+
Indexing without retrieval is a failed run. Probe retrieval per datasource
|
|
91
|
+
through the model-free MCP tools, then once end to end:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
autorag.status {}
|
|
95
|
+
autorag.search {"query":"a word that certainly appears","topK":3}
|
|
96
|
+
autorag.search {"query":"recent topic","tags":["discord"],"topK":3}
|
|
97
|
+
autorag.search {"query":"recent mail subject","scope":"/mailcrawl/**","topK":3}
|
|
98
|
+
```
|
|
92
99
|
|
|
93
100
|
```bash
|
|
94
|
-
autorag lite retrieve "a word that certainly appears" --top-k 3 --json --debug
|
|
95
|
-
autorag lite retrieve "recent topic" --tags discord --top-k 3 --json --debug
|
|
96
|
-
autorag lite retrieve "recent mail subject" --scope "/mailcrawl/**" --top-k 3 --json --debug
|
|
97
101
|
autorag search "summarize the collection" --top-k 3 --json --debug
|
|
98
102
|
```
|
|
99
103
|
|
|
100
|
-
- **Always
|
|
104
|
+
- **Always read the `diagnostics` returned by MCP `autorag.search`.** A run
|
|
101
105
|
that silently dropped a whole retrieval method still looks successful, just
|
|
102
106
|
with fewer results; only the diagnostics name it (`minsync-unavailable`,
|
|
103
|
-
`retrieval-method-failed`). `autorag search --json`
|
|
104
|
-
`sessionId`, and per-result evidence unless `--debug` is
|
|
105
|
-
|
|
106
|
-
hides it without `--debug`.
|
|
107
|
+
`retrieval-method-failed`). The model-backed CLI `autorag search --json`
|
|
108
|
+
hides `diagnostics`, `sessionId`, and per-result evidence unless `--debug` is
|
|
109
|
+
set, so pass `--debug` when diagnosing that path.
|
|
107
110
|
- A method missing from the returned `method` values means that method
|
|
108
111
|
contributed nothing. During a full MinSync re-sync this is expected: the
|
|
109
112
|
store is being rebuilt, `minsync status` reports `NotSynced`, and local-file
|
|
110
113
|
hits stay absent until it finishes. Confirm with `minsync status` before
|
|
111
114
|
treating it as a failure, and never kill a running sync to "fix" it.
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
store
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
real and its source is
|
|
115
|
+
- MCP `autorag.search` needs no model, so it isolates retrieval from model
|
|
116
|
+
failures.
|
|
117
|
+
- Use the MCP `tags` / `scope` arguments to force one datasource; they can only
|
|
118
|
+
narrow trusted access, never grant it. A datasource absent from
|
|
119
|
+
`datasourceAccess` returns nothing no matter how healthy its store is — fix
|
|
120
|
+
the config, not the store.
|
|
121
|
+
- `autorag.evidence {"sessionId":"...","resultNumber":N}` shows the exact chunk
|
|
122
|
+
behind a numbered result; use it to confirm a hit is real and its source is
|
|
123
|
+
readable. The CLI `autorag evidence SESSION --json` remains for terminal
|
|
124
|
+
repair.
|
|
120
125
|
- Local-file hits must map to an absolute, existing path. Datasource hits keep
|
|
121
126
|
source-native identities such as `/kakao/personal/chunks/42`; those are not
|
|
122
127
|
filesystem paths and must never be passed to `cat`.
|
|
@@ -217,6 +222,10 @@ timer, or Task Scheduler).
|
|
|
217
222
|
| `unknown-datasource-skill` | Config name is not a known template | Fix the name or add `"type"` |
|
|
218
223
|
| `retrieval-method-failed` | One method errored during the query | Read `--debug` diagnostics |
|
|
219
224
|
| `auth-error` | Credentials missing or rejected | Report the env var name |
|
|
225
|
+
| `query-route-fallback` | Jev routing unavailable (often `OPENROUTER_API_KEY` unset); searched local with the original question | `test -n "$OPENROUTER_API_KEY"`; report the env var name, never its value |
|
|
226
|
+
| `query-decomposition-failed` | Decomposition model call failed; searched the original question | Check `queryDecomposition.model` resolves (`autorag models list --provider openrouter`) |
|
|
227
|
+
| `follow-up-check-fallback` | Jev post-fast-answer check unavailable; the run verified | Same as `query-route-fallback` |
|
|
228
|
+
| `query-routed` / `follow-up-skipped` | Info: Jev's branch and queries / fast answer judged final | None; working as intended |
|
|
220
229
|
|
|
221
230
|
## Report
|
|
222
231
|
|