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

gllm_datastore/data_store/sql/data_store.pyi

@@ -0,0 +1,201 @@
+from _typeshed import Incomplete
+from gllm_datastore.core.filters import FilterClause as FilterClause, QueryFilter as QueryFilter
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore, CapabilityType as CapabilityType
+from gllm_datastore.data_store.sql.fulltext import SQLFulltextCapability as SQLFulltextCapability
+from gllm_datastore.data_store.sql.query_translator import SQLQueryTranslator as SQLQueryTranslator
+from gllm_datastore.data_store.sql.schema import Base as Base
+from sqlalchemy import Table as Table, URL
+from sqlalchemy.ext.asyncio import AsyncEngine
+from typing import Any
+
+class SQLDataStore(BaseDataStore):
+    '''SQL data store with multiple capability support using async SQLAlchemy.
+
+    This data store follows the "one instance = one table" pattern. Each instance
+    operates on a single table specified at construction time. To work with multiple
+    tables, create multiple instances sharing the same engine.
+
+    Attributes:
+        engine (AsyncEngine): SQLAlchemy async engine instance. Can be shared across
+            multiple SQLDataStore instances for different tables with single connection pool.
+        table_name (str): Name of the table this instance operates on. This is immutable
+            after construction and defines the scope of all operations.
+    '''
+    engine: Incomplete
+    table_name: Incomplete
+    def __init__(self, engine_or_url: AsyncEngine | str | URL, pool_size: int = 10, max_overflow: int = 10, table_name: str = 'chunks', **engine_kwargs: Any) -> None:
+        '''Initialize the SQL data store with async support.
+
+        This creates a data store instance scoped to a single table. Each instance
+        operates exclusively on the table specified by `table_name`. To work with
+        multiple tables, create multiple instances sharing the same engine.
+
+        Examples:
+            ```python
+            # Single table usage
+            datastore = SQLDataStore(
+                engine_or_url="postgresql+asyncpg://user:pass@localhost/mydb",
+                table_name="chunks"
+            )
+
+            # Multiple tables with shared engine (recommended pattern)
+            # Both stores share the same connection pool
+            engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+            chunks_store = SQLDataStore(engine, table_name="chunks")
+            users_store = SQLDataStore(engine, table_name="users")
+            ```
+
+        Args:
+            engine_or_url (AsyncEngine | str | URL): AsyncEngine instance, database URL string, or URL object.
+                For async support, async drivers are automatically added if not specified:
+                1. PostgreSQL: "postgresql://..." -> "postgresql+asyncpg://..."
+                2. MySQL: "mysql://..." -> "mysql+aiomysql://..."
+                3. SQLite: "sqlite://..." -> "sqlite+aiosqlite://..."
+                If a driver is already specified (e.g., "postgresql+asyncpg://"), it is used as-is.
+                If an AsyncEngine is provided, it can be shared across multiple SQLDataStore instances.
+            pool_size (int): The size of the database connection pool. Defaults to 10.
+                Only used when creating a new engine from a URL. Ignored if AsyncEngine is provided.
+            max_overflow (int): The maximum overflow size of the pool. Defaults to 10.
+                Only used when creating a new engine from a URL. Ignored for SQLite or if AsyncEngine is provided.
+            table_name (str): Name of the table this instance will operate on. Defaults to "chunks".
+                This defines the scope of all operations for this instance and cannot be changed after construction.
+            **engine_kwargs (Any): Additional keyword arguments for create_async_engine.
+                Only used when creating a new engine from a URL.
+
+        Raises:
+            ValueError: If the database engine initialization fails or if engine_kwargs
+                contains pool-related parameters that conflict with pool_size/max_overflow.
+        '''
+    async def initialize(self) -> None:
+        '''Initialize the datastore by creating tables.
+
+        This method must be called after instantiation to set up the database schema.
+
+        Example:
+            ```python
+            datastore = SQLDataStore(engine_or_url="sqlite+aiosqlite:///./data.db")
+            await datastore.initialize()
+            datastore.with_fulltext()
+            ```
+        '''
+    async def close(self) -> None:
+        """Close the database engine and clean up connections.
+
+        Example:
+            ```python
+            await datastore.close()
+            ```
+        """
+    @property
+    def supported_capabilities(self) -> list[CapabilityType]:
+        """Return list of currently supported capabilities.
+
+        Returns:
+            list[CapabilityType]: List of capability names that are supported.
+        """
+    @property
+    def fulltext(self) -> SQLFulltextCapability:
+        """Access fulltext capability if registered.
+
+        This method overrides the parent class to return SQLFulltextCapability for better type hinting.
+
+        Returns:
+            SQLFulltextCapability: Fulltext capability handler.
+
+        Raises:
+            NotRegisteredException: If fulltext capability is not registered.
+        """
+    def with_fulltext(self) -> SQLDataStore:
+        '''Configure fulltext capability and return datastore instance.
+
+        Examples:
+            ```python
+            # Enable fulltext
+            datastore.with_fulltext()
+
+            # For multiple tables with shared engine
+            engine = create_async_engine("postgresql+asyncpg://...")
+            chunks_store = SQLDataStore(engine, table_name="chunks")
+            users_store = SQLDataStore(engine, table_name="users")
+            chunks_store.with_fulltext()
+            users_store.with_fulltext()
+            ```
+
+        Returns:
+            SQLDataStore: Self for method chaining.
+        '''
+    @classmethod
+    def translate_query_filter(cls, query_filter: FilterClause | QueryFilter | None = None, table_name: str = 'chunks', engine_or_url: AsyncEngine | str | URL | None = None) -> str | None:
+        '''Translate QueryFilter or FilterClause to SQL WHERE clause string.
+
+        This method delegates to the SQLQueryTranslator and returns the result as a
+        SQL WHERE clause string that can be used in SQL queries. The table structure
+        is reflected from the database using the provided engine_or_url and table_name.
+
+        Examples:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # With database URL string
+            clause = F.eq("id", "test")
+            result = SQLDataStore.translate_query_filter(
+                clause,
+                table_name="chunks",
+                engine_or_url="postgresql://user:pass@localhost/mydb"
+            )
+            # Returns: "chunks.id = \'test\'"
+
+            # With AsyncEngine instance
+            from sqlalchemy.ext.asyncio import create_async_engine
+            engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+            filter_obj = F.and_(
+                F.eq("id", "test"),
+                F.gt("chunk_metadata.age", 25),
+            )
+            result = SQLDataStore.translate_query_filter(
+                filter_obj,
+                table_name="chunks",
+                engine_or_url=engine
+            )
+            # Returns: "(chunks.id = \'test\' AND json_extract(chunks.chunk_metadata, \'$.age\') > 25)"
+
+            # QueryFilter with OR condition
+            filter_obj = F.or_(
+                F.eq("id", "test1"),
+                F.eq("id", "test2"),
+            )
+            result = SQLDataStore.translate_query_filter(
+                filter_obj,
+                table_name="chunks",
+                engine_or_url="sqlite:///./data.db"
+            )
+            # Returns: "(chunks.id = \'test1\' OR chunks.id = \'test2\')"
+
+            # Empty filter returns None
+            result = SQLDataStore.translate_query_filter(
+                None,
+                table_name="chunks",
+                engine_or_url="postgresql://user:pass@localhost/mydb"
+            )
+            # Returns: None
+            ```
+
+        Args:
+            query_filter (FilterClause | QueryFilter): The filter to translate.
+                Can be a single FilterClause or a QueryFilter with multiple clauses.
+            table_name (str): Name of the table to reflect from the database. Defaults to "chunks".
+            engine_or_url (AsyncEngine | str | URL | None): AsyncEngine instance, database URL string,
+                or URL object for table reflection. Required. The table structure is reflected from the database.
+                For async support, async drivers are automatically added if not specified:
+                PostgreSQL -> postgresql+asyncpg://, MySQL -> mysql+aiomysql://,
+                SQLite -> sqlite+aiosqlite://.
+
+        Raises:
+            ValueError: If engine_or_url is None.
+
+        Returns:
+            str: The translated filter as a SQL WHERE clause string.
+
+        Raises:
+            RuntimeError: If table reflection fails or table is not found in database.
+        '''

gllm_datastore/data_store/sql/fulltext.pyi

@@ -0,0 +1,164 @@
+from _typeshed import Incomplete
+from gllm_core.schema.chunk import Chunk
+from gllm_datastore.core.filters import FilterClause as FilterClause, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from gllm_datastore.data_store.sql.query import execute_delete_with_filters as execute_delete_with_filters, execute_update_with_filters as execute_update_with_filters, row_to_chunk as row_to_chunk
+from gllm_datastore.data_store.sql.query_translator import SQLQueryTranslator as SQLQueryTranslator
+from gllm_datastore.data_store.sql.schema import ChunkModel as ChunkModel
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlalchemy.orm import DeclarativeBase
+from typing import Any
+
+class SQLFulltextCapability:
+    """SQL implementation of FulltextCapability protocol using async SQLAlchemy.
+
+    This capability creates its own session factory from the engine, making it
+    self-contained and independent of the data store's session configuration.
+
+    Attributes:
+        engine (AsyncEngine): SQLAlchemy async engine instance.
+        session_factory (async_sessionmaker): Async session factory created from engine.
+        table_name (str): Name of the table this capability operates on. This is immutable
+            and defines the scope of all operations.
+        _table (Table | None): Cached SQLAlchemy Table object. Initialized lazily on first use.
+        _metadata (MetaData): SQLAlchemy metadata instance for table reflection.
+    """
+    engine: Incomplete
+    table_name: Incomplete
+    session_factory: Incomplete
+    def __init__(self, engine: AsyncEngine, table_name: str) -> None:
+        """Initialize the SQL fulltext capability with async support.
+
+        Args:
+            engine (AsyncEngine): SQLAlchemy async engine instance.
+            table_name (str): Name of the table this capability will operate on.
+                This defines the scope of all operations and cannot be changed after initialization.
+        """
+    async def create(self, data: Chunk | list[Chunk] | DeclarativeBase | list[DeclarativeBase]) -> None:
+        '''Create new records in the datastore.
+
+        This method accepts both Chunk and DeclarativeBase instances.
+        1. If data is a Chunk, it will be converted to a ChunkModel instance with flattened metadata.
+        2. If data is a DeclarativeBase, it will be added directly to the database.
+
+        Examples:
+            1. Create a single record using a Chunk.
+            ```python
+            # Create a single chunk
+            chunk = Chunk(id="1", content="Test content", metadata={"source": "test"})
+            await datastore.fulltext.create(chunk)
+
+            # Bulk create
+            chunks = [
+                Chunk(id=str(i), content=f"Test content {i}", metadata={"source": "test"})
+                for i in range(10)
+            ]
+            await datastore.fulltext.create(chunks)
+            ```
+
+            2. Create a single record using a declarative base model.
+            ```python
+            # Create a single user
+            user = UserModel(id="1", name="John", email="john@example.com")
+            await datastore.fulltext.create(user)
+
+            # Bulk create
+            users = [UserModel(id=str(i), name=f"User{i}") for i in range(10)]
+            await datastore.fulltext.create(users)
+            ```
+
+        Args:
+            data (Chunk | list[Chunk] | DeclarativeBase | list[DeclarativeBase]):
+                Data to create (single item or collection). Chunk instances will be converted
+                to ChunkModel. DeclarativeBase instances will be added directly to the database.
+
+        Raises:
+            RuntimeError: If the creation fails.
+        '''
+    async def retrieve(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+        '''Read records from the datastore with optional filtering.
+
+        This method operates on this capability\'s table (specified at initialization).
+        It returns Chunk objects matching the filters and options.
+
+        Examples:
+            ```python
+            # Retrieve all records from the instance\'s table
+            chunks = await datastore.fulltext.retrieve()
+
+            # Retrieve with filters
+            chunks = await datastore.fulltext.retrieve(
+                filters=F.eq("status", "active")
+            )
+
+            # Retrieve with options (using CHUNK_KEYS.ID for column name)
+            chunks = await datastore.fulltext.retrieve(
+                options=QueryOptions(order_by=CHUNK_KEYS.ID, order_desc=True, limit=10)
+            )
+            ```
+
+        Args:
+            filters (FilterClause | QueryFilter | None, optional): Query filters to apply.
+                Defaults to None.
+            options (QueryOptions | None, optional): Query options for sorting and pagination.
+                Defaults to None.
+
+        Returns:
+            list[Chunk]: List of Chunk objects from this capability\'s table.
+
+        Raises:
+            RuntimeError: If the read operation fails.
+        '''
+    async def update(self, update_values: dict[str, Any], filters: FilterClause | QueryFilter | None = None) -> None:
+        '''Update existing records in the datastore.
+
+        This method operates on this capability\'s table (specified at initialization).
+        Updates records matching the filters with the provided values.
+
+        Examples:
+            ```python
+            # Update all records (no filters)
+            await datastore.fulltext.update(
+                {"status": "active"}
+            )
+
+            # Update with filters (using CHUNK_KEYS constants)
+            await datastore.fulltext.update(
+                {CHUNK_KEYS.CONTENT: "Updated content"},
+                filters=F.eq(CHUNK_KEYS.ID, "chunk_123")
+            )
+            ```
+
+        Args:
+            update_values (dict[str, Any]): Mapping of fields to new values to apply.
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to update.
+                Defaults to None. If None, no records will be updated (safety measure).
+
+        Raises:
+            RuntimeError: If the update operation fails.
+        '''
+    async def delete(self, filters: FilterClause | QueryFilter | None = None) -> None:
+        '''Delete records from the datastore.
+
+        This method operates on this capability\'s table (specified at initialization).
+        Deletes records matching the provided filters.
+
+        Examples:
+            ```python
+            # Delete with filters (using CHUNK_KEYS.ID)
+            await datastore.fulltext.delete(
+                filters=F.eq(CHUNK_KEYS.ID, "chunk_123")
+            )
+
+            # Delete multiple records
+            await datastore.fulltext.delete(
+                filters=F.in_("status", ["deleted", "archived"])
+            )
+            ```
+
+        Args:
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to delete.
+                Defaults to None. If None, no records will be deleted (safety measure).
+
+        Raises:
+            RuntimeError: If the delete operation fails.
+        '''

gllm_datastore/data_store/sql/query.pyi

@@ -0,0 +1,81 @@
+from gllm_core.schema.chunk import Chunk
+from gllm_datastore.core.filters import QueryFilter as QueryFilter
+from gllm_datastore.data_store.sql.constants import SQL_COLUMNS as SQL_COLUMNS
+from gllm_datastore.data_store.sql.query_translator import SQLQueryTranslator as SQLQueryTranslator
+from sqlalchemy import Table
+from sqlalchemy.engine import Row
+from sqlalchemy.ext.asyncio import AsyncSession
+from typing import Any
+
+def row_to_chunk(row: Row) -> Chunk:
+    """Convert a database row to a Chunk object.
+
+    Args:
+        row (Row): Database row with _mapping attribute.
+
+    Returns:
+        Chunk: Chunk object created from the row data.
+    """
+async def execute_select(session: AsyncSession, table: Table, filters: QueryFilter | None) -> list[Row]:
+    """Execute a select query on a table with filters.
+
+    Args:
+        session (AsyncSession): Database session.
+        table (Table): SQLAlchemy table.
+        filters (QueryFilter | None): Query filters.
+
+    Returns:
+        list[Row]: List of result rows.
+    """
+async def execute_update(session: AsyncSession, table: Table, update_values: dict[str, Any], rows: list[Row]) -> None:
+    """Execute update operations on table rows.
+
+    Args:
+        session (AsyncSession): Database session.
+        table (Table): SQLAlchemy table.
+        update_values (dict[str, Any]): Values to update.
+        rows (list[Row]): Rows to update.
+
+    Raises:
+        ValueError: If table has no primary key.
+    """
+async def execute_delete(session: AsyncSession, table: Table, rows: list[Row]) -> None:
+    """Execute delete operations on table rows.
+
+    Args:
+        session (AsyncSession): Database session.
+        table (Table): SQLAlchemy table.
+        rows (list[Row]): Rows to delete.
+
+    Raises:
+        ValueError: If table has no primary key.
+    """
+async def execute_update_with_filters(session: AsyncSession, table: Table, update_values: dict[str, Any], filters: QueryFilter | None) -> None:
+    """Execute update operations using filters directly.
+
+    This function constructs a single atomic UPDATE statement with WHERE conditions
+    derived from the filters, avoiding the need to fetch rows first.
+
+    Args:
+        session (AsyncSession): Database session.
+        table (Table): SQLAlchemy table.
+        update_values (dict[str, Any]): Values to update.
+        filters (QueryFilter | None): Query filters to apply as WHERE conditions.
+
+    Returns:
+        None: No return value.
+    """
+async def execute_delete_with_filters(session: AsyncSession, table: Table, filters: QueryFilter | None) -> None:
+    """Execute delete operations using filters directly.
+
+    This function constructs a single atomic DELETE statement with WHERE conditions
+    derived from the filters, avoiding the need to fetch rows first.
+
+    Args:
+        session (AsyncSession): Database session.
+        table (Table): SQLAlchemy table.
+        filters (QueryFilter | None): Query filters to apply as WHERE conditions.
+
+    Returns:
+        None: No return value.
+    """

gllm_datastore/data_store/sql/query_translator.pyi

@@ -0,0 +1,51 @@
+from _typeshed import Incomplete
+from gllm_datastore.core.filters import FilterClause as FilterClause, FilterCondition as FilterCondition, FilterOperator as FilterOperator, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from sqlalchemy import Select, Table
+from sqlalchemy.sql.expression import ColumnElement
+
+class SQLQueryTranslator:
+    """Translates QueryFilter and FilterClause objects to SQLAlchemy ColumnElement expressions.
+
+    This class encapsulates all query translation logic for SQL data stores.
+    It works with reflected Table objects (not DeclarativeBase models) and supports
+    both direct column access and JSON field paths.
+    """
+    table: Incomplete
+    def __init__(self, table: Table) -> None:
+        """Initialize the SQL query translator.
+
+        Args:
+            table (Table): SQLAlchemy Table object for column resolution.
+        """
+    def translate(self, filters: QueryFilter | None) -> ColumnElement | None:
+        """Translate a structured QueryFilter into a SQLAlchemy ColumnElement expression.
+
+        This is the main entry point for filter translation. It handles None filters
+        and delegates to internal translation methods.
+
+        Args:
+            filters (QueryFilter | None): Structured QueryFilter to translate. Defaults to None.
+
+        Returns:
+            ColumnElement | None: A SQLAlchemy condition expression or None if no filters are provided.
+        """
+    def apply_filters(self, query: Select, filters: QueryFilter | None) -> Select:
+        """Apply filters to a SQLAlchemy Select query.
+
+        Args:
+            query (Select): SQLAlchemy Select query.
+            filters (QueryFilter | None): Query filters to apply. Defaults to None.
+
+        Returns:
+            Select: Query with filters applied.
+        """
+    def apply_options(self, query: Select, options: QueryOptions | None) -> Select:
+        """Apply query options to a SQLAlchemy Select query.
+
+        Args:
+            query (Select): SQLAlchemy Select query.
+            options (QueryOptions | None): Query options to apply. Defaults to None.
+
+        Returns:
+            Select: Query with options applied.
+        """

gllm_datastore/data_store/sql/schema.pyi

@@ -0,0 +1,16 @@
+from _typeshed import Incomplete
+
+Base: Incomplete
+
+class ChunkModel(Base):
+    """SQLAlchemy model for the chunk table.
+
+    Attributes:
+        id (Column): The ID of the chunk.
+        content (Column): The content of the chunk.
+        chunk_metadata (Column): The metadata of the chunk stored as JSON.
+    """
+    __tablename__: str
+    id: Incomplete
+    content: Incomplete
+    chunk_metadata: Incomplete

gllm_datastore/encryptor/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_datastore.encryptor.aes_gcm_encryptor import AESGCMEncryptor as AESGCMEncryptor
+from gllm_datastore.encryptor.key_rotating_encryptor import KeyRotatingEncryptor as KeyRotatingEncryptor
+
+__all__ = ['AESGCMEncryptor', 'KeyRotatingEncryptor']

gllm_datastore/encryptor/aes_gcm_encryptor.pyi

@@ -0,0 +1,45 @@
+from _typeshed import Incomplete
+from gllm_datastore.encryptor.encryptor import BaseEncryptor as BaseEncryptor
+
+KEY_LENGTH_BYTES: int
+NONCE_LENGTH_BYTES: int
+
+class AESGCMEncryptor(BaseEncryptor):
+    """AES-GCM 256 Encryptor that accepts keys directly.
+
+    This class provides AES-GCM symmetric encryption and decryption methods
+    with a 256-bit key provided directly by the client.
+
+    Attributes:
+        key (bytes): 256-bit encryption key.
+        aesgcm (AESGCM): AES-GCM instance.
+    """
+    key: Incomplete
+    aesgcm: Incomplete
+    def __init__(self, key: bytes) -> None:
+        """Initialize AESGCMEncryptor with a direct key.
+
+        Args:
+            key (bytes): 256-bit encryption key.
+
+        Raises:
+            ValueError: If key length is not 256 bits.
+        """
+    def encrypt(self, plaintext: str) -> str:
+        """Encrypts the plaintext using AES-GCM with a random nonce.
+
+        Args:
+            plaintext (str): The plaintext data to be encrypted.
+
+        Returns:
+            str: The encrypted data, encoded in base64 format.
+        """
+    def decrypt(self, ciphertext: str) -> str:
+        """Decrypts the AES-GCM ciphertext.
+
+        Args:
+            ciphertext (str): The ciphertext in base64 format to be decrypted.
+
+        Returns:
+            str: The decrypted plaintext data.
+        """

gllm_datastore/encryptor/capability/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_datastore.encryptor.capability.mixin import EncryptionCapabilityMixin as EncryptionCapabilityMixin
+
+__all__ = ['EncryptionCapabilityMixin']

gllm_datastore/encryptor/capability/mixin.pyi

@@ -0,0 +1,32 @@
+from _typeshed import Incomplete
+from gllm_datastore.constants import CHUNK_KEYS as CHUNK_KEYS
+from gllm_datastore.encryptor.encryptor import BaseEncryptor as BaseEncryptor
+
+class EncryptionCapabilityMixin:
+    """Mixin implementation of EncryptionCapability with common encryption logic.
+
+    This class provides the shared encryption and decryption logic that is identical
+    across all backend implementations. Backend-specific encryption capabilities
+    should inherit from this class and add backend-specific initialization.
+
+    Attributes:
+        encryptor (BaseEncryptor): The encryptor instance to use for encryption/decryption.
+    """
+    encryptor: Incomplete
+    def __init__(self, encryptor: BaseEncryptor, encrypted_fields: set[str]) -> None:
+        '''Initialize the encryption capability mixin.
+
+        Args:
+            encryptor (BaseEncryptor): The encryptor instance to use for encryption.
+            encrypted_fields (set[str]): The set of fields to encrypt. Supports:
+                1. Content field: "content"
+                2. Metadata fields using dot notation: "metadata.secret_key", "metadata.secret_value"
+                Example: `{"content", "metadata.secret_key", "metadata.secret_value"}`
+        '''
+    @property
+    def encryption_config(self) -> set[str] | None:
+        """Get the current encryption configuration.
+
+        Returns:
+            set[str] | None: Set of encrypted field names.
+        """

gllm_datastore/encryptor/encryptor.pyi

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+class BaseEncryptor(ABC):
+    """Abstract base class defining the interface for encryption implementations.
+
+    This abstract base class ensures that all encryptors implement the required
+    encrypt and decrypt methods with consistent signatures.
+
+    Thread-safety requirement:
+        Implementations MUST be thread-safe. The client may
+        invoke `encrypt` and `decrypt` concurrently from multiple threads, so
+        any internal state (e.g., buffers, nonces, cipher instances) must be
+        protected or designed to avoid race conditions.
+    """
+    @abstractmethod
+    def encrypt(self, plaintext: str) -> str:
+        """Encrypt plain text into cipher text.
+
+        This method should be implemented by subclasses to provide the encryption functionality.
+
+        Note:
+            The implementation must be thread-safe and must not mutate shared state
+            without proper synchronization.
+
+        Args:
+            plaintext (str): The raw plain text to encrypt.
+
+        Returns:
+            str: The encrypted cipher text.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """
+    @abstractmethod
+    def decrypt(self, ciphertext: str) -> str:
+        """Decrypt cipher text back into plain text.
+
+        This method should be implemented by subclasses to provide the decryption functionality.
+
+        Note:
+            The implementation must be thread-safe and must not mutate shared state
+            without proper synchronization.
+
+        Args:
+            ciphertext (str): The ciphertext to decrypt.
+
+        Returns:
+            str: The decrypted plain text.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """

gllm_datastore/encryptor/key_ring/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_datastore.encryptor.key_ring.in_memory_key_ring import InMemoryKeyRing as InMemoryKeyRing
+
+__all__ = ['InMemoryKeyRing']