gllm-datastore-binary 0.5.50__cp312-cp312-macosx_13_0_arm64.whl

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/signature/webhook_signature.pyi

@@ -0,0 +1,31 @@
+def generate_webhook_signature_with_timestamp(payload: str | bytes, secret: str, timestamp: str) -> str:
+    """Generate HMAC SHA-256 signature with timestamp for webhook payload.
+
+    This function creates a signature that includes a timestamp, which helps prevent
+    replay attacks. The timestamp is prepended to the payload before signing.
+
+    Args:
+        payload (str | bytes): The webhook payload to sign.
+        secret (str): The shared secret key used for signing.
+        timestamp (str): Unix timestamp (in seconds) as a string.
+
+    Returns:
+        str: The hexadecimal representation of the HMAC SHA-256 signature.
+    """
+def verify_webhook_signature_with_timestamp(payload: str | bytes, secret: str, received_signature: str, timestamp: str, tolerance_seconds: int = 300) -> bool:
+    """Verify HMAC SHA-256 signature with timestamp for webhook payload.
+
+    This function verifies the signature and checks that the timestamp is within
+    the acceptable tolerance window. This prevents replay attacks where an attacker
+    could intercept and resend old webhook requests.
+
+    Args:
+        payload (str | bytes): The webhook payload to verify.
+        secret (str): The shared secret key used for verification.
+        received_signature (str): The signature received in the webhook request.
+        timestamp (str): The timestamp received in the webhook request.
+        tolerance_seconds (int): Maximum age of the webhook in seconds. Defaults to 300 (5 minutes).
+
+    Returns:
+        bool: True if the signature is valid and timestamp is within tolerance, False otherwise.
+    """

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.
+        """

gllm_datastore/sql_data_store/sqlalchemy_sql_data_store.pyi

@@ -0,0 +1,216 @@
+import pandas as pd
+from _typeshed import Incomplete
+from concurrent.futures import Future as Future
+from gllm_datastore.encryptor.encryptor import BaseEncryptor as BaseEncryptor
+from gllm_datastore.sql_data_store.adapter.sqlalchemy_adapter import SQLAlchemyAdapter as SQLAlchemyAdapter
+from gllm_datastore.sql_data_store.constants import CREATE_ERROR_MSG as CREATE_ERROR_MSG, DELETE_ERROR_MSG as DELETE_ERROR_MSG, QUERY_ERROR_MSG as QUERY_ERROR_MSG, READ_ERROR_MSG as READ_ERROR_MSG, UNEXPECTED_ERROR_MSG as UNEXPECTED_ERROR_MSG, UPDATE_ERROR_MSG as UPDATE_ERROR_MSG
+from gllm_datastore.sql_data_store.sql_data_store import BaseSQLDataStore as BaseSQLDataStore
+from gllm_datastore.sql_data_store.types import QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from sqlalchemy import Engine
+from sqlalchemy.orm import DeclarativeBase
+from typing import Any
+
+DEFAULT_POOL_SIZE: int
+DEFAULT_MAX_OVERFLOW: int
+DEFAULT_MAX_WORKERS: int
+DEFAULT_BATCH_SIZE: int
+
+class SQLAlchemySQLDataStore(BaseSQLDataStore):
+    """Data store for interacting with SQLAlchemy.
+
+    This class provides methods to interact with a SQL database using SQLAlchemy.
+
+    Attributes:
+        db (Session): The SQLAlchemy session object.
+        engine (Engine): The SQLAlchemy engine object.
+        logger (Logger): The logger object.
+        encryptor (BaseEncryptor | None): The encryptor object to use for encryption.
+        encrypted_table_fields (list[str]): The table.column fields to encrypt.
+    """
+    db: Incomplete
+    engine: Incomplete
+    logger: Incomplete
+    encryptor: Incomplete
+    encrypted_table_fields: Incomplete
+    def __init__(self, engine_or_url: Engine | str, pool_size: int = ..., max_overflow: int = ..., autoflush: bool = True, encryptor: BaseEncryptor | None = None, encrypted_table_fields: list[str] | None = None, **kwargs: Any) -> None:
+        '''Initialize SQLAlchemySQLDataStore class.
+
+        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.
+                This parameter is ignored for SQLite.
+            autoflush (bool, optional): If True, all changes to the database are flushed immediately. Defaults to True.
+            encryptor (BaseEncryptor | None, optional): The encryptor object to use for encryption.
+                Should comply with the BaseEncryptor interface. Defaults to None.
+            encrypted_table_fields (list[str] | None, optional): The table.column fields to encrypt.
+                Format: ["table_name.column_name", "messages.content", "users.email"].
+                Defaults to None, in which case no fields will be encrypted.
+            **kwargs (Any): Additional keyword arguments to support the initialization of the SQLAlchemy adapter.
+
+        Raises:
+            ValueError: If the database adapter is not initialized.
+        '''
+    async def query(self, query: str, params: dict[str, Any] | None = None) -> pd.DataFrame:
+        '''Executes raw SQL queries.
+
+        Preferred for complex queries, when working with legacy schemas without ORM models,
+        or when using an LLM to generate your SQL queries.
+        Use this method when you need advanced SQL operations not supported by read().
+
+        For raw queries, we can\'t determine table context automatically. Therefore, no decryption is performed.
+        Users should handle decryption manually if needed for raw queries.
+
+        Args:
+            query (str): The query string with optional :param style parameters.
+            params (dict[str, Any] | None, optional): Parameters to bind to the query. Defaults to None.
+
+        Returns:
+            pd.DataFrame: The result of the query.
+
+        Note:
+            Using string parameters directly in queries is unsafe and vulnerable to SQL injection.
+            Therefore, please avoid doing as follows as they\'re unsafe:
+            ```
+            name = "O\'Connor"
+            query = f"SELECT * FROM users WHERE last_name = \'{name}\'"
+            ```
+            or
+            ```
+            query = "SELECT * FROM users WHERE last_name = \'" + name + "\'"
+            ```
+            Instead, please use parameterized queries with :param style notation as follows:
+            ```
+            query = "SELECT * FROM users WHERE last_name = :last_name"
+            params = {"last_name": "O\'Connor"}
+            ```
+
+        Raises:
+            RuntimeError: If the query fails.
+            RuntimeError: If an unexpected error occurs.
+        '''
+    def create(self, model: DeclarativeBase | list[DeclarativeBase]) -> None:
+        '''Inserts data into the database using SQLAlchemy ORM.
+
+        This method provides a structured way to insert data using ORM models.
+
+        Args:
+            model (DeclarativeBase | list[DeclarativeBase]): An instance or list of instances of SQLAlchemy
+                model to be inserted.
+
+        Example:
+            To insert a row into a table:
+            ```
+            data_store.create(MyModel(column1="value1", column2="value2"))
+            ```
+
+            To insert multiple rows:
+            ```
+            data_store.create([
+                MyModel(column1="value1", column2="value2"),
+                MyModel(column1="value3", column2="value4")
+            ])
+            ```
+
+        Raises:
+            RuntimeError: If the insertion fails.
+            RuntimeError: If an unexpected error occurs.
+        '''
+    def read(self, model_class: type[DeclarativeBase], filters: QueryFilter | None = None, options: QueryOptions | None = None) -> pd.DataFrame:
+        '''Reads data from the database using SQLAlchemy ORM with a structured, type-safe interface.
+
+        This method provides a high-level interface for querying data using ORM models. It supports
+        filtering, column selection, ordering, and limiting results through a type-safe interface.
+
+        Args:
+            model_class (Type[DeclarativeBase]): The SQLAlchemy model class to query.
+            filters (QueryFilter | None, optional): Optional query filters containing column-value pairs
+                to filter the results. Defaults to None.
+            options (QueryOptions | None, optional): Optional query configuration including:
+                - columns: Specific columns to select
+                - order_by: Column to sort by
+                - order_desc: Sort order (ascending/descending)
+                - limit: Maximum number of results
+                Defaults to None.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing the query results.
+
+        Example:
+            ```python
+            data_store.read(
+                Message,
+                filters=QueryFilter(conditions={"conversation_id": "123"}),
+                options=QueryOptions(
+                    columns=["role", "content"],
+                    order_by="created_at",
+                    order_desc=True,
+                    limit=10
+                )
+            )
+            ```
+
+        Raises:
+            RuntimeError: If the read operation fails.
+            RuntimeError: If an unexpected error occurs.
+        '''
+    def update(self, model_class: type[DeclarativeBase], update_values: dict[str, Any], filters: QueryFilter | None = None, **kwargs: Any) -> None:
+        '''Updates data in the database using SQLAlchemy ORM.
+
+        This method provides a structured way to update data using ORM models.
+
+        Args:
+            model_class (Type[DeclarativeBase]): The SQLAlchemy model class to update.
+            update_values (dict[str, Any]): Values to update.
+            filters (QueryFilter | None, optional): Filters to apply to the query. Defaults to None.
+            **kwargs (Any): Additional keyword arguments to support the update method.
+
+        Example:
+            To update a row in a table:
+            ```
+            data_store.update(
+                MyModel,
+                update_values={"column1": "new_value"}
+                filters=QueryFilter(conditions={"id": 1}),
+            )
+            ```
+
+        Note:
+            Encrypted fields cannot be used in update conditions due to non-deterministic encryption.
+            Use non-encrypted fields (like \'id\') for update conditions.
+
+        Raises:
+            ValueError: If encrypted fields are used in update conditions.
+            RuntimeError: If the update operation fails.
+            RuntimeError: If an unexpected error occurs.
+        '''
+    def delete(self, model_class: type[DeclarativeBase], filters: QueryFilter | None = None, allow_delete_all: bool = False, **kwargs: Any) -> None:
+        '''Deletes data from the database using SQLAlchemy ORM.
+
+        This method provides a structured way to delete data using ORM models.
+
+        Args:
+            model_class (Type[DeclarativeBase]): The SQLAlchemy model class to delete.
+            filters (QueryFilter | None, optional): Filters to apply to the query. Defaults to None.
+            allow_delete_all (bool, optional): If True, allows deletion of all records. Defaults to False.
+            **kwargs (Any): Additional keyword arguments to support the delete method.
+
+        Example:
+            To delete a row from a table:
+            ```
+            data_store.delete(
+                MyModel,
+                filters=QueryFilter(conditions={"id": 1})
+            )
+            ```
+
+        Note:
+            Encrypted fields cannot be used in delete conditions due to non-deterministic encryption.
+            Use non-encrypted fields (like \'id\') for deletion conditions.
+
+        Raises:
+            ValueError: If no filters are provided (to prevent accidental deletion of all records).
+            ValueError: If encrypted fields are used in delete conditions.
+            RuntimeError: If the delete operation fails.
+            RuntimeError: If an unexpected error occurs.
+        '''