ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/services/filters_core.py

@@ -0,0 +1,270 @@
+"""
+Filter Schemas v1 - Universal message filtering system for CIRIS Agent
+
+Provides adaptive filtering capabilities across all adapters and services
+with graph memory persistence and self-configuration support.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FilterPriority(str, Enum):
+    """Message priority levels for agent attention"""
+
+    CRITICAL = "critical"  # DMs, @mentions, name mentions
+    HIGH = "high"  # New users, suspicious patterns
+    MEDIUM = "medium"  # Random sampling, periodic health checks
+    LOW = "low"  # Normal traffic
+    IGNORE = "ignore"  # Filtered out completely
+
+
+class TriggerType(str, Enum):
+    """Types of filter triggers"""
+
+    REGEX = "regex"  # Regular expression pattern
+    COUNT = "count"  # Numeric threshold (e.g., emoji count)
+    LENGTH = "length"  # Message length threshold
+    FREQUENCY = "frequency"  # Message frequency (count:seconds)
+    CUSTOM = "custom"  # Custom logic (e.g., is_dm)
+    SEMANTIC = "semantic"  # Meaning-based (requires LLM)
+
+
+class FilterTrigger(BaseModel):
+    """Individual filter trigger definition"""
+
+    trigger_id: str = Field(description="Unique identifier")
+    name: str = Field(description="Human-readable name")
+    pattern_type: TriggerType = Field(description="Type of pattern matching")
+    pattern: str = Field(description="Pattern or threshold value")
+    priority: FilterPriority = Field(description="Priority level when triggered")
+    description: str = Field(description="Human-readable description")
+    enabled: bool = Field(default=True, description="Whether trigger is active")
+
+    # Learning metadata
+    effectiveness: float = Field(default=0.5, ge=0.0, le=1.0, description="How effective the trigger is")
+    false_positive_rate: float = Field(default=0.0, ge=0.0, le=1.0, description="Rate of false positives")
+    true_positive_count: int = Field(default=0, description="Count of true positives")
+    false_positive_count: int = Field(default=0, description="Count of false positives")
+    last_triggered: Optional[datetime] = Field(default=None, description="When last triggered")
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), description="Creation timestamp")
+    created_by: str = Field(default="system", description="Creator of the trigger")
+
+    # For learned patterns
+    learned_from: Optional[str] = Field(default=None, description="Source of learned pattern")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class UserTrustProfile(BaseModel):
+    """
+    Track user behavior for adaptive filtering.
+
+    Works for both identified and anonymous users - when anonymized,
+    user_id becomes a hash and PII fields are cleared.
+    """
+
+    user_id: str = Field(description="User identifier or hash for anonymous")
+    message_count: int = Field(default=0, description="Total messages from user")
+    violation_count: int = Field(default=0, description="Count of policy violations")
+    helpful_count: int = Field(default=0, description="Count of helpful interactions")
+    first_seen: datetime = Field(description="When user was first seen")
+    last_seen: datetime = Field(description="When user was last active")
+    trust_score: float = Field(default=0.5, ge=0.0, le=1.0, description="User trust score")
+    flags: List[str] = Field(default_factory=list, description="Behavioral flags")
+    roles: List[str] = Field(default_factory=list, description="User roles in community")
+
+    avg_message_length: float = Field(default=0.0, description="Average message length")
+    avg_message_interval: float = Field(default=0.0, description="Average seconds between messages")
+    common_triggers: List[str] = Field(default_factory=list, description="Commonly triggered filters")
+
+    # Privacy-preserving fields
+    is_anonymous: bool = Field(default=False, description="User has anonymous consent")
+    user_hash: Optional[str] = Field(None, description="Stable hash for anonymous tracking")
+    consent_stream: str = Field(default="temporary", description="Current consent stream")
+
+    # Anti-gaming measures
+    consent_transitions_24h: int = Field(default=0, description="Consent changes in 24 hours")
+    rapid_switching_flag: bool = Field(default=False, description="Detected rapid consent switching")
+    evasion_score: float = Field(default=0.0, ge=0.0, le=1.0, description="Gaming detection score")
+    last_moderation: Optional[datetime] = Field(None, description="Last moderation action time")
+
+    # Safety patterns (retained for anonymous)
+    safety_patterns: List[str] = Field(default_factory=list, description="Active safety pattern IDs")
+    pattern_score: float = Field(default=0.0, ge=0.0, le=1.0, description="Pattern-based risk score")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ConversationHealth(BaseModel):
+    """Metrics for conversation health monitoring"""
+
+    channel_id: str = Field(description="Unique channel identifier")
+    sample_rate: float = Field(default=0.1, ge=0.0, le=1.0, description="Sampling rate for messages")
+    health_score: float = Field(default=0.5, ge=0.0, le=1.0, description="Overall health score")
+
+    # Detailed metrics
+    toxicity_level: float = Field(default=0.0, ge=0.0, le=1.0, description="Level of toxic content")
+    engagement_level: float = Field(default=0.5, ge=0.0, le=1.0, description="User engagement level")
+    topic_coherence: float = Field(default=0.5, ge=0.0, le=1.0, description="Coherence of discussion topics")
+    user_satisfaction: float = Field(default=0.5, ge=0.0, le=1.0, description="Estimated user satisfaction")
+
+    # Sampling data
+    last_sample: Optional[datetime] = Field(default=None, description="When last sampled")
+    samples_today: int = Field(default=0, description="Samples taken today")
+    issues_detected: int = Field(default=0, description="Issues found in samples")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ContextHint(BaseModel):
+    """Typed context hint for filter results"""
+
+    key: str = Field(description="Context key")
+    value: str = Field(description="Context value")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FilterResult(BaseModel):
+    """Result of filtering a message"""
+
+    message_id: str = Field(description="ID of filtered message")
+    priority: FilterPriority = Field(description="Assigned priority")
+    triggered_filters: List[str] = Field(default_factory=list, description="IDs of triggered filters")
+    should_process: bool = Field(description="Whether to process the message")
+    should_defer: bool = Field(default=False, description="Whether to defer processing")
+    reasoning: str = Field(description="Human-readable reasoning")
+
+    suggested_action: Optional[str] = Field(default=None, description="Suggested action to take")
+    context_hints: List[ContextHint] = Field(default_factory=list, description="Additional context")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ChannelConfig(BaseModel):
+    """Channel-specific filter configuration"""
+
+    channel_id: str = Field(description="Unique channel identifier")
+    health: ConversationHealth = Field(description="Health monitoring settings")
+    custom_triggers: List[str] = Field(default_factory=list, description="Channel-specific trigger IDs")
+    sample_rate_override: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="Override sample rate")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class AdaptiveFilterConfig(BaseModel):
+    """Complete filter configuration stored in graph memory"""
+
+    config_id: str = Field(default="filter_config", description="Unique configuration ID")
+    version: int = Field(default=1, description="Configuration version")
+
+    # Core attention triggers (agent always sees these)
+    attention_triggers: List[FilterTrigger] = Field(default_factory=list, description="High-priority triggers")
+
+    # Suspicious pattern triggers
+    review_triggers: List[FilterTrigger] = Field(default_factory=list, description="Triggers for review")
+
+    # LLM response filters (protect against malicious LLM)
+    llm_filters: List[FilterTrigger] = Field(default_factory=list, description="LLM output filters")
+
+    # Channel-specific settings
+    channel_configs: List[ChannelConfig] = Field(default_factory=list, description="Per-channel configurations")
+
+    # User tracking
+    new_user_threshold: int = Field(default=5, description="Messages before user is trusted")
+    user_profiles: Dict[str, UserTrustProfile] = Field(
+        default_factory=dict, description="User trust profiles by user ID"
+    )
+
+    # Adaptive learning settings
+    auto_adjust: bool = Field(default=True, description="Enable automatic adjustments")
+    adjustment_interval: int = Field(default=3600, description="Seconds between adjustments")
+    effectiveness_threshold: float = Field(default=0.3, description="Disable filters below this effectiveness")
+    false_positive_threshold: float = Field(default=0.2, description="Review filters above this FP rate")
+
+    # Metadata
+    last_adjustment: Optional[datetime] = Field(default=None, description="When last adjusted")
+    total_messages_processed: int = Field(default=0, description="Total messages filtered")
+    total_issues_caught: int = Field(default=0, description="Total issues detected")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class PriorityStats(BaseModel):
+    """Statistics by priority level"""
+
+    priority: FilterPriority = Field(description="Priority level")
+    count: int = Field(default=0, description="Number of messages at this priority")
+    percentage: float = Field(default=0.0, ge=0.0, le=100.0, description="Percentage of total")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TriggerStats(BaseModel):
+    """Statistics by trigger type"""
+
+    trigger_type: TriggerType = Field(description="Type of trigger")
+    count: int = Field(default=0, description="Number of times triggered")
+    percentage: float = Field(default=0.0, ge=0.0, le=100.0, description="Percentage of total")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FilterStats(BaseModel):
+    """Statistics for filter performance monitoring"""
+
+    total_messages_processed: int = Field(default=0, description="Total messages processed")
+    total_filtered: int = Field(default=0, description="Total messages filtered")
+    by_priority: Dict[FilterPriority, int] = Field(default_factory=dict, description="Message count by priority")
+    by_trigger_type: Dict[TriggerType, int] = Field(default_factory=dict, description="Trigger count by type")
+    false_positive_reports: int = Field(default=0, description="Reported false positives")
+    true_positive_confirmations: int = Field(default=0, description="Confirmed true positives")
+    last_reset: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When stats were reset"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FilterHealth(BaseModel):
+    """Overall health metrics for the filtering system"""
+
+    is_healthy: bool = Field(default=True, description="Whether system is healthy")
+    warnings: List[str] = Field(default_factory=list, description="Active warnings")
+    errors: List[str] = Field(default_factory=list, description="Active errors")
+    stats: FilterStats = Field(default_factory=FilterStats, description="Performance statistics")
+    config_version: int = Field(default=1, description="Current config version")
+    last_updated: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), description="Last update time")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FilterServiceMetadata(BaseModel):
+    """Metadata for adaptive filter service capabilities."""
+
+    description: str = Field(..., description="Service description")
+    features: List[str] = Field(..., description="List of features supported")
+    filter_types: List[str] = Field(..., description="Types of filters supported")
+    max_buffer_size: int = Field(..., description="Maximum message buffer size")
+
+
+__all__ = [
+    "FilterPriority",
+    "TriggerType",
+    "FilterTrigger",
+    "UserTrustProfile",
+    "ConversationHealth",
+    "ContextHint",
+    "FilterResult",
+    "ChannelConfig",
+    "AdaptiveFilterConfig",
+    "PriorityStats",
+    "TriggerStats",
+    "FilterStats",
+    "FilterHealth",
+    "FilterServiceMetadata",
+]

ciris_engine/schemas/services/governance.py

@@ -0,0 +1,26 @@
+"""
+Governance-related schemas for CIRIS.
+
+Provides enums and models for governance operations including deferrals.
+"""
+
+from enum import Enum
+
+
+class DeferralType(str, Enum):
+    """Types of deferrals that can be requested."""
+
+    ETHICAL = "ethical"
+    TECHNICAL = "technical"
+    POLICY = "policy"
+    SAFETY = "safety"
+    LEGAL = "legal"
+    RESOURCE = "resource"
+    AUTHORITY = "authority"
+    OTHER = "other"
+
+
+# Re-export the deferral classes from authority_core for convenience
+from ciris_engine.schemas.services.authority_core import DeferralRequest, DeferralResponse
+
+__all__ = ["DeferralType", "DeferralRequest", "DeferralResponse"]

ciris_engine/schemas/services/graph/__init__.py

@@ -0,0 +1,26 @@
+"""
+Graph service schemas.
+
+Provides strongly-typed schemas for all graph service operations.
+"""
+
+from ciris_engine.schemas.services.graph.attributes import (
+    AnyNodeAttributes,
+    ConfigNodeAttributes,
+    LogNodeAttributes,
+    MemoryNodeAttributes,
+    NodeAttributesBase,
+    TelemetryNodeAttributes,
+    create_node_attributes,
+)
+
+__all__ = [
+    # Node attributes
+    "NodeAttributesBase",
+    "MemoryNodeAttributes",
+    "ConfigNodeAttributes",
+    "TelemetryNodeAttributes",
+    "LogNodeAttributes",
+    "AnyNodeAttributes",
+    "create_node_attributes",
+]

ciris_engine/schemas/services/graph/attributes.py

@@ -0,0 +1,254 @@
+"""
+Typed node attribute schemas for graph services.
+
+Provides strongly-typed schemas for graph node attributes.
+These schemas ensure type safety across all graph node operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Type, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ciris_engine.schemas.types import JSONValue
+
+
+class NodeAttributesBase(BaseModel):
+    """
+    Base schema for all graph node attributes.
+
+    This replaces the Dict[str, Any] pattern in graph services.
+    All node-specific attributes should inherit from this base.
+    """
+
+    # Core temporal tracking
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When this node was created"
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When this node was last updated"
+    )
+
+    # Attribution
+    created_by: str = Field(..., description="Service or user that created this node")
+    updated_by: Optional[str] = Field(None, description="Service or user that last updated this node")
+
+    # Metadata
+    tags: List[str] = Field(default_factory=list, description="Tags for categorization and search")
+    version: int = Field(1, ge=1, description="Schema version for migration support")
+
+    # Security
+    secret_refs: List[str] = Field(default_factory=list, description="Secret reference UUIDs for encrypted data")
+
+    model_config = ConfigDict(
+        extra="forbid",  # No extra fields allowed - ensures type safety
+        validate_assignment=True,  # Validate on attribute assignment
+        str_strip_whitespace=True,  # Clean up string inputs
+    )
+
+
+class MemoryNodeAttributes(NodeAttributesBase):
+    """
+    Specific attributes for memory nodes.
+
+    Used by the memory service for storing knowledge, experiences, and insights.
+    """
+
+    # Memory content
+    content: str = Field(..., description="The actual memory content")
+    content_type: str = Field("text", description="Type of content: text, embedding, reference")
+
+    # Memory classification
+    memory_type: str = Field(..., description="Type: fact, experience, learning, insight, observation")
+    importance: float = Field(0.5, ge=0.0, le=1.0, description="Importance score from 0.0 to 1.0")
+    confidence: float = Field(1.0, ge=0.0, le=1.0, description="Confidence in this memory from 0.0 to 1.0")
+
+    # Source tracking
+    source: str = Field(..., description="Where this memory originated")
+    source_type: str = Field("internal", description="Source type: internal, user, system, external")
+
+    # Context
+    channel_id: Optional[str] = Field(None, description="Channel context if applicable")
+    user_id: Optional[str] = Field(None, description="User context if applicable")
+    task_id: Optional[str] = Field(None, description="Task context if applicable")
+
+    # Usage tracking
+    access_count: int = Field(0, ge=0, description="Number of times accessed")
+    last_accessed: Optional[datetime] = Field(None, description="Last access timestamp")
+
+    # Relationships (stored as edge data, but tracked here for quick access)
+    related_memories: List[str] = Field(default_factory=list, description="IDs of related memory nodes")
+    derived_from: Optional[str] = Field(None, description="Parent memory ID if this is derived")
+
+    # Embeddings support
+    embedding_model: Optional[str] = Field(None, description="Model used for embedding")
+    embedding_dimensions: Optional[int] = Field(None, description="Embedding vector dimensions")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ConfigNodeAttributes(NodeAttributesBase):
+    """
+    Specific attributes for configuration nodes.
+
+    Used by the config service for storing system and behavioral configuration.
+    """
+
+    # Configuration identity
+    key: str = Field(..., description="Configuration key (unique within scope)")
+    value: Union[str, int, float, bool, List[str], Dict[str, str]] = Field(..., description="Configuration value")
+
+    # Metadata
+    description: str = Field(..., description="What this configuration controls")
+    category: str = Field(..., description="Category: system, behavioral, ethical, operational")
+
+    # Validation
+    value_type: str = Field(..., description="Expected type: string, integer, float, boolean, list, dict")
+    validation_rules: List[Dict[str, JSONValue]] = Field(
+        default_factory=list, description="Validation rules for this config"
+    )
+
+    # Security and sensitivity
+    is_sensitive: bool = Field(False, description="Whether this contains sensitive data")
+    requires_authority: bool = Field(False, description="Whether changes require WiseAuthority approval")
+
+    # Change tracking
+    previous_value: Optional[Union[str, int, float, bool, List[str], Dict[str, str]]] = Field(
+        None, description="Previous value before last update"
+    )
+    change_reason: Optional[str] = Field(None, description="Reason for last change")
+    approved_by: Optional[str] = Field(None, description="Who approved this config if required")
+
+    # Scope and applicability
+    scope: str = Field("system", description="Scope: system, channel, user")
+    applies_to: List[str] = Field(default_factory=list, description="Specific entities this applies to")
+
+    # Lifecycle
+    is_active: bool = Field(True, description="Whether this config is currently active")
+    expires_at: Optional[datetime] = Field(None, description="When this config expires")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class TelemetryNodeAttributes(NodeAttributesBase):
+    """
+    Specific attributes for telemetry nodes.
+
+    Used by the telemetry service for storing metrics, performance data, and system observations.
+    """
+
+    # Metric identity
+    metric_name: str = Field(..., description="Name of the metric")
+    metric_type: str = Field(..., description="Type: counter, gauge, histogram, summary")
+
+    # Metric value
+    value: float = Field(..., description="Numeric value of the metric")
+    unit: Optional[str] = Field(None, description="Unit of measurement")
+
+    # Time window
+    start_time: datetime = Field(..., description="Start of measurement period")
+    end_time: datetime = Field(..., description="End of measurement period")
+    duration_seconds: float = Field(..., ge=0, description="Duration of measurement period")
+
+    # Aggregation
+    aggregation_type: Optional[str] = Field(
+        None, description="How this was aggregated: sum, avg, max, min, p50, p95, p99"
+    )
+    sample_count: int = Field(1, ge=1, description="Number of samples in this metric")
+
+    # Statistical data (for histograms/summaries)
+    min_value: Optional[float] = Field(None, description="Minimum observed value")
+    max_value: Optional[float] = Field(None, description="Maximum observed value")
+    mean_value: Optional[float] = Field(None, description="Mean/average value")
+    std_deviation: Optional[float] = Field(None, description="Standard deviation")
+    percentiles: Dict[str, float] = Field(default_factory=dict, description="Percentile values (e.g., p50, p95, p99)")
+
+    # Labels and dimensions
+    labels: Dict[str, str] = Field(default_factory=dict, description="Metric labels for filtering and grouping")
+
+    # Source information
+    service_name: str = Field(..., description="Service that generated this metric")
+    host: Optional[str] = Field(None, description="Host/instance that generated this")
+
+    # Alert thresholds
+    warning_threshold: Optional[float] = Field(None, description="Warning threshold value")
+    critical_threshold: Optional[float] = Field(None, description="Critical threshold value")
+    threshold_direction: Optional[str] = Field(None, description="Threshold direction: above, below")
+
+    # Resource usage (for resource metrics)
+    resource_type: Optional[str] = Field(None, description="Resource type: cpu, memory, disk, network, tokens")
+    resource_limit: Optional[float] = Field(None, description="Resource limit if applicable")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class LogNodeAttributes(NodeAttributesBase):
+    """
+    Specific attributes for log entry nodes.
+
+    Used by the memory service for storing log entries as TSDB_DATA nodes.
+    """
+
+    # Log content
+    log_message: str = Field(..., description="The log message content")
+    log_level: str = Field(..., description="Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL")
+
+    # Log metadata
+    log_tags: Dict[str, str] = Field(default_factory=dict, description="Additional tags for the log entry")
+    retention_policy: str = Field("raw", description="Retention policy for this log")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# Type unions for flexibility
+AnyNodeAttributes = Union[
+    NodeAttributesBase, MemoryNodeAttributes, ConfigNodeAttributes, TelemetryNodeAttributes, LogNodeAttributes
+]
+
+
+def create_node_attributes(node_type: str, data: Dict[str, JSONValue], created_by: str) -> AnyNodeAttributes:
+    """
+    Factory function to create appropriate node attributes based on type.
+
+    Args:
+        node_type: Type of node (memory, config, telemetry)
+        data: Raw attribute data
+        created_by: Who is creating this node
+
+    Returns:
+        Appropriate typed node attributes instance
+
+    Raises:
+        ValueError: If node_type is not recognized
+    """
+    # Ensure required fields
+    if "created_by" not in data:
+        data["created_by"] = created_by
+
+    # Map node types to attribute classes
+    type_map: Dict[str, Type[AnyNodeAttributes]] = {
+        "memory": MemoryNodeAttributes,
+        "config": ConfigNodeAttributes,
+        "telemetry": TelemetryNodeAttributes,
+        "log": LogNodeAttributes,
+    }
+
+    # Get the appropriate class
+    attr_class = type_map.get(node_type)
+    if not attr_class:
+        # Fall back to base attributes for unknown types
+        return NodeAttributesBase(**data)
+
+    # Type is inferred correctly from the typed dictionary
+    return attr_class(**data)
+
+
+__all__ = [
+    "NodeAttributesBase",
+    "MemoryNodeAttributes",
+    "ConfigNodeAttributes",
+    "TelemetryNodeAttributes",
+    "LogNodeAttributes",
+    "AnyNodeAttributes",
+    "create_node_attributes",
+]

ciris_engine/schemas/services/graph/audit.py

@@ -0,0 +1,98 @@
+"""
+Graph audit service schemas.
+
+Provides typed schemas in audit service operations.
+"""
+
+from datetime import datetime
+from typing import Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AuditEventData(BaseModel):
+    """Data for an audit event."""
+
+    entity_id: str = Field("system", description="Entity involved in event")
+    actor: str = Field("system", description="Actor performing the event")
+    outcome: str = Field("success", description="Event outcome")
+    severity: str = Field("info", description="Event severity level")
+
+    # Core event data
+    action: Optional[str] = Field(None, description="Action performed")
+    resource: Optional[str] = Field(None, description="Resource affected")
+    reason: Optional[str] = Field(None, description="Reason for action")
+
+    # Additional context
+    metadata: Dict[str, Union[str, int, float, bool]] = Field(
+        default_factory=dict, description="Additional event metadata"
+    )
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields for flexibility
+
+
+class VerificationReport(BaseModel):
+    """Audit integrity verification report."""
+
+    verified: bool = Field(..., description="Whether integrity check passed")
+    total_entries: int = Field(..., description="Total audit entries checked")
+    valid_entries: int = Field(..., description="Entries with valid signatures")
+    invalid_entries: int = Field(..., description="Entries with invalid signatures")
+    missing_entries: int = Field(0, description="Entries missing from chain")
+
+    # Chain integrity
+    chain_intact: bool = Field(..., description="Whether hash chain is intact")
+    last_valid_entry: Optional[str] = Field(None, description="Last valid entry ID")
+    first_invalid_entry: Optional[str] = Field(None, description="First invalid entry ID")
+
+    # Timing
+    verification_started: datetime = Field(..., description="Verification start time")
+    verification_completed: datetime = Field(..., description="Verification end time")
+    duration_ms: float = Field(..., description="Verification duration in milliseconds")
+
+    # Errors
+    errors: List[str] = Field(default_factory=list, description="Errors encountered")
+    warnings: List[str] = Field(default_factory=list, description="Warnings encountered")
+
+
+class AuditQueryResult(BaseModel):
+    """Result of an audit query."""
+
+    query_type: str = Field(..., description="Type of query performed")
+    total_results: int = Field(..., description="Total matching entries")
+    returned_results: int = Field(..., description="Number of results returned")
+
+    # Results
+    entries: List[Dict[str, Union[str, int, float, bool, datetime]]] = Field(
+        default_factory=list, description="Audit entries matching query"
+    )
+
+    # Query metadata
+    filters_applied: Dict[str, str] = Field(default_factory=dict, description="Filters used")
+    sort_order: Optional[str] = Field(None, description="Sort order applied")
+    offset: int = Field(0, description="Results offset")
+    limit: Optional[int] = Field(None, description="Results limit")
+
+
+class AuditQuery(BaseModel):
+    """Query parameters for audit searches."""
+
+    # Time range
+    start_time: Optional[datetime] = Field(None, description="Start of time range")
+    end_time: Optional[datetime] = Field(None, description="End of time range")
+
+    # Filters
+    event_type: Optional[str] = Field(None, description="Filter by event type")
+    actor: Optional[str] = Field(None, description="Filter by actor")
+    entity_id: Optional[str] = Field(None, description="Filter by entity")
+    outcome: Optional[str] = Field(None, description="Filter by outcome")
+    severity: Optional[str] = Field(None, description="Filter by severity")
+
+    # Search
+    search_text: Optional[str] = Field(None, description="Text search in details")
+
+    # Results
+    order_by: str = Field("timestamp", description="Field to order by")
+    order_desc: bool = Field(True, description="Order descending")
+    limit: Optional[int] = Field(100, description="Maximum results")
+    offset: int = Field(0, description="Results offset")