Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

Let built-in knowledge carry a tighter RAG gate than company docs

Rufusad21a55de3e0
diff --git a/.env.example b/.env.example
index 2afb8eaa..9eb1b1bf 100644
--- a/.env.example
+++ b/.env.example
@@ -327,3 +327,21 @@ WATCHLIST_RESEARCH_MAX_DIRECT_ADDS=2
WATCHLIST_RESEARCH_MAX_PROPOSALS=2
WATCHLIST_MAX_ENABLED=40
WATCHLIST_PROPOSAL_TTL_DAYS=14
+
+# RAG relevance gates (cosine distance — LOWER is stricter; range 0-2).
+# A hit further than the gate is dropped before the top-K slice.
+#
+# KNOWLEDGE_DISTANCE_THRESHOLD is the shared gate: COMPANY docs, the synced
+# Notion wiki, and recent research. Raise it if company documents that
+# obviously answer the question are not being surfaced — a question phrased
+# conversationally embeds further from document prose than the same question
+# phrased as keywords, so the right doc can rank first and still miss the gate.
+#
+# KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD optionally tightens the built-in
+# knowledge base and the shipped failure cases only. Both are generic material
+# and much larger than a typical company corpus, so a gate loose enough for
+# your documents admits a lot of unrelated handbook prose with it. It can only
+# tighten: a value looser than the shared gate is clamped to it. Unset, every
+# collection shares the value above.
+KNOWLEDGE_DISTANCE_THRESHOLD=0.55
+# KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD=0.50
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index d5bda932..87401cb3 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -713,6 +713,39 @@ routing:
carrying the matched term.
knowledge:
+ distance_gates: |
+ Two gates. KNOWLEDGE_DISTANCE_THRESHOLD (default 0.55) is the shared one,
+ applied to COMPANY, NOTION_WIKI and RECENT_RESEARCH.
+ KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD optionally tightens BUILTIN and the
+ FAILURES collection queried by retrieve_failures() — both ship with the
+ repo and are generic by construction, so they move together. Unset (the
+ default) every collection keeps the shared value, which is the historical
+ behaviour.
+
+ The builtin gate can only ever TIGHTEN: _resolve_builtin_threshold takes
+ min() against the shared value. Without that clamp an operator who
+ transposed the two variables would invert the whole point — BUILTIN looser
+ than COMPANY, admitting handbook prose at a distance where a company doc is
+ still dropped. The field is also range-checked to [0, 2]; a negative value
+ would disable builtin retrieval and present as "the knowledge base stopped
+ helping" rather than as a config error.
+
+ Why the split exists: BUILTIN is generic material and an order of magnitude
+ larger than a typical company corpus, so a threshold loose enough to admit
+ the right company doc admits a lot of unrelated handbook prose with it.
+ Raising the shared gate to fix company-doc recall therefore costs precision
+ everywhere; the per-collection gate buys the recall without the noise.
+
+ Precedence inside retrieve(): an explicit `builtin_distance_threshold`
+ argument, then KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD, then the shared
+ threshold — each clamped by min() against the shared value.
+
+ A caller-pinned `distance_threshold` deliberately does NOT suppress the
+ builtin setting. No caller in the repo pins one, so such a tier would be
+ dead code today; and a future caller loosening the shared gate for an
+ unrelated reason must not silently revoke an operator's deployment-level
+ guardrail. A caller that genuinely wants one gate for both collections
+ says so with `builtin_distance_threshold`.
collections:
- name: BUILTIN
what: Curated MBA-style domain knowledge shipped with the repo.
diff --git a/packages/core/openexecutive/architecture/prebuilt/rag.json b/packages/core/openexecutive/architecture/prebuilt/rag.json
index 8c358897..46a83fc9 100644
--- a/packages/core/openexecutive/architecture/prebuilt/rag.json
+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json
@@ -1,7 +1,7 @@
{
"section_id": "rag",
"title": "Knowledge & RAG",
- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Six collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",
+ "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Six collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely. BUILTIN can carry its own tighter gate via `KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD`: built-in knowledge is generic and far larger than a typical company corpus, so the distance that admits the right company doc also admits unrelated handbook prose. Unset, every collection shares `KNOWLEDGE_DISTANCE_THRESHOLD`.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",
"mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Attach[\"integrations.attachments\"] --> Attachments[(ATTACHMENTS<br/>never queried)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class Failures storage\n class Research storage\n class Attachments storage\n class Attach compute\n class Inject hot",
"generated_at": "2026-09-16T22:54:43.608081+00:00"
}
diff --git a/packages/core/openexecutive/config.py b/packages/core/openexecutive/config.py
index 01aa5de9..6f843014 100644
--- a/packages/core/openexecutive/config.py
+++ b/packages/core/openexecutive/config.py
@@ -130,6 +130,17 @@ class Settings(BaseSettings):
knowledge_distance_threshold: float = Field(
0.55, alias="KNOWLEDGE_DISTANCE_THRESHOLD"
)
+ # Optional tighter gate for the BUILTIN collection only. Built-in
+ # knowledge is generic MBA material and an order of magnitude larger than
+ # a typical company corpus, so the distance that admits the right company
+ # doc also admits a lot of unrelated handbook prose. Unset (None) keeps
+ # the single shared threshold, which is the historical behaviour.
+ # Cosine distance is in [0, 2]; a negative value would silently disable
+ # builtin retrieval entirely and read as "the knowledge base stopped
+ # helping" rather than as a config error.
+ knowledge_builtin_distance_threshold: float | None = Field(
+ None, ge=0.0, le=2.0, alias="KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD"
+ )
knowledge_builtin_n_results: int = Field(5, alias="KNOWLEDGE_BUILTIN_N_RESULTS")
knowledge_company_n_results: int = Field(3, alias="KNOWLEDGE_COMPANY_N_RESULTS")
diff --git a/packages/core/openexecutive/knowledge/retriever.py b/packages/core/openexecutive/knowledge/retriever.py
index bf2a3d03..5bda8d3e 100644
--- a/packages/core/openexecutive/knowledge/retriever.py
+++ b/packages/core/openexecutive/knowledge/retriever.py
@@ -44,6 +44,37 @@ def _format_untrusted_wiki(text: str) -> str:
return "\n".join(f"· {line}" for line in cleaned.splitlines())
+def _resolve_builtin_threshold(
+ shared: float,
+ builtin_arg: float | None,
+ settings: Any,
+) -> float:
+ """Gate for the BUILTIN collection: never looser than ``shared``.
+
+ Built-in knowledge is generic material and an order of magnitude larger
+ than a typical company corpus, so a distance loose enough to admit the
+ right company doc admits a lot of unrelated handbook prose with it. This
+ lets an operator tighten BUILTIN alone.
+
+ Only ever *tightens*, via ``min``. The config comment and the architecture
+ notes both promise a tighter gate, and an operator who transposes the two
+ env vars would otherwise invert the change's whole purpose: BUILTIN looser
+ than COMPANY, handbook prose admitted where a company doc is still dropped.
+
+ A caller-pinned ``distance_threshold`` deliberately does NOT suppress the
+ builtin setting. No caller in the repo pins one, and if a future caller
+ loosens the shared gate for an unrelated reason it must not silently
+ revoke an operator's deployment-level guardrail. A caller that genuinely
+ wants one gate for both says so with ``builtin_distance_threshold``.
+ """
+ if builtin_arg is not None:
+ return min(builtin_arg, shared)
+ configured = getattr(settings, "knowledge_builtin_distance_threshold", None)
+ if configured is not None:
+ return min(configured, shared)
+ return shared
+
+
def _passes_threshold(
row: dict[str, Any], threshold: float = _DISTANCE_THRESHOLD
) -> bool:
@@ -191,6 +222,7 @@ def retrieve(
store: ChromaDBStore | None = None,
review_store: ReviewStore | None = None,
distance_threshold: float | None = None,
+ builtin_distance_threshold: float | None = None,
) -> str:
effective_domains = domain_filter
if effective_domains is None and specialist_name:
@@ -229,6 +261,10 @@ def retrieve(
if distance_threshold is None:
distance_threshold = settings.knowledge_distance_threshold
+ builtin_threshold = _resolve_builtin_threshold(
+ distance_threshold, builtin_distance_threshold, settings
+ )
+
if store is None:
store = ChromaDBStore(persist_directory=settings.vector_store_path)
@@ -263,7 +299,7 @@ def retrieve(
if (r["metadata"].get("domain"), r["metadata"].get("filename"))
not in withheld_builtin
and r["metadata"].get("source_id") not in withheld_external
- and _passes_threshold(r, distance_threshold)
+ and _passes_threshold(r, builtin_threshold)
]
filtered_builtin.sort(
key=lambda r: PRIORITY_ORDER.get(
@@ -430,7 +466,15 @@ def retrieve_failures(
# Cosine distance threshold (configurable via KNOWLEDGE_DISTANCE_THRESHOLD):
# a larger distance means the match is too weak to be useful.
- threshold = settings.knowledge_distance_threshold
+ #
+ # Failure cases ship with the repo and are generic by construction, exactly
+ # like BUILTIN, so they follow the builtin gate when one is configured.
+ # Leaving them on the shared gate would mean the same class of content is
+ # admitted at two different distances depending only on which function
+ # queried it.
+ threshold = _resolve_builtin_threshold(
+ settings.knowledge_distance_threshold, None, settings
+ )
rs = review_store or _default_review_store()
# FAILURE, not BUILTIN: failure case studies have their own id namespace
# so a user upload cannot collide with a shipped one.
diff --git a/packages/core/tests/conftest.py b/packages/core/tests/conftest.py
index 225e4896..8a08bb8f 100644
--- a/packages/core/tests/conftest.py
+++ b/packages/core/tests/conftest.py
@@ -14,6 +14,13 @@ os.environ.setdefault("EXEC_EMAIL_ADDRESS", "[email protected]")
# full-app test errors at construction — the same trap BACKEND_SHARED_SECRET sets
# (see CLAUDE.md → Testing). Clear it so the suite matches CI either way.
os.environ.pop("OE_PUBLIC_DEPLOYMENT", None)
+# The RAG distance gates are read by retrieve() at call time and several
+# retrieval tests hard-code distances either side of the 0.55 default. Because
+# config.py loads a developer's .env, putting a tuning value there — the
+# documented way to use these levers — would otherwise change the gate for the
+# whole suite and fail those tests for a reason nothing in them mentions.
+os.environ.pop("KNOWLEDGE_DISTANCE_THRESHOLD", None)
+os.environ.pop("KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD", None)
@pytest.fixture(autouse=True)
diff --git a/packages/core/tests/unit/test_retriever_gating.py b/packages/core/tests/unit/test_retriever_gating.py
index c17aa163..110eaa84 100644
--- a/packages/core/tests/unit/test_retriever_gating.py
+++ b/packages/core/tests/unit/test_retriever_gating.py
@@ -256,3 +256,184 @@ def test_retrieve_failures_honors_withheld_items() -> None:
assert "USEFUL FAILURE STORY" in out
assert "REJECTED FAILURE STORY" not in out
+
+
+def test_builtin_threshold_setting_tightens_builtin_only(
+ fake_review_store: SimpleNamespace, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD gates builtin without touching company.
+
+ Both collections return a hit at 0.62. With the shared gate at 0.65 and the
+ builtin-only gate at 0.60, the company doc survives and the builtin chunk
+ does not -- the whole point of the split.
+ """
+ import openexecutive.config as config_mod
+
+ monkeypatch.setattr(
+ config_mod,
+ "get_settings",
+ lambda: SimpleNamespace(
+ knowledge_builtin_n_results=5,
+ knowledge_company_n_results=3,
+ knowledge_distance_threshold=0.65,
+ knowledge_builtin_distance_threshold=0.60,
+ vector_store_path="/unused",
+ ),
+ )
+ store = _make_store(
+ builtin_hits=[{"text": "generic handbook", "metadata": {"filename": "b.md"}, "distance": 0.62}],
+ company_hits=[{"text": "our own doc", "metadata": {"filename": "c.md"}, "distance": 0.62}],
+ )
+ out = retrieve(query="a real question about strategy", store=store, review_store=fake_review_store)
+ assert "our own doc" in out
+ assert "generic handbook" not in out
+
+
+def test_builtin_threshold_unset_falls_back_to_shared(
+ fake_review_store: SimpleNamespace, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Unset (None) preserves the historical single-threshold behaviour."""
+ import openexecutive.config as config_mod
+
+ monkeypatch.setattr(
+ config_mod,
+ "get_settings",
+ lambda: SimpleNamespace(
+ knowledge_builtin_n_results=5,
+ knowledge_company_n_results=3,
+ knowledge_distance_threshold=0.65,
+ knowledge_builtin_distance_threshold=None,
+ vector_store_path="/unused",
+ ),
+ )
+ store = _make_store(
+ builtin_hits=[{"text": "generic handbook", "metadata": {"filename": "b.md"}, "distance": 0.62}],
+ company_hits=[],
+ )
+ out = retrieve(query="a real question about strategy", store=store, review_store=fake_review_store)
+ assert "generic handbook" in out
+
+
+def test_builtin_setting_survives_a_caller_pinned_shared_threshold(
+ fake_review_store: SimpleNamespace, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A pinned shared threshold must not revoke the operator's builtin gate.
+
+ A caller loosening the shared gate for an unrelated reason (wider company
+ recall for one report) would otherwise silently re-open builtin to the
+ generic-chunk flood the setting exists to prevent.
+ """
+ import openexecutive.config as config_mod
+
+ monkeypatch.setattr(
+ config_mod,
+ "get_settings",
+ lambda: SimpleNamespace(
+ knowledge_builtin_n_results=5,
+ knowledge_company_n_results=3,
+ knowledge_distance_threshold=0.55,
+ knowledge_builtin_distance_threshold=0.60,
+ vector_store_path="/unused",
+ ),
+ )
+ store = _make_store(
+ builtin_hits=[{"text": "generic handbook", "metadata": {"filename": "b.md"}, "distance": 0.70}],
+ company_hits=[{"text": "our own doc", "metadata": {"filename": "c.md"}, "distance": 0.70}],
+ )
+ out = retrieve(
+ query="a real question about strategy",
+ store=store,
+ review_store=fake_review_store,
+ distance_threshold=0.80,
+ )
+ # The pinned 0.80 reaches company...
+ assert "our own doc" in out
+ # ...but builtin stays on its own 0.60 gate.
+ assert "generic handbook" not in out
+
+
+def test_builtin_gate_can_only_tighten_never_loosen(
+ fake_review_store: SimpleNamespace, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A builtin value looser than the shared gate is clamped to the shared gate.
+
+ Guards the transposed-env-var mistake: pasting the company number into the
+ builtin variable would otherwise make builtin LOOSER than company, admitting
+ handbook prose at a distance where a company doc is still dropped.
+ """
+ import openexecutive.config as config_mod
+
+ monkeypatch.setattr(
+ config_mod,
+ "get_settings",
+ lambda: SimpleNamespace(
+ knowledge_builtin_n_results=5,
+ knowledge_company_n_results=3,
+ knowledge_distance_threshold=0.55,
+ knowledge_builtin_distance_threshold=0.65,
+ vector_store_path="/unused",
+ ),
+ )
+ store = _make_store(
+ builtin_hits=[{"text": "generic handbook", "metadata": {"filename": "b.md"}, "distance": 0.62}],
+ company_hits=[{"text": "our own doc", "metadata": {"filename": "c.md"}, "distance": 0.62}],
+ )
+ out = retrieve(query="a real question about strategy", store=store, review_store=fake_review_store)
+ assert "generic handbook" not in out
+ assert "our own doc" not in out
+
+
+def test_builtin_gate_is_inclusive_at_the_boundary(
+ fake_review_store: SimpleNamespace, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """distance == threshold is kept (_passes_threshold uses <=)."""
+ import openexecutive.config as config_mod
+
+ monkeypatch.setattr(
+ config_mod,
+ "get_settings",
+ lambda: SimpleNamespace(
+ knowledge_builtin_n_results=5,
+ knowledge_company_n_results=3,
+ knowledge_distance_threshold=0.65,
+ knowledge_builtin_distance_threshold=0.60,
+ vector_store_path="/unused",
+ ),
+ )
+ store = _make_store(
+ builtin_hits=[{"text": "exactly at the gate", "metadata": {"filename": "b.md"}, "distance": 0.60}],
+ company_hits=[],
+ )
+ out = retrieve(query="a real question about strategy", store=store, review_store=fake_review_store)
+ assert "exactly at the gate" in out
+
+
+def test_explicit_builtin_arg_wins_over_everything(
+ fake_review_store: SimpleNamespace, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """builtin_distance_threshold outranks both the pinned shared arg and the setting."""
+ import openexecutive.config as config_mod
+
+ monkeypatch.setattr(
+ config_mod,
+ "get_settings",
+ lambda: SimpleNamespace(
+ knowledge_builtin_n_results=5,
+ knowledge_company_n_results=3,
+ knowledge_distance_threshold=0.65,
+ knowledge_builtin_distance_threshold=0.99,
+ vector_store_path="/unused",
+ ),
+ )
+ store = _make_store(
+ builtin_hits=[{"text": "generic handbook", "metadata": {"filename": "b.md"}, "distance": 0.62}],
+ company_hits=[],
+ )
+ out = retrieve(
+ query="a real question about strategy",
+ store=store,
+ review_store=fake_review_store,
+ distance_threshold=0.90,
+ builtin_distance_threshold=0.50,
+ )
+ assert "generic handbook" not in out