unrealon 1.1.6__py3-none-any.whl → 2.0.5__py3-none-any.whl

unrealon_core/models/base.py

@@ -0,0 +1,291 @@
+"""
+Base Pydantic models for UnrealOn system.
+
+These models provide common functionality and validation patterns
+used throughout the system. Built with Pydantic v2 for maximum
+performance and type safety.
+
+Phase 1: Bedrock Foundation - These models are the foundation
+for all other models in the system.
+"""
+
+from datetime import datetime
+from typing import Optional, Dict, Any, Union
+from pydantic import BaseModel, Field, ConfigDict, field_validator
+import uuid
+
+from ..utils.time import utc_now
+
+
+class UnrealOnBaseModel(BaseModel):
+    """
+    Base model for all UnrealOn models.
+    
+    Provides:
+    - Strict validation (no extra fields)
+    - JSON serialization/deserialization
+    - Type safety with Pydantic v2
+    - Common utility methods
+    """
+    
+    model_config = ConfigDict(
+        # Pydantic v2 configuration for maximum strictness
+        str_strip_whitespace=True,      # Auto-strip whitespace
+        validate_assignment=True,       # Validate on assignment
+        use_enum_values=True,          # Use enum values in serialization
+        extra='forbid',                # Strict - no extra fields allowed
+        frozen=False,                  # Allow mutation by default
+        arbitrary_types_allowed=True,  # Allow custom types
+        validate_default=True,         # Validate default values
+    )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert model to dictionary for JSON serialization."""
+        return self.model_dump(mode='json', exclude_none=True)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]):
+        """Create instance from dictionary."""
+        return cls.model_validate(data)
+    
+    def to_json(self) -> str:
+        """Convert model to JSON string."""
+        return self.model_dump_json(exclude_none=True)
+    
+    @classmethod
+    def from_json(cls, json_str: str):
+        """Create instance from JSON string."""
+        return cls.model_validate_json(json_str)
+    
+    def update_from_dict(self, data: Dict[str, Any]) -> 'UnrealOnBaseModel':
+        """Update model fields from dictionary."""
+        for key, value in data.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+        return self
+    
+    def copy_with_updates(self, **updates) -> 'UnrealOnBaseModel':
+        """Create a copy with updated fields."""
+        return self.model_copy(update=updates)
+
+
+class TimestampedModel(UnrealOnBaseModel):
+    """
+    Base model with automatic timestamp fields.
+    
+    Provides:
+    - created_at: Auto-set on creation
+    - updated_at: Manual update via touch()
+    - age_seconds: Calculated property
+    """
+    
+    created_at: datetime = Field(
+        default_factory=utc_now,
+        description="Timestamp when the model was created"
+    )
+    updated_at: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp when the model was last updated"
+    )
+    
+    def touch(self) -> 'TimestampedModel':
+        """Update the updated_at timestamp."""
+        self.updated_at = utc_now()
+        return self
+    
+    @property
+    def age_seconds(self) -> float:
+        """Get age of the model in seconds."""
+        return (utc_now() - self.created_at).total_seconds()
+    
+    @property
+    def last_modified_seconds(self) -> float:
+        """Get seconds since last modification."""
+        reference_time = self.updated_at or self.created_at
+        return (utc_now() - reference_time).total_seconds()
+
+
+class IdentifiedModel(UnrealOnBaseModel):
+    """
+    Base model with unique ID field.
+    
+    Provides:
+    - id: UUID4 string by default
+    - String representation
+    - Equality comparison by ID
+    """
+    
+    id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique identifier for the model",
+        min_length=1
+    )
+    
+    @field_validator('id')
+    @classmethod
+    def validate_id(cls, v: str) -> str:
+        """Validate ID is not empty."""
+        if not v or not v.strip():
+            raise ValueError("ID cannot be empty")
+        return v.strip()
+    
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}(id={self.id})"
+    
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(id='{self.id}')"
+    
+    def __eq__(self, other) -> bool:
+        """Compare models by ID."""
+        if not isinstance(other, IdentifiedModel):
+            return False
+        return self.id == other.id
+    
+    def __hash__(self) -> int:
+        """Hash by ID for use in sets/dicts."""
+        return hash(self.id)
+
+
+class StatusModel(UnrealOnBaseModel):
+    """
+    Base model with status tracking.
+    
+    Provides:
+    - status: Current status string
+    - status_message: Optional status description
+    - status_updated_at: Timestamp of last status change
+    - Status update methods
+    """
+    
+    status: str = Field(
+        description="Current status of the model",
+        min_length=1
+    )
+    status_message: Optional[str] = Field(
+        default=None,
+        description="Optional message describing the status"
+    )
+    status_updated_at: datetime = Field(
+        default_factory=utc_now,
+        description="Timestamp when status was last updated"
+    )
+    
+    @field_validator('status')
+    @classmethod
+    def validate_status(cls, v: str) -> str:
+        """Validate status is not empty."""
+        if not v or not v.strip():
+            raise ValueError("Status cannot be empty")
+        return v.strip()
+    
+    def update_status(self, status: str, message: Optional[str] = None) -> 'StatusModel':
+        """Update status with timestamp and optional message."""
+        self.status = status
+        self.status_message = message
+        self.status_updated_at = utc_now()
+        return self
+    
+    @property
+    def status_age_seconds(self) -> float:
+        """Get age of current status in seconds."""
+        return (utc_now() - self.status_updated_at).total_seconds()
+    
+    def is_status(self, *statuses: str) -> bool:
+        """Check if current status matches any of the provided statuses."""
+        return self.status in statuses
+
+
+class MetadataModel(UnrealOnBaseModel):
+    """
+    Base model with metadata field.
+    
+    Provides:
+    - metadata: Dictionary for arbitrary key-value data
+    - Helper methods for metadata manipulation
+    """
+    
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary metadata key-value pairs"
+    )
+    
+    def set_metadata(self, key: str, value: Any) -> 'MetadataModel':
+        """Set metadata value."""
+        self.metadata[key] = value
+        return self
+    
+    def get_metadata(self, key: str, default: Any = None) -> Any:
+        """Get metadata value with optional default."""
+        return self.metadata.get(key, default)
+    
+    def has_metadata(self, key: str) -> bool:
+        """Check if metadata key exists."""
+        return key in self.metadata
+    
+    def remove_metadata(self, key: str) -> 'MetadataModel':
+        """Remove metadata key if it exists."""
+        self.metadata.pop(key, None)
+        return self
+    
+    def clear_metadata(self) -> 'MetadataModel':
+        """Clear all metadata."""
+        self.metadata.clear()
+        return self
+    
+    def update_metadata(self, **updates) -> 'MetadataModel':
+        """Update metadata with multiple key-value pairs."""
+        self.metadata.update(updates)
+        return self
+
+
+# Combined base models for common use cases
+class FullBaseModel(IdentifiedModel, TimestampedModel, StatusModel, MetadataModel):
+    """
+    Complete base model with ID, timestamps, status, and metadata.
+    
+    Use this for complex entities that need full tracking:
+    - Drivers
+    - Tasks
+    - Complex configurations
+    """
+    pass
+
+
+class SimpleBaseModel(IdentifiedModel, TimestampedModel):
+    """
+    Simple base model with ID and timestamps only.
+    
+    Use this for simple entities:
+    - Messages
+    - Simple configurations
+    - Temporary objects
+    """
+    pass
+
+
+class ConfigBaseModel(UnrealOnBaseModel):
+    """
+    Base model for configuration objects.
+    
+    Provides validation for configuration models
+    without unnecessary fields like timestamps.
+    """
+    
+    def validate_config(self) -> bool:
+        """Override in subclasses to add custom validation."""
+        return True
+    
+    def merge_with(self, other: 'ConfigBaseModel') -> 'ConfigBaseModel':
+        """Merge this config with another, other takes precedence."""
+        if not isinstance(other, self.__class__):
+            raise ValueError(f"Cannot merge {self.__class__} with {other.__class__}")
+        
+        # Get all fields from both models
+        self_dict = self.model_dump()
+        other_dict = other.model_dump()
+        
+        # Merge dictionaries (other takes precedence)
+        merged = {**self_dict, **other_dict}
+        
+        # Create new instance
+        return self.__class__.model_validate(merged)

unrealon_core/models/bridge_stats.py

@@ -0,0 +1,58 @@
+"""
+Bridge Statistics Models
+
+Strictly typed models for WebSocket bridge statistics.
+Following critical requirements - no raw Dict[str, Any].
+
+Phase 2: Core Systems - Bridge Statistics
+"""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict
+
+from .base import UnrealOnBaseModel
+from ..utils.time import utc_now
+
+
+class BridgeStatsData(UnrealOnBaseModel):
+    """Internal bridge statistics data."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    tasks_sent: int = Field(default=0, description="Number of tasks sent")
+    tasks_failed: int = Field(default=0, description="Number of tasks failed")
+    configs_sent: int = Field(default=0, description="Number of configurations sent")
+    configs_failed: int = Field(default=0, description="Number of configurations failed")
+    messages_processed: int = Field(default=0, description="Number of messages processed")
+    start_time: str = Field(description="Start time ISO string")
+    
+    def increment_tasks_sent(self) -> None:
+        """Increment tasks sent counter."""
+        self.tasks_sent += 1
+    
+    def increment_tasks_failed(self) -> None:
+        """Increment tasks failed counter."""
+        self.tasks_failed += 1
+    
+    def increment_configs_sent(self) -> None:
+        """Increment configs sent counter."""
+        self.configs_sent += 1
+    
+    def increment_configs_failed(self) -> None:
+        """Increment configs failed counter."""
+        self.configs_failed += 1
+    
+    def increment_messages_processed(self) -> None:
+        """Increment messages processed counter."""
+        self.messages_processed += 1
+
+
+def create_initial_bridge_stats() -> BridgeStatsData:
+    """Create initial bridge statistics."""
+    return BridgeStatsData(
+        start_time=utc_now().isoformat()
+    )

unrealon_core/models/communication.py

@@ -0,0 +1,39 @@
+"""
+WebSocket Communication Models for UnrealOn RPC.
+
+CRITICAL REQUIREMENTS COMPLIANT:
+- No raw Dict[str, Any] usage
+- 100% Pydantic v2 validation  
+- Strict typing throughout
+- Files under 500 lines
+
+This file imports from strictly typed websocket models.
+All raw dictionaries have been replaced with Pydantic models.
+
+Phase 2: Core Systems - WebSocket Bridge
+"""
+
+# Import all strictly typed models from websocket package
+from .websocket import *
+from .websocket.logging import LogContext
+
+# Export commonly used data models for easy access
+__all__ = [
+    # Message types and base
+    'MessageType', 'WebSocketMessage',
+    
+    # Message classes
+    'DriverRegistrationMessage', 'RegistrationResponseMessage',
+    'TaskAssignmentMessage', 'TaskResultMessage', 
+    'LogEntryMessage', 'LogBatchMessage',
+    'HeartbeatMessage', 'ConfigurationUpdateMessage',
+    'ErrorMessage', 'AckMessage',
+    
+    # Data models for strict typing
+    'TaskAssignmentData', 'TaskResultData', 'TaskParameters',
+    'DriverRegistrationData', 'HeartbeatData', 'LogEntryData', 'LogContext',
+    
+    # Utilities
+    'create_error_message', 'create_ack_message',
+    
+]

unrealon_core/models/connection_stats.py

@@ -0,0 +1,47 @@
+"""
+Connection Statistics Models
+
+Strictly typed models for WebSocket connection statistics.
+Following critical requirements - no raw Dict[str, Any].
+
+Phase 2: Core Systems - Connection Statistics
+"""
+
+from pydantic import BaseModel, Field, ConfigDict
+
+from .base import UnrealOnBaseModel
+
+
+class ConnectionStatsData(UnrealOnBaseModel):
+    """Internal connection statistics data."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    total_connections: int = Field(default=0, description="Total connections made")
+    active_connections: int = Field(default=0, description="Currently active connections")
+    total_messages: int = Field(default=0, description="Total messages sent")
+    failed_messages: int = Field(default=0, description="Failed messages")
+    
+    def increment_total_connections(self) -> None:
+        """Increment total connections counter."""
+        self.total_connections += 1
+    
+    def set_active_connections(self, count: int) -> None:
+        """Set active connections count."""
+        self.active_connections = count
+    
+    def increment_total_messages(self) -> None:
+        """Increment total messages counter."""
+        self.total_messages += 1
+    
+    def increment_failed_messages(self) -> None:
+        """Increment failed messages counter."""
+        self.failed_messages += 1
+
+
+def create_initial_connection_stats() -> ConnectionStatsData:
+    """Create initial connection statistics."""
+    return ConnectionStatsData()

unrealon_core/models/driver.py

@@ -0,0 +1,30 @@
+"""
+Driver models - Phase 2 update.
+
+Import from strictly typed websocket models to avoid duplication.
+Following critical requirements - no raw Dict[str, Any].
+"""
+
+# Import strictly typed models from websocket package
+from .websocket.driver import (
+    DriverRegistrationData,
+    DriverMetadata,
+    DriverConfiguration,
+    RegistrationResponseData
+)
+
+# Legacy compatibility
+DriverInfo = DriverRegistrationData
+DriverConfig = DriverConfiguration
+DriverCapability = DriverMetadata
+
+__all__ = [
+    'DriverRegistrationData',
+    'DriverMetadata', 
+    'DriverConfiguration',
+    'RegistrationResponseData',
+    # Legacy names
+    'DriverInfo',
+    'DriverConfig',
+    'DriverCapability'
+]

unrealon_core/models/driver_details.py

@@ -0,0 +1,98 @@
+"""
+Driver Details Models
+
+Strictly typed models for driver information and statistics.
+Following critical requirements - no raw Dict[str, Any].
+
+Phase 2: Core Systems - Driver Details
+"""
+
+from datetime import datetime
+from typing import Optional, List
+from pydantic import BaseModel, Field, ConfigDict
+
+from .base import UnrealOnBaseModel
+
+
+class DriverDetails(UnrealOnBaseModel):
+    """Complete driver details with statistics."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    # Basic driver info
+    driver_id: str = Field(description="Driver ID")
+    driver_name: Optional[str] = Field(default=None, description="Driver name")
+    driver_type: str = Field(description="Driver type")
+    capabilities: List[str] = Field(default_factory=list, description="Driver capabilities")
+    version: Optional[str] = Field(default=None, description="Driver version")
+    
+    # Connection info
+    connection_id: str = Field(description="WebSocket connection ID")
+    status: str = Field(description="Driver status")
+    connected_at: datetime = Field(description="Connection timestamp")
+    last_seen: datetime = Field(description="Last activity timestamp")
+    
+    # Task statistics
+    active_tasks: int = Field(default=0, description="Number of active tasks")
+    completed_tasks: int = Field(default=0, description="Number of completed tasks")
+    failed_tasks: int = Field(default=0, description="Number of failed tasks")
+    
+    # Performance metrics
+    uptime_seconds: float = Field(default=0.0, description="Uptime in seconds")
+    memory_usage_mb: Optional[float] = Field(default=None, description="Memory usage in MB")
+    cpu_usage_percent: Optional[float] = Field(default=None, description="CPU usage percentage")
+
+
+class DriverInfo(UnrealOnBaseModel):
+    """Basic driver information."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    driver_id: str = Field(description="Driver ID")
+    connection_id: str = Field(description="WebSocket connection ID")
+    status: str = Field(description="Driver status")
+    last_heartbeat: Optional[datetime] = Field(default=None, description="Last heartbeat timestamp")
+
+
+class DriverListResult(UnrealOnBaseModel):
+    """Result of driver list query."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    drivers: List[DriverDetails] = Field(description="List of driver details")
+    total_count: int = Field(description="Total number of drivers")
+    filtered_count: int = Field(description="Number of drivers after filtering")
+    filter_applied: Optional[str] = Field(default=None, description="Filter that was applied")
+
+
+def create_driver_details_from_session(
+    driver_info: DriverInfo,
+    session: "DriverSession"
+) -> DriverDetails:
+    """Create DriverDetails from DriverInfo and DriverSession."""
+    return DriverDetails(
+        driver_id=driver_info.driver_id,
+        driver_name=getattr(session, 'driver_name', None),
+        driver_type=session.driver_type,
+        capabilities=session.capabilities,
+        version=getattr(session, 'version', None),
+        connection_id=session.connection_id,
+        status=session.status,
+        connected_at=session.connected_at,
+        last_seen=session.last_seen,
+        active_tasks=session.active_tasks,
+        completed_tasks=getattr(session, 'completed_tasks', 0),
+        failed_tasks=getattr(session, 'failed_tasks', 0),
+        uptime_seconds=(utc_now() - session.connected_at).total_seconds(),
+        memory_usage_mb=getattr(session, 'memory_usage_mb', None),
+        cpu_usage_percent=getattr(session, 'cpu_usage_percent', None)
+    )

unrealon_core/models/logging.py

@@ -0,0 +1,28 @@
+"""
+Logging models - Phase 2 update.
+
+Import from strictly typed websocket models to avoid duplication.
+Following critical requirements - no raw Dict[str, Any].
+"""
+
+# Import strictly typed models from websocket package
+from .websocket.logging import (
+    LogEntryData,
+    LogBatchData,
+    LogContext
+)
+
+# Legacy compatibility
+LogEntry = LogEntryData
+LogQuery = LogContext
+LogMetrics = LogBatchData
+
+__all__ = [
+    'LogEntryData',
+    'LogBatchData',
+    'LogContext',
+    # Legacy names
+    'LogEntry',
+    'LogQuery',
+    'LogMetrics'
+]

unrealon_core/models/task.py

@@ -0,0 +1,21 @@
+"""
+Task models - Phase 2 update.
+
+Import from strictly typed websocket models to avoid duplication.
+Following critical requirements - no raw Dict[str, Any].
+"""
+
+# Import strictly typed models from websocket package
+from .websocket.tasks import (
+    TaskAssignmentData,
+    TaskResultData,
+    TaskParameters,
+    TaskMetadata
+)
+
+__all__ = [
+    'TaskAssignmentData',
+    'TaskResultData',
+    'TaskParameters',
+    'TaskMetadata',
+]