search_jama_semantics
Retrieve relevant items from Jama projects by running natural-language queries with hybrid semantic and keyword search, using multi-query expansion and RRF fusion for accurate results.
Instructions
Semantic search over an initialized Jama project using high-precision RAG.
This is the DEFAULT tool for any non-precise question. It fuses keyword
(FTS5/BM25), vector (sqlite-vec cosine) and RRF in one call — so "like",
"keyword" and "semantic" queries are all best answered here. Prefer it over
native metadata unless the user gives an exact document key / status / item id.
Pipeline: client Multi-Query expansion -> hybrid recall (sqlite-vec +
FTS5) -> RRF fusion (with item-level dedup) -> top_k results. Ranking is
pure RRF by default: the cross-encoder reranker is DISABLED
(``RERANKER_ENABLED=0``) because benchmarking on the Lyra corpus showed it
HURT precision (Recall@50 73.3% RRF-only vs Recall@5 33.3% with rerank).
The reranker code path remains available for re-enablement.
Args:
project_id: numeric string Jama project id (must be initialized first).
query: the ORIGINAL natural-language search query, verbatim. It is
always kept as the primary recall/rerank reference, so even
when `sub_queries` is supplied you MUST pass the original user
query here too.
sub_queries: RECOMMENDED. Rewrite `query` into 3-5 diverse search
sub-queries capturing different semantic angles
(synonyms, broader/narrower scope, related concepts) to
maximize recall for RRF fusion. Pass as a JSON array of
strings. The server normalizes them (forces `query` to the
front, de-duplicates, caps at 5). If omitted, the server
falls back to deterministic lexical variants.
Example for query "how does login timeout work":
["login session expiration",
"authentication timeout policy",
"user inactivity logout"]
item_type: optional Jama item-type id to filter (e.g. "89011" for Test
Cases, "89009" for Requirements). Pass None for all.
top_k: final results to return (default 50). The BEIR sweep showed
top_k=50 + candidate_k=100 is the optimal combination (highest
Recall@50 = 73.3%). Range 1-50; must be <= candidate_k.
candidate_k: candidate pool size after RRF fusion + item dedup
(default 100). A larger pool improves recall (vector+FTS
recall is capped by this): measured vecR@25=7%, @50=13%,
@100=21%, @200=34%. Note: candidate_k=200 DILUTES RRF
rankings and actually lowers Recall@50 to 64.4%, so 100
is the measured sweet spot. Range 1-500; must be >= top_k.
modified_after: optional ISO-8601 lower bound on item modified date
(inclusive). Naive timestamps are assumed UTC.
e.g. "2024-01-01" or "2024-06-01T00:00:00Z".
modified_before: optional ISO-8601 upper bound on item modified date
(inclusive). Naive timestamps are assumed UTC.
Returns:
{"project_id","query","sub_queries_used","results":
[{document_key,name,item_type_name,section,modified_date,text,
score,strategy}, ...]}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| item_type | No | ||
| project_id | Yes | ||
| candidate_k | No | ||
| sub_queries | No | ||
| modified_after | No | ||
| modified_before | No |