feat(core): add inspect query retrieval execution trace - #1250
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8a849d955f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
8a849d9 to
c8ccf63
Compare
phernandez
left a comment
phernandez
left a comment
There was a problem hiding this comment.
Reviewed the --show-ids amendment (8a849d95 → c8ccf630). Verified locally: 27
inspect/trace tests pass, lint + typecheck clean. Assessment:
Right design, cleanly executed. The change is rendering-only — type-qualified row IDs
were always present in the JSON contract, so surfacing them in human output required no
schema or API change, preserving the single-machine-contract invariant. --show-ids
follows the --show-misses render-only pattern exactly (accepted-but-inert under
--json, where IDs are already complete), and the type:id format matches the trace's
own key representation.
Two observations, neither blocking:
- The amendment also adds entity permalinks under result titles unconditionally (no
flag) in both rich and plain output. It's a good call — results become directly
copy-pasteable intobm inspect chunks— but it's beyond the literal "ids as optional
arg" scope, so flagging for awareness. Plain output'spermalink=prefix keeps it
greppable. - Permalinks render only for
type == "entity"rows; observation/relation rows have
synthetic permalinks too but stay ID-only. Reads as deliberate noise reduction — with
--show-idsevery row type gets its identity — andinspect chunksoutput already
leads withtype:idheaders, so the two commands stay consistent.
Test coverage is properly two-sided: the flag's presence asserted in rich/plain/JSON
paths, and its absence asserted in the no-flag plain case. Good to merge with the stack.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c8ccf630c9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 64a81a28b1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
64a81a2 to
90c95b3
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 90c95b338c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
90c95b3 to
5582c5f
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5582c5f9ea
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
5582c5f to
d552e70
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d552e706cc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
d552e70 to
63e2058
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 63e2058e84
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
63e2058 to
06bff0e
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 06bff0e3e6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
06bff0e to
6c59769
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c597695e5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
6c59769 to
4d3cb59
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4d3cb5955c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
4d3cb59 to
b6be274
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6be274b79
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
b6be274 to
2a07c8d
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2a07c8d95e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
2a07c8d to
6596d7f
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6596d7fe48
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
6596d7f to
1dd1dc3
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1dd1dc31b7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
1dd1dc3 to
1ac1d1a
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1ac1d1af9f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
1ac1d1a to
af6b473
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: af6b4739eb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
af6b473 to
26bf0bc
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 26bf0bc64f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
26bf0bc to
cbbe5f8
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cbbe5f8fde
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
cbbe5f8 to
6d97b86
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6d97b86f88
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
6d97b86 to
055b9a2
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 055b9a2d64
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
055b9a2 to
3329041
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3329041db9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Signed-off-by: phernandez <paul@basicmachines.co>
3329041 to
70b7e67
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 70b7e678d2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
1 participant
Stacked on #1249 (
feat/1155-inspect-chunks). PR B of #1155; retarget tomainafter PR A merges.Why
Search currently returns ranked results without exposing how FTS, vector retrieval,
fusion, hydration, filtering, and reranking produced them. That makes score and
index-readiness problems difficult to diagnose without recreating portions of retrieval,
which can diverge from the execution being explained.
This PR adds an opt-in execution trace captured by the same search call that returns the
results. It completes the v0.23 retrieval-inspector scope from #1155 without changing the
ordinary search response or the MCP
search_notescontract.What Changed
SearchTraceCollectorand frozen, per-mode trace unions for FTS, vector, andhybrid retrieval.
threshold/filter/missing-row rejection, normalized FTS scores, fusion, reranking, and
the final page window.
POST /v2/projects/{id}/inspect/queryand the corresponding typed client call.bm inspect query "<query>"with rich, plain, JSON, and auto-JSON output.--show-misses; JSON always includesevery captured candidate and remains the stable machine-readable schema.
--show-idsoptionallyadds type-qualified search-index trace keys such as
entity:1,relation:4, andobservation:9; it does not alter JSON.batches large hydration-drop classifications, and records FTS-only duration on both
SQLite and Postgres.
Implementation Details
reconstruct an explanation, and nested stable-pool retrieval is deliberately excluded
from the visible candidate trace.
FtsQueryTrace | VectorQueryTrace | HybridQueryTraceunion at the service boundary.Finalization fails fast when a required stage is missing.
keys, similarities, bounded rejection details, and stored/configured identities.
trace is not Nonechecks and keywordforwarding. Trace-only readiness and drop-classification SQL executes strictly under
those guards.
SearchResultscorereplacement, as well as post-rerank movement and tail-demotion behavior.
useful permalinks and IDs remain visible at ordinary terminal widths.
Testing
BASIC_MEMORY_ENV=test uv run pytest tests/repository/test_search_trace.py tests/api/v2/ tests/cli/ -q— 937 passed.
BASIC_MEMORY_ENV=test uv run pytest tests/repository/ tests/services/ -q— 1093 passed, 29 skipped.
BASIC_MEMORY_TEST_POSTGRES=1 BASIC_MEMORY_ENV=test uv run pytest tests/repository/test_search_trace.py -q— 7 passed after review hardening.
BASIC_MEMORY_ENV=test uv run pytest tests/repository/test_search_trace.py -q— 7 passed, with
search_trace.pyat 100% coverage.BASIC_MEMORY_ENV=test uv run pytest tests/api/v2/test_inspect_router.py tests/cli/test_inspect_command.py -q— 22 passed after review hardening.
BASIC_MEMORY_ENV=test uv run pytest tests/cli/test_inspect_command.py -q— 15 passed after the permalink/ID rendering update.
BASIC_MEMORY_ENV=test uv run pytest tests/cli/ -q— 695 passed.
just typecheck && just lint— passed.--show-ids;entity permalinks appeared in both, while type-qualified IDs appeared only when
requested.
Risks / Follow-ups
unchanged.
an exhaustive scan of the corpus.
planned.
Closes #1155 for the v0.23 Phase 1+2 scope.