bgts-context-engine 0.2.2__tar.gz → 0.2.4__tar.gz

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/CHANGELOG.md

@@ -7,6 +7,122 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-09-22
+
+This release turns the agent benchmark (a Cursor CLI agent on 14 tasks against a
+React/TypeScript codebase, plain vs. with the engine) into product behaviour. The MCP server alone made a Cursor agent *worse*: it asked the graph late (after
+a round of grep) or eight times per task, and the answer it got back had no file or line.
+With one advertised tool, a rule that says "call it first and treat `file:line` as a
+verified location", the answer handed over before the first turn, and a shorter context
+budget, the same agent on the same 14 tasks, model and machine used 20 % fewer tokens,
+produced 46 % less grep/glob output and 13 % fewer model turns, passed 73/73 checks against
+72/73, and changed 23 % fewer lines. Everything below is what that took.
+
+### Added
+
+- `bce cursor-init [--project DIR] [--repo-id ID]... [--env-file PATH] [--bce-command X]`:
+  writes a project's `.cursor/mcp.json` (merged into an existing one; other servers are
+  kept) with the absolute path of the running `bce`, `serve-mcp --env-file …` and
+  `PYTHONUTF8=1`, plus the `alwaysApply` rule `.cursor/rules/bgts-context-engine.mdc`. The
+  rule ships in the wheel as a template, so every install gets the same instruction: call
+  `get_context_for_task` first with the full task text, open the returned `file:line`
+  entries directly instead of grepping for them, treat the list as places to inspect rather
+  than files to edit, never repeat a call with the same text. Idempotent.
+- `bce claude-init …[--no-hook]`: the Claude Code counterpart — `.mcp.json` (merged), a
+  section in `CLAUDE.md` between `<!-- bgts-context-engine:begin/end -->` markers (the rest
+  of the file is kept), and by default a `UserPromptSubmit` hook in `.claude/settings.json`
+  (other hooks kept) that runs `bce precontext` before every prompt. Cursor gets no hook: its
+  `beforeSubmitPrompt` event can only allow or block a prompt, so there the rule carries the
+  instruction and the agent makes the one call itself.
+- `bce precontext [--task TEXT] [--repo-id ID]...`: the compact "Code context for this
+  task" block an agent prompt carries — a file list in rank order, then one line per symbol
+  (`path:line kind name distance`) with a snippet of at most 12 lines where the snippet says
+  more than the name; about 5 k characters at the default budget. Without `--task` it is the
+  Claude Code hook: reads the hook JSON on stdin, skips prompts under 20 characters and slash
+  commands, prints `hookSpecificOutput.additionalContext` capped at Claude Code's
+  10 000-character limit, and fails open (an unreachable database is a prompt without
+  context, never a blocked prompt). `bce.integrations.precontext.render_context_markdown`
+  is the renderer, for other hosts.
+- `BCE_MCP_TOOLS`: comma-separated names the MCP server advertises (default: all read
+  tools). Agents fetch a tool's schema before first use and chain small calls when many
+  tools are on offer; the benchmark ran with `get_context_for_task` alone. Unknown names
+  fail at startup, and a tool not advertised cannot be dispatched either.
+- `BCE_EMBEDDING_QUERY_TIMEOUT` (10 s, two attempts): the wait for embedding a single
+  *query* at search time, separate from the indexing timeout (600 s). When it expires,
+  `get_context_for_task` and `suggest_change_sites` answer from lexical and structural
+  anchors alone — visible as lower `coverage.confidence` — instead of failing after having
+  waited past an agent's MCP timeout (Cursor: 60 s). Motivated by a RunPod TCP proxy that
+  stalled connects for 19–67 s during the benchmark.
+- Context items carry `name`, `kind`, `file_id` and `line` next to `symbol_id`. Without
+  them an agent had to search the tree for the file behind every symbol id (the module path
+  does not say `.ts` vs `.tsx`, nor the line) — one tool call, one model turn, per item.
+
+### Changed
+
+- **Defaults: `max_candidates` 8 → 20, `max_tokens` 4000 → 1500**, on every surface (CLI
+  `bce context`, REST, MCP schema defaults, and the `bce.core.defaults` module they all
+  read). K=20 is where recall@K flattened in the PR replay for both fitted profiles and
+  what the agent benchmark ran with. The budget is shorter because an agent re-sends the
+  context on every turn: at 1500 it travelled as ~1.3 k tokens per turn and still halved
+  the agent's search output; 4000 travelled as ~4 k per turn for no further gain. Callers
+  wanting longer snippets pass `max_tokens` per request; the assembler still degrades items
+  to reference level rather than dropping them.
+- `.env.example` shows `voyage-code-4` (the model the voyage profile was fitted on) as the
+  Voyage example and documents `BCE_EMBEDDING_QUERY_TIMEOUT` and `BCE_MCP_TOOLS`. The code
+  default stays `voyage-code-3` so indexes built with it keep matching.
+- `server.json` describes the catalog as eight read-only tools plus two write tools rather
+  than "14 tools".
+
+## [0.2.3] - 2026-09-21
+
+### Added
+
+- `BCE_EMBEDDING_PROVIDER=openai`: an encoder that talks to any server speaking the OpenAI
+  `/v1/embeddings` protocol (vLLM, Text Embeddings Inference, Ollama, or OpenAI itself), using
+  only the standard library. This is how an open model such as `jinaai/jina-code-embeddings-1.5b`
+  runs on-prem. Query/document asymmetry is a text prefix — the jina-code family's `nl2code`
+  prompts are the default when the model name contains `jina-code`; anything else is unset
+  unless `BCE_EMBEDDING_QUERY_PREFIX` / `BCE_EMBEDDING_DOCUMENT_PREFIX` say otherwise.
+  `BCE_EMBEDDING_BASE_URL`, `BCE_EMBEDDING_API_KEY`, `BCE_EMBEDDING_EXTRA_BODY` (default
+  `{"truncate_prompt_tokens": -1}` so vLLM truncates instead of rejecting a long batch; set
+  `{}` for OpenAI's own API, which rejects unknown fields) and `BCE_EMBEDDING_TIMEOUT` (600 s)
+  configure the client. Vectors wider than `BCE_EMBEDDING_DIM` are truncated and re-normalised
+  (Matryoshka); a narrower reply is a configuration error. Transient 5xx / connection failures
+  retry three times; 4xx does not.
+- Retrieval profiles (`bce.core.orchestrator.profile`): the three engine constants that encode
+  *where in the model's ranked list the right answers sit* — semantic-anchor rank scale, the
+  share of the answer reserved for the model's ranks, and a guard on its top ranks in
+  narrowing — grouped per embedding family. `BCE_RETRIEVAL_PROFILE=auto` (the default) picks
+  `voyage` for `voyage-*` and unknown models (the historical constants, unchanged) and `jina`
+  for `jina-*`. Name one to force it; `BCE_RETRIEVAL_SEMANTIC_GUARD_RANKS` /
+  `_RESERVE_SHARE` / `_RANK_SCALE` override a single knob for fitting runs. A profile change
+  never needs a re-index. The active profile is written into every `bce bench-prs` report.
+- `bce migrate --reset-embeddings`: after the SQL migrations, `align_embedding_dim` re-types
+  `embeddings.embedding` to `BCE_EMBEDDING_DIM`. Stored vectors of another width are refused
+  unless the flag is set (they belong to another model and would be discarded); then the HNSW
+  index is rebuilt the same way migration `0005` did.
+
+### Changed
+
+- Narrowing reads the active retrieval profile. The voyage path is unchanged (no guard,
+  share 0.5). The jina profile adds a guard of 10: the model's first ten ranks fill slots
+  1–10 (only the container cap can skip one). jina-code finds more correct symbols than
+  voyage-code-4 but spreads them over ranks 1–15, and under the voyage constants the engine's
+  agreement with the model's *deeper* ranks satisfied the reserve share and pushed those mid
+  hits to positions 11–19 or out of the answer (PR replay, 30 PRs: recall@20 35.7 % → 38.2 %,
+  holdout 27.8 % → 34.9 %, retention of the model's own hits 83 % → 92 %). The list stays
+  K-monotonic.
+- `bce bench-prs` titles the markdown with the encoder that actually produced the snapshots
+  (`jina-code-embeddings-1.5b vs … + BCE`), because the JSON key `voyage` is historical, not
+  the model.
+
+### Fixed
+
+- `bce bench-prs --from-report` / `--rerun-bce` no longer treats a stored semantic pool
+  shorter than K as incomplete. A task whose neighbours are mostly tests legitimately has a
+  pool shorter than K — the live run had nothing more either — so the check is now "non-empty
+  and at least as long as the list scored from it".
+
 ## [0.2.2] - 2026-09-18
 
 ### Added
@@ -254,7 +370,9 @@ First public release.
 - Docker Compose deployment with PostgreSQL, Apache AGE and pgvector preconfigured.
 - `server.json` manifest describing the stdio server for the official MCP registry.
 
-[Unreleased]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.1.0...v0.2.0

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/MANIFEST.in

@@ -4,6 +4,7 @@ include README.tr.md
 include CHANGELOG.md
 recursive-include src/bce/core/i18n/catalogs *.json
 recursive-include src/bce/storage/relational/migrations *.sql
+recursive-include src/bce/integrations/templates *.mdc *.md
 
 # Compiled frontend, vendored by scripts/build_ui.py before a release build.
 recursive-include src/bce/api/rest/static *

{bgts_context_engine-0.2.2/src/bgts_context_engine.egg-info → bgts_context_engine-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bgts-context-engine
-Version: 0.2.2
+Version: 0.2.4
 Summary: Deterministic code-graph context engine for AI coding agents - PostgreSQL, Apache AGE and pgvector, over MCP and REST
 Author: Oğuz Öztürk, Enes İyidil
 Maintainer: BGTS
@@ -69,7 +69,7 @@ that actually answer it — ranked, budgeted, and reproducible.
 [![MCP](https://img.shields.io/badge/MCP-compatible-000000.svg)](docs/mcp.md)
 [![Stars](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
 
-[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Documentation](#documentation) · [Türkçe](README.tr.md)
+[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Documentation](#documentation) · [Türkçe](README.tr.md)
 
 </div>
 
@@ -150,9 +150,28 @@ Every MCP client uses the same stdio command plus the database in the environmen
 leave `bce serve-mcp` running in a terminal for the editor: stdout is the protocol, so the
 process stays silent, and the IDE starts its own copy.
 
+**One command per editor.** Run it in the project the agent works on (the repository you
+indexed), pointing at the engine's `.env`:
+
+```bash
+bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
+bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
+```
+
+`cursor-init` writes `.cursor/mcp.json` (merged into an existing one) and the rule
+`.cursor/rules/bgts-context-engine.mdc`, which tells the agent to call
+`get_context_for_task` *first*, treat its `file:line` entries as verified locations instead
+of grepping for them, and not to edit a file just because it was listed. `claude-init`
+writes `.mcp.json`, a marked section in `CLAUDE.md`, and a `UserPromptSubmit` hook
+(`bce precontext`) that runs the graph once per prompt and hands the agent the answer
+before its first turn — the flow the agent benchmark measured (−20 % tokens, half the search
+output, same or better checks; 14 tasks on a React/TypeScript codebase, same model and machine).
+Cursor's prompt hook cannot add context, so there the rule does that job. `--no-hook`,
+`--repo-id` (repeatable) and `--bce-command` adjust the files; both commands are safe to rerun.
+
 After you add or change the MCP config, **restart Cursor or VS Code** (or Command Palette
 → “Developer: Reload Window”). The server should then show as enabled with eight tools (ten with indexing enabled).
-Setup detail: [docs/mcp.md](docs/mcp.md).
+Setup detail: [docs/mcp.md](docs/mcp.md). The manual equivalents:
 
 **Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
 `.cursor/mcp.json` that stays local (the directory is gitignored):
@@ -217,12 +236,14 @@ Not a list of file paths. A ranked pack, with the reasoning attached:
   },
   "context": {
     "items": [
-      { "symbol_id": "...refresh_session#88c2", "detail_level": "full",
+      { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
+        "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
         "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
-      { "symbol_id": "...SESSION_TTL#4b0d",     "detail_level": "signature",
+      { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
+        "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
         "graph_distance": 2, "score": 6.10,  "tokens": 31,  "content": "SESSION_TTL: int" }
     ],
-    "used_tokens": 2913, "budget": 4000, "included": 8, "skipped": 0
+    "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
   },
   "coverage": {
     "anchor_source_count": 3, "connected_component_ratio": 0.875,
@@ -243,8 +264,10 @@ could not corroborate it — the moment for an agent to ask a follow-up question
 editing. `commit_mismatch` means the index is behind your working tree.
 
 **`detail_level`** falls off with graph distance: the symbol you are changing arrives in
-full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how eight
-genuinely relevant symbols fit in 4000 tokens.
+full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how twenty
+genuinely relevant symbols fit in 1500 tokens — short enough for an agent to carry on every
+turn. Every item also names its `file_id` and `line`, so the agent opens the file instead of
+searching for the symbol.
 
 ## How it works
 
@@ -294,7 +317,36 @@ The full formula, every weight, and the confidence thresholds are in
 - **A UI that explains itself.** `/ui` ships in the wheel and replays a real retrieval call
   stage by stage: anchors lighting up, expansion spreading, candidates scored and cut.
 - **Runs offline.** The default embedding provider is deterministic arithmetic over token
-  digests. No API key, no network, repeatable benchmarks.
+  digests. No API key, no network, repeatable benchmarks. `openai` talks to any
+  OpenAI-compatible `/v1/embeddings` server (vLLM, TEI, Ollama), so a model such as
+  [jina-code-embeddings-1.5b](https://huggingface.co/jinaai/jina-code-embeddings-1.5b)
+  can run inside the perimeter.
+
+## Supported models
+
+Embeddings only find entry points when the task text names nothing the graph already
+knows. They never rank the answer. Out of the box that seed is `hashing`: deterministic
+arithmetic, no API key, no network. For a real code model, set `BCE_EMBEDDING_PROVIDER`
+and `BCE_EMBEDDING_MODEL` to one of these:
+
+| Model | Provider | Dimension |
+| --- | --- | --- |
+| [`voyage-code-3`](https://blog.voyageai.com/2024/12/04/voyage-code-3/) | Voyage AI (`voyage`) | 1024 |
+| [`voyage-code-4`](https://blog.voyageai.com/2026/08/13/voyage-code-4/) | Voyage AI (`voyage`) | 1024 |
+| [`jina-code-embeddings-1.5b`](https://huggingface.co/jinaai/jina-code-embeddings-1.5b) | OpenAI-compatible (`openai`) | 1536 |
+
+Voyage is a hosted API — `pip install "bgts-context-engine[embed]"` and
+`BCE_VOYAGE_API_KEY`. Jina is the on-prem path: any server that speaks `/v1/embeddings`
+(vLLM, TEI, Ollama). Switching the model or the dimension is a re-index
+(`bce migrate --reset-embeddings`). The knobs are in
+[docs/deployment.md](docs/deployment.md).
+
+**Coming next** — same `openai` socket, not yet a fitted retrieval profile:
+
+- [`jina-code-embeddings-0.5b`](https://huggingface.co/jinaai/jina-code-embeddings-0.5b)
+  — the smaller sibling of 1.5b, for hosts that cannot hold 1.5B parameters.
+- [`Nomic Embed Code`](https://huggingface.co/nomic-ai/nomic-embed-code) — an open 7B
+  code retriever.
 
 ## Where it fits
 

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/README.md

@@ -16,7 +16,7 @@ that actually answer it — ranked, budgeted, and reproducible.
 [![MCP](https://img.shields.io/badge/MCP-compatible-000000.svg)](docs/mcp.md)
 [![Stars](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
 
-[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Documentation](#documentation) · [Türkçe](README.tr.md)
+[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Documentation](#documentation) · [Türkçe](README.tr.md)
 
 </div>
 
@@ -97,9 +97,28 @@ Every MCP client uses the same stdio command plus the database in the environmen
 leave `bce serve-mcp` running in a terminal for the editor: stdout is the protocol, so the
 process stays silent, and the IDE starts its own copy.
 
+**One command per editor.** Run it in the project the agent works on (the repository you
+indexed), pointing at the engine's `.env`:
+
+```bash
+bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
+bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
+```
+
+`cursor-init` writes `.cursor/mcp.json` (merged into an existing one) and the rule
+`.cursor/rules/bgts-context-engine.mdc`, which tells the agent to call
+`get_context_for_task` *first*, treat its `file:line` entries as verified locations instead
+of grepping for them, and not to edit a file just because it was listed. `claude-init`
+writes `.mcp.json`, a marked section in `CLAUDE.md`, and a `UserPromptSubmit` hook
+(`bce precontext`) that runs the graph once per prompt and hands the agent the answer
+before its first turn — the flow the agent benchmark measured (−20 % tokens, half the search
+output, same or better checks; 14 tasks on a React/TypeScript codebase, same model and machine).
+Cursor's prompt hook cannot add context, so there the rule does that job. `--no-hook`,
+`--repo-id` (repeatable) and `--bce-command` adjust the files; both commands are safe to rerun.
+
 After you add or change the MCP config, **restart Cursor or VS Code** (or Command Palette
 → “Developer: Reload Window”). The server should then show as enabled with eight tools (ten with indexing enabled).
-Setup detail: [docs/mcp.md](docs/mcp.md).
+Setup detail: [docs/mcp.md](docs/mcp.md). The manual equivalents:
 
 **Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
 `.cursor/mcp.json` that stays local (the directory is gitignored):
@@ -164,12 +183,14 @@ Not a list of file paths. A ranked pack, with the reasoning attached:
   },
   "context": {
     "items": [
-      { "symbol_id": "...refresh_session#88c2", "detail_level": "full",
+      { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
+        "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
         "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
-      { "symbol_id": "...SESSION_TTL#4b0d",     "detail_level": "signature",
+      { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
+        "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
         "graph_distance": 2, "score": 6.10,  "tokens": 31,  "content": "SESSION_TTL: int" }
     ],
-    "used_tokens": 2913, "budget": 4000, "included": 8, "skipped": 0
+    "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
   },
   "coverage": {
     "anchor_source_count": 3, "connected_component_ratio": 0.875,
@@ -190,8 +211,10 @@ could not corroborate it — the moment for an agent to ask a follow-up question
 editing. `commit_mismatch` means the index is behind your working tree.
 
 **`detail_level`** falls off with graph distance: the symbol you are changing arrives in
-full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how eight
-genuinely relevant symbols fit in 4000 tokens.
+full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how twenty
+genuinely relevant symbols fit in 1500 tokens — short enough for an agent to carry on every
+turn. Every item also names its `file_id` and `line`, so the agent opens the file instead of
+searching for the symbol.
 
 ## How it works
 
@@ -241,7 +264,36 @@ The full formula, every weight, and the confidence thresholds are in
 - **A UI that explains itself.** `/ui` ships in the wheel and replays a real retrieval call
   stage by stage: anchors lighting up, expansion spreading, candidates scored and cut.
 - **Runs offline.** The default embedding provider is deterministic arithmetic over token
-  digests. No API key, no network, repeatable benchmarks.
+  digests. No API key, no network, repeatable benchmarks. `openai` talks to any
+  OpenAI-compatible `/v1/embeddings` server (vLLM, TEI, Ollama), so a model such as
+  [jina-code-embeddings-1.5b](https://huggingface.co/jinaai/jina-code-embeddings-1.5b)
+  can run inside the perimeter.
+
+## Supported models
+
+Embeddings only find entry points when the task text names nothing the graph already
+knows. They never rank the answer. Out of the box that seed is `hashing`: deterministic
+arithmetic, no API key, no network. For a real code model, set `BCE_EMBEDDING_PROVIDER`
+and `BCE_EMBEDDING_MODEL` to one of these:
+
+| Model | Provider | Dimension |
+| --- | --- | --- |
+| [`voyage-code-3`](https://blog.voyageai.com/2024/12/04/voyage-code-3/) | Voyage AI (`voyage`) | 1024 |
+| [`voyage-code-4`](https://blog.voyageai.com/2026/08/13/voyage-code-4/) | Voyage AI (`voyage`) | 1024 |
+| [`jina-code-embeddings-1.5b`](https://huggingface.co/jinaai/jina-code-embeddings-1.5b) | OpenAI-compatible (`openai`) | 1536 |
+
+Voyage is a hosted API — `pip install "bgts-context-engine[embed]"` and
+`BCE_VOYAGE_API_KEY`. Jina is the on-prem path: any server that speaks `/v1/embeddings`
+(vLLM, TEI, Ollama). Switching the model or the dimension is a re-index
+(`bce migrate --reset-embeddings`). The knobs are in
+[docs/deployment.md](docs/deployment.md).
+
+**Coming next** — same `openai` socket, not yet a fitted retrieval profile:
+
+- [`jina-code-embeddings-0.5b`](https://huggingface.co/jinaai/jina-code-embeddings-0.5b)
+  — the smaller sibling of 1.5b, for hosts that cannot hold 1.5B parameters.
+- [`Nomic Embed Code`](https://huggingface.co/nomic-ai/nomic-embed-code) — an open 7B
+  code retriever.
 
 ## Where it fits
 

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/README.tr.md

@@ -14,7 +14,7 @@ veren sekiz sembolü sıralanmış, bütçelenmiş ve yeniden üretilebilir şek
 [![MCP](https://img.shields.io/badge/MCP-uyumlu-000000.svg)](docs/mcp.md)
 [![Yıldızlar](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
 
-[Hızlı başlangıç](#hızlı-başlangıç) · [Ajanınızdan kullanma](#ajanınızdan-kullanma) · [Nasıl çalışır](#nasıl-çalışır) · [Dokümantasyon](#dokümantasyon) · [English](README.md)
+[Hızlı başlangıç](#hızlı-başlangıç) · [Ajanınızdan kullanma](#ajanınızdan-kullanma) · [Nasıl çalışır](#nasıl-çalışır) · [Desteklenen modeller](#desteklenen-modeller) · [Dokümantasyon](#dokümantasyon) · [English](README.md)
 
 </div>
 
@@ -97,9 +97,31 @@ Her MCP istemcisi aynı stdio komutunu ve ortamındaki veritabanı bağlantısı
 Editör için terminalde `bce serve-mcp` açık bırakmayın: stdout protokoldür, bu yüzden
 süreç sessiz kalır; IDE kendi kopyasını başlatır.
 
+**Editör başına tek komut.** Ajanın çalıştığı projede (indekslediğiniz depoda), motorun
+`.env` dosyasını göstererek çalıştırın:
+
+```bash
+bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
+bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
+```
+
+`cursor-init`, `.cursor/mcp.json` dosyasını (varsa üzerine birleştirerek) ve
+`.cursor/rules/bgts-context-engine.mdc` kuralını yazar. Kural ajana şunları söyler:
+`get_context_for_task` aracını *ilk iş olarak* çağır, döndürdüğü `dosya:satır`
+girdilerini doğrulanmış konum say ve onları grep ile arama, listelendi diye bir dosyayı
+düzenleme. `claude-init` ise `.mcp.json`, `CLAUDE.md` içinde işaretli bir bölüm ve
+`bce precontext` komutunu çalıştıran bir `UserPromptSubmit` kancası yazar: kanca her
+istemde grafı bir kez sorgular ve yanıtı ajana ilk turundan önce verir. Ajan
+benchmark'ında ölçülen akış budur (−%20 token, yarıya inen arama çıktısı, eşit veya daha
+iyi kontroller; React/TypeScript bir kod tabanında 14 görev, aynı model ve makine).
+Cursor'ın istem kancası bağlam ekleyemediği için orada bu işi kural yapar. `--no-hook`,
+`--repo-id` (tekrarlanabilir) ve `--bce-command` dosyaları ayarlar; iki komut da tekrar
+çalıştırılmaya uygundur.
+
 MCP yapılandırmasını ekledikten veya değiştirdikten sonra **Cursor veya VS Code'u
 yeniden başlatın** (veya Komut Paleti → “Developer: Reload Window”). Sunucu sekiz araçla
 (indeksleme açıkken on araçla) etkin görünmelidir. Ayrıntı: [docs/mcp.md](docs/mcp.md).
+Elle yapmanın karşılıkları:
 
 **Cursor** — her proje için kullanıcı yapılandırması `~/.cursor/mcp.json`, ya da yerelde
 kalan bir proje `.cursor/mcp.json` (dizin gitignore'dadır):
@@ -165,12 +187,14 @@ Dosya yolu listesi değil. Gerekçesi ekli, sıralanmış bir paket:
   },
   "context": {
     "items": [
-      { "symbol_id": "...refresh_session#88c2", "detail_level": "full",
+      { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
+        "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
         "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
-      { "symbol_id": "...SESSION_TTL#4b0d",     "detail_level": "signature",
+      { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
+        "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
         "graph_distance": 2, "score": 6.10,  "tokens": 31,  "content": "SESSION_TTL: int" }
     ],
-    "used_tokens": 2913, "budget": 4000, "included": 8, "skipped": 0
+    "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
   },
   "coverage": {
     "anchor_source_count": 3, "connected_component_ratio": 0.875,
@@ -192,7 +216,8 @@ gereken an. `commit_mismatch` ise indeksin çalışma ağacınızın gerisinde k
 
 **`detail_level`** graf mesafesiyle azalır: değiştirdiğiniz sembol tam gövdesiyle,
 komşuları imza olarak, dış halka `name @ dosya:satır` biçiminde gelir. Gerçekten ilgili
-sekiz sembolün 4000 token'a sığması bu sayede olur.
+yirmi sembolün 1500 token'a sığması bu sayede olur — bir ajanın her turda taşıyabileceği
+kadar kısa. Her öge `file_id` ve `line` da taşır; ajan sembolü aramak yerine dosyayı açar.
 
 ## Nasıl çalışır
 
@@ -245,7 +270,36 @@ Formülün tamamı, her ağırlık ve güven eşikleri
   aşama aşama oynatır: çapaların yanması, genişlemenin yayılması, adayların skorlanıp
   kesilmesi.
 - **Çevrimdışı çalışır.** Varsayılan embedding sağlayıcısı, token özetleri üzerinde
-  deterministik aritmetiktir. API anahtarı yok, ağ yok, tekrarlanabilir ölçümler.
+  deterministik aritmetiktir. API anahtarı yok, ağ yok, tekrarlanabilir ölçümler. `openai`
+  sağlayıcısı OpenAI uyumlu herhangi bir `/v1/embeddings` sunucusuna konuşur (vLLM, TEI,
+  Ollama); [jina-code-embeddings-1.5b](https://huggingface.co/jinaai/jina-code-embeddings-1.5b)
+  gibi bir model çevre içinde çalışır.
+
+## Desteklenen modeller
+
+Embedding yalnızca grafın tanımadığı bir görev metninde giriş noktası bulur. Cevabı asla
+sıralamaz. Varsayılan `hashing`'dir: deterministik aritmetik, API anahtarı yok, ağ yok.
+Gerçek bir kod modeli için `BCE_EMBEDDING_PROVIDER` ve `BCE_EMBEDDING_MODEL`'i şunlardan
+birine ayarlayın:
+
+| Model | Sağlayıcı | Boyut |
+| --- | --- | --- |
+| [`voyage-code-3`](https://blog.voyageai.com/2024/12/04/voyage-code-3/) | Voyage AI (`voyage`) | 1024 |
+| [`voyage-code-4`](https://blog.voyageai.com/2026/08/13/voyage-code-4/) | Voyage AI (`voyage`) | 1024 |
+| [`jina-code-embeddings-1.5b`](https://huggingface.co/jinaai/jina-code-embeddings-1.5b) | OpenAI uyumlu (`openai`) | 1536 |
+
+Voyage barındırılan bir API'dir — `pip install "bgts-context-engine[embed]"` ve
+`BCE_VOYAGE_API_KEY`. Jina çevre-içi yoldur: `/v1/embeddings` konuşan herhangi bir
+sunucu (vLLM, TEI, Ollama). Model veya boyutu değiştirmek yeniden indekslemedir
+(`bce migrate --reset-embeddings`). Ayarlar
+[docs/deployment.md](docs/deployment.md) içindedir.
+
+**Sırada** — aynı `openai` soketi, henüz ayrı bir getirme profili yok:
+
+- [`jina-code-embeddings-0.5b`](https://huggingface.co/jinaai/jina-code-embeddings-0.5b)
+  — 1.5b'nin küçük kardeşi; 1.5B parametreyi taşıyamayan makineler için.
+- [`Nomic Embed Code`](https://huggingface.co/nomic-ai/nomic-embed-code) — açık kaynaklı
+  7B kod getiricisi.
 
 ## Nereye oturur
 

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/pyproject.toml

@@ -106,6 +106,7 @@ include = ["bce*"]
 bce = [
     "core/i18n/catalogs/*.json",
     "storage/relational/migrations/*.sql",
+    "integrations/templates/*",
     # Compiled frontend served at /ui; vendored by scripts/build_ui.py before a release build.
     "api/rest/static/**/*",
 ]

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/src/bce/__init__.py

@@ -5,4 +5,4 @@ specification for details. This package is the provider side of the deterministi
 contains no LLM and produces reproducible context packages.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/src/bce/api/mcp/server.py

@@ -44,8 +44,9 @@ def build_server(name: str = "bgts-context-engine") -> Any:
     from bce.config import get_settings
     from bce.storage.relational.db import connection
 
-    allow_write = get_settings().mcp_allow_write
-    specs = available_tool_specs(allow_write=allow_write)
+    settings = get_settings()
+    allow_write = settings.mcp_allow_write
+    specs = available_tool_specs(allow_write=allow_write, allowlist=settings.mcp_tool_allowlist)
     server = Server(name)
 
     @server.list_tools()
@@ -56,6 +57,8 @@ def build_server(name: str = "bgts-context-engine") -> Any:
         ]
 
     def _dispatch_blocking(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        if name not in specs:
+            raise KeyError(f"tool '{name}' is not advertised by this server (BCE_MCP_TOOLS)")
         with connection() as conn:
             try:
                 result = dispatch_tool(conn, name, arguments, allow_write=allow_write)

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/src/bce/api/mcp/tools.py

@@ -26,6 +26,7 @@ from typing import Any
 import psycopg
 
 from bce.core.auth.scope import Principal, ScopeFilter
+from bce.core.defaults import DEFAULT_MAX_CANDIDATES, DEFAULT_MAX_TOKENS
 from bce.core.i18n import get_translator
 from bce.jobs.store import enqueue_job, get_job, list_jobs
 from bce.storage.graph.client import GraphClient
@@ -57,10 +58,21 @@ TOOL_SPECS: dict[str, dict[str, Any]] = {
         ),
         "schema": _schema(
             {
-                "task_text": _STR,
+                "task_text": {
+                    **_STR,
+                    "description": "The task in prose; pass the full request text, once.",
+                },
                 "task_id": _STR,
-                "max_tokens": _INT,
-                "max_candidates": _INT,
+                "max_tokens": {
+                    **_INT,
+                    "default": DEFAULT_MAX_TOKENS,
+                    "description": "Token budget of the assembled context.",
+                },
+                "max_candidates": {
+                    **_INT,
+                    "default": DEFAULT_MAX_CANDIDATES,
+                    "description": "How many symbols to return (K).",
+                },
                 "commit": _STR,
                 "repo_ids": _STR_LIST,
                 "explicit_symbols": _STR_LIST,
@@ -137,11 +149,24 @@ TOOL_SPECS: dict[str, dict[str, Any]] = {
 }
 
 
-def available_tool_specs(*, allow_write: bool) -> dict[str, dict[str, Any]]:
-    """The catalog to advertise: write tools are hidden unless ``allow_write`` is set."""
-    if allow_write:
-        return dict(TOOL_SPECS)
-    return {name: spec for name, spec in TOOL_SPECS.items() if name not in WRITE_TOOLS}
+def available_tool_specs(
+    *, allow_write: bool, allowlist: frozenset[str] | None = None
+) -> dict[str, dict[str, Any]]:
+    """The catalog to advertise: write tools are hidden unless ``allow_write`` is set, and an
+    ``allowlist`` (``BCE_MCP_TOOLS``) narrows it further. Unknown names in the allowlist raise, so a
+    typo does not silently publish nothing."""
+    if allowlist is not None:
+        unknown = sorted(allowlist - set(TOOL_SPECS))
+        if unknown:
+            raise ValueError(
+                f"BCE_MCP_TOOLS names unknown tools {unknown}; known: {sorted(TOOL_SPECS)}"
+            )
+    specs = {
+        name: spec
+        for name, spec in TOOL_SPECS.items()
+        if (allow_write or name not in WRITE_TOOLS) and (allowlist is None or name in allowlist)
+    }
+    return specs
 
 
 def dispatch_tool(

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/src/bce/api/rest/schemas.py

@@ -11,6 +11,8 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
+from bce.core.defaults import DEFAULT_MAX_CANDIDATES, DEFAULT_MAX_TOKENS
+
 
 class IndexRequest(BaseModel):
     repo_path: str = Field(..., description="Path to a local repository to index.")
@@ -64,9 +66,11 @@ class ContextForTaskRequest(BaseModel):
     task_id: str | None = Field(
         default=None, description="Optional Jira task id (audit + history)."
     )
-    max_tokens: int = Field(default=4000, ge=1, le=200000, description="Token budget for assembly.")
+    max_tokens: int = Field(
+        default=DEFAULT_MAX_TOKENS, ge=1, le=200000, description="Token budget for assembly."
+    )
     max_candidates: int = Field(
-        default=8, ge=1, le=100, description="Narrow to at most N candidates."
+        default=DEFAULT_MAX_CANDIDATES, ge=1, le=100, description="Narrow to at most N candidates."
     )
     commit: str | None = Field(default=None, description="Pinned commit sha (stage 0).")
     repo_ids: list[str] | None = Field(
@@ -108,7 +112,7 @@ class AssembleContextRequest(BaseModel):
     symbol_ids: list[str] = Field(
         ..., description="Symbols to deduplicate and fit into the budget."
     )
-    max_tokens: int = Field(default=4000, ge=1, le=200000)
+    max_tokens: int = Field(default=DEFAULT_MAX_TOKENS, ge=1, le=200000)
 
 
 class ToolResponse(BaseModel):

{bgts_context_engine-0.2.2 → bgts_context_engine-0.2.4}/src/bce/api/rest/ui/trace.py

@@ -21,6 +21,7 @@ from bce.core.coverage import compute_coverage
 from bce.core.orchestrator.anchors import find_anchors
 from bce.core.orchestrator.expand import expand_from_anchors, to_candidates
 from bce.core.orchestrator.orchestrator import RetrievalResult, narrow
+from bce.core.orchestrator.profile import active_profile
 from bce.core.orchestrator.text import content_tokens
 from bce.core.scoring.engine import ScoreWeights, score_candidates
 from bce.storage.graph.repository import GraphRepository
@@ -69,6 +70,7 @@ def trace_context_for_task(
 
     # Stage 1: multi-source anchors (spec section 6.2), with evidence strength per anchor.
     t = time.perf_counter()
+    profile = active_profile()
     anchors = find_anchors(
         repository,
         task_text=task_text,
@@ -78,6 +80,7 @@ def trace_context_for_task(
         component_repo_ids=None,
         repo_ids=repo_ids,
         semantic_candidates=semantic_candidates,
+        profile=profile,
     )
     stages.append(
         {
@@ -139,7 +142,7 @@ def trace_context_for_task(
 
     # Stage 4: diversity-aware narrowing to top-N (the "1000 -> 8" step).
     t = time.perf_counter()
-    narrowed = narrow(ranked, max_candidates)
+    narrowed = narrow(ranked, max_candidates, profile=profile)
     stages.append(
         {
             "stage": "narrow",