"""StructuredProvider protocol — interface for structured data backends.

Core code depends on this protocol. Plugin implementations (sqlite_structured, etc.)
implement it. Swappable via loader.py registration.
"""

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class StructuredProvider(Protocol):
    """Protocol for structured data backends (SQLite, Postgres, etc.)."""

    async def initialize(self) -> None:
        """Initialize the database connection and create tables."""
        ...

    async def save_knowledge_entry(
        self,
        content: str,
        source: str,
        tags: list[str] | None = None,
        metadata: dict | None = None,
        dikw_level: str = "data",
    ) -> str:
        """Save a knowledge entry. Returns the entry ID."""
        ...

    async def search_knowledge(
        self,
        query: str,
        tags: list[str] | None = None,
        limit: int = 10,
    ) -> list[dict[str, Any]]:
        """Search knowledge entries by text and/or tags."""
        ...

    async def save_conversation_message(
        self,
        agent_id: str,
        role: str,
        content: str,
    ) -> None:
        """Save a conversation message."""
        ...

    async def get_conversation_history(
        self,
        agent_id: str,
        limit: int = 50,
    ) -> list[dict[str, Any]]:
        """Get conversation history for an agent."""
        ...

    async def save_council_session(self, session: dict) -> str:
        """Save a council session record. Returns session ID."""
        ...

    async def get_council_sessions(self, limit: int = 10) -> list[dict]:
        """Get recent council sessions."""
        ...

    async def close(self) -> None:
        """Close the database connection."""
        ...
