Documentation
¶
Overview ¶
Package search powers clawtool's ToolSearch primitive.
Per ADR-004 / ADR-005, search-first is clawtool's identity feature: when the catalog grows past a few dozen tools, agents can't reasonably hold every schema in context, so they need to *find* the right tool by natural-language query before binding to it. The MCP wire still exposes every tool; ToolSearch is the cheap discovery primitive that lets agents avoid materialising every schema upfront.
Per ADR-007 we don't write a search engine — we wrap one. The chosen engine is bleve (github.com/blevesearch/bleve/v2): pure-Go, BM25 by default, supports phrase + fuzzy + boosted-field queries. We use the in-memory variant so there's no on-disk index to manage.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Doc ¶
type Doc struct {
Name string // wire-form name, e.g. "Bash", "github-personal__create_issue"
Description string // human-readable; main signal
Type string // "core" or "sourced"
Instance string // empty for core; instance name for sourced
Keywords []string // optional extra search terms (synonyms, aliases)
}
Doc is one tool's searchable surface. Only the fields a query realistically matches on are indexed; we deliberately don't index the full input schema because long JSON Schema text dilutes the relevance signal.
type Hit ¶
type Hit struct {
Name string `json:"name"`
Score float64 `json:"score"`
Description string `json:"description"`
Type string `json:"type"`
Instance string `json:"instance,omitempty"`
}
Hit is one ranked search result.
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index is a built search index over a fixed set of tool descriptors.
Lifetime: built once at clawtool serve startup from the union of (enabled core tools, aggregated source tools, ToolSearch itself). Concurrent reads are safe; bleve handles internal locking. The index is not rebuilt on the fly — adding sources at runtime needs a server restart (acknowledged limitation; v0.6 hot-reload addresses it).
func Build ¶
Build constructs an in-memory bleve index from the given docs. Returns an error only when bleve mapping or insert fails — both indicate a clawtool bug, not user input.
func (*Index) Search ¶
Search runs a natural-language query and returns the top `limit` hits.
Query semantics: bleve's QueryStringQuery — which accepts free-form text plus optional field boosts. We apply a name^3 boost so "Bash" matches the literal tool more strongly than tools that mention bash in their descriptions. typeFilter "core" / "sourced" restricts results; "" or "any" returns everything.
Source Files