Alternative D: BM25 + embedding Parallel

Flow

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> candidate union
  -> mix scores
  -> return JSONL
  -> Qwen direct-evidence verification

Role Assignment

What BM25 captures:

Input.is_action_pressed
AnimatedSprite2D
position.clamp
screen_size
Vector2.ZERO

What embedding captures:

player movement
2D movement tutorial
moving inside screen
animation based on movement

What Qwen direct‑evidence validator does:

Check whether there is a string/pattern basis that directly matches the current chunk inside the retrieved JSONL  
Discard unrelated JSONL

Advantages

Complements the weaknesses of string search and semantic search.
Improves the quality of the first‑stage candidates even without Qwen.
Preserves the raw chunk condition.
Can be started without a hard‑coded Godot API signal extractor.

Disadvantages

Score combination tuning is required.
The BM25 score and vector score scales differ.
Ranking can become unstable without a reranker.
False positives cannot be completely prevented.

Expected Results from the Standard Chunk

Top candidates:

first_2d_game / coding_the_player
same page / clamp section

Candidates to be lowered or discarded in verification:

first_3d_game / player_movement_code
unrelated api_mapping
unrelated label_prototypes

PoC Simulation

Search the reference chunk simultaneously through two paths.

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> candidate union
  -> duplicate merging
  -> Qwen direct-evidence validation

BM25 top candidate examples:

Candidate	Reason BM25 captured
`first_2d_game / coding_the_player`	Direct match of `Input.is_action_pressed`, `move_left`, `move_right`, `AnimatedSprite2D.play/stop`
`first_2d_game / clamp section`	Direct match of `position.clamp`, `Vector2.ZERO`, `screen_size`
`first_3d_game / player_movement_code`	Overlap of input handling and normalized movement tokens

embedding top candidate examples:

Candidate	Reason embedding captured
`first_2d_game / coding_the_player`	Meaning of 2D player movement and animation is close
`first_2d_game / clamp explanation`	Meaning of restricting the player within the screen is close
`first_3d_game / player_movement_code`	Meaning of player movement is close
`animation docs`	Meaning of animation play/stop in a moving state is close

The candidate union appears as follows.

candidate A:
  source: BM25 + embedding
  evidence: Input.is_action_pressed, AnimatedSprite2D.play/stop
  expected: accept

candidate B:
  source: BM25 + embedding
  evidence: position.clamp, Vector2.ZERO, screen_size
  expected: accept

candidate C:
  source: BM25 + embedding
  evidence: Input.is_action_pressed, move_left, move_right, normalized
  missing: AnimatedSprite2D, Vector2, screen_size
  expected: lower or reject

candidate D:
  source: embedding only
  evidence: semantic movement/animation similarity
  direct string match: weak
  expected: validator decision needed

When passing to the Qwen direct-evidence validator, it is judged based on the following criteria.

Is the actual string/API call in SOURCE_CODE directly matching the source_api, source_pattern, match_terms, required_when_seen_in_code, before_code in the JSONL, or the content/code_blocks/api_symbols in docs_chunks?

Logs to Verify in PoC

This alternative is important because the union process is critical, so it must show the following.

1. BM25 candidate list  
2. embedding candidate list  
3. Result after union and duplicate removal  
4. Whether each candidate came from BM25 or embedding  
5. Direct string evidence list  
6. Qwen validator's yes/no

Visible conclusion:

BM25 directly uploads API evidence,  
and embedding complements the explanatory candidates.  
However, since false positives remain with union alone, a validator is needed.

Judgment

Realistic Intermediate Stage  
Practical Minimum Recommended Line

If attaching the reranker directly feels burdensome, you can start by comparing this alternative.