Class: Woods::Retrieval::SearchExecutor

Inherits:
Object
  • Object
show all
Defined in:
lib/woods/retrieval/search_executor.rb

Overview

SearchExecutor maps a query classification to a retrieval strategy and executes it against the configured stores.

Strategies:

  • :vector — semantic similarity search (understand, implement, debug)

  • :keyword — exact identifier/text matching (locate, reference)

  • :graph — dependency traversal (trace)

  • :hybrid — vector + keyword + graph expansion (exploratory/comprehensive)

  • :direct — direct metadata lookup (pinpoint + locate/reference)

Examples:

executor = SearchExecutor.new(
  vector_store: vector_store,
  metadata_store: metadata_store,
  graph_store: graph_store,
  embedding_provider: embedding_provider
)
classification = QueryClassifier.new.classify("How does User model work?")
result = executor.execute(query: "How does User model work?", classification: classification)
result.candidates # => [Candidate, ...]
result.strategy   # => :hybrid

Defined Under Namespace

Classes: Candidate, ExecutionResult

Constant Summary collapse

STRATEGY_MAP =

Strategy mapping from (intent, scope) → strategy.

Covers pinpoint overrides for locate/reference (:direct). Trace and framework intents are handled before this map is consulted.

{
  %i[locate pinpoint] => :direct,
  %i[reference pinpoint] => :direct
}.freeze

Instance Method Summary collapse

Constructor Details

#initialize(vector_store:, metadata_store:, graph_store:, embedding_provider:) ⇒ SearchExecutor

Returns a new instance of SearchExecutor.

Parameters:



47
48
49
50
51
52
 
# File 'lib/woods/retrieval/search_executor.rb', line 47

def initialize(vector_store:, metadata_store:, graph_store:, embedding_provider:)
  @vector_store = vector_store
  @metadata_store = metadata_store
  @graph_store = graph_store
  @embedding_provider = embedding_provider
end

Instance Method Details

#execute(query:, classification:, limit: 20, type_filter: nil, strategy: nil) ⇒ ExecutionResult

Execute a search based on query classification.

Parameters:

  • query (String) —

    The original query text

  • classification (QueryClassifier::Classification) —

    Classified query

  • limit (Integer) (defaults to: 20) —

    Maximum candidates to return

  • type_filter (Array<String>, nil) (defaults to: nil) —

    When set, vector and hybrid strategies push this down into the vector store’s metadata filter — used by Woods::Retriever#retrieve to rank-within-type when the unfiltered global top-K had no candidate of the requested type. Overrides the classifier-derived target_type in filter construction.

  • strategy (Symbol, nil) (defaults to: nil) —

    Override the classifier-selected strategy. Woods::Retriever#within_type_fallback passes :vector here because the vector path is the only one that honors type_filter; if the classifier picked :keyword / :graph / :direct the fallback would otherwise silently re-run the same strategy, get filtered to empty, and violate the “never empty when units exist” contract.

Returns:



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/woods/retrieval/search_executor.rb', line 71

def execute(query:, classification:, limit: 20, type_filter: nil, strategy: nil)
  strategy ||= select_strategy(classification)
  candidates = run_strategy(
    strategy,
    query: query,
    classification: classification,
    limit: limit,
    type_filter: type_filter
  )

  ExecutionResult.new(
    candidates: candidates.first(limit),
    strategy: strategy,
    query: query
  )
end