"""Shared protocol for text/JSON generation backends (Ollama, Groq, fallbacks)."""

from __future__ import annotations

from typing import Any, Protocol


class GenerationLLM(Protocol):
    """Minimal interface used by Self-RAG, CRAG, and answer synthesis."""

    @property
    def generation_available(self) -> bool:
        """True when this backend can run generate/generate_json."""

    @property
    def model_label(self) -> str:
        """Human-readable model id for audit logs and API responses."""

    def generate(
        self,
        prompt: str,
        *,
        system: str | None = None,
        json_mode: bool = False,
        temperature: float = 0.1,
    ) -> str: ...

    def generate_json(self, prompt: str, *, system: str | None = None) -> dict[str, Any]: ...