feat(rag): Add OpenAI Vector Store RAG and Local RAG providers

- Add OpenAIVectorStoreRAG provider using OpenAI's managed vector store API
  - Supports file upload, search with relevance scores, and citations
  - Automatic store creation and management
  - Integrates with OpenAI LLM via set_rag_provider()

- Add LocalRAG provider with pluggable components:
  - EmbeddingProvider interface with OpenAIEmbeddings implementation
  - VectorStore interface with InMemoryVectorStore implementation
  - Chunker interface with FixedSizeChunker and SentenceChunker

- Add comprehensive unit tests for all new components
- Export new components from core rag module and OpenAI plugin

Author: d3xvn

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

@@ -7,15 +7,36 @@
     RAGRetrievalCompleteEvent,
     RAGRetrievalStartEvent,
 )
+from .local import (
+    Chunker,
+    EmbeddingProvider,
+    FixedSizeChunker,
+    InMemoryVectorStore,
+    LocalRAG,
+    OpenAIEmbeddings,
+    SentenceChunker,
+    VectorStore,
+)
 from .types import Chunk, Document, RetrievalResult
 
 __all__ = [
+    # Base
     "RAGProvider",
     "Document",
     "Chunk",
     "RetrievalResult",
+    # Events
     "RAGRetrievalStartEvent",
     "RAGRetrievalCompleteEvent",
     "RAGDocumentAddedEvent",
     "RAGFileAddedEvent",
+    # Local RAG
+    "LocalRAG",
+    "EmbeddingProvider",
+    "OpenAIEmbeddings",
+    "VectorStore",
+    "InMemoryVectorStore",
+    "Chunker",
+    "FixedSizeChunker",
+    "SentenceChunker",
 ]

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

@@ -0,0 +1,17 @@
+"""Local RAG implementation with pluggable embeddings and vector stores."""
+
+from .chunker import Chunker, FixedSizeChunker, SentenceChunker
+from .embeddings import EmbeddingProvider, OpenAIEmbeddings
+from .local_rag import LocalRAG
+from .vector_store import InMemoryVectorStore, VectorStore
+
+__all__ = [
+    "LocalRAG",
+    "EmbeddingProvider",
+    "OpenAIEmbeddings",
+    "VectorStore",
+    "InMemoryVectorStore",
+    "Chunker",
+    "FixedSizeChunker",
+    "SentenceChunker",
+]

agents-core/vision_agents/core/rag/local/chunker.py

@@ -0,0 +1,160 @@
+"""Text chunking strategies for local RAG."""
+
+import abc
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class TextChunk:
+    """A chunk of text with position information."""
+
+    content: str
+    start: int
+    end: int
+    index: int
+
+
+class Chunker(abc.ABC):
+    """Abstract base class for text chunking strategies."""
+
+    @abc.abstractmethod
+    def chunk(self, text: str) -> list[TextChunk]:
+        """Split text into chunks.
+
+        Args:
+            text: The text to chunk.
+
+        Returns:
+            List of text chunks with position information.
+        """
+
+
+class FixedSizeChunker(Chunker):
+    """Chunk text into fixed-size pieces with optional overlap.
+
+    Example:
+        ```python
+        chunker = FixedSizeChunker(chunk_size=500, overlap=50)
+        chunks = chunker.chunk("Long document text...")
+        ```
+    """
+
+    def __init__(self, chunk_size: int = 500, overlap: int = 50):
+        """Initialize the fixed-size chunker.
+
+        Args:
+            chunk_size: Maximum size of each chunk in characters.
+            overlap: Number of characters to overlap between chunks.
+        """
+        if overlap >= chunk_size:
+            raise ValueError("Overlap must be less than chunk_size")
+        self._chunk_size = chunk_size
+        self._overlap = overlap
+
+    def chunk(self, text: str) -> list[TextChunk]:
+        """Split text into fixed-size chunks."""
+        if not text:
+            return []
+
+        chunks = []
+        start = 0
+        index = 0
+
+        while start < len(text):
+            end = min(start + self._chunk_size, len(text))
+            chunk_text = text[start:end]
+
+            chunks.append(
+                TextChunk(
+                    content=chunk_text,
+                    start=start,
+                    end=end,
+                    index=index,
+                )
+            )
+
+            # Move to next chunk, accounting for overlap
+            start = end - self._overlap if end < len(text) else end
+            index += 1
+
+        return chunks
+
+
+class SentenceChunker(Chunker):
+    """Chunk text by sentences, respecting a maximum chunk size.
+
+    This chunker tries to keep sentences together while staying
+    within the maximum chunk size.
+
+    Example:
+        ```python
+        chunker = SentenceChunker(max_chunk_size=500)
+        chunks = chunker.chunk("First sentence. Second sentence. Third sentence.")
+        ```
+    """
+
+    # Regex pattern for sentence boundaries
+    _SENTENCE_PATTERN = re.compile(r"(?<=[.!?])\s+")
+
+    def __init__(self, max_chunk_size: int = 500, min_chunk_size: int = 100):
+        """Initialize the sentence chunker.
+
+        Args:
+            max_chunk_size: Maximum size of each chunk in characters.
+            min_chunk_size: Minimum size before starting a new chunk.
+        """
+        self._max_chunk_size = max_chunk_size
+        self._min_chunk_size = min_chunk_size
+
+    def chunk(self, text: str) -> list[TextChunk]:
+        """Split text into sentence-based chunks."""
+        if not text:
+            return []
+
+        # Split into sentences
+        sentences = self._SENTENCE_PATTERN.split(text)
+
+        chunks = []
+        current_chunk = ""
+        current_start = 0
+        index = 0
+        position = 0
+
+        for sentence in sentences:
+            sentence_with_space = sentence + " "
+
+            # If adding this sentence would exceed max size
+            if (
+                len(current_chunk) + len(sentence_with_space) > self._max_chunk_size
+                and len(current_chunk) >= self._min_chunk_size
+            ):
+                # Save current chunk
+                chunks.append(
+                    TextChunk(
+                        content=current_chunk.strip(),
+                        start=current_start,
+                        end=position,
+                        index=index,
+                    )
+                )
+                index += 1
+                current_chunk = sentence_with_space
+                current_start = position
+            else:
+                current_chunk += sentence_with_space
+
+            position += len(sentence_with_space)
+
+        # Don't forget the last chunk
+        if current_chunk.strip():
+            chunks.append(
+                TextChunk(
+                    content=current_chunk.strip(),
+                    start=current_start,
+                    end=len(text),
+                    index=index,
+                )
+            )
+
+        return chunks

agents-core/vision_agents/core/rag/local/embeddings.py

@@ -0,0 +1,108 @@
+"""Embedding providers for local RAG."""
+
+import abc
+from typing import Optional
+
+
+class EmbeddingProvider(abc.ABC):
+    """Abstract base class for embedding providers.
+
+    Embedding providers convert text into vector representations
+    for semantic similarity search.
+    """
+
+    @property
+    @abc.abstractmethod
+    def dimension(self) -> int:
+        """Return the dimension of the embedding vectors."""
+
+    @abc.abstractmethod
+    async def embed(self, text: str) -> list[float]:
+        """Generate an embedding for a single text.
+
+        Args:
+            text: The text to embed.
+
+        Returns:
+            A list of floats representing the embedding vector.
+        """
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts.
+
+        Default implementation calls embed() for each text.
+        Override for more efficient batch processing.
+
+        Args:
+            texts: List of texts to embed.
+
+        Returns:
+            List of embedding vectors.
+        """
+        return [await self.embed(text) for text in texts]
+
+
+class OpenAIEmbeddings(EmbeddingProvider):
+    """Embedding provider using OpenAI's embedding models.
+
+    Example:
+        ```python
+        embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+        vector = await embeddings.embed("Hello world")
+        ```
+    """
+
+    def __init__(
+        self,
+        model: str = "text-embedding-3-small",
+        api_key: Optional[str] = None,
+        dimensions: Optional[int] = None,
+    ):
+        """Initialize OpenAI embeddings provider.
+
+        Args:
+            model: The embedding model to use. Defaults to text-embedding-3-small.
+            api_key: Optional API key. By default loads from OPENAI_API_KEY.
+            dimensions: Optional dimension for the embeddings (for models that support it).
+        """
+        from openai import AsyncOpenAI
+
+        self._model = model
+        self._dimensions = dimensions
+        self._client = AsyncOpenAI(api_key=api_key) if api_key else AsyncOpenAI()
+
+        # Default dimensions for known models
+        self._default_dimensions = {
+            "text-embedding-3-small": 1536,
+            "text-embedding-3-large": 3072,
+            "text-embedding-ada-002": 1536,
+        }
+
+    @property
+    def dimension(self) -> int:
+        """Return the dimension of the embedding vectors."""
+        if self._dimensions:
+            return self._dimensions
+        return self._default_dimensions.get(self._model, 1536)
+
+    async def embed(self, text: str) -> list[float]:
+        """Generate an embedding for a single text."""
+        kwargs: dict = {"model": self._model, "input": text}
+        if self._dimensions is not None:
+            kwargs["dimensions"] = self._dimensions
+        response = await self._client.embeddings.create(**kwargs)
+        return response.data[0].embedding
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts efficiently."""
+        if not texts:
+            return []
+
+        kwargs: dict = {"model": self._model, "input": texts}
+        if self._dimensions is not None:
+            kwargs["dimensions"] = self._dimensions
+        response = await self._client.embeddings.create(**kwargs)
+
+        # Sort by index to maintain order
+        sorted_data = sorted(response.data, key=lambda x: x.index)
+        return [item.embedding for item in sorted_data]