kibi-plugin-search-hints 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# Kibi search hints plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package provides the `kibi.search-hints.v1` capability. When `kb_search` gives a weak or abstained lexical answer, Kibi asks it which current entities the question is probably about, and shows up to ten of their requirements under `queryAnalysis.hints` and in one sentence of the text answer. The agent then re-asks in the KB's own words. Hints never change search results, the governing answer, abstention, `kb_check` or proofs.
+
+Activate it in the project's `package.json` and install it as a dev dependency:
+
+```json
+{
+  "kibi": {
+    "plugins": [
+      {
+        "package": "kibi-plugin-search-hints",
+        "capabilities": { "kibi.search-hints.v1": { "mode": "replace" } }
+      }
+    ]
+  }
+}
+```
+
+Use `"mode": "shadow"` to compute hints for comparison without showing them. `kb_search` with `hints: false` skips them for one call.
+
+The plugin embeds text with the bundled potion-base-8M static embedding (256 dimensions, int8, about 7.7 MB): a text's vector is the normalised mean of its tokens' table rows. It is pure TypeScript with no native code and no network access, and the same text gives the same vector on every platform. Entity vectors are cached under the directory Kibi passes in, keyed by the model and each entity's content hash, so only changed entities are re-embedded. The model is English-only.
+
+See `catalog.json`, `integrity.json`, `SBOM.spdx.json` and `THIRD_PARTY_NOTICES.md` for the shipped component record.

package/SBOM.spdx.json

@@ -0,0 +1,64 @@
+{
+  "spdxVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "kibi-plugin-search-hints-0.1.1",
+  "documentNamespace": "https://github.com/Looted/kibi/spdx/plugin-search-hints/0.1.1",
+  "creationInfo": {
+    "creators": ["Tool: Kibi qualification record"],
+    "created": "2026-10-29T00:00:00Z"
+  },
+  "packages": [
+    {
+      "name": "kibi-plugin-search-hints",
+      "SPDXID": "SPDXRef-KibiPluginSearchHints",
+      "versionInfo": "0.1.1",
+      "downloadLocation": "https://github.com/Looted/kibi/tree/develop/packages/plugin-search-hints",
+      "filesAnalyzed": false,
+      "licenseConcluded": "AGPL-3.0-or-later",
+      "licenseDeclared": "AGPL-3.0-or-later",
+      "copyrightText": "Copyright (C) 2026 Piotr Franczyk",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/kibi-plugin-search-hints@0.1.1"
+        }
+      ]
+    },
+    {
+      "name": "potion-base-8M",
+      "SPDXID": "SPDXRef-PotionBase8M",
+      "versionInfo": "bf8b056651a2c21b8d2565580b8569da283cab23",
+      "downloadLocation": "https://huggingface.co/minishlab/potion-base-8M/resolve/bf8b056651a2c21b8d2565580b8569da283cab23/model.safetensors",
+      "filesAnalyzed": false,
+      "licenseConcluded": "MIT",
+      "licenseDeclared": "MIT",
+      "copyrightText": "Copyright (c) 2024 Thomas van Dongen",
+      "comment": "Embedding table quantized to int8 as assets/potion-base-8M.int8.bin; digests in catalog.json."
+    },
+    {
+      "name": "bge-base-en-v1.5 vocabulary",
+      "SPDXID": "SPDXRef-BgeBaseVocabulary",
+      "versionInfo": "as shipped in potion-base-8M tokenizer.json",
+      "downloadLocation": "https://huggingface.co/BAAI/bge-base-en-v1.5",
+      "filesAnalyzed": false,
+      "licenseConcluded": "MIT",
+      "licenseDeclared": "MIT",
+      "copyrightText": "Copyright (c) 2022 staoxiao",
+      "comment": "WordPiece vocabulary as assets/vocab.txt."
+    }
+  ],
+  "relationships": [
+    {
+      "spdxElementId": "SPDXRef-KibiPluginSearchHints",
+      "relationshipType": "CONTAINS",
+      "relatedSpdxElement": "SPDXRef-PotionBase8M"
+    },
+    {
+      "spdxElementId": "SPDXRef-KibiPluginSearchHints",
+      "relationshipType": "CONTAINS",
+      "relatedSpdxElement": "SPDXRef-BgeBaseVocabulary"
+    }
+  ]
+}

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# Third-party notices
+
+The package bundles the static embedding table of [potion-base-8M](https://huggingface.co/minishlab/potion-base-8M) by Minish Lab (MIT, `licenses/potion-base-8M-MIT.txt`), revision `bf8b056651a2c21b8d2565580b8569da283cab23`, and its WordPiece vocabulary, which comes from [bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) by BAAI (MIT, `licenses/bge-base-en-v1.5-vocabulary-MIT.txt`).
+
+`assets/potion-base-8M.int8.bin` is the upstream `model.safetensors` table quantized to signed 8-bit values with one float32 scale per row by `scripts/build-model-asset.mjs`; `assets/vocab.txt` lists the upstream tokenizer vocabulary in id order. The upstream file digest, the asset digests and the quantization are recorded in `catalog.json`; package-file digests are recorded in `integrity.json`.
+
+The tokenizer and encoder are Kibi-authored TypeScript. No upstream code, Python package or native library is shipped or executed, and nothing is downloaded at runtime.