refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/frontends/accumulate.py

@@ -1,11 +1,7 @@
 """Collapse an Anthropic event stream into one ``Message``.
 
-Extracted from ``AnthropicMessagesFrontend`` so the markdown frontend
-can run the same accumulation logic when it wants the finalized turn
-rather than raw SSE chunks. Mirrors the Anthropic SDK's own accumulator:
-walks events, builds block dicts indexed by their ``content_block``
-index, folds text / thinking deltas in, buffers ``input_json_delta``
-chunks until the block closes (then JSON-parses them once).
+Mirrors the Anthropic SDK's own accumulator: folds content-block deltas
+into finalized blocks, indexed by their ``content_block`` index.
 """
 
 from __future__ import annotations
@@ -42,9 +38,7 @@ __all__ = ["StreamAccumulator", "accumulate"]
 class StreamAccumulator:
     """Folds a stream of events into one ``Message``, incrementally.
 
-    Use when you need to *both* forward events somewhere (SSE) *and*
-    keep a finalized ``Message`` for post-stream work (audit, logging
-    to disk). Call :meth:`feed` for each event, :meth:`finalize` once.
+    Call :meth:`feed` for each event, then :meth:`finalize` once.
     """
 
     __slots__ = (
@@ -67,10 +61,11 @@ class StreamAccumulator:
         self._stop_sequence: str | None = None
 
     def feed(self, ev: MessageStreamEvent) -> None:
-        # isinstance, not ``ev.type == "..."``: ty narrows on the
-        # discriminator only via the class, and the raw event union
-        # carries its own discriminators (``Raw*Event``) the SDK
-        # already promises.
+        """Fold one stream event into the in-progress message state.
+
+        Uses ``isinstance`` rather than ``ev.type == ...`` so ty narrows
+        the event type from the class, not a string comparison.
+        """
         if isinstance(ev, RawMessageStartEvent):
             self._message_id = ev.message.id
             self._role = ev.message.role
@@ -109,6 +104,11 @@ class StreamAccumulator:
                 )
 
     def finalize(self, *, model: str) -> Message:
+        """Build the finalized ``Message`` from accumulated block state.
+
+        ``role`` is always ``"assistant"`` at the wire level; the cast
+        avoids a runtime check ty would otherwise require.
+        """
         content: list[Any] = []
         for idx in sorted(self._blocks):
             bd = self._blocks[idx]
@@ -120,10 +120,6 @@ class StreamAccumulator:
             elif btype == "thinking":
                 content.append(ThinkingBlock.model_validate(bd))
 
-        # ``role`` is always ``"assistant"`` at the wire level — we
-        # initialised the field to that and only overwrite from a
-        # ``RawMessageStartEvent`` which itself carries the same literal.
-        # The cast keeps both type-checkers happy without a runtime check.
         return Message(
             id=self._message_id or "msg_unknown",
             type="message",