interactive-story/backend/app/media/providers.py

"""M10: what a future media provider must satisfy, and nothing that satisfies it.

No provider is implemented here, none is registered by default, and nothing in
this module opens a socket. What it defines is the shape of the boundary, so
that adding a real image, video, audio, TTS or STT provider later is writing an
adapter rather than editing the story engine.

## The rule these types exist to enforce

`MEDIA-EXTENSION-CONTRACT.md` §3: the Story Engine must not call ComfyUI, Stable
Diffusion, a video pipeline, a TTS engine or a third-party media API. It states
that as a recommendation; this module makes it structural. Everything crossing
the boundary is expressed in this vocabulary:

    MediaKind        image | video | audio | tts | stt
    MediaRequest     a scene packet, a kind, and neutral hints
    MediaResult      bytes-or-path, a type, and provenance
    DraftTranscription   STT's deliberately different answer (see below)

**No provider vocabulary appears anywhere in this file or in any story module.**
There is no workflow JSON, no sampler name, no CFG scale, no LoRA, no
`num_inference_steps`, no Whisper option and no voice id. A provider adapter
owns that translation, in its own package, and the story engine never learns it.
`test_m10_providers.py` greps the story modules for that vocabulary so the rule
cannot rot quietly.

## Why Protocols rather than base classes

A future adapter should not have to import from here to be usable — it should
merely have to *fit*. `typing.Protocol` gives a structural contract that a test
double satisfies as readily as a real ComfyUI adapter, which keeps the seam
honest: if the only way to satisfy the interface were to inherit from it, the
interface would be describing this codebase rather than the boundary.

## STT is deliberately shaped differently, and that is the point

Every other provider returns a `MediaResult` — a depiction of something the
story already established. STT returns a `DraftTranscription`, which is a
different type on purpose, because it flows the other way:

    audio -> local STT -> draft text -> the reader edits it -> normal submission

`MEDIA-EXTENSION-CONTRACT.md` §24A states the rule as *"STT output is draft user
input, not an accepted story event."* A shared return type would have made it
possible to hand a transcription to something expecting a finished artefact, and
the asymmetry would have survived only as a comment. `DraftTranscription`
carries `editable = True` and has no path into the turn pipeline: the reader's
edited text enters through the ordinary action endpoint like anything they
typed, and is validated, refereed and snapshotted exactly the same way.

M10 implements no microphone capture and no transcription. The type boundary is
the deliverable.

## Endpoints: loopback only, and stricter than the narrator's on purpose

`endpoints.py` already decides which *inference* endpoints this product will
talk to, and allows an explicitly configured trusted LAN as well as loopback
(ADR 011). Media is not given that latitude. `MEDIA-EXTENSION-CONTRACT.md` §27
and §28 set the media default at loopback, with any future LAN extension
explicit and user-controlled — so `check_endpoint` below reuses the existing,
tested address machinery and then applies the stricter rule on top.

Reusing rather than reimplementing matters: a second endpoint validator would be
a second place for the policy to be wrong, and this one inherits the property
that makes the first one hard to talk around — it judges the address a host
actually resolves to, not the name.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Protocol, runtime_checkable

from .. import endpoints

#: The kinds of media this architecture is required to accommodate. A string
#: enum rather than free text, so a typo is a failure here rather than a request
#: nothing will ever service.
IMAGE = "image"
VIDEO = "video"
AUDIO = "audio"
TTS = "tts"
STT = "stt"

MEDIA_KINDS: tuple[str, ...] = (IMAGE, VIDEO, AUDIO, TTS, STT)


def is_media_kind(value) -> bool:
    return isinstance(value, str) and value in MEDIA_KINDS


class MediaProviderError(RuntimeError):
    """A provider could not do what was asked.

    Deliberately its own type, and deliberately not caught anywhere in the story
    path: nothing in a turn calls a provider, so there is no code path where
    this could reach an accepted narration. If a future coordinator catches it,
    it does so on its own side of the boundary — a failed depiction must leave
    the story exactly as it was (`MEDIA-EXTENSION-CONTRACT.md` §50).
    """


class EndpointRejected(endpoints.EndpointRejected):
    """A media endpoint outside the loopback-only media policy.

    Subclasses the inference rejection so that a caller which already handles
    "this endpoint is not allowed" keeps working, while a caller that wants to
    tell the two policies apart still can.
    """


def endpoint_rejection_reason(url: str) -> str | None:
    """Why this URL may not be a media endpoint, or `None` if it may.

    Two rules, in order, and the first is somebody else's:

    1. the existing inference policy — an address in an allowed private network,
       judged by resolution rather than by name (`endpoints.py`);
    2. **and** loopback specifically, which is the media contract's stricter
       default (§27, §28).

    So a trusted-LAN address that an Ollama may legitimately use is refused here.
    That is not an oversight: narrator inference is a deployment the user has
    already reasoned about and configured, whereas a media endpoint is a new
    surface with no v1 use, and the safe default for a surface nobody needs yet
    is the narrowest one. A future milestone may widen it, explicitly and off by
    default, which is what §27 requires of any such change.
    """
    reason = endpoints.rejection_reason(url)
    if reason is not None:
        return reason
    if not endpoints.is_loopback(url):
        return (
            "A media provider endpoint must be on this machine. "
            f"{url!r} resolves somewhere else — media generation has no "
            "trusted-LAN mode, and adding one would be an explicit, "
            "off-by-default change rather than a setting."
        )
    return None


def check_endpoint(url: str) -> None:
    """Raises `EndpointRejected` unless `url` is an allowed media endpoint."""
    reason = endpoint_rejection_reason(url)
    if reason is not None:
        raise EndpointRejected(reason)


# ----------------------------------------------------------------- the types

@dataclass(frozen=True)
class ProviderCapabilities:
    """What one provider can do, in neutral terms.

    Deliberately small. `MEDIA-EXTENSION-CONTRACT.md` §25 shows a richer example
    — seeds, reference images, inpainting — and M10 does not model those,
    because every one of them is a guess until a provider exists to be asked.
    What is here is what a coordinator would need in order to choose *whether*
    to route to this provider at all; anything finer belongs to the adapter and
    its own capability document.
    """

    provider_id: str
    kinds: tuple[str, ...] = ()
    #: Free-form, provider-owned, and never interpreted by story code. It exists
    #: so an adapter can advertise what it supports without this module growing
    #: a field per feature the ecosystem invents.
    details: dict = field(default_factory=dict)

    def supports(self, kind: str) -> bool:
        return kind in self.kinds


@dataclass(frozen=True)
class MediaRequest:
    """What a coordinator would hand a provider: a scene, a kind, and hints.

    `scene` is a Scene Packet (`packet.build`) — a bounded description of one
    accepted scene, not the transcript. That is the whole point of the packet
    existing (`MEDIA-EXTENSION-CONTRACT.md` §12): a provider is given what it
    needs to depict a moment and no more, which bounds prompt size, keeps
    providers interchangeable, and means swapping one does not hand a new
    process the campaign's history.

    `hints` is provider-neutral and optional — an aspect ratio, a duration, a
    count. It is **not** where a workflow graph or a sampler setting goes; those
    belong to the adapter, which knows what it is talking to.
    """

    kind: str
    scene: dict
    hints: dict = field(default_factory=dict)

    def __post_init__(self):
        if not is_media_kind(self.kind):
            raise ValueError(
                f"{self.kind!r} is not one of {', '.join(MEDIA_KINDS)}"
            )


@dataclass(frozen=True)
class MediaResult:
    """What a provider hands back: a depiction, and where it came from.

    Bytes *or* a path, never both, and the caller says which it wanted. Neither
    is interpreted here; M10 registers no provider, so nothing constructs one of
    these outside a test.

    `provenance` carries the scene identity the request named, so that a future
    asset can always be traced to the accepted position it depicts
    (`MEDIA-EXTENSION-CONTRACT.md` §48). It is a record of what was asked for —
    it does not make the depiction true.
    """

    kind: str
    media_type: str
    provenance: dict = field(default_factory=dict)
    data: bytes | None = None
    path: str | None = None
    details: dict = field(default_factory=dict)


@dataclass(frozen=True)
class DraftTranscription:
    """STT's answer, and deliberately not a `MediaResult`.

    See the module docstring. This is **draft user input**: text the reader is
    expected to read, correct and submit themselves. It is not an accepted turn,
    not a state event, not canon, and it has no route into the story that the
    reader's own typing does not also take.

    `editable` is `True` and there is no constructor that sets it otherwise —
    it is a statement about what this type *is* rather than a setting, and a
    reader that finds it false has been handed something that is not a draft.
    """

    text: str
    editable: bool = True
    confidence: float | None = None
    details: dict = field(default_factory=dict)


# ------------------------------------------------------------- the protocols

@runtime_checkable
class MediaProvider(Protocol):
    """Anything that can depict an accepted scene.

    One protocol covers image, video and audio because the boundary is the same
    for all three: a bounded scene in, a depiction out, nothing written to the
    story. What differs between them is entirely inside the adapter.
    """

    def capabilities(self) -> ProviderCapabilities: ...

    async def generate(self, request: MediaRequest) -> MediaResult: ...


@runtime_checkable
class SpeechProvider(Protocol):
    """Text to speech: still a depiction, of prose the story already accepted."""

    def capabilities(self) -> ProviderCapabilities: ...

    async def speak(self, text: str, hints: dict | None = None) -> MediaResult: ...


@runtime_checkable
class TranscriptionProvider(Protocol):
    """Speech to text, which runs the other way and returns a draft.

    The signature is the asymmetry: it takes audio and returns
    `DraftTranscription`, so no coordinator can hand its output to something
    expecting a finished artefact, and nothing can mistake it for an accepted
    turn.
    """

    def capabilities(self) -> ProviderCapabilities: ...

    async def transcribe(
        self, audio: bytes, hints: dict | None = None
    ) -> DraftTranscription: ...


# -------------------------------------------------------------- the registry

#: Registered providers, by id. **Empty, and empty on purpose.**
#:
#: M10 ships no provider, so nothing is registered at import, nothing is
#: required at startup, and no configuration is read. `test_m10_no_media.py`
#: asserts this is empty after the application has been imported and a campaign
#: has been played — media readiness has to be inert until something explicitly
#: uses it.
_REGISTRY: dict[str, object] = {}


def register(provider_id: str, provider: object) -> None:
    """Makes a provider available to a future coordinator.

    Exists to prove the claim in M10's Definition of Done — that a provider can
    be added *without modifying story authority or history* — by being the only
    thing an adapter has to call. Nothing in `app/routers`, `app/narrative`,
    `app/context` or `app/tree` imports this module, so registering one cannot
    reach them.
    """
    if not isinstance(provider_id, str) or not provider_id.strip():
        raise ValueError("a provider needs an id")
    _REGISTRY[provider_id] = provider


def unregister(provider_id: str) -> None:
    _REGISTRY.pop(provider_id, None)


def registered() -> dict[str, object]:
    """The registry, copied — callers must not mutate it in place."""
    return dict(_REGISTRY)


def for_kind(kind: str) -> list[object]:
    """Every registered provider advertising `kind`. Empty in v1."""
    out = []
    for provider in _REGISTRY.values():
        caps = getattr(provider, "capabilities", None)
        if caps is None:
            continue
        try:
            if caps().supports(kind):
                out.append(provider)
        except Exception:  # noqa: BLE001 - a broken adapter is not this layer's
            continue
    return out