code_semantic_search

Embedding-based retrieval. Given a natural-language query, returns the top-K symbols whose purpose matches — even when no keyword overlaps.

Prereq

Run code_embed_index({}) once per project (or let gl watch auto-build on start).

Usage

code_semantic_search({ query: "payment retry logic", top_k: 10 })
code_semantic_search({ query: "auth middleware", top_k: 5, file_filter: "src/api/" })

Returns a ranked table:

=== Semantic search: "payment retry logic" (model: nomic-embed-text, 462 symbols) ===

 0.714 │ retry_with_backoff (FUNCTION) │ src/reliability/retry.rs:15
 0.685 │ exponential_delay (FUNCTION) │ src/reliability/retry.rs:45
 0.428 │ circuit_breaker_reset (METHOD) │ src/resilience.rs:210

Cosine similarity scores in the first column. Higher = more relevant.

Arguments

Name	Type	Default	Description
`query`	string	required	Natural language description
`top_k`	integer	10	Results to return
`file_filter`	string	—	Only include results whose file path contains this substring

Providers

Pick via GL_EMBED_PROVIDER env var:

ollama (default) — free, local. Pull nomic-embed-text once.
openai — set OPENAI_API_KEY. Best quality. Paid.
fastembed — feature-gated ONNX (local, no deps).

Works inside `gl_run`

gl_run({ code: `
  const hits = gl.code.semantic_search({
    query: "rate limit enforcement",
    top_k: 5
  });
  return hits.map(h => ({
    name: h.name,
    callers: gl.code.callers({ name: h.name })
  }));
` })