omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/handlers/models/model_graph_handler_response.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Graph Handler Response Model.
+
+This module provides the Pydantic model for Graph handler response envelopes
+used by the HandlerGraph.
+
+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.graph import (
+    ModelGraphHandlerPayload,
+)
+
+
+class ModelGraphHandlerResponse(BaseModel):
+    """Full Graph handler response envelope.
+
+    Provides a standardized response format for Graph database (Memgraph/Neo4j)
+    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: Graph 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.graph import (
+        ...     ModelGraphHandlerPayload, ModelGraphQueryPayload,
+        ... )
+        >>> response = ModelGraphHandlerResponse(
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=ModelGraphHandlerPayload(
+        ...         data=ModelGraphQueryPayload(
+        ...             cypher="MATCH (n) RETURN n",
+        ...             records=[],
+        ...             summary={"nodes_created": 0},
+        ...         ),
+        ...     ),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(response.status)
+        <EnumResponseStatus.SUCCESS: 'success'>
+        >>> print(response.payload.data.operation_type)
+        'graph.query'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    status: EnumResponseStatus = Field(
+        description="Operation status indicator",
+    )
+    payload: ModelGraphHandlerPayload = Field(
+        description="Graph 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] = ["ModelGraphHandlerResponse"]

omnibase_infra/handlers/models/model_handler_response.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Generic Handler Response Model.
+
+This module provides a generic handler response model that can be parameterized
+with different payload types, enabling consistent response patterns across all
+infrastructure handlers.
+
+Usage Pattern:
+    Each handler defines its own payload model and uses ModelHandlerResponse[PayloadType]:
+
+    - HandlerConsul: ModelHandlerResponse[ModelConsulHandlerPayload]
+    - HandlerDb: ModelHandlerResponse[ModelDbQueryPayload]
+    - HandlerVault: ModelHandlerResponse[ModelVaultHandlerPayload]
+    - HttpRestHandler: ModelHandlerResponse[ModelHttpHandlerPayload]
+
+This replaces raw dict[str, JsonType] responses with strongly-typed models,
+ensuring consistent access patterns (response.status, response.payload, etc.)
+across all handlers.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumResponseStatus
+
+
+class ModelHandlerResponse[PayloadT: BaseModel](BaseModel):
+    """Generic handler response envelope.
+
+    Provides a standardized response format for all handler operations
+    with status, payload, and correlation tracking.
+
+    This generic model ensures consistent interfaces across all infrastructure
+    handlers. Each handler specializes this with its own payload type.
+
+    Type Parameters:
+        PayloadT: The payload model type specific to the handler.
+
+    Attributes:
+        status: Operation status ("success" or "error")
+        payload: Handler-specific result payload
+        correlation_id: UUID for request/response correlation
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from pydantic import BaseModel
+        >>> from omnibase_infra.enums import EnumResponseStatus
+        >>>
+        >>> class MyPayload(BaseModel):
+        ...     data: str
+        ...
+        >>> response = ModelHandlerResponse[MyPayload](
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=MyPayload(data="test"),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(response.status)
+        <EnumResponseStatus.SUCCESS: 'success'>
+        >>> print(response.payload.data)
+        'test'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    status: EnumResponseStatus = Field(
+        description="Operation status indicator",
+    )
+    payload: PayloadT = Field(
+        description="Handler-specific 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] = ["ModelHandlerResponse"]

omnibase_infra/handlers/models/model_http_handler_response.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""HTTP Handler Response Model.
+
+This module provides the Pydantic model for HTTP handler response envelopes
+used by the HttpRestHandler.
+
+This model provides type consistency with ModelDbQueryResponse,
+ModelConsulHandlerResponse, and ModelVaultHandlerResponse, 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.http import (
+    ModelHttpHandlerPayload,
+)
+
+
+class ModelHttpHandlerResponse(BaseModel):
+    """Full HTTP handler response envelope.
+
+    Provides a standardized response format for HTTP operations
+    with status, payload, and correlation tracking.
+
+    This model mirrors ModelDbQueryResponse, ModelConsulHandlerResponse,
+    and ModelVaultHandlerResponse to ensure consistent interfaces across
+    infrastructure handlers.
+
+    Attributes:
+        status: Operation status (EnumResponseStatus.SUCCESS or EnumResponseStatus.ERROR)
+        payload: HTTP 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.http import (
+        ...     ModelHttpGetPayload,
+        ...     ModelHttpHandlerPayload,
+        ... )
+        >>> response = ModelHttpHandlerResponse(
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=ModelHttpHandlerPayload(
+        ...         data=ModelHttpGetPayload(
+        ...             status_code=200,
+        ...             headers={"content-type": "application/json"},
+        ...             body={"message": "success"},
+        ...         ),
+        ...     ),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(response.status)
+        <EnumResponseStatus.SUCCESS: 'success'>
+        >>> print(response.payload.data.status_code)
+        200
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    status: EnumResponseStatus = Field(
+        description="Operation status indicator",
+    )
+    payload: ModelHttpHandlerPayload = Field(
+        description="HTTP 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] = ["ModelHttpHandlerResponse"]

omnibase_infra/handlers/models/model_manifest_metadata.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Metadata Model.
+
+This module provides the lightweight metadata model for manifest queries
+when full manifest data is not needed.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestMetadata(BaseModel):
+    """Lightweight metadata for a stored manifest.
+
+    Used when querying manifests with metadata_only=True to avoid
+    loading full manifest data. Contains only the essential fields
+    needed for listing, filtering, and identification.
+
+    Attributes:
+        manifest_id: The unique identifier of the manifest.
+        created_at: Timestamp when the manifest was created/stored.
+        correlation_id: The correlation ID from the manifest, if present.
+            Used for tracing related operations across the system.
+        node_id: The node ID from the manifest, if present.
+            Identifies which node generated this manifest.
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> metadata = ModelManifestMetadata(
+        ...     manifest_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+        ...     created_at=datetime.now(timezone.utc),
+        ...     correlation_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+        ...     node_id="registration-orchestrator",
+        ... )
+        >>> print(metadata.manifest_id)
+        UUID('550e8400-e29b-41d4-a716-446655440000')
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    manifest_id: UUID = Field(
+        description="Unique identifier of the manifest.",
+    )
+    created_at: datetime = Field(
+        description="Timestamp when the manifest was created/stored.",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID from the manifest for operation tracing.",
+    )
+    node_id: str | None = Field(
+        default=None,
+        description="Node ID identifying which node generated this manifest.",
+    )
+    file_path: str = Field(
+        min_length=1,
+        description="Absolute path to the manifest file.",
+    )
+    file_size: int = Field(
+        ge=0,
+        description="Size of the manifest file in bytes.",
+    )
+
+
+__all__: list[str] = ["ModelManifestMetadata"]

omnibase_infra/handlers/models/model_manifest_persistence_config.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Persistence Handler Configuration Model.
+
+This module provides the Pydantic model for HandlerManifestPersistence initialization
+configuration, defining storage path and optional settings.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestPersistenceConfig(BaseModel):
+    """Configuration for HandlerManifestPersistence initialization.
+
+    This model defines the configuration parameters required to initialize
+    the manifest persistence handler, including the storage path for manifests.
+
+    Attributes:
+        storage_path: Base directory for manifest storage. Manifests will be
+            stored in date-partitioned subdirectories: {storage_path}/{year}/{month}/{day}/
+        max_file_size: Maximum manifest file size in bytes for read operations.
+            If None, uses default (50 MB).
+        correlation_id: Optional correlation ID for initialization tracing.
+
+    Example:
+        >>> config = ModelManifestPersistenceConfig(
+        ...     storage_path="/data/manifests",
+        ...     max_file_size=100 * 1024 * 1024,  # 100 MB
+        ... )
+        >>> print(config.storage_path)
+        '/data/manifests'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    storage_path: str = Field(
+        min_length=1,
+        description="Base directory path for manifest storage. "
+        "Manifests are stored in date-partitioned subdirectories.",
+    )
+    max_file_size: int | None = Field(
+        default=None,
+        gt=0,
+        description="Maximum manifest file size in bytes for read operations. "
+        "If None, uses default (50 MB).",
+    )
+    correlation_id: UUID | str | None = Field(
+        default=None,
+        description="Optional correlation ID for initialization tracing.",
+    )
+
+
+__all__: list[str] = ["ModelManifestPersistenceConfig"]

omnibase_infra/handlers/models/model_manifest_query_payload.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Query Payload Model.
+
+This module provides the Pydantic model for the manifest.query operation
+payload, supporting flexible filtering by correlation ID, node ID, and
+time ranges.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestQueryPayload(BaseModel):
+    """Payload for manifest.query operation.
+
+    Specifies filter criteria for querying stored manifests. All filter
+    fields are optional and combined with AND logic when multiple are
+    specified.
+
+    Attributes:
+        correlation_id: Filter by correlation ID. Only manifests with
+            this exact correlation_id will be returned.
+        node_id: Filter by node ID. Only manifests with this exact
+            node_id will be returned.
+        created_after: Filter by creation time. Only manifests created
+            at or after this timestamp will be returned.
+        created_before: Filter by creation time. Only manifests created
+            at or before this timestamp will be returned.
+        limit: Maximum number of manifests to return. Defaults to 100.
+            Use to prevent excessive memory usage on large result sets.
+        metadata_only: If True, return only lightweight metadata instead
+            of full manifest data. Useful for listing/browsing operations.
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> payload = ModelManifestQueryPayload(
+        ...     node_id="mynode",
+        ...     created_after=datetime(2025, 1, 1, tzinfo=timezone.utc),
+        ...     limit=50,
+        ... )
+        >>> print(payload.metadata_only)
+        False
+
+        >>> metadata_payload = ModelManifestQueryPayload(
+        ...     metadata_only=True,
+        ...     limit=1000,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Filter by exact correlation ID match.",
+    )
+    node_id: str | None = Field(
+        default=None,
+        description="Filter by exact node ID match.",
+    )
+    created_after: datetime | None = Field(
+        default=None,
+        description="Filter for manifests created at or after this timestamp.",
+    )
+    created_before: datetime | None = Field(
+        default=None,
+        description="Filter for manifests created at or before this timestamp.",
+    )
+    limit: int = Field(
+        default=100,
+        ge=1,
+        le=10000,
+        description="Maximum number of manifests to return (1-10000).",
+    )
+    metadata_only: bool = Field(
+        default=False,
+        description="If True, return only metadata instead of full manifests.",
+    )
+
+
+__all__: list[str] = ["ModelManifestQueryPayload"]

omnibase_infra/handlers/models/model_manifest_query_result.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Query Result Model.
+
+This module provides the Pydantic model for the manifest.query operation
+result, containing the list of matching manifests or metadata.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.handlers.models.model_manifest_metadata import ModelManifestMetadata
+
+
+class ModelManifestQueryResult(BaseModel):
+    """Result from manifest.query operation.
+
+    Contains matching manifests based on the query filters. Uses separate
+    fields for metadata-only and full-manifest results to maintain type safety.
+
+    Attributes:
+        manifests: List of matching manifest metadata (when metadata_only=True).
+            Empty list when metadata_only=False.
+        manifest_data: List of full manifest dictionaries (when metadata_only=False).
+            Empty list when metadata_only=True.
+        total_count: Number of results returned.
+        metadata_only: Whether results contain only metadata.
+
+    Note:
+        This model implements custom __bool__ behavior. The boolean value
+        of an instance reflects whether any manifests were found, enabling
+        idiomatic conditional checks like:
+
+            result = handler.query(payload)
+            if result:  # True only when total_count > 0
+                for manifest in result.manifests:
+                    process(manifest)
+
+    Example:
+        >>> result = ModelManifestQueryResult(
+        ...     manifests=[ModelManifestMetadata(...)],
+        ...     manifest_data=[],
+        ...     total_count=1,
+        ...     metadata_only=True,
+        ... )
+        >>> print(bool(result))
+        True
+
+        >>> empty_result = ModelManifestQueryResult(
+        ...     manifests=[],
+        ...     manifest_data=[],
+        ...     total_count=0,
+        ...     metadata_only=False,
+        ... )
+        >>> print(bool(empty_result))
+        False
+    """
+
+    model_config = ConfigDict(
+        strict=False,  # Allow dict with various value types
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    manifests: list[ModelManifestMetadata] = Field(
+        default_factory=list,
+        description="List of matching manifest metadata (when metadata_only=True).",
+    )
+    manifest_data: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="List of full manifest dictionaries (when metadata_only=False).",
+    )
+    total_count: int = Field(
+        ge=0,
+        description="Number of results returned.",
+    )
+    metadata_only: bool = Field(
+        description="True if results contain metadata only, False for full manifests.",
+    )
+
+    def __bool__(self) -> bool:
+        """Return True if any manifests were found.
+
+        Warning:
+            This differs from standard Pydantic model behavior where
+            bool(model) always returns True. This model returns True
+            only when total_count > 0, enabling idiomatic conditional checks.
+
+        Returns:
+            True if total_count > 0, False otherwise.
+        """
+        return self.total_count > 0
+
+
+__all__: list[str] = ["ModelManifestQueryResult"]

omnibase_infra/handlers/models/model_manifest_retrieve_payload.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Manifest Retrieve Payload Model.
+
+This module provides the Pydantic model for the manifest.retrieve operation
+payload, specifying which manifest to retrieve by ID.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelManifestRetrievePayload(BaseModel):
+    """Payload for manifest.retrieve operation.
+
+    Specifies the manifest to retrieve by its unique identifier.
+
+    Attributes:
+        manifest_id: The unique identifier of the manifest to retrieve.
+            This corresponds to the manifest_id field in the stored
+            ModelExecutionManifest.
+
+    Example:
+        >>> payload = ModelManifestRetrievePayload(
+        ...     manifest_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    manifest_id: UUID = Field(
+        description="Unique identifier of the manifest to retrieve.",
+    )
+
+
+__all__: list[str] = ["ModelManifestRetrievePayload"]