pi-knowledge 0.6.0 → 0.7.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/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+
4
+ ## [0.7.0] - 2026-07-28
5
+
6
+ ### Added
7
+ - Added `PI_KNOWLEDGE_RERANKER_RAW_LOGITS` for trusted single-logit local/Hugging Face cross-encoder rerankers whose sigmoid scores flatten near 1.0.
8
+
9
+ ### Fixed
10
+ - Preserved the default reranker config shape when raw logits are unset.
11
+ - Rejected multi-logit and non-finite raw reranker outputs instead of guessing a relevance score.
12
+
3
13
  ## [0.6.0] - 2026-07-25
4
14
 
5
15
  ### Added
package/README.md CHANGED
@@ -179,7 +179,7 @@ Full configuration details are in [docs/configuration.md](docs/configuration.md)
179
179
  | Storage path | `PI_KNOWLEDGE_DIR`, `OMP_KNOWLEDGE_DIR`, `PI_CODING_AGENT_DIR`, `OMP_CODING_AGENT_DIR`, `OMP_PROFILE` |
180
180
  | Model worker and cache | `PI_KNOWLEDGE_MODEL_CACHE_DIR`, `PI_KNOWLEDGE_NODE_PATH` |
181
181
  | Embedding provider | `PI_KNOWLEDGE_EMBEDDING`, `OPENAI_API_KEY`, `PI_KNOWLEDGE_EMBEDDING_BASE_URL`, `OPENAI_BASE_URL`, `PI_KNOWLEDGE_EMBEDDING_MAX_CHARS`, `PI_KNOWLEDGE_EMBEDDING_API_FALLBACK` |
182
- | Reranker provider | `PI_KNOWLEDGE_RERANKER`, `PI_KNOWLEDGE_RERANKER_REVISION`, `PI_KNOWLEDGE_RERANKER_DTYPE`, `PI_KNOWLEDGE_RERANKER_REMOTE_HOST`, `PI_KNOWLEDGE_RERANKER_REMOTE_PATH_TEMPLATE`, `PI_KNOWLEDGE_RERANKER_API_ENDPOINT`, `PI_KNOWLEDGE_RERANKER_API_BASE_URL`, `PI_KNOWLEDGE_RERANKER_API_KEY`, `PI_KNOWLEDGE_RERANKER_API_FORMAT`, `PI_KNOWLEDGE_RERANKER_API_TIMEOUT_MS`, `PI_KNOWLEDGE_RERANKER_MAX_DOC_CHARS`, `PI_KNOWLEDGE_RERANKER_API_RESULTS_PATH`, `PI_KNOWLEDGE_RERANKER_API_INDEX_FIELD`, `PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD`, `PI_KNOWLEDGE_RERANKER_API_SCORE_DIRECTION` |
182
+ | Reranker provider | `PI_KNOWLEDGE_RERANKER`, `PI_KNOWLEDGE_RERANKER_REVISION`, `PI_KNOWLEDGE_RERANKER_DTYPE`, `PI_KNOWLEDGE_RERANKER_REMOTE_HOST`, `PI_KNOWLEDGE_RERANKER_REMOTE_PATH_TEMPLATE`, `PI_KNOWLEDGE_RERANKER_RAW_LOGITS`, `PI_KNOWLEDGE_RERANKER_API_ENDPOINT`, `PI_KNOWLEDGE_RERANKER_API_BASE_URL`, `PI_KNOWLEDGE_RERANKER_API_KEY`, `PI_KNOWLEDGE_RERANKER_API_FORMAT`, `PI_KNOWLEDGE_RERANKER_API_TIMEOUT_MS`, `PI_KNOWLEDGE_RERANKER_MAX_DOC_CHARS`, `PI_KNOWLEDGE_RERANKER_API_RESULTS_PATH`, `PI_KNOWLEDGE_RERANKER_API_INDEX_FIELD`, `PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD`, `PI_KNOWLEDGE_RERANKER_API_SCORE_DIRECTION` |
183
183
  | Native lifecycle | `PI_KNOWLEDGE_ENABLE_NATIVE_IDLE_DISPOSE`, `PI_KNOWLEDGE_EMBEDDING_IDLE_MS` |
184
184
  | Runtime features | `PI_KNOWLEDGE_WATCH`, `PI_KNOWLEDGE_AUTO_INJECT`, `PI_KNOWLEDGE_STALE_INDEXING_MS`, `PI_KNOWLEDGE_OFFLINE`, `PI_KNOWLEDGE_SEARCH_PROFILE`, `PI_KNOWLEDGE_SEARCH_DEFAULT_LIMIT`, `PI_KNOWLEDGE_SNIPPET_MAX_LENGTH`, `PI_KNOWLEDGE_MIN_HYBRID_SCORE`, `PI_KNOWLEDGE_SEARCH_CANDIDATE_MIN`, `PI_KNOWLEDGE_SEARCH_CANDIDATE_MULTIPLIER`, `PI_KNOWLEDGE_ADAPTIVE_CONTEXT_LINES`, `PI_KNOWLEDGE_ADAPTIVE_MAX_CHARS`, `PI_KNOWLEDGE_ADAPTIVE_NEIGHBOR_TARGET`, `PI_KNOWLEDGE_DEEP_RERANK_CANDIDATES`, `PI_KNOWLEDGE_DEEP_RERANK_TOPK_MULTIPLIER` |
185
185
  | Release fixtures | `PI_KNOWLEDGE_E2E_PDF`, `PI_KNOWLEDGE_E2E_DOCX` |
@@ -1,6 +1,7 @@
1
1
  import { join } from "node:path";
2
2
  import { createInterface } from "node:readline";
3
3
  import { DEFAULT_RERANKER_REMOTE_HOST, DEFAULT_RERANKER_REMOTE_PATH_TEMPLATE, isHfRerankerConfig, rerankerCacheKey, resolveRerankerConfig, } from "./search/reranker-config.js";
4
+ import { rerankWithSingleRawLogit } from "./search/reranker-logits.js";
4
5
  import { getDefaultKnowledgeDir } from "./storage/sqlite.js";
5
6
  let embeddingPipeline = null;
6
7
  let rerankerPipeline = null;
@@ -37,6 +38,21 @@ async function loadRerankerPipeline(config) {
37
38
  const key = rerankerCacheKey(config);
38
39
  if (rerankerPipeline?.key === key)
39
40
  return rerankerPipeline.pipe;
41
+ if (config.rawLogits) {
42
+ const { AutoTokenizer, AutoModelForSequenceClassification, env } = await import("@huggingface/transformers");
43
+ const transformersEnv = env;
44
+ configureTransformersEnv(transformersEnv);
45
+ transformersEnv.remoteHost = config.remoteHost ?? DEFAULT_RERANKER_REMOTE_HOST;
46
+ transformersEnv.remotePathTemplate = config.remotePathTemplate ?? DEFAULT_RERANKER_REMOTE_PATH_TEMPLATE;
47
+ const loadOpts = { revision: config.revision };
48
+ if (config.dtype)
49
+ loadOpts.dtype = config.dtype;
50
+ const tokenizer = (await AutoTokenizer.from_pretrained(config.model, loadOpts));
51
+ const model = (await AutoModelForSequenceClassification.from_pretrained(config.model, loadOpts));
52
+ const pipe = (input) => rerankWithSingleRawLogit(input, tokenizer, model, config.model);
53
+ rerankerPipeline = { key, pipe };
54
+ return pipe;
55
+ }
40
56
  const { pipeline, env } = await import("@huggingface/transformers");
41
57
  const transformersEnv = env;
42
58
  configureTransformersEnv(transformersEnv);
@@ -8,6 +8,9 @@ export interface HfRerankerConfig {
8
8
  dtype?: string;
9
9
  remoteHost?: string;
10
10
  remotePathTemplate?: string;
11
+ /** When true, use raw logits from the model instead of pipeline sigmoid scores.
12
+ * Essential for cross-encoder models (e.g. bge-reranker) whose logits saturate through sigmoid. */
13
+ rawLogits?: boolean;
11
14
  }
12
15
  export interface ApiRerankerConfig {
13
16
  provider: "api";
@@ -117,6 +117,7 @@ export function resolveRerankerConfig(env = process.env) {
117
117
  throw new Error("PI_KNOWLEDGE_RERANKER requires a model id or URL");
118
118
  const resolved = resolveHfModel(modelSource);
119
119
  const revision = cleanEnv(env.PI_KNOWLEDGE_RERANKER_REVISION) ?? resolved.revision ?? DEFAULT_RERANKER_REVISION;
120
+ const rawLogits = cleanEnv(env.PI_KNOWLEDGE_RERANKER_RAW_LOGITS) === "true";
120
121
  return {
121
122
  provider: "hf",
122
123
  model: resolved.model,
@@ -124,6 +125,7 @@ export function resolveRerankerConfig(env = process.env) {
124
125
  dtype: cleanEnv(env.PI_KNOWLEDGE_RERANKER_DTYPE),
125
126
  remoteHost: cleanEnv(env.PI_KNOWLEDGE_RERANKER_REMOTE_HOST) ?? resolved.remoteHost,
126
127
  remotePathTemplate: cleanEnv(env.PI_KNOWLEDGE_RERANKER_REMOTE_PATH_TEMPLATE),
128
+ ...(rawLogits ? { rawLogits: true } : {}),
127
129
  };
128
130
  }
129
131
  export function isHfRerankerConfig(value) {
@@ -137,7 +139,8 @@ export function isHfRerankerConfig(value) {
137
139
  config.revision.length > 0 &&
138
140
  (config.dtype === undefined || typeof config.dtype === "string") &&
139
141
  (config.remoteHost === undefined || typeof config.remoteHost === "string") &&
140
- (config.remotePathTemplate === undefined || typeof config.remotePathTemplate === "string"));
142
+ (config.remotePathTemplate === undefined || typeof config.remotePathTemplate === "string") &&
143
+ (config.rawLogits === undefined || typeof config.rawLogits === "boolean"));
141
144
  }
142
145
  export function rerankerCacheKey(config) {
143
146
  return [
@@ -147,5 +150,6 @@ export function rerankerCacheKey(config) {
147
150
  config.dtype ?? "",
148
151
  config.remoteHost ?? "",
149
152
  config.remotePathTemplate ?? "",
153
+ config.rawLogits ? "raw" : "sigmoid",
150
154
  ].join("\u0000");
151
155
  }
@@ -0,0 +1,20 @@
1
+ export type RawLogitRerankInput = {
2
+ text: string;
3
+ text_pair: string;
4
+ };
5
+ export type RawLogitTokenizer = (text: string, options: {
6
+ text_pair: string;
7
+ padding: true;
8
+ truncation: true;
9
+ }) => Record<string, unknown>;
10
+ export type RawLogitModel = (inputs: Record<string, unknown>) => Promise<{
11
+ logits: {
12
+ data: ArrayLike<number>;
13
+ };
14
+ }>;
15
+ export declare function scoreSingleRawLogit(logits: {
16
+ data: ArrayLike<number>;
17
+ }, model: string): number;
18
+ export declare function rerankWithSingleRawLogit(input: RawLogitRerankInput, tokenizer: RawLogitTokenizer, model: RawLogitModel, modelName: string): Promise<Array<{
19
+ score: number;
20
+ }>>;
@@ -0,0 +1,16 @@
1
+ export function scoreSingleRawLogit(logits, model) {
2
+ const scores = Array.from(logits.data);
3
+ if (scores.length !== 1) {
4
+ throw new Error(`Raw-logit reranker expected a single-logit sequence classifier for ${model}, got ${scores.length} logits. ` +
5
+ "Use a single-logit reranker model or disable PI_KNOWLEDGE_RERANKER_RAW_LOGITS.");
6
+ }
7
+ const score = scores[0];
8
+ if (!Number.isFinite(score))
9
+ throw new Error(`Raw-logit reranker returned a non-finite score for ${model}`);
10
+ return score;
11
+ }
12
+ export async function rerankWithSingleRawLogit(input, tokenizer, model, modelName) {
13
+ const inputs = tokenizer(input.text, { text_pair: input.text_pair, padding: true, truncation: true });
14
+ const { logits } = await model(inputs);
15
+ return [{ score: scoreSingleRawLogit(logits, modelName) }];
16
+ }
@@ -41,6 +41,7 @@ Each KB stores the embedding model label, vector dimension, and a non-secret emb
41
41
  | `PI_KNOWLEDGE_RERANKER_DTYPE` | unset | Optional Transformers.js dtype, such as `fp32`, for local/HF rerankers. |
42
42
  | `PI_KNOWLEDGE_RERANKER_REMOTE_HOST` | Hugging Face host or URL-derived host | Remote artifact host for HF-compatible model repositories. Use with trusted mirrors only. |
43
43
  | `PI_KNOWLEDGE_RERANKER_REMOTE_PATH_TEMPLATE` | `{model}/resolve/{revision}/` | Transformers.js remote path template for HF-compatible mirrors. |
44
+ | `PI_KNOWLEDGE_RERANKER_RAW_LOGITS` | unset | Set to `true` for single-logit cross-encoder rerankers whose raw scores are flattened by sigmoid scoring. Multi-logit classifiers are rejected unless this option is disabled. |
44
45
  | `PI_KNOWLEDGE_RERANKER_API_ENDPOINT` | derived from base URL | Full HTTP rerank endpoint. Takes precedence over `PI_KNOWLEDGE_RERANKER_API_BASE_URL` and `OPENAI_BASE_URL`. |
45
46
  | `PI_KNOWLEDGE_RERANKER_API_BASE_URL` | `https://api.cohere.com/v2` | Base URL for Cohere/Jina-compatible `/rerank` APIs. `OPENAI_BASE_URL` is accepted only as a convenience fallback for gateways exposing the same schema. |
46
47
  | `PI_KNOWLEDGE_RERANKER_API_KEY` | `OPENAI_API_KEY` fallback | Bearer token for API rerankers. Omit only for trusted local services that do not require auth. |
@@ -52,7 +53,7 @@ Each KB stores the embedding model label, vector dimension, and a non-secret emb
52
53
  | `PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD` | `relevance_score` | Field name or dot path holding the rerank score. |
53
54
  | `PI_KNOWLEDGE_RERANKER_API_SCORE_DIRECTION` | `desc` | Sort direction for returned scores: `desc` when higher is better, `asc` when lower is better. |
54
55
 
55
- Reranker settings affect query-time `deep` search only; they do not change indexed KB vectors. Local/HF rerankers run in the isolated model worker. Offline mode sets the model worker to local-only loading, so a local/HF reranker must already exist in the model cache. API rerankers send the query and selected candidate chunk content to the configured external service; failures surface by default and do not silently fall back to the local worker.
56
+ Reranker settings affect query-time `deep` search only; they do not change indexed KB vectors. Local/HF rerankers run in the isolated model worker. Offline mode sets the model worker to local-only loading, so a local/HF reranker must already exist in the model cache. `PI_KNOWLEDGE_RERANKER_RAW_LOGITS=true` switches local/HF rerankers from the Transformers.js text-classification pipeline to direct sequence-classification logits and is intended only for trusted single-logit reranker models; use trusted model repositories or pinned revisions for non-default artifacts. API rerankers send the query and selected candidate chunk content to the configured external service; failures surface by default and do not silently fall back to the local worker.
56
57
 
57
58
  Local embeddings require a real Node 22+ executable for the isolated model worker. `pi-knowledge` first tries Node IPC and automatically falls back to a stdin/stdout JSONL worker transport when the host runtime does not expose `child_process.fork().send()`, which can happen in Windows OMP compatibility layers. On Windows it searches `PI_KNOWLEDGE_NODE_PATH`, persisted `knowledge_configure` settings, common Node, Volta, NVM, Codex `cua_node`, and `PATH` locations before failing. If worker startup still fails, call `knowledge_configure` with the full `node.exe` path such as `C:\Program Files\nodejs\node.exe`; accidental surrounding quotes are ignored. OpenAI-compatible embeddings avoid the local worker entirely.
58
59
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-knowledge",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Local-first RAG knowledge base for Pi and OMP coding agents with hybrid code/doc search, reranking, diagnostics, and large-project indexing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",