pi-knowledge 0.7.0 → 0.8.1

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,6 +1,17 @@
1
1
  # Changelog
2
2
 
3
3
 
4
+ ## [0.8.1] - 2026-08-08
5
+
6
+ ### Fixed
7
+ - Declared host approval tiers for public knowledge tools so read-only search no longer defaults to exec approval in OMP headless sessions (#10).
8
+
9
+ ## [0.8.0] - 2026-08-04
10
+
11
+ ### Added
12
+ - Added Hugging Face Text Embeddings Inference reranker API format support through `PI_KNOWLEDGE_RERANKER_API_FORMAT=tei`.
13
+
14
+
4
15
  ## [0.7.0] - 2026-07-28
5
16
 
6
17
  ### Added
package/README.md CHANGED
@@ -184,6 +184,8 @@ Full configuration details are in [docs/configuration.md](docs/configuration.md)
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` |
186
186
 
187
+ For Hugging Face Text Embeddings Inference rerankers, use `PI_KNOWLEDGE_RERANKER=api:<model>`, `PI_KNOWLEDGE_RERANKER_API_FORMAT=tei`, and `PI_KNOWLEDGE_RERANKER_API_ENDPOINT=http://127.0.0.1:8080/rerank`; TEI exposes OpenAI-compatible embeddings under `/v1`, but reranking uses `/rerank`.
188
+
187
189
  ## Pi and OMP Support
188
190
 
189
191
  `pi-knowledge` supports Pi and [OMP](https://omp.sh/) extension loading through the packaged `extension.js` entry shim. The entry stays startup-light: install-time validation can inspect the extension without resolving native runtime dependencies, and runtime modules load lazily only when tools or lifecycle hooks need them.
package/dist/index.d.ts CHANGED
@@ -7,10 +7,12 @@ type ToolResult = {
7
7
  isError?: boolean;
8
8
  };
9
9
  type ToolUpdate = (result: ToolResult) => void;
10
+ type ToolApproval = "read" | "write" | "exec";
10
11
  type ToolDefinition = {
11
12
  name: string;
12
13
  label: string;
13
14
  description: string;
15
+ approval?: ToolApproval;
14
16
  promptSnippet?: string;
15
17
  promptGuidelines?: string[];
16
18
  parameters: Schema;
package/dist/index.js CHANGED
@@ -201,6 +201,7 @@ export default function (pi) {
201
201
  name: "knowledge_plan",
202
202
  label: "Knowledge Plan",
203
203
  description: "Inspect an indexing source without writing a KB, showing scannable counts, suggested exclusions, and technical skips",
204
+ approval: "read",
204
205
  promptSnippet: "Plan a knowledge-base indexing scope before calling knowledge_add",
205
206
  promptGuidelines: [
206
207
  "Use knowledge_plan before knowledge_add for broad directories, large repositories, or sources that may contain private or low-signal text",
@@ -252,6 +253,7 @@ export default function (pi) {
252
253
  name: "knowledge_configure",
253
254
  label: "Knowledge Configure",
254
255
  description: "Configure pi-knowledge runtime settings such as the local model worker Node executable",
256
+ approval: "write",
255
257
  promptSnippet: "Configure local pi-knowledge runtime prerequisites before indexing",
256
258
  promptGuidelines: [
257
259
  "Use knowledge_configure when knowledge_doctor or knowledge_add reports that local embeddings cannot find a usable Node executable",
@@ -287,6 +289,7 @@ export default function (pi) {
287
289
  name: "knowledge_add",
288
290
  label: "Knowledge Add",
289
291
  description: "Index files, directories, URLs, PDFs, DOCX, or text into a named knowledge base for semantic search",
292
+ approval: "write",
290
293
  promptSnippet: "Index files/dirs/URLs/PDFs/DOCX/text into a searchable knowledge base",
291
294
  promptGuidelines: [
292
295
  "Use knowledge_plan first for broad directories, large repositories, or sources that may contain private or low-signal text",
@@ -355,6 +358,7 @@ export default function (pi) {
355
358
  name: "knowledge_search",
356
359
  label: "Knowledge Search",
357
360
  description: "Search indexed knowledge bases using lexical BM25, semantic vectors, reranking, and filters",
361
+ approval: "read",
358
362
  promptSnippet: "Search knowledge bases (hybrid is lexical-anchored BM25 + semantic fusion)",
359
363
  promptGuidelines: [
360
364
  "Use knowledge_search to find relevant context before answering domain questions",
@@ -453,6 +457,7 @@ export default function (pi) {
453
457
  name: "knowledge_symbol_search",
454
458
  label: "Knowledge Symbol Search",
455
459
  description: "Search indexed code symbols, Markdown headings, config keys, and environment variables exactly or by substring",
460
+ approval: "read",
456
461
  promptSnippet: "Find exact symbols/config keys/headings before broad semantic search",
457
462
  promptGuidelines: [
458
463
  "Use knowledge_symbol_search before knowledge_search when looking for a function, class, env var, config key, route, or Markdown heading",
@@ -522,6 +527,7 @@ export default function (pi) {
522
527
  name: "knowledge_update",
523
528
  label: "Knowledge Update",
524
529
  description: "Incrementally re-index a source-backed knowledge base with a retained file, directory, or URL source",
530
+ approval: "write",
525
531
  promptSnippet: "Refresh an existing source-backed KB",
526
532
  parameters: Type.Object({
527
533
  target: Type.String({ description: "KB name or ID to update" }),
@@ -540,6 +546,7 @@ export default function (pi) {
540
546
  name: "knowledge_status",
541
547
  label: "Knowledge Status",
542
548
  description: "Show knowledge engine status with health diagnostics: staleness, orphans, and coverage",
549
+ approval: "read",
543
550
  parameters: Type.Object({}),
544
551
  async execute(_id, _params, _signal) {
545
552
  if (_signal?.aborted)
@@ -607,6 +614,7 @@ export default function (pi) {
607
614
  name: "knowledge_doctor",
608
615
  label: "Knowledge Doctor",
609
616
  description: "Diagnose knowledge base health, skipped files, stale indexes, stuck jobs, and recommended fixes",
617
+ approval: "read",
610
618
  promptSnippet: "Diagnose knowledge base health and recommended actions",
611
619
  parameters: Type.Object({}),
612
620
  async execute(_id, _params, _signal) {
@@ -632,6 +640,7 @@ export default function (pi) {
632
640
  name: "knowledge_show",
633
641
  label: "Knowledge Show",
634
642
  description: "List all indexed knowledge bases",
643
+ approval: "read",
635
644
  parameters: Type.Object({}),
636
645
  async execute(_id, _params, _signal) {
637
646
  if (_signal?.aborted)
@@ -650,6 +659,7 @@ export default function (pi) {
650
659
  name: "knowledge_remove",
651
660
  label: "Knowledge Remove",
652
661
  description: "Remove a knowledge base by name or ID after explicit confirmation",
662
+ approval: "write",
653
663
  promptGuidelines: [
654
664
  "Destructive: only call after the user explicitly asks to remove knowledge data or confirms a proposed removal",
655
665
  "Prefer knowledge_status or knowledge_doctor before removing data for troubleshooting",
@@ -676,6 +686,7 @@ export default function (pi) {
676
686
  name: "knowledge_export",
677
687
  label: "Knowledge Export",
678
688
  description: "Export a knowledge base to a JSONL file (shareable, git-friendly)",
689
+ approval: "write",
679
690
  parameters: Type.Object({
680
691
  target: Type.String({ description: "KB name or ID to export" }),
681
692
  output: Type.String({ description: "Output file path (.jsonl)" }),
@@ -693,6 +704,7 @@ export default function (pi) {
693
704
  name: "knowledge_import",
694
705
  label: "Knowledge Import",
695
706
  description: "Import a knowledge base from a JSONL file (re-embeds content)",
707
+ approval: "write",
696
708
  parameters: Type.Object({
697
709
  input: Type.String({ description: "Input JSONL file path" }),
698
710
  }),
@@ -708,6 +720,7 @@ export default function (pi) {
708
720
  name: "knowledge_clear",
709
721
  label: "Knowledge Clear",
710
722
  description: "Remove all knowledge bases after explicit confirmation",
723
+ approval: "write",
711
724
  promptGuidelines: [
712
725
  "Destructive: only call after the user explicitly asks to clear all knowledge data or confirms a proposed clear",
713
726
  "Never use knowledge_clear as troubleshooting unless the user explicitly approves",
@@ -37,12 +37,12 @@ function mapApiResult(result, candidates, config) {
37
37
  return { chunkId: candidates[index].chunkId, score };
38
38
  }
39
39
  function requestBody(query, candidates, topK, config) {
40
- const documents = candidates.map((candidate) => {
41
- const text = candidate.content.length > config.maxDocumentChars
42
- ? candidate.content.slice(0, config.maxDocumentChars)
43
- : candidate.content;
44
- return config.format === "custom-json" ? { id: candidate.chunkId, text } : text;
45
- });
40
+ const texts = candidates.map((candidate) => candidate.content.length > config.maxDocumentChars
41
+ ? candidate.content.slice(0, config.maxDocumentChars)
42
+ : candidate.content);
43
+ if (config.format === "tei")
44
+ return JSON.stringify({ query, texts });
45
+ const documents = config.format === "custom-json" ? texts.map((text, index) => ({ id: candidates[index].chunkId, text })) : texts;
46
46
  return JSON.stringify({
47
47
  model: config.model,
48
48
  query,
@@ -1,5 +1,5 @@
1
1
  export type RerankerProvider = "hf" | "api";
2
- export type ApiRerankerFormat = "cohere" | "jina" | "custom-json";
2
+ export type ApiRerankerFormat = "cohere" | "jina" | "custom-json" | "tei";
3
3
  export type ApiScoreDirection = "desc" | "asc";
4
4
  export interface HfRerankerConfig {
5
5
  provider: "hf";
@@ -60,8 +60,9 @@ function normalizeApiFormat(value) {
60
60
  if (value === undefined)
61
61
  return "cohere";
62
62
  const normalized = value.toLowerCase();
63
- if (normalized === "cohere" || normalized === "jina" || normalized === "custom-json")
63
+ if (normalized === "cohere" || normalized === "jina" || normalized === "custom-json" || normalized === "tei") {
64
64
  return normalized;
65
+ }
65
66
  throw new Error(`Unsupported reranker API format: ${value}`);
66
67
  }
67
68
  function normalizeScoreDirection(value) {
@@ -87,17 +88,18 @@ function resolveApiRerankerConfig(model, env) {
87
88
  endpointFromBaseUrl(cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_BASE_URL) ??
88
89
  cleanEnv(env.OPENAI_BASE_URL) ??
89
90
  "https://api.cohere.com/v2"));
91
+ const format = normalizeApiFormat(cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_FORMAT));
90
92
  return {
91
93
  provider: "api",
92
94
  model,
93
95
  endpoint,
94
96
  apiKey: cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_KEY) ?? cleanEnv(env.OPENAI_API_KEY),
95
- format: normalizeApiFormat(cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_FORMAT)),
97
+ format,
96
98
  timeoutMs: parseNumber(cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_TIMEOUT_MS), DEFAULT_RERANKER_API_TIMEOUT_MS, 1_000, 300_000),
97
99
  maxDocumentChars: parseNumber(cleanEnv(env.PI_KNOWLEDGE_RERANKER_MAX_DOC_CHARS), DEFAULT_RERANKER_MAX_DOC_CHARS, 100, 200_000),
98
- resultsPath: cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_RESULTS_PATH) ?? "results",
100
+ resultsPath: cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_RESULTS_PATH) ?? (format === "tei" ? "" : "results"),
99
101
  indexField: cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_INDEX_FIELD) ?? "index",
100
- scoreField: cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD) ?? "relevance_score",
102
+ scoreField: cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD) ?? (format === "tei" ? "score" : "relevance_score"),
101
103
  scoreDirection: normalizeScoreDirection(cleanEnv(env.PI_KNOWLEDGE_RERANKER_API_SCORE_DIRECTION)),
102
104
  };
103
105
  }
@@ -45,16 +45,18 @@ Each KB stores the embedding model label, vector dimension, and a non-secret emb
45
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`. |
46
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. |
47
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. |
48
- | `PI_KNOWLEDGE_RERANKER_API_FORMAT` | `cohere` | Request/response preset: `cohere`, `jina`, or `custom-json`. All presets send `model`, `query`, `documents`, `top_n`, and `return_documents:false`. |
48
+ | `PI_KNOWLEDGE_RERANKER_API_FORMAT` | `cohere` | Request/response preset: `cohere`, `jina`, `custom-json`, or `tei`. Cohere/Jina-compatible presets send `model`, `query`, `documents`, `top_n`, and `return_documents:false`; `tei` sends `query` plus `texts` and parses a root response array with `index`/`score`. |
49
49
  | `PI_KNOWLEDGE_RERANKER_API_TIMEOUT_MS` | `30000` | Per-request timeout for API reranking. |
50
50
  | `PI_KNOWLEDGE_RERANKER_MAX_DOC_CHARS` | `12000` | Per-candidate document safety cap before sending content to the API. |
51
- | `PI_KNOWLEDGE_RERANKER_API_RESULTS_PATH` | `results` | Dot path to the result array for `custom-json` or compatible responses. |
51
+ | `PI_KNOWLEDGE_RERANKER_API_RESULTS_PATH` | `results` (`tei`: root response array) | Dot path to the result array for `custom-json` or compatible responses. |
52
52
  | `PI_KNOWLEDGE_RERANKER_API_INDEX_FIELD` | `index` | Field name or dot path holding the original candidate index. |
53
- | `PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD` | `relevance_score` | Field name or dot path holding the rerank score. |
53
+ | `PI_KNOWLEDGE_RERANKER_API_SCORE_FIELD` | `relevance_score` (`tei`: `score`) | Field name or dot path holding the rerank score. |
54
54
  | `PI_KNOWLEDGE_RERANKER_API_SCORE_DIRECTION` | `desc` | Sort direction for returned scores: `desc` when higher is better, `asc` when lower is better. |
55
55
 
56
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.
57
57
 
58
+ For Hugging Face Text Embeddings Inference rerankers, set `PI_KNOWLEDGE_RERANKER_API_FORMAT=tei` and point `PI_KNOWLEDGE_RERANKER_API_ENDPOINT` at the TEI `/rerank` endpoint, for example `http://127.0.0.1:8080/rerank`. Do not reuse an embeddings `OPENAI_BASE_URL` ending in `/v1` unless the reranker endpoint actually exists there; TEI's OpenAI-compatible route covers embeddings, while reranking uses `/rerank`.
59
+
58
60
  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.
59
61
 
60
62
  API embedding failures intentionally surface by default. Silent fallback can hide bad API keys, wrong base URLs, unsupported model names, or context-window errors and can produce a KB with a different embedding model than intended. Query-time fallback is opt-in; indexing fallback is disabled to prevent mixed vector spaces in one KB.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-knowledge",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
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",