Misleading Definition of hybrid_search: Documentation Suggests Vector + Graph, But Implementation Uses Vector + Text in agentic-rag-knowledge-graph

[siho00]

Issue Summary:

In the agentic-rag-knowledge-graph project, the term "Hybrid Search" is inconsistently defined across the LLM prompt, the README documentation, and the actual code implementation. This inconsistency causes confusion about the tool’s actual behavior and capabilities.

---

Discrepancy Details

Prompt (LLM system instructions):

Hybrid Search: Combining both vector and graph searches for comprehensive results

Interpretation: Implies integration of semantic vector search with graph traversal (e.g., knowledge graph reasoning).

---

README – Key Features:

Hybrid Search: Seamlessly combines vector similarity and graph traversal

Also suggests use of graph-based queries, which are not present in the implementation.

---

README – Tool Usage Visibility:

- `vector_search` - Semantic similarity search  
- `graph_search` - Knowledge graph queries  
- `hybrid_search` - Combined search approach

The phrase “combined search approach” is ambiguous — it seems to reinforce the idea that hybrid_search includes graph reasoning.

---

Actual Implementation Behavior

Looking at the FastAPI route and tool logic:

@app.post("/search/hybrid")
async def search_hybrid(request: SearchRequest):
    ...
    results = await hybrid_search_tool(input_data)

@rag_agent.tool
async def hybrid_search(...)
    """Combines semantic similarity search with keyword matching..."""

The final SQL call:

SELECT * FROM hybrid_search($1::vector, $2, $3, $4)

And the actual logic in PostgreSQL:

combined_score = vector_similarity * (1 - text_weight) + text_similarity * text_weight

This confirms that the tool performs:

• ✅ Vector similarity search (via embeddings)
• ✅ Text/keyword search (via full-text search)
• ❌ No graph traversal
• ❌ No use of a graph database, nodes/edges, or entity linking

---

Conclusion

The current hybrid_search implementation does not match how it is described in the prompt and documentation.

It implements:

Hybrid = vector search + full-text search

But is described as:

Hybrid = vector search + graph traversal

---

Requested Actions

1. Clarify the documentation:

   • Update both the LLM prompt and README to accurately reflect that hybrid_search combines vector search + keyword matching, not graph-based reasoning.

2. Optional (but helpful):

   • Consider renaming or distinguishing:

     • hybrid_vector_text_search (current implementation)
     • hybrid_vector_graph_search (if graph features are added in the future)

Additional Notes (to use the hybrid_search as is)

The hybrid_search function requires the text_similarity column to be of type DOUBLE PRECISION to match the function's declared return type. Since the ts_rank_cd function returns a real type by default, explicitly casting its result to double precision is necessary. This ensures type consistency and prevents errors related to mismatched return types, as shown here:

CREATE OR REPLACE FUNCTION hybrid_search(
...
text_similarity DOUBLE PRECISION,
...
ts_rank_cd(to_tsvector('english', c.content), plainto_tsquery('english', query_text))::double precision AS text_sim,
...