vention-storage 0.6.0__py3-none-any.whl → 0.6.3__py3-none-any.whl

storage/accessor.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from contextlib import contextmanager
+from functools import reduce
 from typing import (
     Any,
     Callable,
@@ -15,6 +16,7 @@ from typing import (
 )
 
 from sqlmodel import SQLModel, Session, select
+from sqlmodel.sql.expression import SelectOfScalar
 
 from storage.auditor import audit_operation
 from storage import database
@@ -25,6 +27,48 @@ from storage.utils import ModelType, utcnow, Operation
 WriteResult = TypeVar("WriteResult")
 
 
+def _apply_conditions(statement: SelectOfScalar[ModelType], conditions: tuple[Any, ...]) -> SelectOfScalar[ModelType]:
+    """Apply filter conditions to a select statement."""
+    return reduce(lambda stmt, cond: stmt.where(cond), conditions, statement)
+
+
+def _apply_soft_delete_filter(
+    statement: SelectOfScalar[ModelType],
+    model: Type[ModelType],
+    has_soft_delete: bool,
+    include_deleted: bool,
+) -> SelectOfScalar[ModelType]:
+    """Apply soft delete filter if applicable."""
+    if not has_soft_delete or include_deleted:
+        return statement
+    return statement.where(getattr(model, "deleted_at").is_(None))
+
+
+def _apply_ordering(
+    statement: SelectOfScalar[ModelType],
+    model: Type[ModelType],
+    order_by: Optional[str],
+    order_desc: bool,
+) -> SelectOfScalar[ModelType]:
+    """Apply ordering to a select statement."""
+    if not order_by:
+        return statement
+    field = getattr(model, order_by, None)
+    if field is None:
+        raise ValueError(f"Field '{order_by}' not found on {model.__name__}")
+    return statement.order_by(field.desc() if order_desc else field)
+
+
+def _apply_pagination(
+    statement: SelectOfScalar[ModelType],
+    limit: Optional[int],
+    offset: int,
+) -> SelectOfScalar[ModelType]:
+    """Apply pagination to a select statement."""
+    limited = statement.limit(limit) if limit is not None else statement
+    return limited.offset(offset) if offset > 0 else limited
+
+
 class ModelAccessor(Generic[ModelType]):
     """
     Accessor for a single SQLModel type with:
@@ -47,6 +91,8 @@ class ModelAccessor(Generic[ModelType]):
         self._hooks: HookRegistry[ModelType] = HookRegistry()
         self._has_soft_delete = hasattr(model, "deleted_at")
         self._enable_auditing = enable_auditing
+        # Field proxy for type-safe filtering: accessor.where.field_name
+        self.where = model
 
     # ---------- Hook decorators ----------
     def before_insert(self) -> Callable[[HookFn[ModelType]], HookFn[ModelType]]:
@@ -73,9 +119,7 @@ class ModelAccessor(Generic[ModelType]):
         with database.use_session(session):
             self._hooks.emit(event, session=session, instance=instance)
 
-    def _audit_create_operation(
-        self, *, session: Session, instance: ModelType, actor: str
-    ) -> None:
+    def _audit_create_operation(self, *, session: Session, instance: ModelType, actor: str) -> None:
         """Audit a create operation."""
         if not self._enable_auditing:
             return
@@ -90,7 +134,7 @@ class ModelAccessor(Generic[ModelType]):
         )
 
     def _run_write(self, fn: Callable[[Session], WriteResult]) -> WriteResult:
-        """Run a write op using the current session if present, else open a transaction."""
+        """Run a write operation using the current session if present, else open a transaction."""
         existing = database.CURRENT_SESSION.get()
         if existing is not None:
             return fn(existing)
@@ -119,12 +163,83 @@ class ModelAccessor(Generic[ModelType]):
                     return None
             return cast(ModelType, obj)
 
-    def all(self, *, include_deleted: bool = False) -> List[ModelType]:
-        """Get all models."""
+    def all(
+        self,
+        *,
+        include_deleted: bool = False,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        order_by: Optional[str] = None,
+        order_desc: bool = False,
+    ) -> List[ModelType]:
+        """Get all models with optional pagination and sorting.
+
+        Args:
+            include_deleted: Whether to include soft-deleted records
+            limit: Maximum number of records to return (None = no limit)
+            offset: Number of records to skip (for pagination)
+            order_by: Field name to sort by (must exist on model)
+            order_desc: If True, sort descending; otherwise ascending
+
+        Returns:
+            List of model instances
+
+        Raises:
+            ValueError: If order_by field doesn't exist on the model
+        """
         with self._read_session() as session:
             statement = select(self.model)
-            if self._has_soft_delete and not include_deleted:
-                statement = statement.where(getattr(self.model, "deleted_at").is_(None))
+            statement = _apply_soft_delete_filter(statement, self.model, self._has_soft_delete, include_deleted)
+            statement = _apply_ordering(statement, self.model, order_by, order_desc)
+            statement = _apply_pagination(statement, limit, offset)
+
+            return cast(List[ModelType], session.exec(statement).all())
+
+    def find(
+        self,
+        *conditions: Any,
+        include_deleted: bool = False,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        order_by: Optional[str] = None,
+        order_desc: bool = False,
+    ) -> List[ModelType]:
+        """Find records matching all given filter conditions.
+
+        Args:
+            *conditions: SQLAlchemy filter conditions using accessor.where.field_name
+            include_deleted: Whether to include soft-deleted records
+            limit: Maximum number of records to return (None = no limit)
+            offset: Number of records to skip (for pagination)
+            order_by: Field name to sort by (must exist on model)
+            order_desc: If True, sort descending; otherwise ascending
+
+        Returns:
+            List of model instances matching all conditions
+
+        Example:
+            # Find active users over 18
+            users = user_accessor.find(
+                user_accessor.where.age >= 18,
+                user_accessor.where.status == "active",
+                limit=10
+            )
+
+            # String operations
+            users = user_accessor.find(
+                user_accessor.where.name.contains("Smith")
+            )
+
+        Raises:
+            ValueError: If order_by field doesn't exist on the model
+        """
+        with self._read_session() as session:
+            statement = select(self.model)
+            statement = _apply_conditions(statement, conditions)
+            statement = _apply_soft_delete_filter(statement, self.model, self._has_soft_delete, include_deleted)
+            statement = _apply_ordering(statement, self.model, order_by, order_desc)
+            statement = _apply_pagination(statement, limit, offset)
+
             return cast(List[ModelType], session.exec(statement).all())
 
     # ---------- Writes ----------
@@ -227,9 +342,7 @@ class ModelAccessor(Generic[ModelType]):
         return self._run_write(write_operation)
 
     # ---------- Batch helpers ----------
-    def insert_many(
-        self, objs: Sequence[ModelType], *, actor: str = "internal"
-    ) -> List[ModelType]:
+    def insert_many(self, objs: Sequence[ModelType], *, actor: str = "internal") -> List[ModelType]:
         """Insert multiple models."""
 
         def write_operation(session: Session) -> List[ModelType]:
@@ -257,9 +370,7 @@ class ModelAccessor(Generic[ModelType]):
                 if obj is None:
                     continue
                 self._emit("before_delete", session=session, instance=obj)
-                op_name, before_payload, after_payload = _soft_or_hard_delete(
-                    session, obj
-                )
+                op_name, before_payload, after_payload = _soft_or_hard_delete(session, obj)
                 if self._enable_auditing:
                     audit_operation(
                         session=session,
@@ -277,9 +388,7 @@ class ModelAccessor(Generic[ModelType]):
         return self._run_write(write_operation)
 
 
-def _soft_or_hard_delete(
-    session: Session, instance: SQLModel
-) -> tuple[Operation, dict[str, Any], dict[str, Any] | None]:
+def _soft_or_hard_delete(session: Session, instance: SQLModel) -> tuple[Operation, dict[str, Any], dict[str, Any] | None]:
     """Soft delete if model defines `deleted_at`, else hard delete."""
     before_payload = instance.model_dump()
     if hasattr(instance, "deleted_at"):

storage/crud_service.py

@@ -1,12 +1,87 @@
 from __future__ import annotations
-from typing import Any, Dict, List, Optional
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, TypedDict, Union
 
 from sqlalchemy.exc import DataError, IntegrityError, StatementError
 from storage.accessor import ModelAccessor
 from storage.utils import ModelType
 
 
-__all__ = ["CrudService", "CrudError"]
+__all__ = ["CrudService", "CrudError", "FilterOperation", "Filter"]
+
+
+# ---------------------------------------------------------
+# Filter Types
+# ---------------------------------------------------------
+
+
+class FilterOperation(str, Enum):
+    """
+    Supported filter operations for find_records queries.
+
+    Comparison operators:
+        EQUALS: Equal (field == value)
+        NOT_EQUALS: Not equal (field != value)
+        GREATER_THAN: Greater than (field > value)
+        GREATER_THAN_OR_EQUALS: Greater than or equal (field >= value)
+        LESS_THAN: Less than (field < value)
+        LESS_THAN_OR_EQUALS: Less than or equal (field <= value)
+
+    Collection operators:
+        IN: Value in list (field IN [values])
+        NOT_IN: Value not in list (field NOT IN [values])
+
+    String operators:
+        CONTAINS: Field contains substring
+        STARTS_WITH: Field starts with prefix
+        ENDS_WITH: Field ends with suffix
+        LIKE: Case-insensitive pattern match (SQL ILIKE)
+
+    Null checks:
+        IS_NULL: Field is None
+        IS_NOT_NULL: Field is not None
+    """
+
+    # Comparison operators
+    EQUALS = "eq"
+    NOT_EQUALS = "ne"
+    GREATER_THAN = "gt"
+    GREATER_THAN_OR_EQUALS = "gte"
+    LESS_THAN = "lt"
+    LESS_THAN_OR_EQUALS = "lte"
+
+    # Collection operators
+    IN = "in"
+    NOT_IN = "not_in"
+
+    # String operators
+    CONTAINS = "contains"
+    STARTS_WITH = "startswith"
+    ENDS_WITH = "endswith"
+    LIKE = "like"
+
+    # Null checks
+    IS_NULL = "is_null"
+    IS_NOT_NULL = "is_not_null"
+
+
+class _FilterRequired(TypedDict):
+    """Required keys for Filter."""
+
+    field: str
+    operation: Union[FilterOperation, str]
+
+
+class Filter(_FilterRequired, total=False):
+    """Type definition for filter dictionaries used in find_records.
+
+    Attributes:
+        field: The name of the model field to filter on (required)
+        operation: The filter operation to apply - use FilterOperation enum for autocompletion (required)
+        value: The value to compare against (optional for IS_NULL/IS_NOT_NULL)
+    """
+
+    value: Any
 
 
 # ---------------------------------------------------------
@@ -55,6 +130,23 @@ class CrudService:
     by both FastAPI routers (REST) and RPC bundles (ConnectRPC).
     """
 
+    _FILTER_OPERATIONS: Dict[FilterOperation, Callable[[Any, Any], Any]] = {
+        FilterOperation.EQUALS: lambda field, value: field == value,
+        FilterOperation.NOT_EQUALS: lambda field, value: field != value,
+        FilterOperation.GREATER_THAN: lambda field, value: field > value,
+        FilterOperation.GREATER_THAN_OR_EQUALS: lambda field, value: field >= value,
+        FilterOperation.LESS_THAN: lambda field, value: field < value,
+        FilterOperation.LESS_THAN_OR_EQUALS: lambda field, value: field <= value,
+        FilterOperation.IN: lambda field, value: field.in_(value),
+        FilterOperation.NOT_IN: lambda field, value: field.notin_(value),
+        FilterOperation.CONTAINS: lambda field, value: field.contains(value),
+        FilterOperation.STARTS_WITH: lambda field, value: field.startswith(value),
+        FilterOperation.ENDS_WITH: lambda field, value: field.endswith(value),
+        FilterOperation.LIKE: lambda field, value: field.ilike(value),
+        FilterOperation.IS_NULL: lambda field, _: field.is_(None),
+        FilterOperation.IS_NOT_NULL: lambda field, _: field.isnot(None),
+    }
+
     def __init__(
         self,
         accessor: ModelAccessor[ModelType],
@@ -66,32 +158,146 @@ class CrudService:
 
     # ---------------- READS ----------------
 
-    def list_records(self, *, include_deleted: bool = False) -> List[ModelType]:
-        """Return all records for this model."""
-        return self.accessor.all(include_deleted=include_deleted)
+    def list_records(
+        self,
+        *,
+        include_deleted: bool = False,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        order_by: Optional[str] = None,
+        order_desc: bool = False,
+    ) -> List[ModelType]:
+        """Return records with optional pagination and sorting.
+
+        Args:
+            include_deleted: Whether to include soft-deleted records
+            limit: Maximum number of records to return (None = no limit)
+            offset: Number of records to skip (for pagination)
+            order_by: Field name to sort by (must exist on model)
+            order_desc: If True, sort descending; otherwise ascending
+
+        Returns:
+            List of model instances
+
+        Raises:
+            ValidationError: If order_by field doesn't exist on the model
+        """
+        try:
+            return self.accessor.all(
+                include_deleted=include_deleted,
+                limit=limit,
+                offset=offset,
+                order_by=order_by,
+                order_desc=order_desc,
+            )
+        except ValueError as e:
+            raise ValidationError(str(e)) from e
 
     def get_record(
         self,
         record_id: int,
         *,
         include_deleted: bool = False,
-    ) -> ModelType:  # type: ignore[type-var]
+    ) -> ModelType:  # type: ignore[type-var,misc]
         """Retrieve a single record by ID."""
         obj = self.accessor.get(record_id, include_deleted=include_deleted)
         if not obj:
             raise NotFoundError()
         return obj
 
+    def find_records(
+        self,
+        filters: List[Filter],
+        *,
+        include_deleted: bool = False,
+        limit: Optional[int] = None,
+        offset: int = 0,
+        order_by: Optional[str] = None,
+        order_desc: bool = False,
+    ) -> List[ModelType]:
+        """Find records matching filter conditions.
+
+        Args:
+            filters: List of Filter dicts with 'field', 'operation' (use FilterOperation enum), and 'value' keys
+            include_deleted: Whether to include soft-deleted records
+            limit: Maximum number of records to return (None = no limit)
+            offset: Number of records to skip (for pagination)
+            order_by: Field name to sort by (must exist on model)
+            order_desc: If True, sort descending; otherwise ascending
+
+        Returns:
+            List of model instances matching all conditions
+
+        Raises:
+            ValidationError: If filter is invalid or field doesn't exist
+
+        Example:
+            >>> filters = [
+            ...     {"field": "name", "operation": FilterOperation.LIKE, "value": "alice%"},
+            ...     {"field": "age", "operation": FilterOperation.GREATER_THAN_OR_EQUALS, "value": 18},
+            ... ]
+            >>> results = crud.find_records(filters)
+        """
+        try:
+            conditions = []
+            for filter_dict in filters:
+                field_name = filter_dict["field"]
+                operation = filter_dict["operation"]
+                value = filter_dict.get("value")
+
+                field = getattr(self.accessor.where, field_name, None)
+                if field is None:
+                    raise ValidationError(f"Field '{field_name}' not found on {self.accessor.model.__name__}")
+
+                condition = self._apply_filter_operation(field, operation, value)
+                conditions.append(condition)
+
+            return self.accessor.find(
+                *conditions,
+                include_deleted=include_deleted,
+                limit=limit,
+                offset=offset,
+                order_by=order_by,
+                order_desc=order_desc,
+            )
+        except (ValueError, KeyError, AttributeError) as e:
+            raise ValidationError(str(e)) from e
+
+    def _apply_filter_operation(self, field: Any, operation: Union[FilterOperation, str], value: Any) -> Any:
+        """Apply a filter operation to a field.
+
+        Args:
+            field: SQLAlchemy field/column
+            operation: Operation (use FilterOperation enum for type safety)
+            value: Value to compare against
+
+        Returns:
+            SQLAlchemy BinaryExpression representing the condition
+
+        Raises:
+            ValidationError: If operation is not supported
+        """
+        # Normalize string to enum if needed
+        try:
+            operation_enum = FilterOperation(operation) if isinstance(operation, str) else operation
+        except ValueError:
+            supported = ", ".join(filter_operation.value for filter_operation in FilterOperation)
+            raise ValidationError(f"Unsupported filter operation '{operation}'. Supported: {supported}")
+
+        operation_fn = self._FILTER_OPERATIONS[operation_enum]
+        try:
+            return operation_fn(field, value)
+        except (TypeError, AttributeError) as error:
+            raise ValidationError(f"Failed to apply '{operation}' operation: {str(error)}") from error
+
     # ---------------- WRITES ----------------
 
-    def create_record(self, payload: Dict[str, Any], actor: str) -> ModelType:  # type: ignore[type-var]
+    def create_record(self, payload: Dict[str, Any], actor: str) -> ModelType:  # type: ignore[type-var,misc]
         """Insert a new record into the database."""
         if self.max_records is not None:
             total = len(self.accessor.all(include_deleted=True))
             if total >= self.max_records:
-                raise ConflictError(
-                    f"Max {self.max_records} records allowed for {self.accessor.component}"
-                )
+                raise ConflictError(f"Max {self.max_records} records allowed for {self.accessor.component}")
 
         obj = self.accessor.model(**payload)
         try:
@@ -105,16 +311,14 @@ class CrudService:
         record_id: int,
         payload: Dict[str, Any],
         actor: str,
-    ) -> ModelType:  # type: ignore[type-var]
+    ) -> ModelType:  # type: ignore[type-var,misc]
         """Upsert a record (PUT semantics)."""
         existed = self.accessor.get(record_id, include_deleted=True) is not None
 
         if not existed and self.max_records is not None:
             total = len(self.accessor.all(include_deleted=True))
             if total >= self.max_records:
-                raise ConflictError(
-                    f"Max {self.max_records} records allowed for {self.accessor.component}"
-                )
+                raise ConflictError(f"Max {self.max_records} records allowed for {self.accessor.component}")
 
         payload_no_id = {k: v for k, v in payload.items() if k != "id"}
         obj = self.accessor.model(id=record_id, **payload_no_id)
@@ -132,7 +336,7 @@ class CrudService:
         if not ok:
             raise NotFoundError()
 
-    def restore_record(self, record_id: int, actor: str) -> ModelType:  # type: ignore[type-var]
+    def restore_record(self, record_id: int, actor: str) -> ModelType:  # type: ignore[type-var,misc]
         """Restore a soft-deleted record (if supported).
 
         Returns the restored model instance. If the record was already
@@ -140,9 +344,7 @@ class CrudService:
         """
         model_cls = self.accessor.model
         if not hasattr(model_cls, "deleted_at"):
-            raise UnsupportedError(
-                f"{self.accessor.component} does not support soft delete/restore"
-            )
+            raise UnsupportedError(f"{self.accessor.component} does not support soft delete/restore")
 
         obj = self.accessor.get(record_id, include_deleted=True)
         if not obj:

storage/database.py

@@ -19,9 +19,7 @@ __all__ = [
 
 _DATABASE_URL = os.getenv("VENTION_STORAGE_DATABASE_URL", "sqlite:///./storage.db")
 _ENGINE: Optional[Engine] = None
-CURRENT_SESSION: ContextVar[Optional[Session]] = ContextVar(
-    "VENTION_STORAGE_CURRENT_SESSION", default=None
-)
+CURRENT_SESSION: ContextVar[Optional[Session]] = ContextVar("VENTION_STORAGE_CURRENT_SESSION", default=None)
 
 
 def set_database_url(url: str) -> None:
@@ -31,9 +29,7 @@ def set_database_url(url: str) -> None:
     """
     global _DATABASE_URL, _ENGINE
     if _ENGINE is not None:
-        raise RuntimeError(
-            "Database engine already initialized. Call set_database_url() before first use."
-        )
+        raise RuntimeError("Database engine already initialized. Call set_database_url() before first use.")
     _DATABASE_URL = url
 
 
@@ -57,9 +53,7 @@ def get_engine() -> Engine:
     """Return a singleton SQLAlchemy engine (created on first use)."""
     global _ENGINE
     if _ENGINE is None:
-        connect_args = (
-            {"check_same_thread": False} if _DATABASE_URL.startswith("sqlite") else {}
-        )
+        connect_args = {"check_same_thread": False} if _DATABASE_URL.startswith("sqlite") else {}
         _ENGINE = create_engine(_DATABASE_URL, echo=False, connect_args=connect_args)
         _attach_sqlite_pragmas(_ENGINE)
     return _ENGINE

storage/database_service.py

@@ -119,9 +119,7 @@ class DatabaseService:
             if until is not None:
                 statement = statement.where(AuditLog.timestamp < until)
 
-            statement = (
-                statement.order_by(desc(AuditLog.timestamp)).offset(offset).limit(limit)
-            )
+            statement = statement.order_by(desc(AuditLog.timestamp)).offset(offset).limit(limit)
             results = session.exec(statement).all()
             return list(results)
 
@@ -135,10 +133,7 @@ class DatabaseService:
         try:
             from sqlalchemy_schemadisplay import create_schema_graph
         except Exception as e:
-            raise DependencyError(
-                "sqlalchemy-schemadisplay is required. Install with: "
-                "pip install sqlalchemy-schemadisplay"
-            ) from e
+            raise DependencyError("sqlalchemy-schemadisplay is required. Install with: pip install sqlalchemy-schemadisplay") from e
 
         try:
             graph = create_schema_graph(
@@ -156,8 +151,7 @@ class DatabaseService:
             msg = str(e).lower()
             if "executable" in msg or "dot not found" in msg or "graphviz" in msg:
                 raise DependencyError(
-                    "Graphviz is required to render the diagram. "
-                    "Install it via `brew install graphviz` or `apt-get install graphviz`."
+                    "Graphviz is required to render the diagram. Install it via `brew install graphviz` or `apt-get install graphviz`."
                 ) from e
             raise OperationalError(f"Failed to generate schema diagram: {e}") from e
 
@@ -209,9 +203,7 @@ class DatabaseService:
         db_dir = Path(path).resolve().parent
 
         try:
-            tmp_path, total = io_helpers.save_bytes_to_temp(
-                file_bytes, db_dir, filename=filename
-            )
+            tmp_path, total = io_helpers.save_bytes_to_temp(file_bytes, db_dir, filename=filename)
         except Exception as e:
             raise OperationalError(f"Failed to save upload: {e}") from e
 

storage/hooks.py

@@ -24,13 +24,9 @@ class HookRegistry(Generic[ModelRecord]):
     """Lightweight per-accessor registry for lifecycle hooks."""
 
     def __init__(self) -> None:
-        self._hooks: DefaultDict[HookEvent, List[HookFn[ModelRecord]]] = defaultdict(
-            list
-        )
+        self._hooks: DefaultDict[HookEvent, List[HookFn[ModelRecord]]] = defaultdict(list)
 
-    def decorator(
-        self, event: HookEvent
-    ) -> Callable[[HookFn[ModelRecord]], HookFn[ModelRecord]]:
+    def decorator(self, event: HookEvent) -> Callable[[HookFn[ModelRecord]], HookFn[ModelRecord]]:
         """Return a decorator that registers a function for `event`."""
 
         def deco(fn: HookFn[ModelRecord]) -> HookFn[ModelRecord]:
@@ -39,9 +35,7 @@ class HookRegistry(Generic[ModelRecord]):
 
         return deco
 
-    def emit(
-        self, event: HookEvent, *, session: Session, instance: ModelRecord
-    ) -> None:
+    def emit(self, event: HookEvent, *, session: Session, instance: ModelRecord) -> None:
         """Invoke all hooks registered for `event`."""
         for fn in self._hooks.get(event, []):
             fn(session, instance)

storage/io_helpers.py

@@ -45,15 +45,11 @@ def write_table_csv_buffer(session: Session, table: Table) -> io.StringIO:
     """SELECT * and return CSV (header + rows) in a StringIO."""
     buffer = io.StringIO(newline="")
     columns = list(table.columns)
-    writer = csv.DictWriter(
-        buffer, fieldnames=[column.name for column in columns], extrasaction="ignore"
-    )
+    writer = csv.DictWriter(buffer, fieldnames=[column.name for column in columns], extrasaction="ignore")
     writer.writeheader()
     result = session.exec(select(table))
     for row in result:
-        writer.writerow(
-            {column.name: to_primitive(row._mapping[column]) for column in columns}
-        )
+        writer.writerow({column.name: to_primitive(row._mapping[column]) for column in columns})
     return buffer
 
 
@@ -87,9 +83,7 @@ def build_backup_bytes(db_path: str) -> bytes:
     Build a consistent .sqlite backup and return bytes.
     """
     db_dir = Path(db_path).resolve().parent
-    with tempfile.NamedTemporaryFile(
-        prefix="backup-", suffix=".sqlite", dir=db_dir, delete=False
-    ) as tmp:
+    with tempfile.NamedTemporaryFile(prefix="backup-", suffix=".sqlite", dir=db_dir, delete=False) as tmp:
         tmp_path = Path(tmp.name)
 
     try:
@@ -130,9 +124,7 @@ def validate_sqlite_file(path: Path, *, run_integrity_check: bool = True) -> Non
             row = connection.execute("PRAGMA integrity_check;").fetchone()
             ok = row and str(row[0]).lower() == "ok"
             if not ok:
-                raise ValueError(
-                    f"Integrity check failed: {row[0] if row else 'unknown'}"
-                )
+                raise ValueError(f"Integrity check failed: {row[0] if row else 'unknown'}")
         finally:
             connection.close()
     except ValueError:
@@ -142,9 +134,7 @@ def validate_sqlite_file(path: Path, *, run_integrity_check: bool = True) -> Non
 
 
 def save_upload_to_temp(file: UploadFile, dest_dir: Path) -> tuple[Path, int]:
-    with tempfile.NamedTemporaryFile(
-        prefix="restore-", suffix=".sqlite", dir=dest_dir, delete=False
-    ) as tmp:
+    with tempfile.NamedTemporaryFile(prefix="restore-", suffix=".sqlite", dir=dest_dir, delete=False) as tmp:
         tmp_path = Path(tmp.name)
         total = 0
         while True:
@@ -160,13 +150,9 @@ def save_upload_to_temp(file: UploadFile, dest_dir: Path) -> tuple[Path, int]:
     return tmp_path, total
 
 
-def save_bytes_to_temp(
-    file_bytes: bytes, dest_dir: Path, *, filename: str = "upload.sqlite"
-) -> tuple[Path, int]:
+def save_bytes_to_temp(file_bytes: bytes, dest_dir: Path, *, filename: str = "upload.sqlite") -> tuple[Path, int]:
     """Save bytes to a temporary file in the destination directory."""
-    with tempfile.NamedTemporaryFile(
-        prefix="restore-", suffix=".sqlite", dir=dest_dir, delete=False
-    ) as tmp:
+    with tempfile.NamedTemporaryFile(prefix="restore-", suffix=".sqlite", dir=dest_dir, delete=False) as tmp:
         tmp_path = Path(tmp.name)
         tmp.write(file_bytes)
         total = len(file_bytes)

storage/utils.py

@@ -28,9 +28,7 @@ def parse_audit_operation(operation: Optional[str]) -> Optional[Operation]:
         return None
 
     if operation not in get_args(Operation):
-        raise ValueError(
-            f"Invalid operation: {operation}. Must be one of {get_args(Operation)}"
-        )
+        raise ValueError(f"Invalid operation: {operation}. Must be one of {get_args(Operation)}")
 
     return operation  # type: ignore
 

storage/vention_communication.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
-from typing import Any, Dict, List, Optional, Sequence, Type
+from typing import Any, Dict, List, Optional, Sequence, Type, cast
 
-from pydantic import BaseModel, create_model
+from pydantic import BaseModel, Field, create_model
 
 from communication.entries import RpcBundle, ActionEntry
 from communication.errors import ConnectError
@@ -10,6 +10,8 @@ from storage.accessor import ModelAccessor
 from storage.crud_service import (
     CrudService,
     CrudError,
+    Filter,
+    FilterOperation,
     NotFoundError,
     ConflictError,
     ValidationError,
@@ -25,8 +27,17 @@ from storage.utils import parse_audit_operation, parse_audit_datetime
 __all__ = ["build_storage_rpc_bundle"]
 
 
+def _convert_filters_to_dicts(filters: List["FilterCondition"]) -> List[Filter]:
+    """Convert FilterCondition Pydantic models to Filter TypedDicts for CrudService."""
+    return cast(List[Filter], [f.model_dump() for f in filters])
+
+
 class CrudListRequest(BaseModel):
     include_deleted: bool = False
+    limit: Optional[int] = Field(default=None, gt=0)
+    offset: int = Field(default=0, ge=0)
+    order_by: Optional[str] = None
+    order_desc: bool = False
 
 
 class CrudGetRequest(BaseModel):
@@ -44,6 +55,21 @@ class CrudRestoreRequest(BaseModel):
     actor: str
 
 
+class FilterCondition(BaseModel):
+    field: str
+    operation: FilterOperation
+    value: Optional[Any] = None
+
+
+class CrudFindRequest(BaseModel):
+    filters: List[FilterCondition] = []
+    include_deleted: bool = False
+    limit: Optional[int] = Field(default=None, gt=0)
+    offset: int = Field(default=0, ge=0)
+    order_by: Optional[str] = None
+    order_desc: bool = False
+
+
 class AuditQueryRequest(BaseModel):
     component: Optional[str] = None
     record_id: Optional[int] = None
@@ -51,8 +77,8 @@ class AuditQueryRequest(BaseModel):
     operation: Optional[str] = None
     since: Optional[str] = None
     until: Optional[str] = None
-    limit: Optional[int] = None
-    offset: int = 0
+    limit: Optional[int] = Field(default=None, gt=0)
+    offset: int = Field(default=0, ge=0)
 
 
 class FileResponse(BaseModel):
@@ -186,7 +212,13 @@ def build_storage_rpc_bundle(
         ) -> BaseModel:
             try:
                 records: List[BaseModel] = list(
-                    _crud.list_records(include_deleted=req.include_deleted)
+                    _crud.list_records(
+                        include_deleted=req.include_deleted,
+                        limit=req.limit,
+                        offset=req.offset,
+                        order_by=req.order_by,
+                        order_desc=req.order_desc,
+                    )
                 )
                 return _Resp(records=records)
             except CrudError as e:
@@ -201,6 +233,37 @@ def build_storage_rpc_bundle(
             )
         )
 
+        # ---------------- Find ----------------
+        async def find_records(
+            req: CrudFindRequest,
+            _crud: CrudService = crud,
+            _Resp: Type[BaseModel] = ListResponse,
+        ) -> BaseModel:
+            try:
+                filter_dicts = _convert_filters_to_dicts(req.filters)
+                records: List[BaseModel] = list(
+                    _crud.find_records(
+                        filters=filter_dicts,
+                        include_deleted=req.include_deleted,
+                        limit=req.limit,
+                        offset=req.offset,
+                        order_by=req.order_by,
+                        order_desc=req.order_desc,
+                    )
+                )
+                return _Resp(records=records)
+            except CrudError as e:
+                raise _to_rpc(e)
+
+        bundle.actions.append(
+            ActionEntry(
+                name=f"{model_name}_FindRecords",
+                func=find_records,
+                input_type=CrudFindRequest,
+                output_type=ListResponse,
+            )
+        )
+
         # ---------------- Get ----------------
         async def get_record(
             req: CrudGetRequest,
@@ -208,9 +271,7 @@ def build_storage_rpc_bundle(
             _Resp: Type[BaseModel] = GetResponse,
         ) -> BaseModel:
             try:
-                rec: BaseModel = _crud.get_record(
-                    req.record_id, include_deleted=req.include_deleted
-                )
+                rec: BaseModel = _crud.get_record(req.record_id, include_deleted=req.include_deleted)
                 return _Resp(record=rec)
             except CrudError as e:
                 raise _to_rpc(e)

{vention_storage-0.6.0.dist-info → vention_storage-0.6.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vention-storage
-Version: 0.6.0
+Version: 0.6.3
 Summary: A framework for storing and managing component and application data for machine apps.
 License: Proprietary
 Author: VentionCo
@@ -8,9 +8,26 @@ Requires-Python: >=3.10,<3.11
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
-Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
-Requires-Dist: sqlmodel (==0.0.27)
-Requires-Dist: vention-communication (>=0.2.2,<0.3.0)
+Requires-Dist: annotated-doc (==0.0.4) ; python_version == "3.10"
+Requires-Dist: annotated-types (==0.7.0) ; python_version == "3.10"
+Requires-Dist: anyio (==4.12.1) ; python_version == "3.10"
+Requires-Dist: click (==8.3.1) ; python_version == "3.10"
+Requires-Dist: colorama (==0.4.6) ; python_version == "3.10" and platform_system == "Windows"
+Requires-Dist: exceptiongroup (==1.3.1) ; python_version == "3.10"
+Requires-Dist: fastapi (==0.121.1) ; python_version == "3.10"
+Requires-Dist: greenlet (==3.3.1) ; python_version == "3.10" and (platform_machine == "aarch64" or platform_machine == "ppc64le" or platform_machine == "x86_64" or platform_machine == "amd64" or platform_machine == "AMD64" or platform_machine == "win32" or platform_machine == "WIN32")
+Requires-Dist: h11 (==0.16.0) ; python_version == "3.10"
+Requires-Dist: idna (==3.11) ; python_version == "3.10"
+Requires-Dist: pydantic (==2.12.5) ; python_version == "3.10"
+Requires-Dist: pydantic-core (==2.41.5) ; python_version == "3.10"
+Requires-Dist: python-multipart (==0.0.20) ; python_version == "3.10"
+Requires-Dist: sqlalchemy (==2.0.46) ; python_version == "3.10"
+Requires-Dist: sqlmodel (==0.0.27) ; python_version == "3.10"
+Requires-Dist: starlette (==0.49.3) ; python_version == "3.10"
+Requires-Dist: typing-extensions (==4.15.0) ; python_version == "3.10"
+Requires-Dist: typing-inspection (==0.4.2) ; python_version == "3.10"
+Requires-Dist: uvicorn (==0.35.0) ; python_version == "3.10"
+Requires-Dist: vention-communication (==0.3.0) ; python_version == "3.10"
 Description-Content-Type: text/markdown
 
 # Vention Storage
@@ -207,8 +224,47 @@ user_accessor.delete(user.id, actor="admin")
 
 # Restore (for soft-deleted models)
 user_accessor.restore(user.id, actor="admin")
-```
 
+# Find users by exact match
+users = user_accessor.find(user_accessor.where.email == "alice@example.com")
+
+# Multiple conditions (AND logic)
+users = user_accessor.find(
+    user_accessor.where.name == "Alice",
+    user_accessor.where.email == "alice@example.com"
+)
+
+# Comparison operators
+adults = user_accessor.find(user_accessor.where.age >= 18)
+recent = user_accessor.find(user_accessor.where.created_at > cutoff_date)
+
+# String operations
+smiths = user_accessor.find(user_accessor.where.name.contains("Smith"))
+gmail_users = user_accessor.find(user_accessor.where.email.endswith("@gmail.com"))
+search = user_accessor.find(user_accessor.where.name.ilike("%alice%"))  # case-insensitive
+
+# Collection check
+admins = user_accessor.find(user_accessor.where.role.in_(["admin", "superadmin"]))
+
+# Null checks
+unverified = user_accessor.find(user_accessor.where.verified_at.is_(None))
+verified = user_accessor.find(user_accessor.where.verified_at.isnot(None))
+
+# With pagination and sorting
+page = user_accessor.find(
+    user_accessor.where.status == "active",
+    limit=10,
+    offset=20,
+    order_by="created_at",
+    order_desc=True
+)
+
+# Include soft-deleted records
+all_users = user_accessor.find(
+    user_accessor.where.role == "admin",
+    include_deleted=True
+)
+```
 
 ### Using ConnectRPC Client
 
@@ -278,8 +334,73 @@ export async function listUsers() {
   });
   return res.records;
 }
+
+// Find by exact match
+export async function findUserByEmail(email: string) {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "email", operation: "eq", value: email }
+    ]
+  });
+  return res.records;
+}
+
+// Find with multiple conditions (AND logic)
+export async function findActiveAdmins() {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "role", operation: "eq", value: "admin" },
+      { field: "age", operation: "gte", value: "18" }
+    ]
+  });
+  return res.records;
+}
+
+// Find with null checks
+export async function findUnverifiedUsers() {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "verified_at", operation: "is_null" }
+    ]
+  });
+  return res.records;
+}
+
+// Complex query example
+export async function findRecentPremiumUsers(cutoffDate: string) {
+  const res = await client.usersFindRecords({
+    filters: [
+      { field: "subscription", operation: "in", value: ["premium", "enterprise"] },
+      { field: "created_at", operation: "gte", value: cutoffDate },
+      { field: "email_verified", operation: "is_not_null" }
+    ],
+    limit: 50,
+    orderBy: "created_at",
+    orderDesc: true
+  });
+  return res.records;
+}
 ```
 
+### Filter Operations Reference
+
+| Operation      | Description                          |
+|----------------|--------------------------------------|
+| `eq`           | Exact match                          |
+| `ne`           | Not equal to value                   |
+| `gt`           | Greater than value                   |
+| `gte`          | Greater than or equal                |
+| `lt`           | Less than value                      |
+| `lte`          | Less than or equal                   |
+| `in`           | Value in array                       |
+| `not_in`       | Value not in array                   |
+| `contains`     | Field contains substring             |
+| `starts_with`  | Field starts with prefix             |
+| `ends_with`    | Field ends with suffix               |
+| `like`         | Case-insensitive pattern match       |
+| `is_null`      | Field is null (no value needed)      |
+| `is_not_null`  | Field is not null (no value needed)  |
+
 
 ## 📖 API Reference
 

vention_storage-0.6.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+storage/accessor.py,sha256=7rm1B57kLKb5-1ou6dOlq8Bvl7MQuPpJdtPnn-8uQyk,15076
+storage/auditor.py,sha256=tsvsb9qlHdcknY5OAXRZBMcN4nFDKtN3Ln1LfgozJrw,2090
+storage/bootstrap.py,sha256=rZBXQF4M-Lm4Rw2T74M4-swMBgAWEts16v9mG64t2hM,846
+storage/crud_service.py,sha256=w-OFFh9fcHmEt0As7jsCcIWZhheg8jcnVapOoaqeNAU,12794
+storage/database.py,sha256=5Ird_CNwikMe07CBhDANrKJN-SJGR2ESOSB0RT6JvKs,3132
+storage/database_service.py,sha256=DqDA-xwCuJ5FHimBjb0PXvffLC970kIZcusxGFyIr-E,7734
+storage/hooks.py,sha256=ks8M8Lv7dIJsuetEJ91c1SdnvmF4RCF8d5suCiZRddA,1248
+storage/io_helpers.py,sha256=ADjdQsNSPXfgg2-7-r5utdPDr_k0f605mcavHQLQP_Y,5406
+storage/utils.py,sha256=JfZV3wYqg6miAIs1M4QGmIMpZCE4nMi6IrLdDDc-b5Q,1298
+storage/vention_communication.py,sha256=diwFarPhaE9w2CxqiqAWK0KE9I8hg-2qSjXkPvC1WjI,17577
+vention_storage-0.6.3.dist-info/METADATA,sha256=EkkAGYcflPTeAt3sKsTqsIAVySjX5RpNurzoVuJOnI0,14702
+vention_storage-0.6.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+vention_storage-0.6.3.dist-info/RECORD,,

vention_storage-0.6.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-storage/accessor.py,sha256=QgLnju-31jBprLtFMyAy8duKZKAshO8Rngd5cBjduhY,10879
-storage/auditor.py,sha256=tsvsb9qlHdcknY5OAXRZBMcN4nFDKtN3Ln1LfgozJrw,2090
-storage/bootstrap.py,sha256=rZBXQF4M-Lm4Rw2T74M4-swMBgAWEts16v9mG64t2hM,846
-storage/crud_service.py,sha256=9XUkOjiw16O9UzRYPBUV1NYUu34-pEbYTp310xopgkU,5281
-storage/database.py,sha256=BGRnlH0qBVnYffp0F1TCWGb6OS8cdlMmEJ1-LeHH4oc,3184
-storage/database_service.py,sha256=pUhS3LfSswIfr7wlIcUbO3uVuT_GzfKh4QwOuQrwf1k,7868
-storage/hooks.py,sha256=rMK8R-VO0B7caZn9HtTlcetx0KQMvsl1Aq-t9mbFA4Q,1298
-storage/io_helpers.py,sha256=oTyVXRdD4eVuqpIOFNh_4ULqiNJ46pNCT38he1dzMBg,5528
-storage/utils.py,sha256=AV8d1WQmdBLAnpoGJX3c8th5_mYFAei6d_ZxDG5QOAE,1320
-storage/vention_communication.py,sha256=sBtwA5SLBSq0-fnQgwL1UmQwloSSnbv-pS2Iiv32o3g,15421
-vention_storage-0.6.0.dist-info/METADATA,sha256=xWgWEcwA-9z4zVJepXBTTUFmhngRQan7fkxuLV_uAtk,9858
-vention_storage-0.6.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-vention_storage-0.6.0.dist-info/RECORD,,