feat: enhance RAG module and docs (#198)

Author: yueliao11

doc/rag/backends.md

@@ -6,13 +6,13 @@ Vector Stores
 
 The RAG registry supports the following backends via `RAG_BACKEND`:
 
-- `faiss` (default): 本地与离线友好。提供真实 FAISS 适配器（如未安装 `faiss` 将自动回退到内存余弦检索）。
-- `pinecone`: 云端向量库（需要 `PINECONE_API_KEY`，默认索引名 `spoon-rag`，可用 `RAG_PINECONE_INDEX` 指定）。已提供真实适配器。
-- `qdrant`: 本地/云端（需要 `pip install qdrant-client` 且服务默认 `http://localhost:6333`）。已提供真实适配器。
-  - 支持嵌入式模式：`QDRANT_URL=:memory:` 或设置 `QDRANT_PATH=:memory:` 可在本地无服务运行。
-- `chroma`: 本地（需要 `pip install chromadb`，默认持久目录 `${RAG_DIR:-.rag_store}/chroma`）。已提供真实适配器。
+- `faiss` (default): Local and offline friendly. Provides a real FAISS adapter (falls back to in-memory cosine retrieval if `faiss` is not installed).
+- `pinecone`: Cloud vector database (requires `PINECONE_API_KEY`, default index name `spoon-rag`, can be specified via `RAG_PINECONE_INDEX`). Real adapter provided.
+- `qdrant`: Local/Cloud (requires `pip install qdrant-client` and service at `http://localhost:6333` by default). Real adapter provided.
+  - Supports embedded mode: `QDRANT_URL=:memory:` or set `QDRANT_PATH=:memory:` to run locally without a service.
+- `chroma`: Local (requires `pip install chromadb`, default persistence directory `${RAG_DIR:-.rag_store}/chroma`). Real adapter provided.
 
-说明：为了保证离线测试稳定，`faiss` 仍默认以内存向量库运行。其余后端需要按需安装/配置，适配器层保持统一 API。
+Note: To ensure stable offline testing, `faiss` still defaults to in-memory vector store behavior. Other backends require installation/configuration as needed, while the adapter layer maintains a unified API.
 
 Embeddings
 ----------
@@ -21,29 +21,29 @@ Embeddings
 - OpenAI: set `OPENAI_API_KEY` (uses `text-embedding-3-small` by default).
 - Hash (fallback): deterministic offline embedding for tests and demos (no env needed).
 
-Backend Smoke 测试
-------------------
+Backend Smoke Tests
+-------------------
 
-- FAISS：
+- FAISS:
   ```bash
-  # 如未安装 faiss，会自动回退到内存实现
+  # Automatically falls back to in-memory implementation if faiss is not installed
   RAG_BACKEND=faiss RAG_FAKE_QA=1 python examples/smoke/rag_faiss_smoke.py
   ```
 
-- Pinecone：
+- Pinecone:
   ```bash
   export PINECONE_API_KEY=...
   RAG_BACKEND=pinecone RAG_FAKE_QA=1 python examples/smoke/rag_pinecone_smoke.py
   ```
 
-- Qdrant（需本地/远程服务与 `qdrant-client`）
+- Qdrant (requires local/remote service and `qdrant-client`)
   ```bash
   pip install qdrant-client
-  export QDRANT_URL=http://localhost:6333  # 如需
+  export QDRANT_URL=http://localhost:6333  # if needed
   RAG_BACKEND=qdrant RAG_FAKE_QA=1 python examples/smoke/rag_qdrant_smoke.py
   ```
 
-- Chroma（需 `chromadb`）
+- Chroma (requires `chromadb`)
   ```bash
   pip install chromadb
   RAG_BACKEND=chroma RAG_FAKE_QA=1 python examples/smoke/rag_chroma_smoke.py

examples/rag_graph_agent_demo.py

@@ -0,0 +1,82 @@
+"""Graph Agent demo using the RAG component (ingest -> retrieve -> answer).
+
+Offline by default (hash embeddings + in-memory store).
+"""
+
+import asyncio
+from typing import Dict, Any, List
+
+from spoon_ai.graph import StateGraph
+from spoon_ai.agents.graph_agent import GraphAgent
+from spoon_ai.chat import ChatBot
+
+from spoon_ai.rag import (
+    get_default_config,
+    get_embedding_client,
+    get_vector_store,
+    RagIndex,
+    RagRetriever,
+    RagQA,
+)
+
+
+def build_pipeline():
+    cfg = get_default_config()
+    store = get_vector_store(cfg.backend)
+    embed = get_embedding_client(
+        cfg.embeddings_provider,
+        openai_api_key=cfg.openai_api_key,
+        openai_model=cfg.openai_embeddings_model,
+        anyroute_api_key=cfg.anyroute_api_key,
+        anyroute_base_url=cfg.anyroute_base_url,
+        anyroute_model=cfg.anyroute_model,
+    )
+
+    index = RagIndex(config=cfg, store=store, embeddings=embed)
+    retriever = RagRetriever(config=cfg, store=store, embeddings=embed)
+    # Offline-friendly: if RAG_FAKE_QA=1, avoid initializing ChatBot
+    import os
+    llm = None if os.getenv("RAG_FAKE_QA") == "1" else ChatBot()
+    qa = RagQA(config=cfg, llm=llm)
+
+    def ingest_node(state: Dict[str, Any]) -> Dict[str, Any]:
+        inputs = state.get("inputs", [])
+        n = index.ingest(inputs)
+        return {"ingested": n}
+
+    def retrieve_node(state: Dict[str, Any]) -> Dict[str, Any]:
+        q = state.get("question", "")
+        chunks = retriever.retrieve(q)
+        return {"chunks": chunks, "context": retriever.build_context(chunks)}
+
+    async def answer_node(state: Dict[str, Any]) -> Dict[str, Any]:
+        q = state.get("question", "")
+        chunks = state.get("chunks", [])
+        res = await qa.answer(q, chunks)
+        return {"answer": res.answer, "citations": res.citations}
+
+    graph = StateGraph(dict)
+    graph.add_node("RAGIngestNode", ingest_node)
+    graph.add_node("RAGRetrieveNode", retrieve_node)
+    graph.add_node("RAGAnswerNode", answer_node)
+    graph.add_edge("RAGIngestNode", "RAGRetrieveNode")
+    graph.add_edge("RAGRetrieveNode", "RAGAnswerNode")
+    graph.set_entry_point("RAGIngestNode")
+    return graph.compile()
+
+
+async def main():
+    compiled = build_pipeline()
+    agent = GraphAgent(name="rag-graph", graph=compiled.graph)
+    initial_state = {
+        "inputs": ["./doc"],
+        "question": "How do I install the SDK?",
+    }
+    result = await compiled.ainvoke(initial_state)
+    print("\n== RAG Graph Agent Demo ==")
+    print("Answer:", result.get("answer"))
+    print("Citations:", result.get("citations"))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/rag_react_agent_demo.py

@@ -0,0 +1,57 @@
+"""ReAct Agent demo using the RAG component (ingest -> search -> QA).
+
+Runs offline by default using a deterministic hash embedding and in-memory store.
+If OPENAI_API_KEY or ANYROUTE_* are present, will use those embeddings.
+
+Env vars:
+- RAG_BACKEND=faiss|pinecone|qdrant|chroma (default: faiss)
+- RAG_COLLECTION=<name> (default: default)
+- TOP_K, CHUNK_SIZE, CHUNK_OVERLAP optional
+"""
+
+import asyncio
+import os
+from spoon_ai.chat import ChatBot
+from spoon_ai.agents.toolcall import ToolCallAgent
+from spoon_ai.tools import ToolManager
+from spoon_ai.tools.rag_tools import RAGIngestTool, RAGSearchTool, RAGQATool
+
+
+async def main() -> None:
+    tools = ToolManager([
+        RAGIngestTool(),
+        RAGSearchTool(),
+        RAGQATool(),
+    ])
+
+    agent = ToolCallAgent(
+        name="rag-react",
+        llm=ChatBot(),
+        available_tools=tools,
+    )
+
+    print("\n== RAG ReAct Agent Demo ==\n")
+
+    # 1) Ingest a local directory or url
+    docs_dir = os.getenv("RAG_DOCS", "./doc")
+    ingest_request = f"Use rag_ingest to index docs in {docs_dir}"
+    print("User:", ingest_request)
+    out = await agent.run(ingest_request)
+    print("Assistant:", out)
+
+    # 2) Search
+    search_request = "Use rag_search to find info about installation"
+    print("\nUser:", search_request)
+    out = await agent.run(search_request)
+    print("Assistant:", out)
+
+    # 3) QA
+    qa_request = "Use rag_qa to answer: How do I install the SDK?"
+    print("\nUser:", qa_request)
+    out = await agent.run(qa_request)
+    print("Assistant:", out)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

examples/smoke/rag_react_offline_smoke.py

@@ -6,7 +6,7 @@
 import asyncio
 import os
 try:
-    from spoon_ai.tools.rag_tools import RAGIngestTool, RAGSearchTool, RAGQATool
+    from spoon_ai.tools.rag_tools import , RAGSearchTool, RAGQATool
 except ModuleNotFoundError:
     import sys, pathlib
     sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))

examples/smoke/rag_tools_smoke.py

@@ -0,0 +1,104 @@
+"""Smoke test for RAG Tools, verifying dependency injection and backward compatibility.
+
+Run:
+  python3 examples/smoke/rag_tools_smoke.py
+"""
+
+import asyncio
+import os
+import sys
+import pathlib
+
+# Add project root to path
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
+
+# Mock missing dependencies to isolate tool logic testing
+from unittest.mock import MagicMock
+import sys
+
+# Mock openai and related modules that might be missing in this env
+sys.modules["openai"] = MagicMock()
+sys.modules["spoon_ai.min_pypi"] = MagicMock() # potential internal dep
+
+# We need to mock ChatBot because rag_tools imports it
+mock_chat = MagicMock()
+sys.modules["spoon_ai.chat"] = mock_chat
+
+# Mock RAG backends
+sys.modules["pinecone"] = MagicMock()
+sys.modules["chromadb"] = MagicMock()
+sys.modules["qdrant_client"] = MagicMock()
+sys.modules["faiss"] = MagicMock()
+
+try:
+    from spoon_ai.tools.rag_tools import RAGQATool, RAGSearchTool
+    # Mock ChatBot inside the module if needed, though sys.modules should cover it
+    mock_chat.ChatBot = MagicMock
+except ImportError as e:
+    print(f"Error importing modules: {e}")
+    # Print sys.path to help debug
+    print(sys.path)
+    sys.exit(1)
+
+class MockLLM:
+    async def ask(self, messages, **kwargs):
+        return "This is a mock answer with citation [1]."
+
+async def main():
+    print("=== Testing RAG Tools Compatibility ===")
+    
+    # 1. Test Backward Compatibility (No args)
+    try:
+        tool_v1 = RAGQATool()
+        print("[PASS] V1 Initialization (No args) passed.")
+        assert tool_v1._llm is None
+    except Exception as e:
+        print(f"[FAIL] V1 Initialization failed: {e}")
+
+    # 2. Test Backward Compatibility (Pydantic fields)
+    try:
+        tool_v2 = RAGQATool(name="custom_rag", description="Custom desc")
+        print("[PASS] V1 Initialization (Pydantic fields) passed.")
+        assert tool_v2.name == "custom_rag"
+        assert tool_v2._llm is None
+    except Exception as e:
+        print(f"[FAIL] V1 Initialization (Pydantic fields) failed: {e}")
+
+    # 3. Test Dependency Injection (New feature)
+    try:
+        mock_llm = MockLLM()
+        tool_v3 = RAGQATool(llm=mock_llm)
+        print("[PASS] V2 Initialization (Dependency Injection) passed.")
+        assert tool_v3._llm is mock_llm
+    except Exception as e:
+        print(f"[FAIL] V2 Initialization (Dependency Injection) failed: {e}")
+
+    # 4. Test Dependency Injection Mixed with Pydantic
+    try:
+        mock_llm = MockLLM()
+        tool_v4 = RAGQATool(llm=mock_llm, name="injected_tool")
+        print("[PASS] V2 Initialization (Mixed) passed.")
+        assert tool_v4.name == "injected_tool"
+        assert tool_v4._llm is mock_llm
+    except Exception as e:
+        print(f"[FAIL] V2 Initialization (Mixed) failed: {e}")
+
+    print("\n=== Testing Parameter Defaults ===")
+    # 5. Check schema defaults
+    search_tool = RAGSearchTool()
+    props = search_tool.parameters["properties"]
+    
+    if "default: 5" in props["top_k"].get("description", ""):
+        print("[PASS] RAGSearchTool top_k description contains default.")
+    else:
+        print(f"[FAIL] RAGSearchTool top_k description missing default: {props['top_k']}")
+
+    if "default: 'default'" in props["collection"].get("description", ""):
+        print("[PASS] RAGSearchTool collection description contains default.")
+    else:
+        print(f"[FAIL] RAGSearchTool collection description missing default: {props['collection']}")
+
+    print("\nAll Smoke Tests Completed.")
+
+if __name__ == "__main__":
+    asyncio.run(main())