@lacneu/openclaw-knowledge 3.1.2 → 3.2.0

package/dist/tracing/events.d.ts

@@ -0,0 +1,83 @@
+import type { Route, RouterReason } from "../router/types.js";
+/**
+ * Minimal logger surface used by this module. Matches the relevant subset of
+ * `PluginLogger` from the OpenClaw SDK so it can be unit-tested without
+ * importing the full SDK type graph.
+ */
+export interface TracingLogger {
+    info: (message: string) => void;
+    debug?: (message: string) => void;
+}
+/**
+ * Marker prefix for every structured line emitted by this module. Pick a
+ * value that is unlikely to clash with other plugins and stable across
+ * versions — log scrapers and Opik rules depend on it.
+ */
+export declare const EVENT_PREFIX = "[knowledge.event]";
+export interface RouterEvent {
+    type: "router";
+    route: Route;
+    reason: RouterReason;
+    score: number | null;
+    queryLength: number;
+    trigger?: string;
+}
+export interface PgvectorEvent {
+    type: "pgvector";
+    collections: string[];
+    rawCount: number;
+    rerankedCount: number | null;
+    topScore: number | null;
+    durationMs: number;
+}
+export interface LightRAGEvent {
+    type: "lightrag";
+    mode: string;
+    contextChars: number;
+    truncatedChars: number;
+    durationMs: number;
+}
+export interface JinaUsageEvent {
+    type: "jina";
+    endpoint: "classify" | "rerank";
+    model: string;
+    durationMs: number;
+    inputCount: number;
+}
+export interface CooldownEvent {
+    type: "cooldown";
+    scope: "global" | "router" | "pgvector_reranker";
+    consecutiveErrors: number;
+}
+export type KnowledgeEvent = RouterEvent | PgvectorEvent | LightRAGEvent | JinaUsageEvent | CooldownEvent;
+/**
+ * Emit a structured event line through `logger.info`.
+ *
+ * Never throws. If JSON serialization or the logger itself fails (e.g.
+ * upstream broke the contract), we silently swallow — the plugin must keep
+ * working even if tracing breaks.
+ */
+export declare function emitEvent(logger: TracingLogger, event: KnowledgeEvent): void;
+/**
+ * Optional debug-level emission of turn metadata for correlation.
+ *
+ * What goes into the log line:
+ *   - `runId`: the OpenClaw SDK's runId for this agent turn (or
+ *              `"unknown"` when the SDK did not supply one). This is the
+ *              ONLY correlation key we expose — it is non-query-derived
+ *              by construction, so it cannot be dictionary-recovered
+ *              from the log line.
+ *   - `qlen`:  character length of the query (a count, not content).
+ *
+ * What does NOT go in: any portion of the query text, AND no hash of it.
+ * An earlier iteration of this plugin emitted `SHA-256(query)` truncated
+ * to 12 hex chars under the assumption it was "non-reversible". Code
+ * review (2026-05-23) correctly pointed out that for short or low-entropy
+ * prompts (the hook accepts ≥ 3 chars), the hash is dictionary-recoverable
+ * offline. We removed the hash entirely and rely on `runId` instead.
+ *
+ * Operators who want CONTENT correlation across turns must instrument
+ * Opik / LangFuse at the SDK layer with their own keyed scheme (HMAC
+ * with a deployment secret); the plugin will not do it for them.
+ */
+export declare function emitTurnMetadata(logger: TracingLogger, runId: string | undefined, queryLength: number): void;

package/dist/tracing/events.js

@@ -0,0 +1,86 @@
+// Structured event emission for downstream observability tools.
+//
+// The plugin already runs inside an OpenClaw deployment that includes Opik
+// (https://www.comet.com/docs/opik/) for tracing — but the plugin itself
+// MUST NOT depend on the Opik SDK directly. Two reasons:
+//
+//   1. Deps. The plugin proudly ships with a single runtime dep (`pg`).
+//      Adding `opik` would force every consumer to install it.
+//   2. Coupling. Operators may swap Opik for LangFuse or pure OTLP. The
+//      plugin should not care.
+//
+// Solution: emit structured JSON lines through OpenClaw's logger. The
+// upstream gateway already forwards `logger.info(...)` to Opik (when
+// configured) and to stdout in any case. A grep-friendly prefix
+// (`[knowledge.event]`) lets a downstream scraper or Opik rule pick the
+// records out without ambiguity.
+//
+// Privacy invariant: NO event in this module ever logs the raw user
+// query, query excerpts, retrieved chunk content, OR ANY HASH OF THEM.
+// We log metadata only (lengths, scores, counts, durations) plus the
+// `runId` provided by the OpenClaw SDK when turn-level correlation is
+// needed. The runId is non-query-derived by construction, so it cannot
+// be reversed offline against a dictionary of likely prompts.
+//
+// The events module is intentionally tiny and synchronous — emitting a log
+// line must NEVER throw, NEVER consume noticeable CPU, and NEVER hold the
+// agent turn open.
+/**
+ * Marker prefix for every structured line emitted by this module. Pick a
+ * value that is unlikely to clash with other plugins and stable across
+ * versions — log scrapers and Opik rules depend on it.
+ */
+export const EVENT_PREFIX = "[knowledge.event]";
+// ---------------------------------------------------------------------------
+// Emitters
+// ---------------------------------------------------------------------------
+/**
+ * Emit a structured event line through `logger.info`.
+ *
+ * Never throws. If JSON serialization or the logger itself fails (e.g.
+ * upstream broke the contract), we silently swallow — the plugin must keep
+ * working even if tracing breaks.
+ */
+export function emitEvent(logger, event) {
+    try {
+        const payload = JSON.stringify(event);
+        logger.info(`${EVENT_PREFIX} ${payload}`);
+    }
+    catch {
+        // intentional swallow — tracing must never crash the plugin
+    }
+}
+/**
+ * Optional debug-level emission of turn metadata for correlation.
+ *
+ * What goes into the log line:
+ *   - `runId`: the OpenClaw SDK's runId for this agent turn (or
+ *              `"unknown"` when the SDK did not supply one). This is the
+ *              ONLY correlation key we expose — it is non-query-derived
+ *              by construction, so it cannot be dictionary-recovered
+ *              from the log line.
+ *   - `qlen`:  character length of the query (a count, not content).
+ *
+ * What does NOT go in: any portion of the query text, AND no hash of it.
+ * An earlier iteration of this plugin emitted `SHA-256(query)` truncated
+ * to 12 hex chars under the assumption it was "non-reversible". Code
+ * review (2026-05-23) correctly pointed out that for short or low-entropy
+ * prompts (the hook accepts ≥ 3 chars), the hash is dictionary-recoverable
+ * offline. We removed the hash entirely and rely on `runId` instead.
+ *
+ * Operators who want CONTENT correlation across turns must instrument
+ * Opik / LangFuse at the SDK layer with their own keyed scheme (HMAC
+ * with a deployment secret); the plugin will not do it for them.
+ */
+export function emitTurnMetadata(logger, runId, queryLength) {
+    if (!logger.debug)
+        return;
+    try {
+        const id = runId && runId.length > 0 ? runId : "unknown";
+        logger.debug(`${EVENT_PREFIX} turn.metadata runId=${id} qlen=${queryLength}`);
+    }
+    catch {
+        // swallow — tracing must never crash the plugin
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/tracing/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/tracing/events.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,yDAAyD;AACzD,EAAE;AACF,wEAAwE;AACxE,+DAA+D;AAC/D,wEAAwE;AACxE,+BAA+B;AAC/B,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,gEAAgE;AAChE,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,qEAAqE;AACrE,sEAAsE;AACtE,uEAAuE;AACvE,8DAA8D;AAC9D,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,mBAAmB;AAcnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAqDhD,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAqB,EAAE,KAAqB;IACpE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,IAAI,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAqB,EACrB,KAAyB,EACzB,WAAmB;IAEnB,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,wBAAwB,EAAE,SAAS,WAAW,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -1,3 +1,25 @@
+import type { RerankerModel } from "./jina/types.js";
+/**
+ * Subset of `PluginHookAgentContext` from the OpenClaw plugin SDK that this
+ * plugin actually consumes. Declared locally to keep the test suite free of
+ * SDK runtime imports.
+ *
+ * Fields beyond this subset (workspaceDir, modelProviderId, ...) are
+ * deliberately omitted — the handler does not depend on them.
+ *
+ * @see https://github.com/openclaw/openclaw plugin-sdk types.d.ts
+ */
+export interface PluginHookAgentContext {
+    /** What initiated this agent run. */
+    trigger?: "user" | "heartbeat" | "cron" | "memory" | string;
+    /** Channel-derived sender id. The plugin currently only uses `"cli"`. */
+    messageProvider?: string;
+    channelId?: string;
+    agentId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    runId?: string;
+}
 /**
  * Runtime configuration as it appears in `plugins.entries.openclaw-knowledge.config`.
  * All fields are optional — defaults are applied in {@link resolveConfig}.
@@ -16,6 +38,30 @@ export interface KnowledgePluginConfig {
     lightragQueryMode?: LightRAGQueryMode;
     lightragMaxChars?: number;
     lightragEnabled?: boolean;
+    jina?: JinaPluginConfig;
+}
+export interface JinaPluginConfig {
+    /** Jina API key. Required for `router.mode=jina-classifier` or `pgvectorReranker.enabled`. Supports `${ENV_VAR}` substitution. */
+    apiKey?: string;
+    router?: RouterPluginConfig;
+    pgvectorReranker?: PgvectorRerankerPluginConfig;
+}
+export interface RouterPluginConfig {
+    enabled?: boolean;
+    mode?: "heuristic" | "jina-classifier";
+    /**
+     * Optional pre-trained Jina classifier_id. When set, the router calls
+     * `/v1/classify` with this ID (few-shot mode). Train it out-of-band via
+     * `POST /v1/train` — the plugin does NOT implement training.
+     */
+    classifierId?: string;
+}
+export interface PgvectorRerankerPluginConfig {
+    enabled?: boolean;
+    /** Reranker model. Default: `jina-reranker-v2-base-multilingual` (best FR coverage). */
+    model?: RerankerModel;
+    /** Cap on results returned post-rerank. Default: `5`. */
+    topN?: number;
 }
 export type LightRAGQueryMode = "naive" | "local" | "global" | "hybrid";
 /**
@@ -36,6 +82,13 @@ export interface ResolvedKnowledgeConfig {
     lightragQueryMode: LightRAGQueryMode;
     lightragMaxChars: number;
     lightragEnabled: boolean;
+    jinaApiKey: string;
+    routerEnabled: boolean;
+    routerMode: "heuristic" | "jina-classifier";
+    routerClassifierId: string;
+    pgvectorRerankerEnabled: boolean;
+    pgvectorRerankerModel: RerankerModel;
+    pgvectorRerankerTopN: number;
 }
 /**
  * One search hit from the PostgreSQL `knowledge_vectors` table, after score
@@ -86,6 +139,10 @@ export interface PgvectorRow {
 /**
  * Shape of the `before_prompt_build` event payload as consumed by this plugin.
  * We only rely on `messages`; the SDK may add other fields that we ignore.
+ *
+ * The full SDK type also exposes `prompt: string` (the raw user text). The
+ * handler keeps using `extractQueryFromMessages` to stay compatible with the
+ * existing tests; `prompt` is left to the SDK without being read here.
  */
 export interface BeforePromptBuildEvent {
     messages?: PromptMessage[];

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "openclaw-knowledge",
   "name": "Knowledge Base",
-  "description": "Multi-source knowledge search (pgvector + LightRAG) — injects relevant documents and knowledge graph context before each turn via the before_prompt_build hook",
-  "version": "3.1.2",
+  "description": "Multi-source knowledge search (pgvector + LightRAG) with optional Jina-powered router & reranker — injects relevant documents and knowledge graph context before each turn via the before_prompt_build hook",
+  "version": "3.2.0",
   "activation": {
     "onStartup": true
   },
@@ -34,7 +34,7 @@
         "minimum": 1,
         "maximum": 100,
         "default": 5,
-        "description": "Maximum number of results returned per collection"
+        "description": "Maximum number of results returned per collection (raw recall stage)"
       },
       "scoreThreshold": {
         "type": "number",
@@ -76,6 +76,63 @@
       "lightragEnabled": {
         "type": "boolean",
         "description": "Disable LightRAG search while keeping pgvector. Defaults to true when lightragUrl is set."
+      },
+      "jina": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Optional Jina-powered enhancements: router (skip irrelevant retrievals) and pgvector reranker (re-order vector results by cross-encoder relevance).",
+        "properties": {
+          "apiKey": {
+            "type": "string",
+            "description": "Jina API key shared by router and reranker. Required when router.mode=jina-classifier or pgvectorReranker.enabled. Supports ${ENV_VAR} substitution."
+          },
+          "router": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Adaptive routing: classify each user turn and skip retrieval when irrelevant.",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable the router. When false (default), every eligible turn calls every configured source — pre-3.2.0 behavior."
+              },
+              "mode": {
+                "type": "string",
+                "enum": ["heuristic", "jina-classifier"],
+                "default": "heuristic",
+                "description": "heuristic: zero-cost regex + trigger rules only (safe start). jina-classifier: same heuristics first, then Jina /v1/classify for ambiguous queries."
+              },
+              "classifierId": {
+                "type": "string",
+                "description": "Optional pre-trained Jina classifier_id (few-shot mode). Train it out-of-band via POST /v1/train then paste the ID here. When omitted, the router uses zero-shot with built-in labels."
+              }
+            }
+          },
+          "pgvectorReranker": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Re-order pgvector results with a Jina cross-encoder. Boosts precision when topK candidates contain noise.",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable cross-encoder rerank on pgvector results. Requires jina.apiKey."
+              },
+              "model": {
+                "type": "string",
+                "default": "jina-reranker-v2-base-multilingual",
+                "description": "Jina reranker model. v2-base-multilingual is recommended for French content (v3 is English-biased)."
+              },
+              "topN": {
+                "type": "number",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 5,
+                "description": "Max number of results returned after rerank. Recommendation: keep topK ≥ topN × 2 so the cross-encoder has room to re-order."
+              }
+            }
+          }
+        }
       }
     },
     "required": []
@@ -105,7 +162,7 @@
     "topK": {
       "label": "Top-K per collection",
       "advanced": true,
-      "help": "Maximum number of results returned per collection (default: 5)"
+      "help": "Maximum number of results returned per collection (default: 5). When the reranker is enabled, recommended ≥ 2× rerank topN."
     },
     "scoreThreshold": {
       "label": "Score threshold",
@@ -147,6 +204,42 @@
       "label": "Enable LightRAG source",
       "advanced": true,
       "help": "Disable LightRAG while keeping pgvector. Defaults to true when lightragUrl is set."
+    },
+    "jina.apiKey": {
+      "label": "Jina API Key",
+      "placeholder": "${JINA_API_KEY}",
+      "sensitive": true,
+      "help": "Shared by router and reranker. Use ${JINA_API_KEY} for env var substitution."
+    },
+    "jina.router.enabled": {
+      "label": "Enable router",
+      "advanced": true,
+      "help": "Adaptive routing that skips retrieval on heartbeats and meta-questions. Default: false (pre-3.2.0 behavior)."
+    },
+    "jina.router.mode": {
+      "label": "Router mode",
+      "advanced": true,
+      "help": "heuristic: zero-cost rules only. jina-classifier: heuristics + Jina /v1/classify fallback."
+    },
+    "jina.router.classifierId": {
+      "label": "Few-shot classifier ID",
+      "advanced": true,
+      "help": "Optional. When set, the router uses your pre-trained classifier instead of zero-shot labels."
+    },
+    "jina.pgvectorReranker.enabled": {
+      "label": "Enable pgvector reranker",
+      "advanced": true,
+      "help": "Cross-encoder re-ordering of pgvector results. Requires Jina API key."
+    },
+    "jina.pgvectorReranker.model": {
+      "label": "Reranker model",
+      "advanced": true,
+      "help": "Default: jina-reranker-v2-base-multilingual (best for French)."
+    },
+    "jina.pgvectorReranker.topN": {
+      "label": "Reranker top-N",
+      "advanced": true,
+      "help": "Max results returned after rerank. Keep topK ≥ topN × 2."
     }
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lacneu/openclaw-knowledge",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "type": "module",
-  "description": "Multi-source knowledge plugin for OpenClaw — pgvector + LightRAG injection via before_prompt_build hook",
+  "description": "Multi-source knowledge plugin for OpenClaw — pgvector + LightRAG injection with optional Jina-powered router & reranker, via before_prompt_build hook",
   "license": "MIT",
   "author": "Olivier Neu",
   "homepage": "https://github.com/OlivierNeu/openclaw-knowledge-plugin#readme",
@@ -40,7 +40,7 @@
     "build:test": "tsc -p tsconfig.test-build.json",
     "clean": "rm -rf dist dist-test",
     "typecheck": "tsc -p tsconfig.test.json",
-    "test": "npm run build:test && node --test dist-test/test/*.test.js",
+    "test": "npm run build:test && node --test $(find dist-test/test -name '*.test.js' -print)",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "openclaw": {