Merge pull request #24 from royisme/codex/refactor-neo4jknowledgeservice-to-querypipeline

Refactor Neo4j knowledge query pipeline

Author: royisme

README.md

@@ -87,6 +87,22 @@ The platform combines vector search, graph traversal, and LLM-driven analysis to
 - Docker (optional, for containerized deployment)
 - Node.js 18+ (for frontend development)
 
+### Querying Knowledge
+```python
+# Query the knowledge base
+response = httpx.post("http://localhost:8000/api/v1/knowledge/query", json={
+    "question": "How does the authentication system work?",
+    "mode": "hybrid",  # or "graph_only", "vector_only"
+    "use_tools": False,
+    "top_k": 5
+})
+
+# Search similar documents
+response = httpx.post("http://localhost:8000/api/v1/knowledge/search", json={
+    "query": "user authentication",
+    "top_k": 10
+})
+```
 ### Installation
 
 Clone the repository and install dependencies:

README_CN.md

@@ -150,7 +150,9 @@ response = httpx.post("http://localhost:8000/api/v1/documents/directory", json={
 # 查询知识库
 response = httpx.post("http://localhost:8000/api/v1/knowledge/query", json={
     "question": "认证系统是如何工作的？",
-    "mode": "hybrid"  # 或 "graph_only", "vector_only"
+    "mode": "hybrid",  # 或 "graph_only", "vector_only"
+    "use_tools": False,
+    "top_k": 5
 })
 
 # 搜索相似文档

docs/api/rest.md

@@ -135,16 +135,26 @@ Query the knowledge base using GraphRAG.
 ```json
 {
   "question": "How does authentication work in this system?",
-  "mode": "hybrid"
+  "mode": "hybrid",
+  "use_graph": true,
+  "use_vector": true,
+  "use_tools": false,
+  "top_k": 5,
+  "graph_depth": 2
 }
 ```
 
 **Parameters**:
 - `question` (string, required): Question to ask
 - `mode` (string, optional): Query mode
-  - `hybrid` (default): Graph traversal + vector search
-  - `graph_only`: Only graph relationships
-  - `vector_only`: Only vector similarity
+  - `hybrid` (default): Run graph + vector retrieval sequentially
+  - `graph_only`: Only run graph retrieval
+  - `vector_only`: Only run vector retrieval
+- `use_graph` / `use_vector` (boolean, optional): Override mode defaults
+- `use_tools` (boolean, optional): Execute registered workflow tools (default: `false`)
+- `top_k` (integer, optional): Override vector retrieval `top_k` (default: global setting)
+- `graph_depth` (integer, optional): Override graph traversal depth (default: `2`)
+- `tool_kwargs` (object, optional): Extra parameters passed to workflow tools
 
 **Response**:
 ```json
@@ -153,6 +163,7 @@ Query the knowledge base using GraphRAG.
   "answer": "The system uses JWT-based authentication...",
   "source_nodes": [
     {
+      "node_id": "node-123",
       "text": "JWT implementation details...",
       "score": 0.92,
       "metadata": {
@@ -161,7 +172,33 @@ Query the knowledge base using GraphRAG.
       }
     }
   ],
-  "mode": "hybrid"
+  "retrieved_nodes": [...],
+  "pipeline_steps": [
+    {
+      "step": "graph_retrieval",
+      "node_count": 3,
+      "config": {
+        "graph_traversal_depth": 2,
+        "max_knowledge_sequence": 30
+      }
+    },
+    {
+      "step": "vector_retrieval",
+      "node_count": 5,
+      "config": {
+        "top_k": 5
+      }
+    }
+  ],
+  "tool_outputs": [],
+  "query_mode": "hybrid",
+  "config": {
+    "graph": true,
+    "vector": true,
+    "tools": false,
+    "top_k": 5,
+    "graph_depth": 2
+  }
 }
 ```
 

docs/architecture/components.md

@@ -367,9 +367,14 @@ async def lifespan(app: FastAPI):
 ```python
 class Neo4jKnowledgeService:
     def __init__(self):
-        self.graph_store = None          # Neo4j graph store
-        self.knowledge_index = None      # LlamaIndex KnowledgeGraphIndex
-        self.query_engine = None         # RAG query engine
+        self.graph_store = None              # Neo4j graph store
+        self.storage_context = None          # Shared storage context
+        self.knowledge_index = None          # KnowledgeGraphIndex
+        self.vector_index = None             # VectorStoreIndex for similarity search
+        self.response_synthesizer = None     # LLM-backed synthesizer
+        self.query_pipeline = None           # Graph/Vector pipeline
+        self.function_tools = []             # Workflow tools
+        self.tool_node = None                # Optional ToolNode
         self._initialized = False
 ```
 
@@ -389,7 +394,7 @@ sequenceDiagram
     KnowServ->>LlamaIndex: Configure Settings
     KnowServ->>LlamaIndex: Create KnowledgeGraphIndex
     LlamaIndex-->>KnowServ: Index ready
-    KnowServ->>KnowServ: Create query engine
+    KnowServ->>KnowServ: Build QueryPipeline (graph + vector + synth)
     KnowServ-->>Client: Initialized
 ```
 
@@ -419,24 +424,29 @@ async def add_document(
 async def query(
     self,
     question: str,
-    top_k: int = 5
+    *,
+    mode: str = "hybrid",
+    use_tools: bool = False
 ) -> Dict[str, Any]:
-    """Query knowledge base with RAG"""
-    # 1. Use query engine to retrieve relevant context
-    # 2. Generate answer using LLM with context
-    response = await asyncio.to_thread(
-        self.query_engine.query,
-        question
-    )
+    """Run the QueryPipeline composed of graph/vector retrievers and a synthesizer."""
+    config = self._resolve_pipeline_config(mode, use_tools=use_tools)
+    result = await asyncio.to_thread(self.query_pipeline.run, question, config)
 
-    # 3. Return answer with source nodes
     return {
         "success": True,
-        "answer": str(response),
-        "sources": [node.metadata for node in response.source_nodes]
+        "answer": str(result["response"]),
+        "source_nodes": format_sources(result["source_nodes"]),
+        "pipeline_steps": result["steps"],
+        "tool_outputs": result["tool_outputs"]
     }
 ```
 
+**Pipeline Components**:
+1. `KnowledgeGraphRAGRetriever` — extracts entities and traverses the property graph.
+2. `VectorIndexRetriever` — performs vector similarity search over the Neo4j vector index.
+3. `ResponseSynthesizer` — merges retrieved context and generates the final answer.
+4. `FunctionTool` / `ToolNode` (optional) — exposes the query as a workflow tool for multi-turn agents.
+
 #### 3. Semantic Search
 ```python
 async def search_similar(