feat: implement raycast backend

src/beaver_gateway/backends/base.py

@@ -0,0 +1,37 @@
+"""Backend protocol.
+
+A backend turns an Anthropic-style turn (``messages`` + agent definition)
+into a stream of :class:`~beaver_gateway.core.events.MessageStreamEvent`
+records. The frontend serializes whatever comes out straight to SSE, so
+backends are the only place where provider quirks are translated.
+
+Implementations are plain :class:`typing.Protocol` conformers — no ABC
+subclassing — to keep them swappable in tests with bare async generators.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterable
+
+    from anthropic.types import MessageParam
+
+    from beaver_gateway.agents.base import BaseAgent
+    from beaver_gateway.core.events import MessageStreamEvent
+
+
+class Backend(Protocol):
+    """Single-method protocol; ``complete`` returns an async iterator of events."""
+
+    def complete(
+        self,
+        *,
+        agent: BaseAgent,
+        messages: Iterable[MessageParam],
+        system: str | None = None,
+        **options: Any,
+    ) -> AsyncIterator[MessageStreamEvent]:
+        """Yield Anthropic stream events for one turn against ``agent``."""
+        ...