content-find-agent-new/content_agent/interfaces.py

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Any, Protocol


class RuntimeStore(Protocol):
    def prepare_run(self, run_id: str) -> Path: ...
    def run_dir(self, run_id: str) -> Path: ...
    def write_json(self, run_id: str, filename: str, data: dict[str, Any]) -> Path: ...
    def update_json(self, run_id: str, filename: str, data: dict[str, Any]) -> Path: ...
    def append_jsonl(self, run_id: str, filename: str, rows: list[dict[str, Any]]) -> Path: ...
    def read_json(self, run_id: str, filename: str) -> dict[str, Any]: ...
    def read_jsonl(self, run_id: str, filename: str) -> list[dict[str, Any]]: ...
    def file_status(self, run_id: str) -> dict[str, bool]: ...
    def create_run_record(self, record: dict[str, Any]) -> None: ...
    def update_run_record(self, run_id: str, updates: dict[str, Any]) -> None: ...
    def record_policy_run(self, record: dict[str, Any]) -> None: ...
    def append_run_event_records(
        self,
        run_id: str,
        policy_run_id: str,
        rows: list[dict[str, Any]],
    ) -> None: ...
    def write_publish_jobs(
        self,
        run_id: str,
        policy_run_id: str,
        rows: list[dict[str, Any]],
    ) -> None: ...
    def write_author_assets(self, rows: list[dict[str, Any]]) -> None: ...
    def write_author_asset_roles(self, rows: list[dict[str, Any]]) -> None: ...
    def write_search_clue_assets(self, rows: list[dict[str, Any]]) -> None: ...
    def write_search_clue_asset_evidence(self, rows: list[dict[str, Any]]) -> None: ...
    def read_performance_feedback(
        self,
        run_id: str,
        policy_run_id: str,
    ) -> list[dict[str, Any]]: ...


RuntimeFileStore = RuntimeStore


@dataclass(frozen=True)
class QueryVariantResult:
    query: str
    model: str
    prompt_version: str
    input_evidence: dict[str, Any]


class QueryVariantClient(Protocol):
    def generate_variant(
        self,
        *,
        seed_term: str,
        evidence_context: dict[str, Any],
    ) -> QueryVariantResult: ...


class GeminiVideoClient(Protocol):
    def analyze(
        self,
        content: dict[str, Any],
        media: dict[str, Any],
        source_context: dict[str, Any],
    ) -> dict[str, Any]: ...


class PlatformSearchClient(Protocol):
    def search(self, search_query: dict[str, Any]) -> list[dict[str, Any]]: ...


class PolicyBundleStore(Protocol):
    def load_policy_bundle(self, strategy_version: str) -> dict[str, Any]: ...