Alternative C: embedding only

Flow

raw chunkText
  -> embedding vector
  -> docs_chunks/api_mapping/label_prototypes embedding and cosine search
  -> return top JSONL

Why Embedding Is Needed

BM25 is strong with exact strings, but it can become weak when the description and code representation differ.

For example, the chunk contains the following code.

position = position.clamp(Vector2.ZERO, screen_size)

The document may be described as follows.

prevent the player from leaving the screen
clamping a value means restricting it to a given range

In this case, embedding can capture semantic connections.

Expected Success from the Standard Chunk

Embedding may find the following topics.

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

Expected Failures in the Standard Chunk

Embedding can also give high scores to candidates with similar meanings.

Expected false positive:

3D player movement
scripting player input
vector math
animation player docs

The phrase “player movement” can be similar enough that the distinction between 2D and 3D may become blurred.

PoC Simulation

Convert the reference chunk into an embedding vector.

Input meaning:

2D player movement
keyboard input
velocity normalization
animation while moving
keep player inside screen

embedding is likely to find the following candidates:

Candidate	Why it appears	Judgment
`first_2d_game / coding_the_player`	2D player movement, input, animation, screen clamp meaning is close	accept
`first_2d_game / clamp explanation`	The meaning of preventing the player from going off-screen is close	accept
`first_3d_game / player_movement_code`	Player movement, input, normalized direction meaning is close	false positive
`Vector math / movement tutorial`	Velocity, vector, normalized meaning is close	maybe
`Animation player docs`	Play/stop animation meaning is close	maybe

Issues that stand out in embedding only:

The string is evaluated based on how close its meaning is rather than an exact match.  
Therefore, criteria that need to be strictly distinguished, such as 2D/3D, Godot 3/Godot 4, or whether migration is required, can become blurred.

For example, both the reference chunk and the 3D movement document share the following meaning.

keyboard input
movement direction
normalized velocity
player movement

However, the standard chunk has the following direct clues.

AnimatedSprite2D
Vector2.ZERO
position.clamp
screen_size

embedding only may not be able to explain this direct clue as transparently as BM25.

Logs to Verify in PoC

In the embedding PoC, it should be displayed as follows.

1. query chunkText  
2. Summary of candidate document heading/content  
3. cosine similarity  
4. List of directly matched strings  
5. Show candidates with close meaning when there is no directly matched string

Visible conclusion:

Embedding complements explanatory documents that BM25 missed.  
However, it is weak for direct evidence judgment, so it should not be used alone.

Advantages

Finds matches even if the expression is different.
Strong with document explanatory content.
Easy to insert raw chunks as they are.
Can serve as a fallback when BM25 returns zero results.

Disadvantages

Weak at accurately determining the API.
May mix differences between Godot 3 and Godot 4 versions.
May mix 2D/3D contexts.
Difficult to explain why a particular result was produced.
In api_mapping, the risk of false positives is high.

Judgment

Do not use alone  
Use for supplementing BM25 candidates