feat: Add RAG (Retrieval-Augmented Generation) support

- Add core RAG module with Document, Chunk, RetrievalResult models
- Add RAGProvider abstract base class for pluggable implementations
- Add RAG events for observability (retrieval start/complete, document/file added)
- Integrate RAG into base LLM class with automatic context injection
- Implement GeminiFileSearchRAG using Google's native File Search Tool
- Add comprehensive tests for RAG functionality
- Add gemini_rag_demo example showing RAG in action

Author: d3xvn

agents-core/vision_agents/core/__init__.py

@@ -4,5 +4,15 @@
 
 from vision_agents.core.cli.cli_runner import cli
 from vision_agents.core.agents.agent_launcher import AgentLauncher
+from vision_agents.core.rag import RAGProvider, Document, Chunk, RetrievalResult
 
-__all__ = ["Agent", "User", "cli", "AgentLauncher"]
+__all__ = [
+    "Agent",
+    "User",
+    "cli",
+    "AgentLauncher",
+    "RAGProvider",
+    "Document",
+    "Chunk",
+    "RetrievalResult",
+]

agents-core/vision_agents/core/llm/llm.py

@@ -23,6 +23,7 @@
 if TYPE_CHECKING:
     from vision_agents.core.agents import Agent
     from vision_agents.core.agents.conversation import Conversation
+    from vision_agents.core.rag import RAGProvider
 
 from getstream.video.rtc import PcmData
 from getstream.video.rtc.pb.stream.video.sfu.models.models_pb2 import Participant
@@ -62,6 +63,10 @@ def __init__(self):
         # LLM instructions. Provided by the Agent via `set_instructions` method
         self._instructions: str = ""
         self._conversation: Optional[Conversation] = None
+        # RAG provider for retrieval-augmented generation
+        self._rag_provider: Optional[RAGProvider] = None
+        self._rag_top_k: int = 5
+        self._rag_include_citations: bool = True
 
     async def warmup(self) -> None:
         """
@@ -192,6 +197,59 @@ def set_instructions(self, instructions: Instructions | str) -> None:
                 f"Invalid instructions type {type(instructions)}, expected str or Instructions"
             )
 
+    def set_rag_provider(
+        self,
+        provider: RAGProvider,
+        top_k: int = 5,
+        include_citations: bool = True,
+    ) -> None:
+        """Attach a RAG provider to this LLM for retrieval-augmented generation.
+
+        When a RAG provider is attached, queries will automatically be augmented
+        with relevant context retrieved from the knowledge base.
+
+        Args:
+            provider: The RAG provider to use for retrieval.
+            top_k: Number of results to retrieve per query.
+            include_citations: Whether to include citations in the context.
+        """
+        self._rag_provider = provider
+        self._rag_top_k = top_k
+        self._rag_include_citations = include_citations
+
+    @property
+    def rag_provider(self) -> Optional[RAGProvider]:
+        """Get the attached RAG provider, if any."""
+        return self._rag_provider
+
+    async def _augment_with_rag(self, text: str) -> str:
+        """Augment a query with RAG context if a provider is attached.
+
+        Args:
+            text: The original query text.
+
+        Returns:
+            The query augmented with retrieved context, or the original
+            text if no RAG provider is attached or no results found.
+        """
+        if self._rag_provider is None:
+            return text
+
+        results = await self._rag_provider.search_with_events(
+            query=text,
+            top_k=self._rag_top_k,
+        )
+
+        if not results:
+            return text
+
+        context = self._rag_provider.build_context_prompt(
+            results,
+            include_citations=self._rag_include_citations,
+        )
+
+        return f"{context}\n\nUser question: {text}"
+
     def register_function(
         self, name: Optional[str] = None, description: Optional[str] = None
     ) -> Callable:

agents-core/vision_agents/core/rag/__init__.py

@@ -0,0 +1,22 @@
+"""RAG (Retrieval-Augmented Generation) module for Vision Agents."""
+
+from .base import RAGProvider
+from .events import (
+    RAGDocumentAddedEvent,
+    RAGFileAddedEvent,
+    RAGRetrievalCompleteEvent,
+    RAGRetrievalStartEvent,
+)
+from .types import Chunk, Document, RetrievalResult
+
+__all__ = [
+    "RAGProvider",
+    "Document",
+    "Chunk",
+    "RetrievalResult",
+    "RAGRetrievalStartEvent",
+    "RAGRetrievalCompleteEvent",
+    "RAGDocumentAddedEvent",
+    "RAGFileAddedEvent",
+]
+

agents-core/vision_agents/core/rag/base.py

@@ -0,0 +1,159 @@
+"""Base RAG provider interface."""
+
+import abc
+import time
+from typing import Optional
+
+from vision_agents.core.events.manager import EventManager
+
+from . import events
+from .types import Document, RetrievalResult
+
+
+class RAGProvider(abc.ABC):
+    """Abstract base class for RAG (Retrieval-Augmented Generation) providers.
+
+    RAG providers handle document ingestion, storage, and retrieval for
+    augmenting LLM responses with relevant context.
+
+    Implementations can be:
+    - Provider-native (e.g., Gemini File Search, OpenAI Vector Store)
+    - Local (e.g., FAISS, ChromaDB with custom embeddings)
+    """
+
+    def __init__(self):
+        self.events = EventManager()
+        self.events.register_events_from_module(events)
+
+    @abc.abstractmethod
+    async def add_documents(self, documents: list[Document]) -> None:
+        """Ingest documents into the knowledge base.
+
+        Args:
+            documents: List of documents to add.
+        """
+
+    @abc.abstractmethod
+    async def add_file(self, file_path: str, metadata: Optional[dict] = None) -> str:
+        """Ingest a file into the knowledge base.
+
+        Args:
+            file_path: Path to the file to ingest.
+            metadata: Optional metadata to associate with the file.
+
+        Returns:
+            ID of the ingested file/document.
+        """
+
+    async def add_files(self, file_paths: list[str]) -> list[str]:
+        """Ingest multiple files into the knowledge base.
+
+        Args:
+            file_paths: List of file paths to ingest.
+
+        Returns:
+            List of IDs for the ingested files.
+        """
+        ids = []
+        for path in file_paths:
+            file_id = await self.add_file(path)
+            ids.append(file_id)
+        return ids
+
+    @abc.abstractmethod
+    async def search(
+        self,
+        query: str,
+        top_k: int = 5,
+    ) -> list[RetrievalResult]:
+        """Retrieve relevant chunks for a query.
+
+        Args:
+            query: The search query.
+            top_k: Maximum number of results to return.
+
+        Returns:
+            List of retrieval results ordered by relevance.
+        """
+
+    async def search_with_events(
+        self,
+        query: str,
+        top_k: int = 5,
+    ) -> list[RetrievalResult]:
+        """Search with event emission for observability.
+
+        Args:
+            query: The search query.
+            top_k: Maximum number of results to return.
+
+        Returns:
+            List of retrieval results ordered by relevance.
+        """
+        self.events.send(
+            events.RAGRetrievalStartEvent(
+                query=query,
+                top_k=top_k,
+            )
+        )
+
+        start_time = time.time()
+        results = await self.search(query, top_k)
+        elapsed_ms = (time.time() - start_time) * 1000
+
+        self.events.send(
+            events.RAGRetrievalCompleteEvent(
+                query=query,
+                results=results,
+                retrieval_time_ms=elapsed_ms,
+            )
+        )
+
+        return results
+
+    def build_context_prompt(
+        self,
+        results: list[RetrievalResult],
+        include_citations: bool = True,
+    ) -> str:
+        """Format retrieved results for injection into LLM prompt.
+
+        Args:
+            results: List of retrieval results.
+            include_citations: Whether to include citation markers.
+
+        Returns:
+            Formatted context string to prepend to the user's query.
+        """
+        if not results:
+            return ""
+
+        context_parts = [
+            "Use the following context to answer the question. "
+            "If the context doesn't contain relevant information, say so.\n"
+        ]
+
+        for i, result in enumerate(results, 1):
+            citation = f" {result.format_citation()}" if include_citations else ""
+            context_parts.append(f"[{i}]{citation}: {result.content}\n")
+
+        return "\n".join(context_parts)
+
+    @abc.abstractmethod
+    async def delete_document(self, document_id: str) -> bool:
+        """Delete a document from the knowledge base.
+
+        Args:
+            document_id: ID of the document to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+
+    async def clear(self) -> None:
+        """Clear all documents from the knowledge base.
+
+        Default implementation does nothing. Override if supported.
+        """
+        pass
+

agents-core/vision_agents/core/rag/events.py

@@ -0,0 +1,58 @@
+"""RAG-specific events for observability."""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from vision_agents.core.events import BaseEvent
+
+from .types import RetrievalResult
+
+
+@dataclass
+class RAGRetrievalStartEvent(BaseEvent):
+    """Emitted when RAG retrieval begins."""
+
+    type: str = field(default="rag.retrieval.start", init=False)
+    plugin_name: str = "rag"
+    query: str = ""
+    top_k: int = 5
+
+
+@dataclass
+class RAGRetrievalCompleteEvent(BaseEvent):
+    """Emitted when RAG retrieval completes."""
+
+    type: str = field(default="rag.retrieval.complete", init=False)
+    plugin_name: str = "rag"
+    query: str = ""
+    results: list[RetrievalResult] = field(default_factory=list)
+    retrieval_time_ms: float = 0.0
+
+    @property
+    def result_count(self) -> int:
+        return len(self.results)
+
+
+@dataclass
+class RAGDocumentAddedEvent(BaseEvent):
+    """Emitted when a document is added to the RAG system."""
+
+    type: str = field(default="rag.document.added", init=False)
+    plugin_name: str = "rag"
+    document_id: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    chunk_count: int = 0
+
+
+@dataclass
+class RAGFileAddedEvent(BaseEvent):
+    """Emitted when a file is uploaded to the RAG system."""
+
+    type: str = field(default="rag.file.added", init=False)
+    plugin_name: str = "rag"
+    file_path: str = ""
+    file_id: Optional[str] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+