Skip to content

feat: semantic-search fallback in the search command - #2

Merged
mayank-d3 merged 6 commits into
agent-root:mainfrom
mayank-d3:feature/semantic-search-fallback
Jul 1, 2026
Merged

mayank-d3 merged 6 commits into
agent-root:mainfrom
mayank-d3:feature/semantic-search-fallback

Conversation

@mayank-d3

Copy link
Copy Markdown
Collaborator

Summary

agent-root search now falls back to the registry's hybrid semantic endpoint (/api/search, BM25 + pgvector RRF) when keyword search (/api/records) returns no results — so natural-language queries like "skill to pay in USDC" surface relevant records instead of nothing. Fallback hits are clearly labeled as approximate. Drafted with help from Claude; I reviewed every line before submitting.

Changes

  • Zero-result fallback to /api/search, ordered: records → semantic → legacy (find-skills, manifest probe)
  • New --no-semantic flag (keyword-only opt-out)
  • Approximate hits shown under a // no exact match — closest semantic matches: header, each tagged {hybrid}/{vector}/{keyword}
  • --json gains a top-level approximate boolean (uniform across empty + non-empty envelopes)
  • One request per failed search (respects the 5-req/min rate limit); --all unaffected; embedder-offline surfaces naturally as {keyword} tags
  • vitest tests, CHANGELOG, README, per-command help, and docs/TESTING.md updated

Checklist

  • Conventional Commit message format (feat:, docs:)
  • Added tests under tests/ that fail without this change (mappers, searchSemantic incl. 429 → [], fallback ordering, display + --json)
  • pnpm test passes locally (only the pre-existing live-DNS integration-smoke tests fail in a no-network sandbox)
  • Updated CHANGELOG.md under ## [Unreleased]
  • Updated README.md + per-command help for the new flag/behavior
  • Commits signed off with DCO (git commit -s)
  • Manually verified — see "How to test"

How to test

Built locally (pnpm build) and run against production:

node dist/bin/agentroot.js search "skill to pay in USDC"                 # closest semantic matches + {vector} tags
node dist/bin/agentroot.js search "skill to pay in USDC" --no-semantic   # No records found
node dist/bin/agentroot.js search "payments"                            # normal keyword hit, no semantic header
node dist/bin/agentroot.js search "stablecoin checkout" --json | jq '{approximate, match: .results[0].match}'   # {"approximate":true,"match":"vector"}
node dist/bin/agentroot.js search "payments" --json | jq .approximate    # false

Closes / Related

Closes #1

Signed-off-by: mayank-d3 <mayank.rawat@d3.com>
Signed-off-by: mayank-d3 <mayank.rawat@d3.com>
Signed-off-by: mayank-d3 <mayank.rawat@d3.com>
Signed-off-by: mayank-d3 <mayank.rawat@d3.com>
…ate json field

Signed-off-by: mayank-d3 <mayank.rawat@d3.com>
@mayank-d3
mayank-d3 merged commit 9bf2ec0 into agent-root:main Jul 1, 2026
4 checks passed
@mayank-d3
mayank-d3 deleted the feature/semantic-search-fallback branch July 1, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[feat] Semantic-search fallback in the search command

1 participant