"""KnowledgeBase 协议定义 - 外部知识库统一接口

独立于 Memory 接口，提供语义检索模型的知识库协议。
Memory 的 retrieve(key)/delete(key) 是精确 key-value 语义，
而 KnowledgeBase 的 query()/ingest() 更适合知识库的语义检索场景。

参见 KTD-7: KBAdapter 使用独立 KnowledgeBase 协议，不直接实现 Memory 接口。
"""

from __future__ import annotations

from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any, Protocol, runtime_checkable


@dataclass
class Document:
    """知识库文档"""

    doc_id: str
    content: str
    title: str = ""
    source_id: str = ""
    metadata: dict[str, Any] = field(default_factory=dict)
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))


@dataclass
class QueryResult:
    """知识库检索结果"""

    content: str
    source_id: str
    source_name: str
    score: float
    metadata: dict[str, Any] = field(default_factory=dict)
    doc_id: str = ""
    title: str = ""


@dataclass
class SourceInfo:
    """知识库信息源描述"""

    source_id: str
    source_name: str
    source_type: str  # e.g. "feishu", "confluence", "generic_http"
    document_count: int = 0
    last_updated: datetime | None = None


@runtime_checkable
class KnowledgeBase(Protocol):
    """知识库协议 - 统一的外部知识库接口

    所有知识库适配器（飞书、Confluence、通用 HTTP 等）均实现此协议。
    与 Memory 接口不同，KnowledgeBase 专注于语义检索模型：
    - ingest() 批量写入文档
    - query() 语义检索
    - delete_by_id() 按文档 ID 删除
    - list_sources() 列出可用信息源
    - health_check() 检查连接状态
    """

    async def ingest(self, documents: list[Document]) -> list[str]:
        """写入文档到知识库，返回文档 ID 列表"""
        ...

    async def query(self, text: str, top_k: int = 5) -> list[QueryResult]:
        """语义检索知识库"""
        ...

    async def delete_by_id(self, id: str) -> bool:
        """按文档 ID 删除"""
        ...

    async def list_sources(self) -> list[SourceInfo]:
        """列出可用信息源"""
        ...

    async def health_check(self) -> bool:
        """检查知识库连接状态"""
        ...
