@lacneu/openclaw-knowledge 3.1.2 → 3.2.0

package/dist/jina/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Embedding model used as backbone for Classifier zero-shot requests.
+ * The Reranker endpoint uses its own model identifiers (see RerankerModel).
+ */
+export type ClassifierEmbeddingModel = "jina-embeddings-v3" | "jina-embeddings-v4" | "jina-clip-v2";
+/**
+ * Supported Jina reranker models.
+ *
+ * - `jina-reranker-v2-base-multilingual` (default in this plugin) — trained on
+ *   100+ languages, ideal for French content. Context cap: 8 192 tokens.
+ * - `jina-reranker-v3` — bigger context (131 K), primarily English-trained.
+ * - `jina-reranker-m0` — multimodal.
+ * - `jina-colbert-v2` — late-interaction.
+ */
+export type RerankerModel = "jina-reranker-v2-base-multilingual" | "jina-reranker-v3" | "jina-reranker-m0" | "jina-colbert-v2" | (string & {});
+/**
+ * Input element for the Classifier endpoint. Text-only is what the plugin
+ * uses; the API also supports `{image: "..."}` with `jina-clip-v2`, but the
+ * router never classifies images.
+ */
+export interface ClassifierTextInput {
+    text: string;
+}
+/**
+ * Zero-shot classification request body for POST /v1/classify.
+ *
+ * `labels` must contain semantic category strings (the Classifier embeds
+ * them and picks the closest one to each input). At least 2 labels.
+ */
+export interface JinaClassifyZeroShotRequest {
+    model: ClassifierEmbeddingModel;
+    input: ClassifierTextInput[];
+    labels: string[];
+}
+/**
+ * Few-shot classification request body for POST /v1/classify (with a
+ * pre-trained classifier_id obtained out-of-band — the plugin does NOT
+ * implement /v1/train; operators train via the Jina Playground or CLI and
+ * paste the ID into the plugin config).
+ */
+export interface JinaClassifyFewShotRequest {
+    classifier_id: string;
+    input: ClassifierTextInput[];
+}
+export type JinaClassifyRequest = JinaClassifyZeroShotRequest | JinaClassifyFewShotRequest;
+/**
+ * Normalized classification outcome as seen by the rest of the plugin.
+ * `label` is the picked class. `score` is the confidence in [0, 1] when
+ * Jina returns it; `null` when the field is not in the response (the
+ * defensive parser still produces a label in that case).
+ */
+export interface ClassificationOutcome {
+    label: string;
+    score: number | null;
+}
+/**
+ * Reranker request body for POST /v1/rerank.
+ *
+ * We always send `return_documents: false`: the caller already holds the
+ * original documents (PgvectorResult[]) and only needs the new ordering. This
+ * saves a meaningful chunk of egress tokens on large payloads.
+ */
+export interface JinaRerankRequest {
+    model: RerankerModel;
+    query: string;
+    documents: string[];
+    top_n?: number;
+    return_documents: false;
+    truncate?: boolean;
+}
+/**
+ * Single reranked result item — `index` references the original `documents`
+ * array position.
+ */
+export interface RerankedItem {
+    index: number;
+    score: number;
+}

package/dist/jina/types.js

@@ -0,0 +1,12 @@
+// Jina AI API request/response types.
+//
+// Documented at:
+//   https://jina.ai/classifier/   (POST /v1/classify, zero-shot + few-shot)
+//   https://jina.ai/reranker/     (POST /v1/rerank)
+//
+// We deliberately keep the response shapes flexible (`unknown`-leaning) so the
+// parser can stay defensive: Jina has changed field names between iterations
+// (e.g. `predictions[]` vs `results[]`), and a brittle interface would mask
+// silent breakage. Strong typing happens at the parser boundary.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jina/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jina/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,iBAAiB;AACjB,4EAA4E;AAC5E,oDAAoD;AACpD,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,iEAAiE"}

package/dist/pgvector.d.ts

@@ -1,3 +1,4 @@
+import type { RerankerModel } from "./jina/types.js";
 import type { PgPoolLike, PgvectorResult } from "./types.js";
 /**
  * Search a single collection in `knowledge_vectors` using cosine similarity.
@@ -19,3 +20,31 @@ export declare function searchCollection(pool: PgPoolLike, collection: string, v
  * easily skip empty sections.
  */
 export declare function formatPgvectorResults(results: PgvectorResult[], maxChars: number): string | null;
+export interface RerankPgvectorParams {
+    apiKey: string;
+    query: string;
+    model?: RerankerModel;
+    /** Cap on the number of results returned post-rerank. */
+    topN?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Re-order `results` using the Jina cross-encoder reranker.
+ *
+ * This is the precision stage on top of pgvector's recall: the cosine pass
+ * grabs ~20 coarse candidates, the reranker promotes the ones that actually
+ * match the user's intent.
+ *
+ * Contract:
+ * - On success, returns at most `topN` items in descending relevance order.
+ *   The original cosine `score` is **preserved** on each item; the reranker
+ *   produces its own score we expose via the log event, not in the
+ *   PgvectorResult.
+ * - On any error (including auth / rate limit), throws a `JinaError`. The
+ *   caller is responsible for falling back to the original cosine order —
+ *   we do NOT swallow here because the caller wants to track the failure
+ *   for the cooldown breaker.
+ * - On empty input, returns `[]` without hitting the network.
+ */
+export declare function rerankPgvectorResults(results: PgvectorResult[], params: RerankPgvectorParams): Promise<PgvectorResult[]>;

package/dist/pgvector.js

@@ -4,6 +4,12 @@
 // `halfvec(3072)` because pgvector's HNSW implementation caps at 2000 dims
 // for the native `vector` type. Both the column cast and the query parameter
 // cast must match, otherwise the planner falls back to a sequential scan.
+//
+// As of v3.2.0, results from `searchCollection` may optionally be re-ordered
+// by a Jina cross-encoder reranker (see `rerankPgvectorResults`). The vector
+// search remains the recall stage; the reranker is the precision stage.
+import { rerank } from "./jina/reranker.js";
+import { JinaError } from "./jina/errors.js";
 const SEARCH_SQL = `SELECT file_name, mime_type, text, file_id, source, owner,
               chunk_index, total_chunks, timestamp_start, timestamp_end,
               embedded_at,
@@ -78,4 +84,66 @@ export function formatPgvectorResults(results, maxChars) {
     }
     return output;
 }
+/**
+ * Re-order `results` using the Jina cross-encoder reranker.
+ *
+ * This is the precision stage on top of pgvector's recall: the cosine pass
+ * grabs ~20 coarse candidates, the reranker promotes the ones that actually
+ * match the user's intent.
+ *
+ * Contract:
+ * - On success, returns at most `topN` items in descending relevance order.
+ *   The original cosine `score` is **preserved** on each item; the reranker
+ *   produces its own score we expose via the log event, not in the
+ *   PgvectorResult.
+ * - On any error (including auth / rate limit), throws a `JinaError`. The
+ *   caller is responsible for falling back to the original cosine order —
+ *   we do NOT swallow here because the caller wants to track the failure
+ *   for the cooldown breaker.
+ * - On empty input, returns `[]` without hitting the network.
+ */
+export async function rerankPgvectorResults(results, params) {
+    if (results.length === 0)
+        return [];
+    // The reranker only sees the textual content. Empty/null texts cannot be
+    // ranked, so we filter them out BEFORE the API call to avoid wasting
+    // tokens on rows the cross-encoder can't score anyway.
+    const indexed = results
+        .map((r, i) => ({ row: r, originalIndex: i, text: r.text ?? "" }))
+        .filter((x) => x.text.trim().length > 0);
+    if (indexed.length === 0)
+        return results.slice(0, params.topN ?? results.length);
+    try {
+        const reranked = await rerank({
+            apiKey: params.apiKey,
+            query: params.query,
+            documents: indexed.map((x) => x.text),
+            model: params.model,
+            topN: params.topN,
+            timeoutMs: params.timeoutMs,
+            signal: params.signal,
+        });
+        if (reranked.length === 0) {
+            // Defensive: reranker returned no usable items. Surface the original
+            // cosine order rather than wiping the candidate list.
+            return results.slice(0, params.topN ?? results.length);
+        }
+        // Map back to PgvectorResult using the reranker's `index` (which points
+        // into our filtered `indexed` array, NOT the original `results` array).
+        const out = [];
+        for (const item of reranked) {
+            const found = indexed[item.index];
+            if (found)
+                out.push(found.row);
+        }
+        return out;
+    }
+    catch (err) {
+        // Re-throw only if it's a Jina error the caller will recognize. Any
+        // other failure (programmer error) propagates as-is.
+        if (err instanceof JinaError)
+            throw err;
+        throw err;
+    }
+}
 //# sourceMappingURL=pgvector.js.map

package/dist/pgvector.js.map

@@ -1 +1 @@
-{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAI1E,MAAM,UAAU,GAAG;;;;;;;gBAOH,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAgB,EAChB,UAAkB,EAClB,MAAgB,EAChB,IAAY,EACZ,cAAsB;IAEtB,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAE3E,wEAAwE;QACxE,OAAO,MAAM,CAAC,IAAI;aACf,GAAG,CAAC,CAAC,GAAgB,EAAkB,EAAE,CAAC,CAAC;YAC1C,UAAU;YACV,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;YAC5B,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;YACtB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI;YAC1B,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;YACxB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,IAAI;YACpC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;YACtC,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,IAAI;YAC5C,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;SACzC,CAAC,CAAC;aACF,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAyB,EACzB,QAAgB;IAEhB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAa;YACtB,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,SAAS,IAAI,SAAS,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;SAC/E,CAAC;QAEF,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,eAAe,MAAM,CAAC,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACX,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,uCAAuC;QACvD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM;QACnD,MAAM,IAAI,KAAK,CAAC;IAClB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"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"}

package/dist/router/heuristic.d.ts

@@ -0,0 +1,29 @@
+import type { Route, RouterReason } from "./types.js";
+/**
+ * Triggers from the OpenClaw SDK that mean "not a user-initiated turn".
+ *
+ * Sourced from `PluginHookAgentContext.trigger` in the OpenClaw plugin SDK:
+ * `"user" | "heartbeat" | "cron" | "memory"`.
+ */
+export declare const NON_USER_TRIGGERS: Set<string>;
+export interface HeuristicInput {
+    /** The extracted user query (already trimmed and length-validated). */
+    query: string;
+    /** Trigger from `PluginHookAgentContext`. May be undefined on legacy SDKs. */
+    trigger?: string;
+    /** Whether the sender is the local CLI test harness (id: "cli"). */
+    isCli?: boolean;
+}
+export interface HeuristicVerdict {
+    route: Route | null;
+    reason: RouterReason;
+}
+/**
+ * Decide a route from cheap signals only. Returns `route: null` when the
+ * input is ambiguous and a classifier (or `ALL` fallback) should take over.
+ *
+ * The returned `reason` always identifies the rule that fired (or
+ * `"classifier_fallback"` if no rule did — yes that's reused, but a `null`
+ * route forces the caller to consult the classifier or fall back).
+ */
+export declare function heuristicRoute(input: HeuristicInput): HeuristicVerdict;

package/dist/router/heuristic.js

@@ -0,0 +1,104 @@
+// Zero-cost router heuristics.
+//
+// Runs BEFORE any Jina call. Three jobs:
+//
+//   1. **Deterministic skip on operational triggers.** When OpenClaw fires
+//      `before_prompt_build` with `ctx.trigger ∈ {heartbeat, cron, memory}`,
+//      we know the turn is not a real user question — skip retrieval
+//      unconditionally. This is the cheapest and most important gain:
+//      heartbeats fire continuously and were eating ~95% of the previous
+//      Jina quota.
+//
+//   2. **Meta-agent regex matches.** Questions like "what is your session
+//      id" or "combien d'agents ici" cannot be answered by the knowledge
+//      base, so we skip them deterministically too.
+//
+//   3. **Keyword fast-paths for common business questions.** A small set of
+//      regex hints lets the heuristic decide on its own (PGVECTOR_ONLY vs
+//      LIGHTRAG_ONLY) without paying for a Jina call. The router falls back
+//      to the classifier — or to `ALL` — when nothing matches.
+//
+// Everything in this module is pure (no I/O, no side effects) so the tests
+// can exhaustively cover the matrix.
+/**
+ * Triggers from the OpenClaw SDK that mean "not a user-initiated turn".
+ *
+ * Sourced from `PluginHookAgentContext.trigger` in the OpenClaw plugin SDK:
+ * `"user" | "heartbeat" | "cron" | "memory"`.
+ */
+export const NON_USER_TRIGGERS = new Set(["heartbeat", "cron", "memory"]);
+// ---------------------------------------------------------------------------
+// Meta-agent questions — skip entirely
+// ---------------------------------------------------------------------------
+const META_PATTERNS = [
+    // Identifiant/Id de session, session id, runId, agent id
+    /\b(?:session\s*id|runid|run\s*id|identifiant\s+(?:de\s+)?session|sessions?\s*identifi(?:ant|cation))\b/i,
+    // Combien d'agents/subagents
+    /\bcombien\s+d['e\s]?\s*(?:sub-?)?agent/i,
+    // Self-introspection "qui es-tu", "what model are you", "who are you"
+    /\b(?:qui\s+es-tu|what\s+model\s+are\s+you|who\s+are\s+you|what\s+is\s+your\s+name|comment\s+t['e]appelles?-tu)\b/i,
+    // Trivial system pings — the WHOLE prompt must be a status/ping check.
+    // Anchored on `^` so business questions ending with the word "status"
+    // (e.g. "what is the ACME project status?") are NOT classified as meta.
+    // Same anchoring for the FR variants ("tu es là ?").
+    /^\s*(?:(?:system|the\s+system)\s+)?(?:status|ping|heartbeat)\s*[?!.]*\s*$/i,
+    /^\s*(?:are\s+you\s+(?:there|alive)|t['e]es?\s+(?:la|en\s+ligne))\s*[?!.]*\s*$/i,
+];
+// ---------------------------------------------------------------------------
+// CLI test guards — short trivial prompts coming from `id:"cli"`
+// ---------------------------------------------------------------------------
+const CLI_TRIVIAL_PATTERN = /^\s*(?:test|test\s+de\s+(?:bon\s+)?fonctionnement|ping|hello|hi|salut|coucou|ok|yes|no|oui|non)\W*\s*$/i;
+// ---------------------------------------------------------------------------
+// Keyword fast-paths
+// ---------------------------------------------------------------------------
+const PGVECTOR_KEYWORDS = [
+    /\bversion\b/i,
+    /\brelease\s+notes?\b/i,
+    /\bchangelog\b/i,
+    /\bsource\s+(?:document|file|pdf|markdown)\b/i,
+    /\b\w+\.(?:md|pdf|yaml|yml|json|ts|js|py|sh)\b/i, // file name with extension
+];
+const LIGHTRAG_KEYWORDS = [
+    /\bcompare\w*\b/i,
+    /\baudit\b/i,
+    /\bsynth[éè]se\b/i,
+    /\brelations?\s+entre\b/i,
+    /\bqui\s+(?:travaille|collabore|coach|forme)\s+(?:avec|pour|chez)\b/i,
+    /\bdifferent\w*\s+(?:entre|de)\b/i,
+];
+/**
+ * Decide a route from cheap signals only. Returns `route: null` when the
+ * input is ambiguous and a classifier (or `ALL` fallback) should take over.
+ *
+ * The returned `reason` always identifies the rule that fired (or
+ * `"classifier_fallback"` if no rule did — yes that's reused, but a `null`
+ * route forces the caller to consult the classifier or fall back).
+ */
+export function heuristicRoute(input) {
+    const { query, trigger, isCli } = input;
+    // 1. Operational trigger → NEVER call any source.
+    if (trigger && NON_USER_TRIGGERS.has(trigger)) {
+        return { route: "NONE", reason: "heuristic_trigger" };
+    }
+    // 2. Meta-agent question → NEVER call any source.
+    for (const re of META_PATTERNS) {
+        if (re.test(query)) {
+            return { route: "NONE", reason: "heuristic_meta" };
+        }
+    }
+    // 3. CLI trivial prompt → NEVER call any source. Restricted to CLI to
+    //    avoid blocking legitimate-but-short collaborator questions.
+    if (isCli && CLI_TRIVIAL_PATTERN.test(query)) {
+        return { route: "NONE", reason: "heuristic_short" };
+    }
+    // 4. Keyword fast-paths.
+    if (PGVECTOR_KEYWORDS.some((re) => re.test(query))) {
+        return { route: "PGVECTOR_ONLY", reason: "heuristic_keyword" };
+    }
+    if (LIGHTRAG_KEYWORDS.some((re) => re.test(query))) {
+        return { route: "LIGHTRAG_ONLY", reason: "heuristic_keyword" };
+    }
+    // 5. Nothing fired — defer to the classifier (or fallback to ALL).
+    return { route: null, reason: "classifier_fallback" };
+}
+//# sourceMappingURL=heuristic.js.map

package/dist/router/heuristic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristic.js","sourceRoot":"","sources":["../../src/router/heuristic.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,yCAAyC;AACzC,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,qEAAqE;AACrE,sEAAsE;AACtE,yEAAyE;AACzE,mBAAmB;AACnB,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,+DAA+D;AAC/D,EAAE;AACF,2EAA2E;AAC3E,qCAAqC;AAIrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE1E,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,MAAM,aAAa,GAAa;IAC9B,yDAAyD;IACzD,yGAAyG;IACzG,6BAA6B;IAC7B,yCAAyC;IACzC,sEAAsE;IACtE,mHAAmH;IACnH,uEAAuE;IACvE,sEAAsE;IACtE,wEAAwE;IACxE,qDAAqD;IACrD,4EAA4E;IAC5E,gFAAgF;CACjF,CAAC;AAEF,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,MAAM,mBAAmB,GACvB,yGAAyG,CAAC;AAE5G,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,MAAM,iBAAiB,GAAa;IAClC,cAAc;IACd,uBAAuB;IACvB,gBAAgB;IAChB,8CAA8C;IAC9C,gDAAgD,EAAE,2BAA2B;CAC9E,CAAC;AAEF,MAAM,iBAAiB,GAAa;IAClC,iBAAiB;IACjB,YAAY;IACZ,kBAAkB;IAClB,yBAAyB;IACzB,qEAAqE;IACrE,kCAAkC;CACnC,CAAC;AAoBF;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAExC,kDAAkD;IAClD,IAAI,OAAO,IAAI,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACxD,CAAC;IAED,kDAAkD;IAClD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,iEAAiE;IACjE,IAAI,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACtD,CAAC;IAED,yBAAyB;IACzB,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACjE,CAAC;IAED,mEAAmE;IACnE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;AACxD,CAAC"}

package/dist/router/index.d.ts

@@ -0,0 +1,33 @@
+import type { RouterDecision } from "./types.js";
+export interface RouterConfig {
+    /** Master switch. When false, every call returns `{route: "ALL"}`. */
+    enabled: boolean;
+    /** Which engine fills the gap when heuristics are ambiguous. */
+    mode: "heuristic" | "jina-classifier";
+    /** Jina API key — required when mode === "jina-classifier". */
+    jinaApiKey: string;
+    /**
+     * Optional few-shot classifier ID. When provided, the router calls
+     * `/v1/classify` with this ID instead of running zero-shot.
+     */
+    classifierId?: string;
+    /** Labels for zero-shot classification. Defaults to {@link DEFAULT_ROUTER_LABELS}. */
+    labels?: readonly string[];
+    /** Triggers that bypass retrieval (subset of NON_USER_TRIGGERS). */
+    skipTriggers?: readonly string[];
+}
+export interface RouterRuntimeContext {
+    query: string;
+    trigger?: string;
+    /** Whether the sender is the local CLI test harness. */
+    isCli?: boolean;
+    /** Optional AbortSignal propagated to the classifier HTTP call. */
+    signal?: AbortSignal;
+}
+/**
+ * Decide the route for one user turn.
+ *
+ * Returns a {@link RouterDecision}. The plugin caller logs `reason` and
+ * uses `route` to gate source calls.
+ */
+export declare function decideRoute(cfg: RouterConfig, ctx: RouterRuntimeContext): Promise<RouterDecision>;

package/dist/router/index.js

@@ -0,0 +1,94 @@
+// Router orchestrator: heuristic → classifier (optional) → fallback.
+//
+// Public entry point is `decideRoute(...)`. It produces a `RouterDecision`
+// the hook handler consumes to gate calls to pgvector / LightRAG.
+//
+// Design contract (fail-open):
+//   - Any error in the classifier MUST yield `ALL` so retrieval keeps
+//     working. The router never blocks the agent.
+//   - The classifier is only called when the heuristic returns `null`
+//     (ambiguous input). Heuristic hits are deterministic and free.
+//   - Classifier results that don't map to a known label fall back to
+//     `ALL` with reason `"classifier_fallback"`.
+import { classifyFewShot, classifyZeroShot, } from "../jina/classifier.js";
+import { JinaError } from "../jina/errors.js";
+import { DEFAULT_ROUTER_LABELS, ROUTER_LABEL_NAMES, extractRouteFromLabel, } from "./labels.js";
+import { heuristicRoute } from "./heuristic.js";
+const FALLBACK = "ALL";
+/**
+ * Decide the route for one user turn.
+ *
+ * Returns a {@link RouterDecision}. The plugin caller logs `reason` and
+ * uses `route` to gate source calls.
+ */
+export async function decideRoute(cfg, ctx) {
+    // 0. Disabled → preserve legacy behavior.
+    if (!cfg.enabled) {
+        return { route: "ALL", reason: "router_disabled", score: null };
+    }
+    // 1. Heuristic pass — cheap and deterministic.
+    const verdict = heuristicRoute({
+        query: ctx.query,
+        trigger: ctx.trigger,
+        isCli: ctx.isCli,
+    });
+    if (verdict.route !== null) {
+        return { route: verdict.route, reason: verdict.reason, score: null };
+    }
+    // 2. Classifier pass — only when heuristics were ambiguous.
+    if (cfg.mode === "heuristic") {
+        // Operator asked for heuristic-only routing; ambiguous → ALL.
+        return { route: FALLBACK, reason: "classifier_fallback", score: null };
+    }
+    if (!cfg.jinaApiKey) {
+        // Misconfiguration safety net — never crash, just fall back.
+        return { route: FALLBACK, reason: "classifier_fallback", score: null };
+    }
+    try {
+        const outcome = cfg.classifierId
+            ? await classifyFewShot({
+                apiKey: cfg.jinaApiKey,
+                text: ctx.query,
+                classifierId: cfg.classifierId,
+                expectedLabels: ROUTER_LABEL_NAMES,
+                signal: ctx.signal,
+            })
+            : await classifyZeroShot({
+                apiKey: cfg.jinaApiKey,
+                text: ctx.query,
+                labels: (cfg.labels ?? DEFAULT_ROUTER_LABELS),
+                signal: ctx.signal,
+            });
+        if (!outcome) {
+            return { route: FALLBACK, reason: "classifier_fallback", score: null };
+        }
+        const routeName = 
+        // Few-shot classifiers return the raw label name as trained; zero-shot
+        // returns the full descriptive label — strip the colon prefix.
+        cfg.classifierId
+            ? outcome.label
+            : (extractRouteFromLabel(outcome.label) ?? outcome.label);
+        if (!isKnownRoute(routeName)) {
+            return { route: FALLBACK, reason: "classifier_fallback", score: outcome.score };
+        }
+        return {
+            route: routeName,
+            reason: "classifier_hit",
+            score: outcome.score,
+        };
+    }
+    catch (err) {
+        // Re-throw non-Jina errors (programmer errors, type mismatches). Jina
+        // failures fail open.
+        if (!(err instanceof JinaError))
+            throw err;
+        return { route: FALLBACK, reason: "classifier_error", score: null };
+    }
+}
+function isKnownRoute(value) {
+    return (value === "NONE" ||
+        value === "PGVECTOR_ONLY" ||
+        value === "LIGHTRAG_ONLY" ||
+        value === "ALL");
+}
+//# sourceMappingURL=index.js.map

package/dist/router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"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"}

package/dist/router/labels.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Public constants — MUST stay in sync with `Route` in `types.js`.
+ *
+ * The label prefix passed to Jina (zero-shot) and the canonical name a
+ * few-shot classifier MUST be trained against share the same literal
+ * values as the `Route` union ("NONE" | "PGVECTOR_ONLY" | "LIGHTRAG_ONLY"
+ * | "ALL"). If they diverged, the classifier path would always fall back
+ * to "ALL" because `isKnownRoute` would reject the predicted label.
+ */
+export declare const ROUTE_NONE = "NONE";
+export declare const ROUTE_PGVECTOR_ONLY = "PGVECTOR_ONLY";
+export declare const ROUTE_LIGHTRAG_ONLY = "LIGHTRAG_ONLY";
+export declare const ROUTE_ALL = "ALL";
+/**
+ * Default labels handed to Jina `/v1/classify` in zero-shot mode when the
+ * operator does not supply a few-shot `classifierId`.
+ *
+ * Order does not matter for correctness, but we keep `NONE` first by
+ * convention so test output is stable.
+ */
+export declare const DEFAULT_ROUTER_LABELS: readonly string[];
+/**
+ * The label names that the classifier may legitimately return.
+ * Used by the defensive parser to refuse hallucinated classes.
+ */
+export declare const ROUTER_LABEL_NAMES: readonly string[];
+/**
+ * Extract the route name from a full label string (the part before the
+ * colon). Returns `null` when the label is malformed.
+ *
+ * @internal exported for unit testing
+ */
+export declare function extractRouteFromLabel(label: string): string | null;

package/dist/router/labels.js

@@ -0,0 +1,67 @@
+// Default zero-shot labels for the Jina Classifier.
+//
+// The labels are intentionally bilingual: most prompts in the observed
+// traces are French (Ataraxis is a French-speaking deployment) but the
+// system prompts and agent meta-questions are often English. Jina
+// `jina-embeddings-v3` handles both languages natively.
+//
+// Each label is a short sentence describing the kind of question that
+// belongs to that route. Jina embeds both the label and the input, then
+// picks the closest one — so the more discriminative the labels, the
+// better the routing. Empirically, "describe the kind of question"
+// outperforms "give a category name" by ~25% on small samples
+// (https://jina.ai/news/rephrased-labels-improve-zero-shot-text-classification-30/).
+/**
+ * Public constants — MUST stay in sync with `Route` in `types.js`.
+ *
+ * The label prefix passed to Jina (zero-shot) and the canonical name a
+ * few-shot classifier MUST be trained against share the same literal
+ * values as the `Route` union ("NONE" | "PGVECTOR_ONLY" | "LIGHTRAG_ONLY"
+ * | "ALL"). If they diverged, the classifier path would always fall back
+ * to "ALL" because `isKnownRoute` would reject the predicted label.
+ */
+export const ROUTE_NONE = "NONE";
+export const ROUTE_PGVECTOR_ONLY = "PGVECTOR_ONLY";
+export const ROUTE_LIGHTRAG_ONLY = "LIGHTRAG_ONLY";
+export const ROUTE_ALL = "ALL";
+/**
+ * Default labels handed to Jina `/v1/classify` in zero-shot mode when the
+ * operator does not supply a few-shot `classifierId`.
+ *
+ * Order does not matter for correctness, but we keep `NONE` first by
+ * convention so test output is stable.
+ */
+export const DEFAULT_ROUTER_LABELS = [
+    // NONE — agent meta, smalltalk, test pings
+    `${ROUTE_NONE}: meta-question about the agent itself, session identifier, system test, simple greeting, weather, or trivial smalltalk that does not depend on the knowledge base`,
+    // PGVECTOR_ONLY — single-document factual lookup
+    `${ROUTE_PGVECTOR_ONLY}: factual lookup that can be answered by a single document excerpt — version numbers, file names, dates, configuration values, raw quotes`,
+    // LIGHTRAG_ONLY — entity-relation traversal
+    `${ROUTE_LIGHTRAG_ONLY}: knowledge graph question about entities and their relationships — which client, which coach, which mission, which programme links to which livrable`,
+    // ALL — broad / synthesizing / unclear
+    `${ROUTE_ALL}: broad synthesis, multi-hop reasoning, audit, comparison, or any question whose scope is unclear and benefits from both vector search and knowledge graph context`,
+];
+/**
+ * The label names that the classifier may legitimately return.
+ * Used by the defensive parser to refuse hallucinated classes.
+ */
+export const ROUTER_LABEL_NAMES = [
+    ROUTE_NONE,
+    ROUTE_PGVECTOR_ONLY,
+    ROUTE_LIGHTRAG_ONLY,
+    ROUTE_ALL,
+];
+/**
+ * Extract the route name from a full label string (the part before the
+ * colon). Returns `null` when the label is malformed.
+ *
+ * @internal exported for unit testing
+ */
+export function extractRouteFromLabel(label) {
+    const colonIndex = label.indexOf(":");
+    if (colonIndex <= 0)
+        return null;
+    const name = label.slice(0, colonIndex).trim();
+    return name.length > 0 ? name : null;
+}
+//# sourceMappingURL=labels.js.map

package/dist/router/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../src/router/labels.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,kEAAkE;AAClE,wDAAwD;AACxD,EAAE;AACF,sEAAsE;AACtE,wEAAwE;AACxE,qEAAqE;AACrE,mEAAmE;AACnE,8DAA8D;AAC9D,qFAAqF;AAErF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AACjC,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AACnD,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,2CAA2C;IAC3C,GAAG,UAAU,oKAAoK;IAEjL,iDAAiD;IACjD,GAAG,mBAAmB,2IAA2I;IAEjK,4CAA4C;IAC5C,GAAG,mBAAmB,uJAAuJ;IAE7K,uCAAuC;IACvC,GAAG,SAAS,oKAAoK;CACjL,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,UAAU;IACV,mBAAmB;IACnB,mBAAmB;IACnB,SAAS;CACV,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC"}

package/dist/router/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The four mutually exclusive routes the router can pick.
+ *
+ *   - `NONE`            — skip every source. Used for heartbeats, cron,
+ *                          memory triggers, agent meta-questions, system
+ *                          tests. Saves the cost of an irrelevant retrieval.
+ *   - `PGVECTOR_ONLY`   — vector search only (no graph). Cheap factual
+ *                          lookups: file names, version numbers, simple
+ *                          excerpts.
+ *   - `LIGHTRAG_ONLY`   — knowledge graph only (no vectors). Multi-hop
+ *                          reasoning, entity-relationship queries.
+ *   - `ALL`             — both sources in parallel. The current default
+ *                          behavior; preserved when the router is disabled.
+ */
+export type Route = "NONE" | "PGVECTOR_ONLY" | "LIGHTRAG_ONLY" | "ALL";
+/** Source of a router decision — used in logs to trace the reasoning path. */
+export type RouterReason = "router_disabled" | "heuristic_trigger" | "heuristic_meta" | "heuristic_short" | "heuristic_keyword" | "classifier_hit" | "classifier_fallback" | "classifier_error";
+export interface RouterDecision {
+    route: Route;
+    reason: RouterReason;
+    /** Confidence in [0, 1] when the classifier produced a score, else null. */
+    score: number | null;
+}

package/dist/router/types.js

@@ -0,0 +1,7 @@
+// Router types — shared by heuristic + classifier paths.
+//
+// The router decides which knowledge sources should be queried for a given
+// user turn. The decision is consumed by the `before_prompt_build` handler
+// to gate calls to pgvector and LightRAG.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/router/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/router/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C"}