planar 0.5.0__py3-none-any.whl

planar/modeling/mixins/timestamp.py

@@ -0,0 +1,53 @@
+from datetime import datetime
+from typing import Any, Callable
+
+from sqlmodel import Field, SQLModel
+
+from planar.utils import utc_now
+
+
+def timestamp_column(
+    index: bool = False,
+    nullable: bool = False,
+    onupdate: Callable[[], datetime] | bool | None = None,
+    default: Callable[[], datetime] | None = utc_now,
+):
+    if onupdate is True:
+        onupdate = utc_now
+    return Field(
+        default_factory=default,
+        nullable=nullable,
+        index=index,
+        sa_column_kwargs={"onupdate": onupdate},
+    )
+
+
+class TimestampMixin(SQLModel, table=False):
+    """
+    Mixin that adds created_at and updated_at fields to a model.
+
+    This standardizes timestamp handling across all internal models.
+
+    Attributes:
+        created_at: Timestamp when the record was created
+        updated_at: Timestamp that updates whenever the record is modified
+    """
+
+    __abstract__ = True
+
+    created_at: datetime = timestamp_column()
+    updated_at: datetime = timestamp_column(onupdate=utc_now)
+
+    def __init__(self, **kwargs: Any):
+        """
+        Initializes the TimestampMixin.
+        Ensures that `updated_at` is the same as `created_at` if `updated_at`
+        is not explicitly provided during instantiation.
+        """
+        super().__init__(**kwargs)
+        # If 'updated_at' was not passed during construction,
+        # set it to the value of 'created_at'.
+        # 'created_at' itself would have been set by super().__init__()
+        # either from kwargs or its default_factory.
+        if "updated_at" not in kwargs and self.created_at is not None:
+            self.updated_at = self.created_at

planar/modeling/mixins/uuid_primary_key.py

@@ -0,0 +1,19 @@
+from uuid import UUID, uuid4
+
+from sqlmodel import Field, SQLModel
+
+
+class UUIDPrimaryKeyMixin(SQLModel, table=False):
+    """
+    Mixin that provides a UUID primary key field.
+
+    This standardizes primary key handling across all models that need
+    a UUID-based primary key.
+
+    Attributes:
+        id: UUID primary key field with automatic generation
+    """
+
+    __abstract__ = True
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)

planar/modeling/orm/__init__.py

@@ -0,0 +1,18 @@
+from .planar_base_entity import PLANAR_APPLICATION_METADATA, PlanarBaseEntity
+from .reexports import (
+    Field,
+    Relationship,
+    Session,
+    SQLModel,
+    create_engine,
+)
+
+__all__ = [
+    "Field",
+    "Relationship",
+    "Session",
+    "SQLModel",
+    "create_engine",
+    "PlanarBaseEntity",
+    "PLANAR_APPLICATION_METADATA",
+]

planar/modeling/orm/planar_base_entity.py

@@ -0,0 +1,29 @@
+from pydantic import ConfigDict
+from sqlalchemy import MetaData, event
+from sqlalchemy.engine import Connection
+from sqlalchemy.orm import Mapper
+
+from planar.logging import get_logger
+from planar.modeling.mixins.auditable import AuditableMixin
+from planar.modeling.mixins.uuid_primary_key import UUIDPrimaryKeyMixin
+
+from .reexports import SQLModel
+
+logger = get_logger("orm.PlanarBaseEntity")
+
+
+PLANAR_APPLICATION_METADATA = MetaData()
+
+
+class PlanarBaseEntity(UUIDPrimaryKeyMixin, AuditableMixin, SQLModel, table=False):
+    __abstract__ = True
+    model_config = ConfigDict(validate_assignment=True)  # type: ignore
+    metadata = PLANAR_APPLICATION_METADATA
+
+
+@event.listens_for(PlanarBaseEntity, "before_delete", propagate=True)
+def log_deletion(
+    mapper: Mapper, connection: Connection, target: PlanarBaseEntity
+) -> None:
+    """Logs the deletion of the entity."""
+    logger.info("deleting entity", table_name=target.__tablename__, key=target.id)

planar/modeling/orm/query_filter_builder.py

@@ -0,0 +1,122 @@
+from sqlalchemy.sql import func as sql_func
+from sqlmodel import desc, select
+
+from planar.routers.models import SortDirection
+
+
+def build_paginated_query(
+    query, filters=None, offset=None, limit=None, order_by=None, order_direction=None
+):
+    """
+    Helper function to build paginated and filtered queries.
+
+    Args:
+        query: The base SQL query to build upon
+        filters: Optional list of filter conditions, where each condition is a tuple of
+                (column, operator, value). Operator should be one of:
+                '==', '!=', '>', '>=', '<', '<=', 'like', 'ilike', 'in', 'not_in'
+                For example: [(User.name, '==', 'John'), (User.age, '>', 18)]
+                For date ranges: [(Workflow.created_at, '>=', start_date)]
+        offset: Optional offset for pagination
+        limit: Optional limit for pagination
+        order_by: Optional field or list of fields to order by
+        order_direction: Optional direction to order by
+    Returns:
+        Tuple of (paginated query, total count query)
+        The count query is guaranteed to work with the session.exec().one() pattern
+    """
+    # Create a copy of the query for filtering
+    filtered_query = query
+
+    # Apply filters if provided
+    if filters:
+        for column, operator, value in filters:
+            if value is not None:  # Skip None values
+                if operator == "==" or operator == "=":
+                    filtered_query = filtered_query.where(column == value)
+                elif operator == "!=":
+                    filtered_query = filtered_query.where(column != value)
+                elif operator == ">":
+                    filtered_query = filtered_query.where(column > value)
+                elif operator == ">=":
+                    filtered_query = filtered_query.where(column >= value)
+                elif operator == "<":
+                    filtered_query = filtered_query.where(column < value)
+                elif operator == "<=":
+                    filtered_query = filtered_query.where(column <= value)
+                elif operator == "like":
+                    filtered_query = filtered_query.where(column.like(value))
+                elif operator == "ilike":
+                    filtered_query = filtered_query.where(column.ilike(value))
+                elif operator == "in":
+                    filtered_query = filtered_query.where(column.in_(value))
+                elif operator == "not_in":
+                    filtered_query = filtered_query.where(column.not_in(value))
+
+    # Create a total count query based on the filtered query
+    # For select queries with a clear table source
+    if hasattr(filtered_query, "whereclause"):
+        # For standard select queries, create a count query from the same structure
+        count_query = select(sql_func.count())
+
+        # Try to determine the table to select from
+        if (
+            hasattr(filtered_query, "get_final_froms")
+            and filtered_query.get_final_froms()
+        ):
+            count_query = count_query.select_from(filtered_query.get_final_froms()[0])
+        elif hasattr(filtered_query, "columns") and filtered_query.columns:
+            # If we can't get froms, try to extract from columns
+            for col in filtered_query.columns:
+                if hasattr(col, "table"):
+                    count_query = count_query.select_from(col.table)
+                    break
+
+        # Apply the same where clause if it exists
+        if filtered_query.whereclause is not None:
+            count_query = count_query.where(filtered_query.whereclause)
+    else:
+        # For manually constructed queries, extract from first part of query
+        # Assuming the query has a clear identifier of the table it's querying
+        first_table = None
+
+        # Try to find the table by examining the query structure
+        # This is a simplified approach - adjust as needed based on your query structure
+        if hasattr(query, "columns") and query.columns:
+            for col in query.columns:
+                if hasattr(col, "table"):
+                    first_table = col.table
+                    break
+
+        # Build count query based on the table and where clause
+        if first_table is not None:
+            count_query = select(sql_func.count()).select_from(first_table)
+            if (
+                hasattr(filtered_query, "whereclause")
+                and filtered_query.whereclause is not None
+            ):
+                count_query = count_query.where(filtered_query.whereclause)
+        else:
+            # If we can't determine the table, create a dummy count query that returns 0
+            # This ensures we don't need fallback code in the endpoint handlers
+            count_query = select(sql_func.lit(0).label("count"))
+
+    # Apply pagination
+    result_query = filtered_query
+
+    # Apply offset if provided
+    if offset is not None:
+        result_query = result_query.offset(offset)
+
+    # Apply limit if provided
+    if limit is not None:
+        result_query = result_query.limit(limit)
+
+    # Apply ordering
+    if order_by:
+        if order_direction == SortDirection.ASC:
+            result_query = result_query.order_by(order_by)
+        else:
+            result_query = result_query.order_by(desc(order_by))
+
+    return result_query, count_query

planar/modeling/orm/reexports.py

@@ -0,0 +1,15 @@
+import sqlmodel as _sqlmodel
+
+SQLModel = _sqlmodel.SQLModel
+Field = _sqlmodel.Field
+Relationship = _sqlmodel.Relationship
+Session = _sqlmodel.Session
+create_engine = _sqlmodel.create_engine
+
+__all__ = [
+    "SQLModel",
+    "Field",
+    "Relationship",
+    "Session",
+    "create_engine",
+]

planar/object_config/__init__.py

@@ -0,0 +1,11 @@
+from .models import ConfigurableObjectType, ObjectConfiguration, ObjectConfigurationBase
+from .object_config import DEFAULT_UUID, ConfigNotFoundError, ObjectConfigurationIO
+
+__all__ = [
+    "ObjectConfiguration",
+    "ObjectConfigurationBase",
+    "ConfigurableObjectType",
+    "DEFAULT_UUID",
+    "ObjectConfigurationIO",
+    "ConfigNotFoundError",
+]

planar/object_config/models.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any, Generic, TypeVar
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel
+from sqlalchemy import VARCHAR, UniqueConstraint
+from sqlalchemy.sql.type_api import TypeDecorator
+from sqlmodel import Column
+from sqlmodel import Field as SQLField
+
+from planar.db import PlanarInternalBase
+from planar.modeling.mixins.timestamp import timestamp_column
+
+T = TypeVar("T", bound="BaseModel")
+V = TypeVar("V")
+
+
+class ConfigurableObjectType(str, Enum):
+    RULE = "rule"
+    AGENT = "agent"
+
+
+class JSONEncodedDict(TypeDecorator):
+    """Create a SQLAlchemy type that converts BaseModel to JSON string on write and to dict on read."""
+
+    impl = VARCHAR
+    cache_ok = True  # Required for SQLAlchemy caching mechanism
+
+    def process_bind_param(self, value, dialect):
+        if value is None:
+            return None
+
+        if isinstance(value, BaseModel):
+            return value.model_dump_json(by_alias=True)
+
+        raise ValueError(f"Invalid type: {type(value)}")
+
+    def process_result_value(self, value, dialect):
+        if value is None:
+            return None
+
+        return json.loads(value)
+
+
+class DiffErrorCode(Enum):
+    """Error codes for dictionary comparison diagnostics."""
+
+    MISSING_FIELD = "MISSING_FIELD"
+    VALUE_MISMATCH = "VALUE_MISMATCH"
+    EXTRA_FIELD = "EXTRA_FIELD"
+    CONFIG_MODEL_CHANGED = "CONFIG_MODEL_CHANGED"
+
+
+class ConfigDiagnosticIssue(BaseModel):
+    """Represents a single diagnostic issue found during dictionary comparison."""
+
+    error_code: DiffErrorCode
+    field_path: str
+    message: str
+    reference_value: Any | None = None
+    current_value: Any | None = None
+    for_object: str
+
+
+class ConfigDiagnostics(BaseModel, Generic[T]):
+    is_valid: bool
+    suggested_fix: T | None = None
+    issues: list[ConfigDiagnosticIssue]
+
+
+class ObjectConfigurationBase(BaseModel, Generic[T]):
+    """Base Pydantic model for object configurations without SQLModel dependencies.
+
+    This class mirrors the fields in ObjectConfiguration but can be used for
+    serialization in FastAPI routes and other places where SQLModel references
+    should be avoided.
+    """
+
+    id: UUID
+    object_name: str
+    object_type: ConfigurableObjectType
+    created_at: datetime
+    version: int
+    data: T
+    active: bool
+
+
+class ObjectConfiguration(PlanarInternalBase, Generic[T], table=True):
+    __table_args__ = (
+        UniqueConstraint(
+            "object_name",
+            "object_type",
+            "version",
+            name="uq_object_config_name_type_version",
+        ),
+    )
+
+    __tablename__ = "object_configuration"  # type: ignore
+
+    id: UUID = SQLField(default_factory=uuid4, primary_key=True)
+
+    object_name: str = SQLField(index=True)
+    object_type: ConfigurableObjectType = SQLField(index=True)
+    created_at: datetime = timestamp_column()
+
+    version: int = SQLField(default=1)
+
+    data: T = SQLField(sa_column=Column(JSONEncodedDict))
+
+    active: bool = SQLField(default=False)