briar-cli 1.1.1__py3-none-any.whl

briar/__init__.py

@@ -0,0 +1,8 @@
+"""briar — terminal client for the Briar agent-orchestration API.
+
+Stdlib-only. Importing the top-level package exposes only the version;
+public surfaces live in `briar.cli` (entry point) and the typed
+sub-packages (`briar.commands`, `briar.iac`, `briar.formatting`, etc.).
+"""
+
+__version__ = "1.1.0"

briar/__main__.py

@@ -0,0 +1,11 @@
+"""Allow `python -m briar` to drive the CLI without an installed entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from briar.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

briar/_registry.py

@@ -0,0 +1,36 @@
+"""Defensive `build_registry` helper.
+
+Every plugin family in the codebase builds its `_REGISTRY` dict with
+the same pattern: ``{x.name: x for x in (Item1(), Item2(), ...)}``.
+That comprehension silently drops a duplicate-name collision (Python
+dict-literal semantics: later assignment wins).
+
+If two adapters ever claim the same `name` — say, two refactors both
+typing ``kind = "github"`` — the registry would silently expose only
+one. Hours of debugging.
+
+This module's `build_registry()` does the exact same thing but raises
+on a dup. Every registry in the codebase should use it."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, TypeVar
+
+
+T = TypeVar("T")
+
+
+def build_registry(items: Iterable[T], *, kind: str, name_attr: str = "name") -> dict:
+    """Build the `{item.<name_attr>: item}` map, raising on a
+    duplicate. `kind` is the human-readable family name shown in the
+    error message ("repository provider", "tracker", "agent op", etc.)."""
+    out: dict = {}
+    for item in items:
+        key = getattr(item, name_attr, None)
+        if not key:
+            raise RuntimeError(f"build_registry({kind}): item {item!r} has empty {name_attr!r}")
+        if key in out:
+            existing = out[key]
+            raise RuntimeError(f"build_registry({kind}): duplicate {name_attr}={key!r} (already registered: {existing!r}, second: {item!r})")
+        out[key] = item
+    return out

briar/agent/__init__.py

@@ -0,0 +1,16 @@
+"""Autonomous agent runtime.
+
+`briar agent prfix --company X [--pr N]` invokes an Anthropic-API-driven
+loop that reads PR review threads, applies minimum-correct fixes, and
+commits + pushes follow-ups as the human GitHub identity. The system
+prompt comes from the pr-fixer archetype + the spliced knowledge for
+the company; the tools are git/gh/file-edit primitives behind a strict
+allowlist.
+
+The runner is deliberately separate from the scheduler — opt-in via the
+CLI for now. Wiring it into the scheduled prfix task is a follow-up.
+"""
+
+from briar.agent.runner import AgentRunner, AgentRunResult
+
+__all__ = ["AgentRunner", "AgentRunResult"]

briar/agent/_llm.py

@@ -0,0 +1,90 @@
+"""`LLMProvider` — vendor-neutral facade the agent runner uses instead
+of constructing an Anthropic / OpenAI / Bedrock client directly.
+
+Strategy + Registry, same shape as `RepositoryProvider` and
+`TrackerProvider`. Concrete adapters live in `_llms/`.
+
+The trick with LLM abstraction is that each vendor's tool-call format
+(Anthropic `tool_use` blocks vs OpenAI `function_call` vs Bedrock's
+shape) differs in both the model's *output* and the format you echo
+*results* back. So this contract has two verbs: `complete` (one turn)
+and `format_tool_result` (how to wire a tool's output into the next
+turn's messages). The runner iterates; the provider stays stateless."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Dict, List
+
+from briar.error_policy import ErrorPolicyRegistry
+
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class LLMToolCall:
+    """One tool-use request from the model."""
+
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    """One turn's response, normalised across vendors.
+
+    `raw_assistant_message` carries the provider-specific echo-back
+    payload so the runner can append it to `messages` for the next
+    turn without knowing the vendor's format. This is the only field
+    that isn't fully normalised — every other field is portable."""
+
+    text: str
+    tool_calls: List[LLMToolCall]
+    stop_reason: str
+    input_tokens: int
+    output_tokens: int
+    raw_assistant_message: Dict[str, Any] = field(default_factory=dict)
+
+
+class LLMProvider(ABC):
+    """Strategy contract. Adapters translate one vendor's API onto
+    these two verbs."""
+
+    kind: ClassVar[str] = ""
+
+    @classmethod
+    def default_error_policies(cls) -> ErrorPolicyRegistry:
+        """The provider's default error-response policies — consumed
+        by the agent runner's RetryingExecutor. Subclasses override to
+        encode their SDK's exception taxonomy (rate limits, transient
+        errors, 5xx, etc.). Base returns an empty registry — the
+        executor will Abort on every exception, preserving the original
+        "propagate everything" behaviour for providers that haven't yet
+        declared their own policies."""
+        return ErrorPolicyRegistry()
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """True iff credentials are present and the provider is usable."""
+
+    @abstractmethod
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        max_tokens: int,
+    ) -> LLMResponse:
+        """One turn. Returns the normalised response. The provider
+        handles retries / rate-limit / auth internally."""
+
+    @abstractmethod
+    def format_tool_result(self, tool_call_id: str, output: str, is_error: bool = False) -> Dict[str, Any]:
+        """Provider-specific shape for echoing one tool's output back
+        to the model. Anthropic: ``{"type": "tool_result", ...}``;
+        OpenAI: ``{"role": "tool", "tool_call_id": ..., "content": ...}``."""

briar/agent/_llms/__init__.py

@@ -0,0 +1,40 @@
+"""LLM provider registry."""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple, Type
+
+from briar._registry import build_registry
+from briar.agent._llm import LLMProvider
+from briar.agent._llms.anthropic_llm import AnthropicLLM
+from briar.agent._llms.bedrock import BedrockLLM
+from briar.agent._llms.gemini import GeminiLLM
+from briar.agent._llms.openai_llm import OpenAILLM
+from briar.errors import CliError
+
+
+LLMS: Dict[str, Type[LLMProvider]] = build_registry(
+    (AnthropicLLM, OpenAILLM, GeminiLLM, BedrockLLM),
+    kind="LLM provider",
+    name_attr="kind",
+)
+
+
+class LLMRegistry:
+    @classmethod
+    def kinds(cls) -> Tuple[str, ...]:
+        return tuple(LLMS.keys())
+
+    @classmethod
+    def make(cls, kind: str, *, model: str = "") -> LLMProvider:
+        llm_cls = LLMS.get(kind)
+        if llm_cls is None:
+            known = ", ".join(sorted(LLMS.keys()))
+            raise CliError(f"unknown LLM provider {kind!r}; known: {known}")
+        return llm_cls(model=model)
+
+
+make_llm = LLMRegistry.make
+
+
+__all__ = ["LLMS", "LLMProvider", "LLMRegistry", "make_llm"]

briar/agent/_llms/anthropic_llm.py

@@ -0,0 +1,185 @@
+"""Anthropic `LLMProvider`. Captures the call shape that
+`agent/runner.py` previously inlined: OAuth `auth_token` + the
+`oauth-2025-04-20` beta header, the rate-limit retry schedule
+(now expressed declaratively via the error-policy registry), and
+the `tool_use` block normalisation."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, List
+
+from briar.agent._llm import LLMProvider, LLMResponse, LLMToolCall
+from briar.error_policy import (
+    Abort,
+    ErrorPolicyRegistry,
+    ExceptionTypePolicy,
+    HttpStatusPolicy,
+    RetryAfter,
+    RetryingExecutor,
+)
+
+
+log = logging.getLogger(__name__)
+
+
+class AnthropicLLM(LLMProvider):
+    kind = "anthropic"
+    DEFAULT_MODEL = "claude-sonnet-4-5"
+
+    @classmethod
+    def default_error_policies(cls) -> ErrorPolicyRegistry:
+        """Anthropic's SDK exception taxonomy → retry/abort strategy.
+
+        Order is intentional — more-specific matches come first. The
+        ``HttpStatusPolicy(APIStatusError, status=…)`` entries fire
+        before the broad ``ExceptionTypePolicy(APIStatusError, …)``
+        fallback, so specific status codes get tailored waits.
+
+        Tunable: edit the ``wait_seconds`` values below or compose an
+        overlay via ``registry.with_(extra_policy)`` from a company's
+        YAML if/when that lands."""
+        import anthropic
+
+        return ErrorPolicyRegistry(
+            policies=(
+                # 429 — account-level rate limit. Anthropic resets on
+                # the hour; wait 1h then retry rather than the old
+                # 30s-doubling schedule, which never recovers when the
+                # quota itself is exhausted.
+                ExceptionTypePolicy(
+                    exception_type=anthropic.RateLimitError,
+                    decision=RetryAfter(wait_seconds=3600, reason="anthropic rate limit"),
+                ),
+                # Transient TCP-level / DNS / TLS errors.
+                ExceptionTypePolicy(
+                    exception_type=anthropic.APIConnectionError,
+                    decision=RetryAfter(wait_seconds=10, reason="anthropic transient connect"),
+                ),
+                # Targeted 503 (service-unavailable) — short retry.
+                HttpStatusPolicy(
+                    exception_type=anthropic.APIStatusError,
+                    status=503,
+                    decision=RetryAfter(wait_seconds=30, reason="anthropic 503 service unavailable"),
+                ),
+                # 529 — Anthropic's "overloaded" signal. Longer wait.
+                HttpStatusPolicy(
+                    exception_type=anthropic.APIStatusError,
+                    status=529,
+                    decision=RetryAfter(wait_seconds=120, reason="anthropic 529 overloaded"),
+                ),
+                # 401 / 403 — auth misconfig. No amount of retrying
+                # will fix it; abort fast so the operator sees it.
+                HttpStatusPolicy(
+                    exception_type=anthropic.APIStatusError,
+                    status=401,
+                    decision=Abort(reason="anthropic 401 — check CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY"),
+                ),
+                HttpStatusPolicy(
+                    exception_type=anthropic.APIStatusError,
+                    status=403,
+                    decision=Abort(reason="anthropic 403 — forbidden (model access / billing)"),
+                ),
+            ),
+        )
+
+    def __init__(self, *, model: str = "") -> None:
+        self._model = model or self.DEFAULT_MODEL
+        self._oauth_token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", "")
+        self._api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        self._client = None
+        # Build the executor once per provider instance. The registry
+        # is immutable; reusing the same executor across .complete()
+        # calls preserves the agent's retry budget across one task.
+        self._executor = RetryingExecutor(
+            registry=self.default_error_policies(),
+            max_attempts=5,
+        )
+
+    def _build_client(self):
+        if self._client is not None:
+            return self._client
+        import anthropic
+
+        if self._oauth_token:
+            # Subscription billing via OAuth; the beta header is required.
+            log.info("anthropic-auth: using CLAUDE_CODE_OAUTH_TOKEN")
+            self._client = anthropic.Anthropic(
+                auth_token=self._oauth_token,
+                default_headers={"anthropic-beta": "oauth-2025-04-20"},
+            )
+        elif self._api_key:
+            log.info("anthropic-auth: using ANTHROPIC_API_KEY")
+            self._client = anthropic.Anthropic(api_key=self._api_key)
+        else:
+            raise RuntimeError("Anthropic: CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY required")
+        return self._client
+
+    def is_available(self) -> bool:
+        return bool(self._oauth_token or self._api_key)
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        max_tokens: int,
+    ) -> LLMResponse:
+        """One turn. The executor handles every retryable failure mode
+        declared in ``default_error_policies()`` — this method has zero
+        ``try / except`` of its own. Adding a new error class is a
+        registry entry, not a code change here."""
+        client = self._build_client()
+
+        def _call() -> LLMResponse:
+            response = client.messages.create(
+                model=self._model,
+                max_tokens=max_tokens,
+                system=system,
+                tools=tools,
+                messages=messages,
+            )
+            return self._normalise(response)
+
+        return self._executor.run(_call)
+
+    def format_tool_result(self, tool_call_id: str, output: str, is_error: bool = False) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "type": "tool_result",
+            "tool_use_id": tool_call_id,
+            "content": output,
+        }
+        if is_error:
+            result["is_error"] = True
+        return result
+
+    @staticmethod
+    def _normalise(response) -> LLMResponse:
+        """Translate Anthropic's typed response into LLMResponse."""
+        tool_calls: List[LLMToolCall] = []
+        text_parts: List[str] = []
+        for block in response.content:
+            block_type = getattr(block, "type", "")
+            if block_type == "text":
+                text_parts.append(getattr(block, "text", ""))
+            elif block_type == "tool_use":
+                tool_calls.append(
+                    LLMToolCall(
+                        id=getattr(block, "id", ""),
+                        name=getattr(block, "name", ""),
+                        arguments=dict(getattr(block, "input", {}) or {}),
+                    )
+                )
+        return LLMResponse(
+            text="".join(text_parts),
+            tool_calls=tool_calls,
+            stop_reason=str(getattr(response, "stop_reason", "") or ""),
+            input_tokens=int((getattr(response, "usage", None) and response.usage.input_tokens) or 0),
+            output_tokens=int((getattr(response, "usage", None) and response.usage.output_tokens) or 0),
+            raw_assistant_message={
+                "role": "assistant",
+                "content": [b.model_dump() for b in response.content],
+            },
+        )

briar/agent/_llms/bedrock.py

@@ -0,0 +1,154 @@
+"""AWS Bedrock `LLMProvider`.
+
+Uses the unified Bedrock ``Converse`` API which abstracts over the
+provider-specific protocols (Anthropic, Mistral, Meta, Cohere all
+expose the same `converse(modelId, system, messages, toolConfig)`
+surface).
+
+Auth: ambient AWS credential chain (boto3 default). Region comes from
+``AWS_REGION`` or the boto3 default chain.
+
+Model IDs are vendor-prefixed (e.g.
+``anthropic.claude-sonnet-4-20250514-v1:0``,
+``meta.llama3-70b-instruct-v1:0``). The Converse API normalises the
+response shape across all of them — this adapter doesn't branch on
+the prefix."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+
+from briar.agent._llm import LLMProvider, LLMResponse, LLMToolCall
+
+
+log = logging.getLogger(__name__)
+
+
+class BedrockLLM(LLMProvider):
+    kind = "bedrock"
+    DEFAULT_MODEL = "anthropic.claude-sonnet-4-20250514-v1:0"
+
+    def __init__(self, *, model: str = "") -> None:
+        self._model = model or self.DEFAULT_MODEL
+        self._client = None
+
+    def _make_client(self):
+        if self._client is not None:
+            return self._client
+        import boto3
+
+        self._client = boto3.client("bedrock-runtime")
+        return self._client
+
+    def is_available(self) -> bool:
+        try:
+            import boto3  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        max_tokens: int,
+    ) -> LLMResponse:
+        client = self._make_client()
+        # Translate Anthropic-shaped `tools` (name/description/input_schema)
+        # onto Bedrock's toolConfig.tools[].toolSpec format.
+        tool_config = self._to_bedrock_tools(tools)
+        kwargs: Dict[str, Any] = {
+            "modelId": self._model,
+            "system": [{"text": system}] if system else [],
+            "messages": self._to_bedrock_messages(messages),
+            "inferenceConfig": {"maxTokens": max_tokens},
+        }
+        if tool_config:
+            kwargs["toolConfig"] = tool_config
+
+        resp = client.converse(**kwargs)
+        return self._normalise(resp)
+
+    def format_tool_result(self, tool_call_id: str, output: str, is_error: bool = False) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "toolResult": {
+                "toolUseId": tool_call_id,
+                "content": [{"text": output}],
+            }
+        }
+        if is_error:
+            result["toolResult"]["status"] = "error"
+        return {"role": "user", "content": [result]}
+
+    # ---- shape translation ------------------------------------------------
+
+    @staticmethod
+    def _to_bedrock_tools(tools: List[Dict[str, Any]]) -> Dict[str, Any]:
+        out: List[Dict[str, Any]] = []
+        for t in tools:
+            out.append(
+                {
+                    "toolSpec": {
+                        "name": t.get("name", ""),
+                        "description": t.get("description", ""),
+                        "inputSchema": {"json": t.get("input_schema", {})},
+                    }
+                }
+            )
+        return {"tools": out} if out else {}
+
+    @staticmethod
+    def _to_bedrock_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Bedrock content blocks differ from Anthropic's: Anthropic uses
+        ``{type: tool_result, tool_use_id, content}``; Bedrock uses
+        ``{toolResult: {toolUseId, content}}``. The format_tool_result
+        method emits the Bedrock shape already; this just passes things
+        through, only translating the simple ``{role, content: <str>}``
+        case where the user message is plain text."""
+        out: List[Dict[str, Any]] = []
+        for m in messages:
+            content = m.get("content")
+            if isinstance(content, str):
+                out.append({"role": m.get("role", "user"), "content": [{"text": content}]})
+            else:
+                out.append(m)
+        return out
+
+    @staticmethod
+    def _normalise(resp: Dict[str, Any]) -> LLMResponse:
+        output = (resp.get("output") or {}).get("message") or {}
+        blocks = output.get("content") or []
+        text_parts: List[str] = []
+        tool_calls: List[LLMToolCall] = []
+        for block in blocks:
+            if "text" in block:
+                text_parts.append(str(block["text"]))
+            elif "toolUse" in block:
+                tu = block["toolUse"]
+                tool_calls.append(
+                    LLMToolCall(
+                        id=str(tu.get("toolUseId") or ""),
+                        name=str(tu.get("name") or ""),
+                        arguments=dict(tu.get("input") or {}),
+                    )
+                )
+        usage = resp.get("usage") or {}
+        # Bedrock reports `end_turn` / `tool_use` / `max_tokens` / `stop_sequence`
+        # in `stopReason` — same vocabulary as Anthropic, snake-cased.
+        stop = str(resp.get("stopReason") or "")
+        if stop == "endTurn":
+            stop = "end_turn"
+        elif stop == "toolUse":
+            stop = "tool_use"
+        return LLMResponse(
+            text="".join(text_parts),
+            tool_calls=tool_calls,
+            stop_reason=stop,
+            input_tokens=int(usage.get("inputTokens") or 0),
+            output_tokens=int(usage.get("outputTokens") or 0),
+            raw_assistant_message={"role": "assistant", "content": blocks},
+        )