Create-knowledge-find-decode/acquisition/platforms/base.py

"""Formal platform adapter contracts for acquisition."""
from __future__ import annotations

from typing import Any, Protocol

from pydantic import BaseModel, ConfigDict, Field

from core.config import Settings


class PlatformCandidate(BaseModel):
    model_config = ConfigDict(extra="forbid")

    rank: int
    platform: str
    source_id: str = ""
    url: str = ""
    title: str = ""
    author: str = ""
    cover_url: str = ""
    raw: dict[str, Any] = Field(default_factory=dict)


class PlatformItem(BaseModel):
    model_config = ConfigDict(extra="forbid")

    platform: str
    source_id: str = ""
    url: str = ""
    content_type: str = ""
    title: str = ""
    author: str = ""
    body_text: str = ""
    image_urls: list[str] = Field(default_factory=list)
    video_urls: list[str] = Field(default_factory=list)
    raw: dict[str, Any] = Field(default_factory=dict)


class PlatformAdapter(Protocol):
    platform: str

    def search(
        self,
        query: str,
        *,
        settings: Settings,
        limit: int,
        rate_limiter: Any,
    ) -> list[PlatformCandidate]:
        ...

    def fetch_detail(
        self,
        candidate: PlatformCandidate,
        *,
        settings: Settings,
        rate_limiter: Any,
    ) -> PlatformItem:
        ...