context-engineering-core 0.14.0__tar.gz → 0.15.0__tar.gz

{context_engineering_core-0.14.0 → context_engineering_core-0.15.0}/CHANGELOG.md

@@ -3,7 +3,29 @@
 Earlier versions (0.1.0–0.9.6) are documented in `docs/C01_REPORT.md` through
 `docs/C10_STORAGE_ACL_REPORT.md` and preserved as wheels under `archives/`.
 
-## 0.14.0 — 2026-10-31 (unreleased)
+## 0.15.0 — 2026-10-31 (unreleased)
+
+### Changed (behavior)
+- Hybrid retrieval is the default (`assemble_context(embedder="builtin")`): the
+  bundled potion-base-8M model (8-bit vectors, ~7 MB in the package; MIT notice in
+  `embedding_data/LICENSE`) with a pure-Python WordPiece tokenizer. No download,
+  network or new dependency. `embedder=None` gives the pre-0.15.0 keyword-only path.
+- Default `semantic_weight` 0.7 → 0.5: a needle-in-filler check showed 0.7 losing
+  exact keyword matches (22/31 vs 31/31); 0.5 is equal or better on every set.
+- `strategy-eval` includes the hybrid strategies by default (`--no-semantic` to
+  skip; `--semantic` removed). `context-engine-mcp` is hybrid by default
+  (`--no-semantic`; `--semantic` removed).
+- The frozen benchmark harness pins keyword-only retrieval.
+
+### Added
+- `BuiltinEmbedder`, `default_embedder()`, `context_engine.wordpiece`.
+- Lenient grading v2 (`answer_correct_lenient`, `GRADERS`) beside frozen strict v1;
+  `scripts/regrade_live.py` writes `grading.json` for both live runs.
+
+### Unchanged
+- 0.14.0 wheel/freeze archived in `archives/c15-default-semantic-0150/`.
+
+## 0.14.0 — 2026-10-31 (PyPI)
 
 ### Added
 - Optional hybrid retrieval: `assemble_context(..., embedder=, semantic_weight=0.7)`

{context_engineering_core-0.14.0 → context_engineering_core-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: context-engineering-core
-Version: 0.14.0
+Version: 0.15.0
 Summary: Provider-independent context layers, source contracts, and token budget accounting
 Project-URL: Homepage, https://github.com/Nandu1729/Context-Engine
 Project-URL: Repository, https://github.com/Nandu1729/Context-Engine
@@ -50,7 +50,7 @@ that fits the budget. Those messages keep the recent turns, the facts you pinned
 and the older evidence that matches the question. It never calls a model by
 itself, so you send the messages to any provider you like.
 
-> **Status: alpha (0.14.0).** Good for developers to try locally. It is not yet
+> **Status: alpha (0.15.0).** Good for developers to try locally. It is not yet
 > proven on real-world data, and there is no hosted service. See
 > [What is not proven yet](#what-is-not-proven-yet).
 
@@ -111,22 +111,20 @@ chat_model.invoke(langchain_messages(result))  # pip install 'context-engineerin
 history = turns_from_openai(existing_openai_messages, scope)  # reuse a chat history you already have
 ```
 
-### Better recall for reworded questions (optional)
+### Finds meaning, not just matching words
 
-Keyword search needs the question to reuse the fact's words. Add a small local
-embedding model so meaning matches too ("retailer" finds "merchant"):
+Retrieval combines keyword search with a small embedding model bundled in the
+package, so "retailer" finds "merchant". It runs locally with numpy: no download,
+no network, no extra dependency (the package is ~7 MB because of the model).
+Ranking is 0.5 x meaning score + 0.5 x keyword score.
 
 ```python
-# pip install 'context-engineering-core[semantic]'   (~30 MB model, downloaded once)
-from context_engine.embeddings import Model2VecEmbedder
-
-embedder = Model2VecEmbedder()   # pinned minishlab/potion-base-8M; loads only when you create it
-result = assemble_context(history, question, pins, budget, system=system, embedder=embedder)
+result = assemble_context(..., embedder=None)   # keyword-only, as before 0.15.0
+from context_engine.embeddings import FastEmbedEmbedder, FunctionEmbedder, Model2VecEmbedder
+result = assemble_context(..., embedder=FastEmbedEmbedder())  # more accurate, slower (extra [fastembed])
 ```
 
-Ranking becomes 0.7 x meaning score + 0.3 x keyword score. Prefer accuracy over
-speed? `FastEmbedEmbedder("BAAI/bge-small-en-v1.5")` (extra `[fastembed]`). Or wrap
-your own embedding function or API with `FunctionEmbedder`.
+`FunctionEmbedder` wraps your own embedding function or API.
 
 ### Use it from an MCP client
 
@@ -178,12 +176,14 @@ These are enforced in code and covered by about 1,400 tests:
   benchmark, the default settings keep 31 of 31 planted facts at 900 and 3000
   tokens, and a live model run answered 31 of 31 correctly at 900 tokens. But
   that benchmark is one synthetic conversation written alongside the engine.
-- **Reworded questions.** By default, retrieval is keyword-based (BM25). When we
-  reword the 31 benchmark questions so they share no words with the stored facts,
-  the default settings keep only 3 of 31 facts. With the optional embedder (see
-  above) they keep 21 of 31 (retrieval alone: 24–25 of 31), with no loss on the
-  original questions. Run it yourself:
-  `context-engine strategy-eval --questions paraphrased --semantic`.
+- **Reworded questions.** When we reword the 31 benchmark questions so they share
+  no words with the stored facts, keyword-only retrieval keeps 3 of 31 facts; the
+  default hybrid retrieval keeps 21 of 31 (retrieval alone: 24–25 of 31), with no
+  loss on the original questions. In a live model run on the reworded questions,
+  keyword-only answered 3 of 31 correctly and hybrid 18 of 31 (21 of 31 with
+  lenient grading, which ignores trailing punctuation and dash characters). A fact
+  buried in a long, repetitive message and asked with different words is still
+  hard (12 of 31). Run the offline test: `context-engine strategy-eval --questions paraphrased`.
 - **Real-world data.** There are no results yet on real user conversations.
 - **Exact provider token counts.** Budgets use a local tokenizer estimate.
   Providers may count differently. On small requests, provider counts were up

{context_engineering_core-0.14.0 → context_engineering_core-0.15.0}/README.md

@@ -9,7 +9,7 @@ that fits the budget. Those messages keep the recent turns, the facts you pinned
 and the older evidence that matches the question. It never calls a model by
 itself, so you send the messages to any provider you like.
 
-> **Status: alpha (0.14.0).** Good for developers to try locally. It is not yet
+> **Status: alpha (0.15.0).** Good for developers to try locally. It is not yet
 > proven on real-world data, and there is no hosted service. See
 > [What is not proven yet](#what-is-not-proven-yet).
 
@@ -70,22 +70,20 @@ chat_model.invoke(langchain_messages(result))  # pip install 'context-engineerin
 history = turns_from_openai(existing_openai_messages, scope)  # reuse a chat history you already have
 ```
 
-### Better recall for reworded questions (optional)
+### Finds meaning, not just matching words
 
-Keyword search needs the question to reuse the fact's words. Add a small local
-embedding model so meaning matches too ("retailer" finds "merchant"):
+Retrieval combines keyword search with a small embedding model bundled in the
+package, so "retailer" finds "merchant". It runs locally with numpy: no download,
+no network, no extra dependency (the package is ~7 MB because of the model).
+Ranking is 0.5 x meaning score + 0.5 x keyword score.
 
 ```python
-# pip install 'context-engineering-core[semantic]'   (~30 MB model, downloaded once)
-from context_engine.embeddings import Model2VecEmbedder
-
-embedder = Model2VecEmbedder()   # pinned minishlab/potion-base-8M; loads only when you create it
-result = assemble_context(history, question, pins, budget, system=system, embedder=embedder)
+result = assemble_context(..., embedder=None)   # keyword-only, as before 0.15.0
+from context_engine.embeddings import FastEmbedEmbedder, FunctionEmbedder, Model2VecEmbedder
+result = assemble_context(..., embedder=FastEmbedEmbedder())  # more accurate, slower (extra [fastembed])
 ```
 
-Ranking becomes 0.7 x meaning score + 0.3 x keyword score. Prefer accuracy over
-speed? `FastEmbedEmbedder("BAAI/bge-small-en-v1.5")` (extra `[fastembed]`). Or wrap
-your own embedding function or API with `FunctionEmbedder`.
+`FunctionEmbedder` wraps your own embedding function or API.
 
 ### Use it from an MCP client
 
@@ -137,12 +135,14 @@ These are enforced in code and covered by about 1,400 tests:
   benchmark, the default settings keep 31 of 31 planted facts at 900 and 3000
   tokens, and a live model run answered 31 of 31 correctly at 900 tokens. But
   that benchmark is one synthetic conversation written alongside the engine.
-- **Reworded questions.** By default, retrieval is keyword-based (BM25). When we
-  reword the 31 benchmark questions so they share no words with the stored facts,
-  the default settings keep only 3 of 31 facts. With the optional embedder (see
-  above) they keep 21 of 31 (retrieval alone: 24–25 of 31), with no loss on the
-  original questions. Run it yourself:
-  `context-engine strategy-eval --questions paraphrased --semantic`.
+- **Reworded questions.** When we reword the 31 benchmark questions so they share
+  no words with the stored facts, keyword-only retrieval keeps 3 of 31 facts; the
+  default hybrid retrieval keeps 21 of 31 (retrieval alone: 24–25 of 31), with no
+  loss on the original questions. In a live model run on the reworded questions,
+  keyword-only answered 3 of 31 correctly and hybrid 18 of 31 (21 of 31 with
+  lenient grading, which ignores trailing punctuation and dash characters). A fact
+  buried in a long, repetitive message and asked with different words is still
+  hard (12 of 31). Run the offline test: `context-engine strategy-eval --questions paraphrased`.
 - **Real-world data.** There are no results yet on real user conversations.
 - **Exact provider token counts.** Budgets use a local tokenizer estimate.
   Providers may count differently. On small requests, provider counts were up

{context_engineering_core-0.14.0 → context_engineering_core-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-engineering-core"
-version = "0.14.0"
+version = "0.15.0"
 description = "Provider-independent context layers, source contracts, and token budget accounting"
 readme = "README.md"
 license = "Apache-2.0"

{context_engineering_core-0.14.0 → context_engineering_core-0.15.0}/src/context_engine/__init__.py

@@ -1,6 +1,6 @@
 """Core contracts. Importing this package performs no configuration or network I/O."""
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 
 def __getattr__(name):

{context_engineering_core-0.14.0 → context_engineering_core-0.15.0}/src/context_engine/cli.py

@@ -88,9 +88,9 @@ def main(argv: list[str] | None = None) -> int:
         help="paraphrased: reworded questions with no shared words (lexical stress test)",
     )
     strategies.add_argument(
-        "--semantic",
+        "--no-semantic",
         action="store_true",
-        help="Also run hybrid strategies with the default embedder (needs the [semantic] extra)",
+        help="Skip the hybrid strategies (retrieval_semantic, combined_semantic)",
     )
     strategies.add_argument("--data-dir", type=Path)
     strategies.add_argument("--output", type=Path, help="Save JSON to a new file; never overwrite")
@@ -147,17 +147,12 @@ def main(argv: list[str] | None = None) -> int:
             budgets = None if args.budget is None else tuple(args.budget)
             if budgets is not None and any(b <= 0 for b in budgets):
                 raise ContextEngineError("Budgets must be positive integers")
-            embedder = None
-            if args.semantic:
-                from .embeddings import Model2VecEmbedder
-
-                embedder = Model2VecEmbedder()
             result = compare_strategies(
                 bundle,
                 budgets,
                 include_probes=args.probes,
                 questions=args.questions,
-                embedder=embedder,
+                embedder=None if args.no_semantic else "builtin",
             )
             if args.output is not None:
                 save_inspection(args.output, result)

context_engineering_core-0.15.0/src/context_engine/embedding_data/LICENSE

@@ -0,0 +1,33 @@
+Bundled embedding model data
+============================
+
+potion-base-8M-int8.npz and potion-base-8M-vocab.txt are derived from the
+Model2Vec model "minishlab/potion-base-8M" (revision
+bf8b056651a2c21b8d2565580b8569da283cab23), https://huggingface.co/minishlab/potion-base-8M,
+licensed under the MIT License. Its vocabulary comes from BAAI/bge-base-en-v1.5
+(MIT License). The vectors were quantized to 8-bit integers with one float32
+scale per token by the Context Engine project; no other changes.
+
+MIT License
+
+Copyright (c) 2024 Thomas van Dongen
+(copyright line as in the MIT license of the model2vec project; the model card
+of minishlab/potion-base-8M declares "license: mit")
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.