"""
HandlerProtocol defines the interface all TrustMem handlers must implement.

Implementations:
- PersistentHandler: SQLite + VectorStore (production self-hosted)
"""
from __future__ import annotations

from typing import Protocol, runtime_checkable


@runtime_checkable
class HandlerProtocol(Protocol):
    """Interface for TrustMem memory store handlers."""

    # --- Core CRUD ---
    def add_memory(
        self,
        content: str,
        tags: list | None = None,
        metadata: dict | None = None,
        user_id: str | None = None,
        memory_type: str = "semantic",
    ) -> dict: ...

    def search_memory(
        self,
        query: str,
        limit: int = 10,
        user_id: str | None = None,
        memory_type: str | None = None,
        search_mode: str = "hybrid",
    ) -> dict: ...

    def search_memory_raw(
        self,
        query: str,
        limit: int = 10,
        user_id: str | None = None,
        memory_type: str | None = None,
    ) -> dict: ...

    def get_memory(self, memory_id: str, accessor: str = "system") -> dict: ...

    def list_memories(
        self,
        limit: int = 50,
        offset: int = 0,
        user_id: str | None = None,
        memory_type: str | None = None,
    ) -> dict: ...

    def list_all_memories(
        self,
        user_id: str | None = None,
        limit: int = 100,
        offset: int = 0,
        memory_type: str | None = None,
    ) -> dict: ...

    def delete_memory(self, memory_id: str) -> bool: ...

    def get_memory_stats(self, user_id: str | None = None) -> dict: ...

    # --- Audit Trail ---
    def record_audit_trail(
        self,
        memory_id: str,
        event_type: str,
        triggered_by: str = "system",
        detail: dict | None = None,
        old_confidence: str | None = None,
        new_confidence: str | None = None,
    ) -> dict: ...

    def get_audit_trail(self, memory_id: str, limit: int = 50, offset: int = 0) -> list: ...

    def get_contradictions(self, memory_id: str, limit: int = 20, offset: int = 0) -> list: ...

    def get_provenance(self, memory_id: str, limit: int = 20, offset: int = 0) -> list: ...

    # --- Auto Extraction ---
    def remember(
        self,
        messages: list[dict],
        user_id: str | None = None,
        session_id: str | None = None,
        tags: list[str] | None = None,
        metadata: dict | None = None,
        custom_extraction_prompt: str | None = None,
        auto_resolve_conflicts: bool = True,
        dry_run: bool = False,
    ) -> dict:
        """Extract memories from conversation messages using LLM pipeline."""
        ...

    # --- Knowledge Graph ---
    def add_entity(
        self,
        name: str,
        entity_type: str = "other",
        source_memory_id: str | None = None,
        metadata: dict | None = None,
        user_id: str | None = None,
    ) -> dict: ...

    def add_entity_edge(
        self,
        subject_name: str,
        subject_type: str = "other",
        predicate: str = "",
        object_name: str = "",
        object_type: str = "other",
        source_memory_id: str | None = None,
        metadata: dict | None = None,
        user_id: str | None = None,
    ) -> dict: ...

    def search_entity_relations(
        self,
        entity_name: str,
        predicate: str | None = None,
        direction: str = "both",
        limit: int = 20,
        partial_match: bool = False,
        user_id: str | None = None,
    ) -> list: ...

    def list_entity_edges(
        self,
        user_id: str | None = None,
        limit: int = 100,
    ) -> list[dict]: ...

    def get_entity_graph(
        self,
        entity_name: str,
        hops: int = 2,
        user_id: str | None = None,
    ) -> dict: ...

    def delete_entity(self, entity_id: str) -> bool: ...

    def delete_entity_edge(self, edge_id: str) -> bool: ...

    def get_entity_stats(self, user_id: str | None = None) -> dict: ...

    # --- Version Management ---
    def update_memory(
        self,
        memory_id: str,
        content: str,
        *,
        embedding: list[float] | None = None,
        tags: list[str] | None = None,
        metadata: dict | None = None,
        reason: str = "",
    ) -> dict: ...

    # --- Object Store / Integrity ---
    def verify_memory(self, memory_id: str, auto_quarantine: bool = True) -> dict: ...

    def verify_all_memories(self) -> dict: ...

    def backfill_content_hash(self) -> dict: ...

    # --- Cleanup ---
    def cleanup_audit_trail(self, before: str, dry_run: bool = False) -> dict: ...

    # --- Store Management ---
    def reset_stores(self) -> None: ...
