gllm-datastore-binary 0.5.45__cp311-cp311-macosx_13_0_arm64.whl

gllm_datastore/graph_data_store/neo4j_graph_data_store.pyi

@@ -0,0 +1,182 @@
+from _typeshed import Incomplete
+from gllm_core.utils.retry import RetryConfig
+from gllm_datastore.graph_data_store.graph_data_store import BaseGraphDataStore as BaseGraphDataStore
+from typing import Any
+
+class Neo4jGraphDataStore(BaseGraphDataStore):
+    '''Implementation of BaseGraphDataStore for Neo4j.
+
+    This class provides an interface for graph-based Retrieval-Augmented Generation (RAG)
+    operations on Neo4j graph databases.
+
+    Attributes:
+        driver (Driver): The Neo4j driver.
+
+    Example:
+        ```python
+        store = Neo4jGraphDataStore(
+            uri="bolt://localhost:7687",
+            user="neo4j",
+            password="password"
+        )
+        # Perform async operations
+        results = await store.query("MATCH (n) RETURN n")
+
+        # Create a node
+        node = await store.upsert_node("Person", "name", "John", {"age": 30})
+        ```
+    '''
+    driver: Incomplete
+    retry_config: Incomplete
+    def __init__(self, uri: str, user: str, password: str, max_connection_pool_size: int = 100, retry_config: RetryConfig | None = None, **kwargs: Any) -> None:
+        """Initialize Neo4jGraphDataStore.
+
+        Args:
+            uri (str): The URI of the graph store.
+            user (str): The user of the graph store.
+            password (str): The password of the graph store.
+            max_connection_pool_size (int, optional): The maximum size of the connection pool. Defaults to 100.
+            retry_config (RetryConfig | None, optional): Configuration for retry behavior. Defaults to None.
+                If provided, query operations will be retried according to the specified RetryConfig parameters.
+                When a database operation fails with a retryable exception (e.g., neo4j.exceptions.ServiceUnavailable),
+                the operation will be automatically retried based on the retry policy defined in the configuration.
+            **kwargs (Any): Additional keyword arguments for the driver.
+        """
+    async def upsert_node(self, label: str, identifier_key: str, identifier_value: str, properties: dict[str, Any] | None = None) -> Any:
+        """Upsert a node in the graph.
+
+        Args:
+            label (str): The label of the node.
+            identifier_key (str): The key of the identifier.
+            identifier_value (str): The value of the identifier.
+            properties (dict[str, Any] | None, optional): The properties of the node. Defaults to None.
+
+        Returns:
+            Any: The result of the operation.
+        """
+    async def upsert_relationship(self, node_source_key: str, node_source_value: str, relation: str, node_target_key: str, node_target_value: str, properties: dict[str, Any] | None = None) -> Any:
+        """Upsert a relationship between two nodes in the graph.
+
+        Args:
+            node_source_key (str): The key of the source node.
+            node_source_value (str): The value of the source node.
+            relation (str): The type of the relationship.
+            node_target_key (str): The key of the target node.
+            node_target_value (str): The value of the target node.
+            properties (dict[str, Any] | None, optional): The properties of the relationship. Defaults to None.
+
+        Returns:
+            Any: The result of the operation.
+        """
+    async def delete_node(self, label: str, identifier_key: str, identifier_value: str) -> Any:
+        """Delete a node from the graph.
+
+        Args:
+            label (str): The label of the node.
+            identifier_key (str): The key of the identifier.
+            identifier_value (str): The identifier of the node.
+
+        Returns:
+            Any: The result of the operation.
+        """
+    async def delete_relationship(self, node_source_key: str, node_source_value: str, relation: str, node_target_key: str, node_target_value: str) -> Any:
+        """Delete a relationship between two nodes in the graph.
+
+        Args:
+            node_source_key (str): The key of the source node.
+            node_source_value (str): The identifier of the source node.
+            relation (str): The type of the relationship.
+            node_target_key (str): The key of the target node.
+            node_target_value (str): The identifier of the target node.
+
+        Returns:
+            Any: The result of the operation.
+        """
+    async def query(self, query: str, parameters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Query the graph store.
+
+        Args:
+            query (str): The query to be executed.
+            parameters (dict[str, Any] | None, optional): The parameters of the query. Defaults to None.
+
+        Returns:
+            list[dict[str, Any]]: The result of the query.
+        """
+    async def traverse_graph(self, node_properties: dict[str, Any], extracted_node_properties: list[str] | None = None, extracted_relationship_properties: list[str] | None = None, depth: int = 3) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        '''Traverse graph from a node with specified properties, ignoring relationship\'s direction, up to a given depth.
+
+        Example:
+            ```python
+            nodes, relationships = await graph_data_store.traverse_graph(
+                node_properties={"name": "John Doe"},
+                extracted_node_properties=["name", "age"],
+                extracted_relationship_properties=["since"],
+                depth=1
+            )
+            ```
+            Means starting from the node with property `name` equal to "John Doe", traverse
+            the graph up to depth 1, extracting the `name` and `age` properties from nodes
+            and the `since` property from relationships.
+
+            ```python
+            nodes, relationships = await graph_data_store.traverse_graph(
+                node_properties={"name": "John Doe"},
+                depth=2
+            )
+            ```
+            Means starting from the node with property `name` equal to "John Doe", traverse
+            the graph up to depth 2, extracting all properties from nodes and relationships.
+
+        Args:
+            node_properties (dict[str, Any]): The properties of the starting node.
+            extracted_node_properties (list[str] | None, optional): The properties to extract from nodes during
+                traversal. If None or empty list, all node properties will be returned. Defaults to None.
+            extracted_relationship_properties (list[str] | None, optional): The properties to extract from relationships
+                during traversal. If None or empty list, all relationship properties will be returned. Defaults to None.
+            depth (int, optional): The depth of traversal. Defaults to 3.
+
+        Returns:
+            tuple[list[dict[str, Any]], list[dict[str, Any]]]: A tuple containing two lists:
+                - List of nodes with their extracted properties (including the source node).
+                - List of relationships with their extracted properties.
+
+            Example return value:
+            nodes = [
+                {
+                    "id": 1001,
+                    "labels": ["Person"],
+                    "properties": {
+                        "name": "John Doe",
+                        "age": 30,
+                        "occupation": "Engineer"
+                    }
+                },
+                {
+                    "id": 2001,
+                    "labels": ["Company"],
+                    "properties": {
+                        "name": "TechCorp",
+                        "industry": "Technology",
+                        "employees": 500
+                    }
+                }
+            ]
+
+            relationships = [
+                {
+                    "id": 5002,
+                    "type": "FRIEND_OF",
+                    "start_node": 1001,
+                    "end_node": 1002,
+                    "properties": {
+                        "since": "2018-05-20",
+                        "closeness": 8
+                    }
+                }
+            ]
+
+        Raises:
+            ValueError: If node_properties is empty or depth is less than 1.
+        '''
+    async def close(self) -> None:
+        """Close the graph data store."""

gllm_datastore/graph_data_store/utils/__init__.pyi

@@ -0,0 +1,6 @@
+from gllm_datastore.graph_data_store.utils.light_rag_em_invoker_adapter import LightRAGEMInvokerAdapter as LightRAGEMInvokerAdapter
+from gllm_datastore.graph_data_store.utils.light_rag_lm_invoker_adapter import LightRAGLMInvokerAdapter as LightRAGLMInvokerAdapter
+from gllm_datastore.graph_data_store.utils.llama_index_em_invoker_adapter import LlamaIndexEMInvokerAdapter as LlamaIndexEMInvokerAdapter
+from gllm_datastore.graph_data_store.utils.llama_index_lm_invoker_adapter import LlamaIndexLMInvokerAdapter as LlamaIndexLMInvokerAdapter
+
+__all__ = ['LightRAGEMInvokerAdapter', 'LightRAGLMInvokerAdapter', 'LlamaIndexEMInvokerAdapter', 'LlamaIndexLMInvokerAdapter']

gllm_datastore/graph_data_store/utils/constants.pyi

@@ -0,0 +1,21 @@
+class LightRAGKeys:
+    """Keys used in LightRAG indexer."""
+    ENTITY_TYPE: str
+    ENTITY_ID: str
+    SOURCE_ID: str
+    ROLE: str
+    CONTENT: str
+
+class LightRAGConstants:
+    """Constants used in LightRAG indexer."""
+    CHUNK_TYPE: str
+    DEVELOPER_ROLE: str
+    EMBEDDING_PAYLOAD_TEST: str
+    FILE_TYPE: str
+
+class LightRAGPostgresStorageConstants:
+    """Constants used in LightRAG indexer with PostgreSQL storage."""
+    DOC_STATUS_STORAGE: str
+    GRAPH_STORAGE: str
+    KV_STORAGE: str
+    VECTOR_STORAGE: str

gllm_datastore/graph_data_store/utils/light_rag_em_invoker_adapter.pyi

@@ -0,0 +1,56 @@
+from _typeshed import Incomplete
+from gllm_datastore.graph_data_store.utils.constants import LightRAGConstants as LightRAGConstants
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker
+from lightrag.base import EmbeddingFunc
+
+class LightRAGEMInvokerAdapter(EmbeddingFunc):
+    """Adapter for embedding model invokers to work with LightRAG.
+
+    This adapter wraps BaseEMInvoker instances to make them compatible
+    with LightRAG's expected interface.
+
+    Attributes:
+        _em_invoker (BaseEMInvoker): The EM invoker to use.
+        func (callable): The embedding function.
+        embedding_dim (int): The embedding dimension. Defaults to 0.
+    """
+    func: Incomplete
+    embedding_dim: int
+    def __init__(self, em_invoker: BaseEMInvoker) -> None:
+        """Initialize the LightRAGEMInvokerAdapter.
+
+        Args:
+            em_invoker (BaseEMInvoker): The EM invoker to use.
+        """
+    async def ensure_initialized(self) -> None:
+        """Ensure that the adapter is initialized.
+
+        This asynchronous method ensures that the embedding dimension is determined.
+        If the embedding dimension is 0, it will determine the dimension by calling
+        the embedding invoker with a test input. Raises an error if initialization fails.
+
+        Raises:
+            RuntimeError: If embedding dimension cannot be determined after initialization.
+        """
+    def __deepcopy__(self, memo: dict) -> LightRAGEMInvokerAdapter:
+        """Custom deepcopy implementation to handle non-serializable objects.
+
+        This method is called when copy.deepcopy() is invoked on this object.
+        We create a new instance without deep-copying the invoker object
+        which may contain non-serializable components.
+
+        Args:
+            memo (dict): Memoization dictionary for deepcopy process
+
+        Returns:
+            LightRAGEMInvokerAdapter: A new instance with the same invoker reference
+        """
+    async def __call__(self, input: str | list[str]) -> list[list[float]]:
+        """Make the adapter callable for compatibility with LightRAG.
+
+        Args:
+            input (str | list[str]): The input text or list of texts to embed.
+
+        Returns:
+            list[list[float]]: The embeddings for the input texts.
+        """

gllm_datastore/graph_data_store/utils/light_rag_lm_invoker_adapter.pyi

@@ -0,0 +1,43 @@
+from gllm_datastore.graph_data_store.utils.constants import LightRAGConstants as LightRAGConstants, LightRAGKeys as LightRAGKeys
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from typing import Any
+
+class LightRAGLMInvokerAdapter:
+    """LMInvoker adapter for the LightRAG module.
+
+    This adapter is used to adapt the LMInvoker interface to the LightRAG module.
+    It handles the conversion between different prompt formats and manages
+    asynchronous invocation in a way that's compatible with nested event loops.
+    """
+    def __init__(self, lm_invoker: BaseLMInvoker) -> None:
+        """Initialize the LightRAGLMInvokerAdapter.
+
+        Args:
+            lm_invoker (BaseLMInvoker): The LM invoker to use.
+        """
+    def __deepcopy__(self, memo: dict) -> LightRAGLMInvokerAdapter:
+        """Custom deepcopy implementation to handle non-serializable objects.
+
+        This method is called when copy.deepcopy() is invoked on this object.
+        We create a new instance without deep-copying the invoker object
+        which may contain non-serializable components.
+
+        Args:
+            memo (dict): Memoization dictionary for deepcopy process
+
+        Returns:
+            LightRAGLMInvokerAdapter: A new instance with the same invoker reference
+        """
+    async def __call__(self, prompt: str, system_prompt: str | None = None, history_messages: list[dict[str, Any]] | None = None, **kwargs: Any) -> str:
+        """Make the adapter callable for compatibility with LightRAG.
+
+        Args:
+            prompt (str): The prompt to invoke the LM invoker with.
+            system_prompt (str | None, optional): The system prompt to format in string format. Defaults to None.
+            history_messages (list[dict[str, Any]] | None, optional): The history messages to format in OpenAI format.
+                Defaults to None.
+            **kwargs (Any): Additional keyword arguments for the LM invoker.
+
+        Returns:
+            str: The response from the LM invoker.
+        """

gllm_datastore/graph_data_store/utils/llama_index_em_invoker_adapter.pyi

@@ -0,0 +1,45 @@
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker
+from llama_index.core.base.embeddings.base import BaseEmbedding
+from typing import Any
+
+class LlamaIndexEMInvokerAdapter(BaseEmbedding):
+    """Minimal EMInvoker adapter for the LlamaIndex BaseEmbedding interface.
+
+    This adapter wraps a BaseEMInvoker instance to provide compatibility with
+    LlamaIndex's BaseEmbedding interface. Embeddings from the underlying invoker
+    are returned directly without any conversion, assuming they are already in
+    the correct format (list of floats).
+
+    The adapter provides both synchronous and asynchronous methods for:
+    - Query embeddings: Single text embedding for search queries
+    - Text embeddings: Single or batch text embedding for documents
+
+    Attributes:
+        em_invoker (BaseEMInvoker): The underlying EM invoker instance.
+        model_name (str): The name of the embedding model (inherited from invoker).
+        embed_batch_size (int): The batch size for batch embedding operations.
+
+    Note:
+        Sync methods (_get_*) use asyncio.run internally to call async methods.
+        The implementation uses nest_asyncio to handle nested event loops if needed.
+    """
+    em_invoker: BaseEMInvoker
+    def __init__(self, em_invoker: BaseEMInvoker, embed_batch_size: int = ..., **kwargs: Any) -> None:
+        """Initialize the LlamaIndexEMInvokerAdapter.
+
+        Args:
+            em_invoker (BaseEMInvoker): The EM invoker to wrap.
+            embed_batch_size (int, optional): The batch size for embedding operations.
+                Defaults to DEFAULT_EMBED_BATCH_SIZE from LlamaIndex.
+            **kwargs (Any): Additional keyword arguments passed to BaseEmbedding (e.g.,
+                callback_manager).
+        """
+    @classmethod
+    def class_name(cls) -> str:
+        '''Get the class name (implements BaseEmbedding.class_name).
+
+        This is used by LlamaIndex for serialization and debugging.
+
+        Returns:
+            str: The class name "LlamaIndexEMInvokerAdapter".
+        '''

gllm_datastore/graph_data_store/utils/llama_index_lm_invoker_adapter.pyi

@@ -0,0 +1,169 @@
+from _typeshed import Incomplete
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from llama_index.core.base.llms.types import ChatMessage, ChatResponse, CompletionResponse, LLMMetadata
+from llama_index.core.llms import LLM
+from typing import Any, AsyncGenerator, Sequence
+
+ROLE_MAPPING: Incomplete
+
+class LlamaIndexLMInvokerAdapter(LLM):
+    """Minimal LMInvoker adapter for the LlamaIndex LLM interface.
+
+    This adapter wraps a BaseLMInvoker instance to provide compatibility with
+    LlamaIndex's LLM interface. It handles conversion between GLLM message formats
+    and LlamaIndex ChatMessage formats.
+
+    Only chat functionality is implemented. Completion and streaming methods raise
+    NotImplementedError to keep the implementation minimal.
+
+    Attributes:
+        lm_invoker (BaseLMInvoker): The underlying LM invoker instance.
+
+    Note:
+        Message roles are converted using the ROLE_MAPPING constant, which maps
+        all LlamaIndex message roles (SYSTEM, DEVELOPER, USER, ASSISTANT, TOOL,
+        FUNCTION, CHATBOT, MODEL) to GLLM MessageRole values.
+    """
+    lm_invoker: BaseLMInvoker
+    def __init__(self, lm_invoker: BaseLMInvoker, **kwargs: Any) -> None:
+        """Initialize the LlamaIndexLMInvokerAdapter.
+
+        Args:
+            lm_invoker (BaseLMInvoker): The LM invoker to wrap.
+            **kwargs (Any): Additional keyword arguments.
+        """
+    @property
+    def metadata(self) -> LLMMetadata:
+        """Get metadata about the language model.
+
+        Returns:
+            LLMMetadata: Metadata containing model information.
+        """
+    def chat(self, messages: Sequence[ChatMessage], **kwargs: Any) -> ChatResponse:
+        """Synchronous chat endpoint (implements LlamaIndex LLM.chat).
+
+        This is a synchronous wrapper around the async achat() method.
+        It handles both scenarios: when called from within an event loop and when
+        called from synchronous code.
+
+        Converts LlamaIndex ChatMessage objects to GLLM Message format, invokes
+        the underlying LM invoker, and converts the response back to ChatResponse.
+
+        Args:
+            messages (Sequence[ChatMessage]): The chat messages in LlamaIndex format.
+            **kwargs (Any): Additional keyword arguments. Supports:
+                - hyperparameters (dict, optional): Model hyperparameters like
+                  temperature, max_tokens, etc.
+
+        Returns:
+            ChatResponse: The chat response in LlamaIndex format with message content,
+                role, and optional metadata (token usage, finish details).
+        """
+    def complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> CompletionResponse:
+        """Synchronous completion endpoint.
+
+        Args:
+            prompt (str): The prompt string.
+            formatted (bool, optional): Whether the prompt is already formatted. Defaults to False.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+            CompletionResponse: The completion response.
+
+        Raises:
+            NotImplementedError: Always raises this exception.
+        """
+    def stream_chat(self, messages: Sequence[ChatMessage], **kwargs: Any) -> AsyncGenerator[ChatResponse, None]:
+        """Streaming chat endpoint.
+
+        Args:
+            messages (Sequence[ChatMessage]): The chat messages.
+            **kwargs (Any): Additional keyword arguments.
+
+        Yields:
+            ChatResponse: Streaming chat responses.
+
+        Raises:
+            NotImplementedError: Always raises this exception.
+        """
+    def stream_complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> AsyncGenerator[CompletionResponse, None]:
+        """Streaming completion endpoint.
+
+        Args:
+            prompt (str): The prompt string.
+            formatted (bool, optional): Whether the prompt is already formatted. Defaults to False.
+            **kwargs (Any): Additional keyword arguments.
+
+        Yields:
+            CompletionResponse: Streaming completion responses.
+
+        Raises:
+            NotImplementedError: Always raises this exception.
+        """
+    async def achat(self, messages: Sequence[ChatMessage], **kwargs: Any) -> ChatResponse:
+        """Asynchronous chat endpoint (implements LlamaIndex LLM.achat).
+
+        Converts LlamaIndex ChatMessage objects to GLLM Message format, invokes
+        the underlying LM invoker asynchronously, and converts the response back
+        to ChatResponse.
+
+        Args:
+            messages (Sequence[ChatMessage]): The chat messages in LlamaIndex format.
+            **kwargs (Any): Additional keyword arguments. Supports:
+                - hyperparameters (dict, optional): Model hyperparameters like
+                  temperature, max_tokens, etc.
+
+        Returns:
+            ChatResponse: The chat response in LlamaIndex format with message content,
+                role, and optional metadata (token usage, finish details).
+        """
+    async def acomplete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> CompletionResponse:
+        """Asynchronous completion endpoint.
+
+        Args:
+            prompt (str): The prompt string.
+            formatted (bool, optional): Whether the prompt is already formatted. Defaults to False.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+            CompletionResponse: The completion response.
+
+        Raises:
+            NotImplementedError: Always raises this exception.
+        """
+    def astream_chat(self, messages: Sequence[ChatMessage], **kwargs: Any) -> AsyncGenerator[ChatResponse, None]:
+        """Asynchronous streaming chat endpoint.
+
+        Args:
+            messages (Sequence[ChatMessage]): The chat messages.
+            **kwargs (Any): Additional keyword arguments.
+
+        Yields:
+            ChatResponse: Streaming chat responses.
+
+        Raises:
+            NotImplementedError: Always raises this exception.
+        """
+    def astream_complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> AsyncGenerator[CompletionResponse, None]:
+        """Asynchronous streaming completion endpoint.
+
+        Args:
+            prompt (str): The prompt string.
+            formatted (bool, optional): Whether the prompt is already formatted. Defaults to False.
+            **kwargs (Any): Additional keyword arguments.
+
+        Yields:
+            CompletionResponse: Streaming completion responses.
+
+        Raises:
+            NotImplementedError: Always raises this exception.
+        """
+    @classmethod
+    def class_name(cls) -> str:
+        '''Get the class name (implements LLM.class_name).
+
+        This is used by LlamaIndex for serialization and debugging.
+
+        Returns:
+            str: The class name "LlamaIndexLMInvokerAdapter".
+        '''

gllm_datastore/sql_data_store/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_datastore.sql_data_store.sqlalchemy_sql_data_store import SQLAlchemySQLDataStore as SQLAlchemySQLDataStore
+from gllm_datastore.sql_data_store.types import QueryFilter as QueryFilter, QueryOptions as QueryOptions
+
+__all__ = ['SQLAlchemySQLDataStore', 'QueryFilter', 'QueryOptions']

gllm_datastore/sql_data_store/adapter/sqlalchemy_adapter.pyi

@@ -0,0 +1,38 @@
+from _typeshed import Incomplete
+from sqlalchemy.engine import Engine
+from typing import Any
+
+class SQLAlchemyAdapter:
+    """Initializes a database engine and session using SQLAlchemy.
+
+    Provides a scoped session and a base query property for interacting with the database.
+
+    Attributes:
+        engine (Engine): The SQLAlchemy engine object.
+        db (Session): The SQLAlchemy session object.
+        base (DeclarativeMeta): The SQLAlchemy declarative base object.
+    """
+    engine: Incomplete
+    db: Incomplete
+    base: Incomplete
+    @classmethod
+    def initialize(cls, engine_or_url: Engine | str, pool_size: int = 10, max_overflow: int = 10, autocommit: bool = False, autoflush: bool = True, **kwargs: Any):
+        """Creates a new database engine and session.
+
+        Must provide either an engine or a database URL.
+        If a database URL is provided, the engine will be created with the specified configurations:
+            1. For SQLite, only the pool size can be specified, since the engine will use SingletonThreadPool which
+                doesn't support max_overflow.
+            2. For other databases, the pool size and max overflow can be specified.
+
+        Args:
+            engine_or_url (Engine | str): Sqlalchemy engine object or database URL.
+            pool_size (int, optional): The size of the database connections to be maintained. Defaults to 10.
+            max_overflow (int, optional): The maximum overflow size of the pool. Defaults to 10.
+                If the engine_or_url is a SQLite URL, this parameter is ignored.
+            autocommit (bool, optional): If True, all changes to the database are committed immediately.
+                Defaults to False.
+            autoflush (bool, optional): If True, all changes to the database are flushed immediately. Defaults to True.
+            **kwargs (Any): Additional keyword arguments to be passed to the SQLAlchemy create_engine function.
+                These are only used when engine_or_url is a string URL.
+        """

gllm_datastore/sql_data_store/constants.pyi

@@ -0,0 +1,6 @@
+QUERY_ERROR_MSG: str
+CREATE_ERROR_MSG: str
+READ_ERROR_MSG: str
+DELETE_ERROR_MSG: str
+UPDATE_ERROR_MSG: str
+UNEXPECTED_ERROR_MSG: str

gllm_datastore/sql_data_store/sql_data_store.pyi

@@ -0,0 +1,86 @@
+import pandas as pd
+from abc import ABC, abstractmethod
+from gllm_datastore.sql_data_store.types import QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from typing import Any
+
+class BaseSQLDataStore(ABC):
+    """Abstract base class for SQL data stores.
+
+    This class defines the interface for all SQL data store implementations.
+    Subclasses must implement the abstract methods.
+    """
+    @abstractmethod
+    async def query(self, query: str, params: dict[str, Any] | None = None) -> pd.DataFrame:
+        """Executes raw SQL query.
+
+        This method must be implemented by subclasses to execute a raw SQL query.
+        Use this method for raw queries, complex queries, or for executing a query generated by LLM.
+
+        Args:
+            query (str): The query string to execute.
+            params (dict[str, Any] | None, optional): Parameters to bind to the query. Defaults to None.
+
+        Returns:
+            pd.DataFrame: A DataFrame of query results.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def create(self, **kwargs: Any) -> None:
+        """Create data using available information in kwargs.
+
+        This method must be implemented by subclasses to create data in the data store.
+
+        Args:
+            **kwargs (Any): A dictionary of information to create data.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def read(self, filters: QueryFilter | None = None, options: QueryOptions | None = None, **kwargs: Any) -> pd.DataFrame:
+        """Read data from the data store using optional filters and options.
+
+        This method must be implemented by subclasses to read data from the data store.
+        Use this method for simple queries with filters and options.
+
+        Args:
+            filters (QueryFilter | None, optional): Filters to apply to the query. Defaults to None.
+            options (QueryOptions | None, optional): Options to apply to the query. Defaults to None.
+            **kwargs (Any): A dictionary of additional information to support the read method.
+
+        Returns:
+            pd.DataFrame: A DataFrame of query results.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def update(self, update_values: dict[str, Any], filters: QueryFilter | None = None, **kwargs: Any) -> None:
+        """Update data in the data store using optional filters and update values.
+
+        This method must be implemented by subclasses to update data in the data store.
+
+        Args:
+            update_values (dict[str, Any]): Values to update in the data store.
+            filters (QueryFilter | None, optional): Filters to apply to the query. Defaults to None.
+            **kwargs (Any): A dictionary of additional information to support the update method.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def delete(self, filters: QueryFilter | None = None, allow_delete_all: bool = False, **kwargs: Any) -> None:
+        """Delete data in the data store using filters.
+
+        This method must be implemented by subclasses to delete data in the data store.
+
+        Args:
+            filters (QueryFilter | None, optional): Filters to apply to the query. Defaults to None.
+            allow_delete_all (bool, optional): A flag to allow deleting all data. Defaults to False.
+            **kwargs (Any): A dictionary of additional information to support the delete method.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """