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

src/beaver_gateway/agents/raycast.py

@@ -1,31 +1,12 @@
 """Raycast agent definition.
 
-Field set is the union of ``raycast_api.ChatAPI.stream`` parameters that
-make sense as **per-agent defaults**. Per-request values (currently:
-``temperature``) win when both are set; the rest fall back to whatever
-the agent declared, then to Raycast's own defaults.
-
-``BaseAgent.system_prompt`` maps onto Raycast's wire field
-``additional_system_instructions`` (the slot the real client uses for
-*content*); the wire field ``system_instructions`` stays at the Raycast
-source default — ``"markdown"`` for ``AI_CHAT``, ``"plain"`` otherwise.
-We don't expose that wire dichotomy to the user — they get one
-conceptual "system prompt".
-
-Excluded on purpose:
-
-* ``buffer_id``/``message_id``/``current_date`` — per-call ephemeral
-* ``provider`` override — escape hatch for non-catalog models, no clear
-  use case yet (revisit in PRD §14 when discovery lands)
-* ``locale`` — process-wide via ``Settings.raycast_locale`` because we
-  only spin up one ``raycast_api.Client`` per gateway
-* ``system_instructions`` (wire) — that's a format marker, not content;
-  the SDK fills it from the source default and we let it
+Field set is the union of ``raycast_api.ChatAPI.stream`` parameters useful
+as per-agent defaults; per-request values override them where both exist.
 """
 
 from __future__ import annotations
 
-from raycast_api import (  # noqa: F401  — UserPreferences re-exported for user configs
+from raycast_api import (  # noqa: F401
     RemoteTool,
     Source,
     UserPreferences,
@@ -36,44 +17,21 @@ from beaver_gateway.agents.base import BaseAgent
 
 
 class RaycastAgent(BaseAgent):
-    """Agent backed by ``raycast-api``.
-
-    ``available_native_tools`` is the closed set of Raycast's server-side
-    "remote tools" (``web_search``, ``search_images``, ``read_page``) —
-    typed as ``RemoteTool`` so config-time IDE completion lists exactly
-    the three valid values. Pydantic also coerces string literals, so
-    ``("web_search", "read_page")`` keeps working unchanged.
-
-    ``user_preferences`` toggles the auto-generated ``<user-preferences>``
-    block Raycast prepends to ``additional_system_instructions``:
-
-    * ``True`` (default) → auto from host locale/timezone/today, rebuilt
-      every request so the date stays fresh;
-    * ``False`` → omit the block entirely;
-    * ``UserPreferences(...)`` instance → used verbatim (frozen at the
-      time the agent was loaded, so the date won't auto-update);
-    * ``Callable[[], UserPreferencesArg]`` → re-invoked on every request.
-      Use this for the common case "fresh date but custom
-      locale/timezone": ``user_preferences=lambda:
-      UserPreferences(locale="ru-RU", timezone="Europe/Berlin",
-      current_date=date.today().isoformat())``. Callables may nest
-      (a lambda returning a lambda…) but there's no real reason to.
-
-    The library uses this block for date/locale-aware formatting, not
-    for personalisation/memory — those are out of scope upstream.
-
-    ``reasoning_effort`` values vary by model: GPT-5 takes
-    ``"minimal"|"low"|"medium"|"high"``; Anthropic exposes nothing here
-    (Claude reasoning lives in a separate ``…-reasoning`` model variant
-    in the catalog). Unknown effort for the chosen model is ignored
-    server-side, so we stay loose as ``str | None``.
-    """
+    """Agent backed by ``raycast-api``."""
 
     streaming: bool = True
     available_native_tools: tuple[RemoteTool, ...] = ()
+    """Raycast's server-side "remote tools": ``web_search``, ``search_images``,
+    ``read_page``."""
+
     source: Source = Source.AI_CHAT
 
     temperature: float | None = None
     reasoning_effort: str | None = None
+    """Model-specific (e.g. GPT-5: ``"minimal"``/``"low"``/``"medium"``/``"high"``);
+    ignored server-side if the model doesn't support it."""
+
     tool_choice: str | None = None
     user_preferences: UserPreferencesArg = True
+    """Auto-fills the ``<user-preferences>`` block from host locale/timezone/date;
+    ``False`` omits it, or pass ``UserPreferences(...)`` / a zero-arg callable."""