omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/handlers/models/model_manifest_retrieve_result.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Retrieve Result Model.
+
+This module provides the Pydantic model for the manifest.retrieve operation
+result, containing the retrieved manifest or indication of not found.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestRetrieveResult(BaseModel):
+    """Result from manifest.retrieve operation.
+
+    Contains the retrieved manifest data and metadata, or indicates that
+    the requested manifest was not found.
+
+    Attributes:
+        manifest_id: The unique identifier of the manifest that was queried.
+        manifest: The serialized ModelExecutionManifest as a dictionary,
+            or None if the manifest was not found. When present, this can
+            be passed to ModelExecutionManifest.model_validate() to
+            reconstruct the original manifest object.
+        file_path: The absolute path where the manifest was found,
+            or None if the manifest was not found.
+        found: True if the manifest was found and retrieved, False if
+            no manifest exists with the requested ID.
+
+    Note:
+        This model implements custom __bool__ behavior. The boolean value
+        of an instance reflects the 'found' status, enabling idiomatic
+        conditional checks like:
+
+            result = handler.retrieve(manifest_id)
+            if result:  # True only when found=True
+                process_manifest(result.manifest)
+
+    Example:
+        >>> from uuid import UUID
+        >>> result = ModelManifestRetrieveResult(
+        ...     manifest_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+        ...     manifest={"manifest_id": "...", "node_id": "..."},
+        ...     file_path="/data/manifests/2025/01/15/550e8400.json",
+        ...     found=True,
+        ... )
+        >>> print(bool(result))
+        True
+
+        >>> not_found = ModelManifestRetrieveResult(
+        ...     manifest_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+        ...     manifest=None,
+        ...     file_path=None,
+        ...     found=False,
+        ... )
+        >>> print(bool(not_found))
+        False
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    manifest_id: UUID = Field(
+        description="Unique identifier of the manifest that was queried.",
+    )
+    manifest: dict[str, object] | None = Field(
+        description="Serialized manifest dictionary, or None if not found.",
+    )
+    file_path: str | None = Field(
+        default=None,
+        description="Absolute path where manifest was found, or None if not found.",
+    )
+    found: bool = Field(
+        description="True if manifest was found, False otherwise.",
+    )
+
+    def __bool__(self) -> bool:
+        """Return True if manifest was found.
+
+        Warning:
+            This differs from standard Pydantic model behavior where
+            bool(model) always returns True. This model returns True
+            only when found=True, enabling idiomatic conditional checks.
+
+        Returns:
+            True if found=True, False otherwise.
+        """
+        return self.found
+
+
+__all__: list[str] = ["ModelManifestRetrieveResult"]

omnibase_infra/handlers/models/model_manifest_store_payload.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Store Payload Model.
+
+This module provides the Pydantic model for the manifest.store operation
+payload, containing the serialized ModelExecutionManifest to persist.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestStorePayload(BaseModel):
+    """Payload for manifest.store operation.
+
+    Contains the serialized execution manifest to be persisted. The manifest
+    is stored as a dictionary to allow flexible schema evolution while
+    maintaining the ability to deserialize back to ModelExecutionManifest.
+
+    Attributes:
+        manifest: The serialized ModelExecutionManifest as a dictionary.
+            This should be the result of calling .model_dump() on a
+            ModelExecutionManifest instance. The manifest_id field within
+            the manifest is used as the storage key.
+
+    Example:
+        >>> from omnibase_core.models import ModelExecutionManifest
+        >>> manifest = ModelExecutionManifest(...)
+        >>> payload = ModelManifestStorePayload(
+        ...     manifest=manifest.model_dump()
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    manifest: dict[str, object] = Field(
+        description="Serialized ModelExecutionManifest dictionary from model_dump().",
+    )
+
+
+__all__: list[str] = ["ModelManifestStorePayload"]

omnibase_infra/handlers/models/model_manifest_store_result.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Store Result Model.
+
+This module provides the Pydantic model for the manifest.store operation
+result, containing storage metadata and idempotency status.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestStoreResult(BaseModel):
+    """Result from manifest.store operation.
+
+    Contains metadata about the completed store operation, including
+    the storage location and whether a new manifest was created.
+
+    Attributes:
+        manifest_id: The unique identifier of the stored manifest,
+            extracted from the input manifest's manifest_id field.
+        file_path: The resolved absolute filesystem path where the manifest
+            was stored (e.g., /var/lib/onex/manifests/2025/01/14/{id}.json).
+        created: True if a new manifest was created, False if a manifest
+            with the same ID already existed (idempotent operation).
+            When False, the existing manifest is not overwritten.
+        bytes_written: Number of bytes written to storage. Zero if the
+            manifest already existed (idempotent, no overwrite).
+
+    Example:
+        >>> result = ModelManifestStoreResult(
+        ...     manifest_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+        ...     file_path="/var/lib/onex/manifests/2025/01/14/550e8400.json",
+        ...     created=True,
+        ...     bytes_written=4096,
+        ... )
+        >>> print(result.created)
+        True
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    manifest_id: UUID = Field(
+        description="Unique identifier of the stored manifest.",
+    )
+    file_path: str = Field(
+        min_length=1,
+        description="Resolved absolute path where the manifest was stored.",
+    )
+    created: bool = Field(
+        description="True if new manifest created, False if already existed (idempotent).",
+    )
+    bytes_written: int = Field(
+        ge=0,
+        description="Number of bytes written. Zero if manifest already existed.",
+    )
+
+
+__all__: list[str] = ["ModelManifestStoreResult"]

omnibase_infra/handlers/models/model_operation_context.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Operation Context Model for handler tracking.
+
+This module provides a Pydantic model for encapsulating operation context
+during handler execution, enabling consistent tracking and tracing.
+"""
+
+from __future__ import annotations
+
+import time
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOperationContext(BaseModel):
+    """Encapsulates operation context for handler tracking.
+
+    This model provides a strongly-typed container for operation metadata,
+    replacing scattered local variables with a cohesive context object.
+
+    Attributes:
+        correlation_id: UUID for distributed tracing across services
+        operation_name: Name of the operation being executed
+        started_at: Unix timestamp when the operation started
+        timeout_seconds: Maximum allowed execution time
+        metadata: Additional key-value pairs for operation-specific context
+
+    Example:
+        >>> ctx = ModelOperationContext.create("consul.kv_get")
+        >>> ctx.operation_name
+        'consul.kv_get'
+        >>> ctx.is_timed_out()
+        False
+
+    ID Semantics:
+        correlation_id: Groups related operations across distributed services.
+            Used for filtering logs, tracing request flows, and debugging.
+            Propagated from request envelopes for consistent distributed tracing.
+
+    Security:
+        The metadata field should contain SANITIZED values only.
+        Never include credentials, tokens, or other sensitive data.
+        See CLAUDE.md "Error Sanitization Guidelines" for the security policy.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    correlation_id: UUID = Field(
+        description="UUID for distributed tracing across services",
+    )
+    operation_name: str = Field(
+        description="Name of the operation being executed",
+    )
+    started_at: float = Field(
+        description="Unix timestamp when the operation started",
+    )
+    timeout_seconds: float = Field(
+        default=30.0,
+        ge=0.0,
+        le=3600.0,
+        description="Maximum allowed execution time in seconds",
+    )
+    metadata: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional key-value pairs for operation-specific context",
+    )
+
+    @classmethod
+    def create(
+        cls,
+        operation_name: str,
+        correlation_id: UUID | None = None,
+        timeout_seconds: float = 30.0,
+        metadata: dict[str, str] | None = None,
+    ) -> ModelOperationContext:
+        """Create a new operation context with current timestamp.
+
+        Args:
+            operation_name: Name of the operation being executed
+            correlation_id: Optional UUID for tracing (auto-generated if None)
+            timeout_seconds: Maximum allowed execution time (default: 30.0)
+            metadata: Optional additional key-value pairs
+
+        Returns:
+            New ModelOperationContext with current timestamp.
+
+        Example:
+            >>> ctx = ModelOperationContext.create("vault.read_secret")
+            >>> ctx.operation_name
+            'vault.read_secret'
+        """
+        return cls(
+            correlation_id=correlation_id if correlation_id is not None else uuid4(),
+            operation_name=operation_name,
+            started_at=time.time(),
+            timeout_seconds=timeout_seconds,
+            metadata=metadata if metadata is not None else {},
+        )
+
+    def elapsed_seconds(self) -> float:
+        """Calculate elapsed time since operation started.
+
+        Returns:
+            Elapsed time in seconds since started_at.
+
+        Note:
+            Calls time.time() on each invocation. Multiple calls within
+            a tight loop may return slightly different values.
+        """
+        return time.time() - self.started_at
+
+    def remaining_seconds(self) -> float:
+        """Calculate remaining time before timeout.
+
+        Returns:
+            Remaining time in seconds (can be negative if timed out).
+
+        Note:
+            Calls elapsed_seconds() internally, which uses time.time().
+            Multiple calls may return slightly different values.
+        """
+        return self.timeout_seconds - self.elapsed_seconds()
+
+    def is_timed_out(self) -> bool:
+        """Check if the operation has exceeded its timeout.
+
+        Returns:
+            True if elapsed time exceeds timeout_seconds, False otherwise.
+
+        Note:
+            Calls elapsed_seconds() internally, which uses time.time().
+            Result may change between calls if near the timeout boundary.
+        """
+        return self.elapsed_seconds() > self.timeout_seconds
+
+    def with_metadata(self, key: str, value: str) -> ModelOperationContext:
+        """Create a copy with additional metadata.
+
+        Args:
+            key: Metadata key
+            value: Metadata value (must be sanitized)
+
+        Returns:
+            New ModelOperationContext with updated metadata.
+
+        Note:
+            Values should be sanitized before calling this method.
+        """
+        new_metadata = dict(self.metadata)
+        new_metadata[key] = value
+        return ModelOperationContext(
+            correlation_id=self.correlation_id,
+            operation_name=self.operation_name,
+            started_at=self.started_at,
+            timeout_seconds=self.timeout_seconds,
+            metadata=new_metadata,
+        )
+
+    def with_operation_name(self, operation_name: str) -> ModelOperationContext:
+        """Create a copy with a different operation name.
+
+        Useful when a handler routes to sub-operations while preserving
+        the correlation_id and timing context.
+
+        Args:
+            operation_name: New operation name
+
+        Returns:
+            New ModelOperationContext with updated operation_name.
+        """
+        return ModelOperationContext(
+            correlation_id=self.correlation_id,
+            operation_name=operation_name,
+            started_at=self.started_at,
+            timeout_seconds=self.timeout_seconds,
+            metadata=self.metadata,
+        )
+
+
+__all__: list[str] = ["ModelOperationContext"]

omnibase_infra/handlers/models/model_qdrant_handler_response.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Qdrant Handler Response Model.
+
+This module provides the Pydantic model for Qdrant handler response envelopes
+used by the HandlerQdrant.
+
+This model provides type consistency with ModelDbQueryResponse and
+ModelConsulHandlerResponse, ensuring all handlers return strongly-typed
+Pydantic models with consistent interfaces (status, payload, correlation_id).
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumResponseStatus
+from omnibase_infra.handlers.models.qdrant import (
+    ModelQdrantHandlerPayload,
+)
+
+
+class ModelQdrantHandlerResponse(BaseModel):
+    """Full Qdrant handler response envelope.
+
+    Provides a standardized response format for Qdrant vector database
+    operations with status, payload, and correlation tracking.
+
+    This model mirrors ModelConsulHandlerResponse and ModelDbQueryResponse
+    to ensure consistent interfaces across infrastructure handlers.
+
+    Attributes:
+        status: Operation status (EnumResponseStatus.SUCCESS or EnumResponseStatus.ERROR)
+        payload: Qdrant operation result payload containing operation-specific data
+        correlation_id: UUID for request/response correlation
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumResponseStatus
+        >>> from omnibase_infra.handlers.models.qdrant import (
+        ...     ModelQdrantHandlerPayload, ModelQdrantSearchPayload,
+        ... )
+        >>> response = ModelQdrantHandlerResponse(
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=ModelQdrantHandlerPayload(
+        ...         data=ModelQdrantSearchPayload(
+        ...             collection_name="test_collection",
+        ...             results=[],
+        ...             limit=10,
+        ...         ),
+        ...     ),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(response.status)
+        <EnumResponseStatus.SUCCESS: 'success'>
+        >>> print(response.payload.data.operation_type)
+        'qdrant.search'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    status: EnumResponseStatus = Field(
+        description="Operation status indicator",
+    )
+    payload: ModelQdrantHandlerPayload = Field(
+        description="Qdrant operation result payload",
+    )
+    correlation_id: UUID = Field(
+        description="UUID for request/response correlation",
+    )
+
+    @property
+    def is_success(self) -> bool:
+        """Check if the response indicates a successful operation.
+
+        Returns:
+            True if status is SUCCESS, False otherwise.
+        """
+        return self.status == EnumResponseStatus.SUCCESS
+
+    @property
+    def is_error(self) -> bool:
+        """Check if the response indicates an error.
+
+        Returns:
+            True if status is ERROR, False otherwise.
+        """
+        return self.status == EnumResponseStatus.ERROR
+
+
+__all__: list[str] = ["ModelQdrantHandlerResponse"]

omnibase_infra/handlers/models/model_retry_state.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Retry State Model for handler operations.
+
+This module provides a Pydantic model for encapsulating retry state during
+handler operation execution with exponential backoff.
+"""
+
+from __future__ import annotations
+
+import time
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelRetryState(BaseModel):
+    """Encapsulates retry state for handler operations.
+
+    This model tracks the runtime state during retry loops, providing
+    a strongly-typed alternative to scattered local variables.
+
+    Attributes:
+        attempt: Current retry attempt number (0-based, starts at 0)
+        max_attempts: Maximum number of retry attempts allowed
+        delay_seconds: Current delay before next retry (calculated with backoff)
+        backoff_multiplier: Exponential backoff multiplier for delay calculation
+        last_error: Description of the last error encountered (sanitized)
+        last_attempt_at: Unix timestamp of the last attempt (None if not yet attempted)
+
+    Example:
+        >>> state = ModelRetryState(max_attempts=3)
+        >>> state.is_retriable()
+        True
+        >>> state = state.next_attempt("Connection failed")
+        >>> state.attempt
+        1
+
+    Note:
+        The last_error field should contain SANITIZED error descriptions only.
+        Never include credentials, tokens, or other sensitive data in this field.
+        See CLAUDE.md "Error Sanitization Guidelines" for the security policy.
+
+    Design Rationale:
+        This model stores error messages as strings rather than exception objects.
+        This trade-off ensures: (1) immutability (frozen=True), (2) serialization
+        safety for logging/persistence, and (3) model simplicity. The original
+        exception should be handled by the caller if traceback preservation is
+        needed (e.g., wrap in try/except and log before calling next_attempt()).
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    attempt: int = Field(
+        default=0,
+        ge=0,
+        description="Current retry attempt number (0-based)",
+    )
+    max_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=100,
+        description="Maximum number of retry attempts allowed",
+    )
+    delay_seconds: float = Field(
+        default=1.0,
+        ge=0.0,
+        description="Current delay in seconds before next retry",
+    )
+    backoff_multiplier: float = Field(
+        default=2.0,
+        ge=1.0,
+        le=10.0,
+        description="Exponential backoff multiplier for delay calculation",
+    )
+    last_error: str | None = Field(
+        default=None,
+        description="Sanitized description of the last error encountered",
+    )
+    last_attempt_at: float | None = Field(
+        default=None,
+        description="Unix timestamp of the last attempt",
+    )
+
+    def is_retriable(self) -> bool:
+        """Check if more retry attempts are allowed.
+
+        Returns:
+            True if current attempt is less than max_attempts, False otherwise.
+        """
+        return self.attempt < self.max_attempts
+
+    def is_final_attempt(self) -> bool:
+        """Check if this is the final retry attempt.
+
+        Returns:
+            True if this is the last allowed attempt, False otherwise.
+        """
+        return self.attempt >= self.max_attempts - 1
+
+    def next_attempt(
+        self,
+        error_message: str | None = None,
+        timestamp: float | None = None,
+        max_delay_seconds: float = 300.0,
+    ) -> ModelRetryState:
+        """Create a new state for the next retry attempt.
+
+        Args:
+            error_message: Sanitized description of the error (optional)
+            timestamp: Unix timestamp of this attempt (optional, for testing)
+            max_delay_seconds: Maximum delay cap for backoff calculation
+
+        Returns:
+            New ModelRetryState with incremented attempt and calculated delay.
+
+        Example:
+            >>> state = ModelRetryState(delay_seconds=1.0, backoff_multiplier=2.0)
+            >>> next_state = state.next_attempt("Connection timeout")
+            >>> next_state.attempt
+            1
+            >>> next_state.delay_seconds  # 1.0 * 2.0 = 2.0
+            2.0
+        """
+        new_delay = min(
+            self.delay_seconds * self.backoff_multiplier,
+            max_delay_seconds,
+        )
+
+        return ModelRetryState(
+            attempt=self.attempt + 1,
+            max_attempts=self.max_attempts,
+            delay_seconds=new_delay,
+            backoff_multiplier=self.backoff_multiplier,
+            last_error=error_message,
+            last_attempt_at=timestamp if timestamp is not None else time.time(),
+        )
+
+    def with_initial_delay(self, initial_delay: float) -> ModelRetryState:
+        """Create a copy with a new initial delay value.
+
+        Args:
+            initial_delay: New delay value in seconds
+
+        Returns:
+            New ModelRetryState with updated delay_seconds.
+        """
+        return ModelRetryState(
+            attempt=self.attempt,
+            max_attempts=self.max_attempts,
+            delay_seconds=initial_delay,
+            backoff_multiplier=self.backoff_multiplier,
+            last_error=self.last_error,
+            last_attempt_at=self.last_attempt_at,
+        )
+
+
+__all__: list[str] = ["ModelRetryState"]