ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/api/emergency.py

@@ -0,0 +1,111 @@
+"""
+Emergency shutdown schemas for CIRIS API v2.0.
+
+Provides cryptographically signed emergency shutdown capability
+that bypasses normal authentication for critical situations.
+"""
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EmergencyShutdownCommand(BaseModel):
+    """
+    Emergency shutdown command with cryptographic signature.
+
+    Must be signed by a ROOT or AUTHORITY key to be valid.
+    Timestamp must be within 5 minutes to prevent replay attacks.
+    """
+
+    action: Literal["emergency_shutdown"] = Field(
+        "emergency_shutdown", description="Action type (always 'emergency_shutdown')"
+    )
+    reason: str = Field(..., description="Reason for emergency shutdown", min_length=1, max_length=500)
+    timestamp: str = Field(..., description="ISO format timestamp of command creation")
+    force: bool = Field(True, description="Force immediate shutdown without graceful cleanup")
+    signature: str = Field(..., description="HMAC-SHA256 signature of command")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "action": "emergency_shutdown",
+                "reason": "Critical security breach detected",
+                "timestamp": "2025-01-01T12:00:00Z",
+                "force": True,
+                "signature": "a1b2c3d4e5f6...",
+            }
+        }
+    )
+
+
+class EmergencyShutdownResponse(BaseModel):
+    """Response to emergency shutdown command."""
+
+    status: str = Field(..., description="Command status (accepted/rejected)")
+    message: str = Field(..., description="Human-readable status message")
+    authority: Optional[str] = Field(None, description="Authority ID who issued the command")
+    timestamp: datetime = Field(..., description="When command was processed")
+    shutdown_initiated: bool = Field(..., description="Whether shutdown was initiated")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "status": "accepted",
+                "message": "Emergency shutdown initiated",
+                "authority": "ROOT",
+                "timestamp": "2025-01-01T12:00:05Z",
+                "shutdown_initiated": True,
+            }
+        }
+    )
+
+
+class EmergencyStatus(BaseModel):
+    """Current emergency system status."""
+
+    emergency_system_ready: bool = Field(..., description="Whether emergency system is operational")
+    trusted_authorities: int = Field(..., description="Number of trusted authority keys configured")
+    last_emergency_command: Optional[datetime] = Field(None, description="Timestamp of last emergency command")
+    failed_attempts_24h: int = Field(0, description="Failed emergency attempts in last 24 hours")
+
+
+class EmergencySignatureResult(BaseModel):
+    """Result of emergency shutdown signature verification."""
+
+    valid: bool = Field(..., description="Whether signature is valid")
+    authority_id: Optional[str] = Field(None, description="Authority ID if valid")
+    reason: Optional[str] = Field(None, description="Reason for invalid signature")
+
+
+class EmergencyAuditEntry(BaseModel):
+    """Audit entry for emergency shutdown attempts."""
+
+    timestamp: datetime = Field(..., description="When attempt occurred")
+    success: bool = Field(..., description="Whether shutdown was initiated")
+    authority_id: Optional[str] = Field(None, description="Authority ID if valid")
+    reason: str = Field(..., description="Shutdown reason provided")
+    failure_reason: Optional[str] = Field(None, description="Why command failed if applicable")
+    source_ip: Optional[str] = Field(None, description="Source IP address")
+
+
+class TrustedAuthority(BaseModel):
+    """Trusted authority for emergency shutdown."""
+
+    authority_id: str = Field(..., description="Unique authority identifier")
+    public_key: str = Field(..., description="Public key for signature verification")
+    role: str = Field(..., description="Role (ROOT or AUTHORITY)")
+    added_at: datetime = Field(..., description="When authority was added")
+    added_by: str = Field(..., description="Who added this authority")
+    is_active: bool = Field(True, description="Whether authority is active")
+
+
+__all__ = [
+    "EmergencyShutdownCommand",
+    "EmergencyShutdownResponse",
+    "EmergencyStatus",
+    "EmergencySignatureResult",
+    "EmergencyAuditEntry",
+    "TrustedAuthority",
+]

ciris_engine/schemas/api/responses.py

@@ -0,0 +1,72 @@
+"""
+Base response schemas for CIRIS API v1.
+
+All API responses follow these patterns - NO Dict[str, Any]!
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Generic, Optional, TypeVar
+
+from pydantic import BaseModel, Field, field_serializer
+
+from ciris_engine.schemas.types import JSONDict
+from ciris_engine.utils.serialization import serialize_timestamp
+
+T = TypeVar("T")
+
+
+class ResponseMetadata(BaseModel):
+    """Metadata included with all responses."""
+
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    request_id: Optional[str] = Field(None, description="Request tracking ID")
+    duration_ms: Optional[int] = Field(None, description="Request processing duration")
+
+    @field_serializer("timestamp")
+    def serialize_ts(self, timestamp: datetime, _info: Any) -> Optional[str]:
+        return serialize_timestamp(timestamp, _info)
+
+
+class SuccessResponse(BaseModel, Generic[T]):
+    """Standard success response wrapper."""
+
+    data: T = Field(..., description="Response data")
+    metadata: ResponseMetadata = Field(
+        default_factory=lambda: ResponseMetadata(
+            timestamp=datetime.now(timezone.utc), request_id=None, duration_ms=None
+        )
+    )
+
+
+class ErrorDetail(BaseModel):
+    """Detailed error information."""
+
+    code: str = Field(..., description="Error code (e.g., RESOURCE_NOT_FOUND)")
+    message: str = Field(..., description="Human-readable error message")
+    details: Optional[JSONDict] = Field(None, description="Additional error context")
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response."""
+
+    error: ErrorDetail = Field(..., description="Error information")
+    metadata: ResponseMetadata = Field(
+        default_factory=lambda: ResponseMetadata(
+            timestamp=datetime.now(timezone.utc), request_id=None, duration_ms=None
+        )
+    )
+
+
+# Common error codes
+class ErrorCode:
+    """Standard error codes used across the API."""
+
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"
+    INVALID_REQUEST = "INVALID_REQUEST"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+    RATE_LIMITED = "RATE_LIMITED"
+    CONFLICT = "CONFLICT"
+    VALIDATION_ERROR = "VALIDATION_ERROR"

ciris_engine/schemas/api/runtime.py

@@ -0,0 +1,26 @@
+"""
+Runtime API response schemas - fully typed replacements for Dict[str, Any].
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class StateTransitionResult(BaseModel):
+    """Result of state transition request."""
+
+    success: bool = Field(..., description="Whether transition succeeded")
+    target_state: str = Field(..., description="Requested target state")
+    current_state: str = Field(..., description="Current state after request")
+    reason: str = Field(..., description="Reason for transition")
+    transition_time_ms: Optional[float] = Field(None, description="Time taken for transition")
+
+
+class ProcessingSpeedResult(BaseModel):
+    """Result of processing speed change."""
+
+    success: bool = Field(..., description="Whether speed change succeeded")
+    multiplier: float = Field(..., description="New speed multiplier")
+    description: str = Field(..., description="Human-readable description")
+    effective_immediately: bool = Field(True, description="Whether change is immediate")

ciris_engine/schemas/api/telemetry.py

@@ -0,0 +1,109 @@
+"""
+Telemetry API response schemas - fully typed replacements for Dict[str, Any].
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_serializer
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class MetricTags(BaseModel):
+    """Standard metric tags."""
+
+    service: Optional[str] = Field(None, description="Source service")
+    operation: Optional[str] = Field(None, description="Operation name")
+    model: Optional[str] = Field(None, description="Model used (for LLM metrics)")
+    status: Optional[str] = Field(None, description="Operation status")
+    environment: Optional[str] = Field(None, description="Environment (prod/dev)")
+
+
+class ServiceMetricValue(BaseModel):
+    """Metric value broken down by service."""
+
+    service_name: str = Field(..., description="Service name")
+    value: float = Field(..., description="Metric value")
+    percentage: Optional[float] = Field(None, description="Percentage of total")
+
+
+class APIResponseThoughtStep(BaseModel):
+    """Individual thought step in API reasoning response."""
+
+    step: int = Field(..., description="Step number")
+    content: str = Field(..., description="Thought content")
+    timestamp: datetime = Field(..., description="When thought occurred")
+    depth: int = Field(0, description="Reasoning depth")
+    action: Optional[str] = Field(None, description="Action taken")
+    confidence: Optional[float] = Field(None, description="Confidence level")
+
+
+# Backward compatibility alias - will be removed in future
+ThoughtStep = APIResponseThoughtStep
+
+
+class LogContext(BaseModel):
+    """Structured log context."""
+
+    trace_id: Optional[str] = Field(None, description="Trace ID for correlation")
+    correlation_id: Optional[str] = Field(None, description="Correlation ID")
+    user_id: Optional[str] = Field(None, description="User ID if applicable")
+    entity_id: Optional[str] = Field(None, description="Entity being operated on")
+    error_details: Optional[JSONDict] = Field(None, description="Error specifics if error log")
+    metadata: Optional[JSONDict] = Field(None, description="Additional metadata")
+
+
+class QueryFilter(BaseModel):
+    """Structured query filter."""
+
+    field: str = Field(..., description="Field to filter on")
+    operator: str = Field("eq", description="Filter operator (eq, gt, lt, contains, etc)")
+    value: str = Field(..., description="Filter value")
+
+
+class TelemetryQueryFilters(BaseModel):
+    """Telemetry query filters."""
+
+    metric_names: Optional[List[str]] = Field(None, description="Metrics to query")
+    metrics: Optional[List[str]] = Field(None, description="Metrics to query (alias)")
+    services: Optional[List[str]] = Field(None, description="Services to include")
+    tags: Optional[Dict[str, str]] = Field(None, description="Tag filters")
+    severity: Optional[str] = Field(None, description="Log severity filter")
+    status: Optional[str] = Field(None, description="Status filter for incidents")
+    category: Optional[str] = Field(None, description="Category filter")
+    aggregation: Optional[str] = Field(None, description="Aggregation method")
+    limit: Optional[int] = Field(None, description="Result limit override")
+
+
+class QueryResult(BaseModel):
+    """Individual query result."""
+
+    id: str = Field(..., description="Result ID")
+    type: str = Field(..., description="Result type")
+    timestamp: datetime = Field(..., description="Result timestamp")
+    data: JSONDict = Field(..., description="Result data (type-specific)")
+
+
+class TimeSyncStatus(BaseModel):
+    """Time synchronization status."""
+
+    synchronized: bool = Field(..., description="Whether time is synchronized")
+    drift_ms: float = Field(..., description="Time drift in milliseconds")
+    last_sync: datetime = Field(..., description="Last sync timestamp")
+    sync_source: str = Field(..., description="Sync source (system/mock/ntp)")
+
+    @field_serializer("last_sync")
+    def serialize_last_sync(self, dt: datetime, _info: Any) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+class ServiceMetrics(BaseModel):
+    """Service-specific metrics."""
+
+    uptime_seconds: Optional[float] = Field(None, description="Service uptime")
+    requests_handled: Optional[int] = Field(None, description="Total requests")
+    error_count: Optional[int] = Field(None, description="Error count")
+    avg_response_time_ms: Optional[float] = Field(None, description="Average response time")
+    memory_mb: Optional[float] = Field(None, description="Memory usage")
+    custom_metrics: Optional[JSONDict] = Field(None, description="Service-specific metrics")

ciris_engine/schemas/api/wa.py

@@ -0,0 +1,90 @@
+"""
+WA (Wise Authority) API schemas for CIRIS API v3 (Simplified).
+
+Provides type-safe structures for WA API endpoints.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_serializer
+
+from ciris_engine.schemas.services.authority.wise_authority import PendingDeferral
+from ciris_engine.schemas.services.authority_core import WAPermission
+from ciris_engine.schemas.types import JSONDict
+
+
+class DeferralListResponse(BaseModel):
+    """Response containing list of pending deferrals."""
+
+    deferrals: List[PendingDeferral] = Field(..., description="List of pending deferrals")
+    total: int = Field(..., description="Total number of pending deferrals")
+
+
+class ResolveDeferralRequest(BaseModel):
+    """Request to resolve a deferral with integrated guidance."""
+
+    resolution: str = Field(..., pattern="^(approve|reject|modify)$", description="Resolution type")
+    guidance: str = Field(..., description="WA wisdom guidance integrated with the decision")
+
+
+class ResolveDeferralResponse(BaseModel):
+    """Response after resolving a deferral."""
+
+    success: bool = Field(..., description="Whether resolution succeeded")
+    deferral_id: str = Field(..., description="ID of resolved deferral")
+    resolved_at: datetime = Field(..., description="When deferral was resolved")
+
+
+class PermissionsListResponse(BaseModel):
+    """Response containing list of permissions."""
+
+    permissions: List[WAPermission] = Field(..., description="List of permissions")
+    wa_id: str = Field(..., description="WA ID these permissions belong to")
+
+
+class WAStatusResponse(BaseModel):
+    """WA service status response."""
+
+    service_healthy: bool = Field(..., description="Whether WA service is healthy")
+    active_was: int = Field(..., description="Number of active WAs")
+    pending_deferrals: int = Field(..., description="Number of pending deferrals")
+    deferrals_24h: int = Field(..., description="Deferrals created in last 24 hours")
+    average_resolution_time_minutes: float = Field(..., description="Average deferral resolution time")
+    timestamp: datetime = Field(..., description="Status timestamp")
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, timestamp: datetime, _info: Any) -> Optional[str]:
+        return timestamp.isoformat() if timestamp else None
+
+
+class UrgencyLevel(str, Enum):
+    """Urgency level for guidance requests."""
+
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class WAGuidanceRequest(BaseModel):
+    """Request for WA guidance on a topic."""
+
+    topic: str = Field(..., description="Topic requiring guidance")
+    context: Optional[str] = Field(None, description="Additional context for the guidance request")
+    urgency: Optional[UrgencyLevel] = Field(None, description="Urgency level")
+
+
+class WAGuidanceResponse(BaseModel):
+    """WA guidance response."""
+
+    guidance: str = Field(..., description="Wisdom guidance provided")
+    wa_id: str = Field(..., description="ID of WA who provided guidance")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Confidence level (0-1)")
+    additional_context: JSONDict = Field(default_factory=dict, description="Additional context")
+    timestamp: datetime = Field(..., description="When guidance was provided")
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, timestamp: datetime, _info: Any) -> Optional[str]:
+        return timestamp.isoformat() if timestamp else None

ciris_engine/schemas/audit/__init__.py

@@ -0,0 +1,13 @@
+"""Audit schemas v1."""
+
+from .core import AuditEvent, AuditEventType, AuditLogEntry, AuditQuery, AuditSummary, EventOutcome, EventPayload
+
+__all__ = [
+    "AuditEventType",
+    "EventOutcome",
+    "EventPayload",
+    "AuditEvent",
+    "AuditLogEntry",
+    "AuditSummary",
+    "AuditQuery",
+]

ciris_engine/schemas/audit/core.py

@@ -0,0 +1,139 @@
+"""
+Audit Schemas v1 - Audit event tracking for CIRIS Agent
+
+Provides schemas for comprehensive audit logging of all agent actions and system events.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import List, Optional, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AuditEventType(str, Enum):
+    """Types of audit events"""
+
+    # Handler actions
+    HANDLER_ACTION_SPEAK = "handler_action_speak"
+    HANDLER_ACTION_MEMORIZE = "handler_action_memorize"
+    HANDLER_ACTION_RECALL = "handler_action_recall"
+    HANDLER_ACTION_FORGET = "handler_action_forget"
+    HANDLER_ACTION_TOOL = "handler_action_tool"
+    HANDLER_ACTION_DEFER = "handler_action_defer"
+    HANDLER_ACTION_REJECT = "handler_action_reject"
+    HANDLER_ACTION_PONDER = "handler_action_ponder"
+    HANDLER_ACTION_OBSERVE = "handler_action_observe"
+    HANDLER_ACTION_TASK_COMPLETE = "handler_action_task_complete"
+
+    # System events
+    SYSTEM_EVENT = "system_event"
+    SECURITY_EVENT = "security_event"
+    CONFIG_CHANGE = "config_change"
+    SERVICE_LIFECYCLE = "service_lifecycle"
+    ERROR_EVENT = "error_event"
+
+
+class EventOutcome(str, Enum):
+    """Outcome of an audited event"""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"
+    SKIPPED = "skipped"
+
+
+class EventPayload(BaseModel):
+    """Typed event payload data"""
+
+    action: Optional[str] = Field(default=None, description="Action taken")
+    result: Optional[str] = Field(default=None, description="Result of action")
+    error: Optional[str] = Field(default=None, description="Error message if failed")
+    duration_ms: Optional[float] = Field(default=None, ge=0.0, description="Duration in milliseconds")
+
+    # Additional context
+    user_id: Optional[str] = Field(default=None, description="User involved")
+    channel_id: Optional[str] = Field(default=None, description="Channel involved")
+    service_name: Optional[str] = Field(default=None, description="Service involved")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AuditEvent(BaseModel):
+    """Schema for audit events"""
+
+    event_type: AuditEventType = Field(description="Type of audit event")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), description="Event timestamp")
+    thought_id: Optional[str] = Field(default=None, description="Associated thought ID")
+    task_id: Optional[str] = Field(default=None, description="Associated task ID")
+    handler_name: str = Field(description="Name of handler that generated event")
+    event_data: EventPayload = Field(description="Structured event data")
+    outcome: EventOutcome = Field(default=EventOutcome.SUCCESS, description="Event outcome")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AuditLogEntry(BaseModel):
+    """Schema for audit log entries"""
+
+    event_id: str = Field(description="Unique event identifier")
+    event_timestamp: datetime = Field(description="When event occurred")
+    event_type: str = Field(description="Type of event")
+    originator_id: str = Field(description="ID of originating component")
+    target_id: Optional[str] = Field(default=None, description="ID of target component")
+    event_summary: str = Field(description="Human-readable event summary")
+    event_payload: Optional[EventPayload] = Field(default=None, description="Structured event data")
+
+    # Additional metadata
+    agent_template: Optional[str] = Field(default=None, description="Agent template in use")
+    round_number: Optional[int] = Field(default=None, ge=0, description="Processing round number")
+    thought_id: Optional[str] = Field(default=None, description="Associated thought ID")
+    task_id: Optional[str] = Field(default=None, description="Associated task ID")
+
+    # Hash chain fields
+    previous_hash: Optional[str] = Field(default=None, description="Hash of previous entry for tamper detection")
+    entry_hash: Optional[str] = Field(default=None, description="Hash of this entry")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AuditSummary(BaseModel):
+    """Summary statistics for audit entries"""
+
+    total_events: int = Field(ge=0, description="Total number of events")
+    events_by_type: List[Tuple[str, int]] = Field(default_factory=list, description="Count by event type")
+    events_by_outcome: List[Tuple[str, int]] = Field(default_factory=list, description="Count by outcome")
+    error_count: int = Field(ge=0, default=0, description="Number of error events")
+    security_event_count: int = Field(ge=0, default=0, description="Number of security events")
+
+    # Time range
+    earliest_event: Optional[datetime] = Field(default=None, description="Timestamp of earliest event")
+    latest_event: Optional[datetime] = Field(default=None, description="Timestamp of latest event")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AuditQuery(BaseModel):
+    """Query parameters for audit log search"""
+
+    event_types: Optional[List[AuditEventType]] = Field(default=None, description="Filter by event types")
+    start_time: Optional[datetime] = Field(default=None, description="Start of time range")
+    end_time: Optional[datetime] = Field(default=None, description="End of time range")
+    thought_id: Optional[str] = Field(default=None, description="Filter by thought ID")
+    task_id: Optional[str] = Field(default=None, description="Filter by task ID")
+    handler_name: Optional[str] = Field(default=None, description="Filter by handler name")
+    outcome: Optional[EventOutcome] = Field(default=None, description="Filter by outcome")
+    limit: int = Field(default=100, ge=1, le=1000, description="Maximum results to return")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = [
+    "AuditEventType",
+    "EventOutcome",
+    "EventPayload",
+    "AuditEvent",
+    "AuditLogEntry",
+    "AuditSummary",
+    "AuditQuery",
+]

ciris_engine/schemas/audit/hash_chain.py

@@ -0,0 +1,58 @@
+"""
+Schemas for audit hash chain operations.
+
+These replace all Dict[str, Any] usage in logic/audit/hash_chain.py.
+"""
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class HashChainAuditEntry(BaseModel):
+    """An entry in the audit log with hash chain fields."""
+
+    event_id: str = Field(..., description="Unique event ID")
+    event_timestamp: str = Field(..., description="Event timestamp")
+    event_type: str = Field(..., description="Type of event")
+    originator_id: str = Field(..., description="ID of the originator")
+    event_payload: str = Field("", description="Event payload data")
+    sequence_number: int = Field(..., description="Sequence number in chain")
+    previous_hash: str = Field(..., description="Hash of previous entry or 'genesis'")
+    entry_hash: Optional[str] = Field(None, description="Hash of this entry")
+
+
+class HashChainVerificationResult(BaseModel):
+    """Result from verifying hash chain integrity."""
+
+    valid: bool = Field(..., description="Whether chain is valid")
+    entries_checked: int = Field(..., description="Number of entries verified")
+    errors: List[str] = Field(default_factory=list, description="List of validation errors")
+    last_sequence: Optional[int] = Field(None, description="Last sequence number checked")
+    tampering_location: Optional[int] = Field(None, description="First tampered sequence if found")
+
+
+class ChainSummary(BaseModel):
+    """Summary of the hash chain state."""
+
+    total_entries: int = Field(0, description="Total number of entries")
+    sequence_range: List[int] = Field(default_factory=list, description="Min and max sequence")
+    current_sequence: int = Field(0, description="Current sequence number")
+    current_hash: Optional[str] = Field(None, description="Current hash value")
+    oldest_entry: Optional[str] = Field(None, description="Timestamp of oldest entry")
+    newest_entry: Optional[str] = Field(None, description="Timestamp of newest entry")
+    error: Optional[str] = Field(None, description="Error if any")
+
+
+class AuditEntryResult(BaseModel):
+    """Result from creating an audit entry with hash chain data (ALWAYS enabled in production)."""
+
+    entry_id: str = Field(..., description="Unique ID of the audit entry (REQUIRED)")
+    sequence_number: int = Field(..., description="Sequence number in hash chain (REQUIRED)")
+    entry_hash: str = Field(..., description="Hash of this entry (REQUIRED)")
+    previous_hash: Optional[str] = Field(None, description="Hash of previous entry (None for first entry)")
+    signature: str = Field(..., description="Cryptographic signature (REQUIRED)")
+    signing_key_id: Optional[str] = Field(None, description="ID of key used for signing")
+
+
+__all__ = ["HashChainAuditEntry", "HashChainVerificationResult", "ChainSummary", "AuditEntryResult"]