brrragent 0.4.2__tar.gz

brrragent-0.4.2/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.egg-info/
+.venv/
+.coverage
+.coverage.*
+.pytest_cache/
+.ruff_cache/
+coverage.xml
+htmlcov/
+build/
+dist/
+*.pyc
+.env
+.env.*
+!.env.example

brrragent-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Volpato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brrragent-0.4.2/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: brrragent
+Version: 0.4.2
+Summary: Reusable agent loop with multi-provider routing and MCP tool calling
+Project-URL: Homepage, https://github.com/bvolpato/brrragent
+Project-URL: Repository, https://github.com/bvolpato/brrragent
+Project-URL: Issues, https://github.com/bvolpato/brrragent/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx2<3,>=2.5
+Requires-Dist: httpx<1,>=0.27.1
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: openai<3,>=2.45.0
+Provides-Extra: gemini
+Requires-Dist: google-genai<3,>=1.0.0; extra == 'gemini'
+Description-Content-Type: text/markdown
+
+# brrragent
+
+`brrragent` is a Python package for running a synchronous model/tool loop. It
+provides a common entry point for several model APIs and converts MCP tools into
+the function-calling formats expected by those APIs.
+
+## Overview
+
+Main components:
+
+- `run_agent`: executes model responses and tool calls until completion.
+- `McpToolCaller`: discovers, filters, routes, and executes tools across one or
+  more MCP servers.
+- `McpServerConfig`: configures Streamable HTTP, legacy HTTP+SSE, stdio, or raw
+  JSON-RPC compatibility connections.
+- `KeyPool`: selects API keys and removes rate-limited keys from rotation.
+
+Model adapters cover OpenAI, OpenAI-compatible APIs, Google Gemini, OpenRouter,
+and the optional Codex OAuth backend. Structured outputs, retry handling, tool
+result truncation, and provider routing are handled by the package.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+uv add brrragent
+```
+
+Gemini support uses an optional dependency:
+
+```bash
+uv add "brrragent[gemini]"
+```
+
+Use `uv pip install` instead when installing into an existing environment.
+
+## Basic use
+
+```python
+from brrragent import McpToolCaller, run_agent
+
+with McpToolCaller(endpoint="https://mcp.example.com/mcp") as mcp:
+    result = run_agent(
+        system_prompt="Follow the request and use available tools when needed.",
+        user_prompt="Return a short response.",
+        model="openai/gpt-5.5",
+        mcp=mcp,
+    )
+
+print(result)
+```
+
+Provider credentials are read from the caller's environment. Common variables
+are `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `GEMINI_API_KEY`.
+
+## Codex OAuth
+
+Create brrragent-owned Codex credentials with device login:
+
+```bash
+uv run brrragent-auth login
+```
+
+This writes direct OAuth credentials to `~/.cache/brrragent/codex-auth.json`
+and Codex CLI credentials to `~/.cache/brrragent/codex-home/auth.json`, both
+with `0600` permissions. Default routing does not read shared OpenCode auth or
+`~/.codex/auth.json`.
+
+Override locations with `BRRRAGENT_AUTH_PATH`, `BRRRAGENT_CODEX_HOME`, or
+command flags. Existing callers can still use `BRRRAGENT_OPENCODE_AUTH_PATH`
+and explicit `CODEX_HOME` values.
+
+Use one independently issued profile per application or worker group to avoid
+refresh-token rotation conflicts:
+
+```bash
+uv run brrragent-auth login --profile content-worker
+BRRRAGENT_PROFILE=content-worker uv run your-application
+```
+
+Prefer per-call selection when one process handles multiple use cases:
+
+```python
+from brrragent import CodexAuthConfig, run_agent
+
+result = run_agent(
+    system_prompt="Return a concise answer.",
+    user_prompt="Summarize this input.",
+    model="codex/gpt-5.6-luna:medium",
+    codex_auth=CodexAuthConfig(profile="content-worker"),
+)
+```
+
+Explicit paths are also supported with
+`CodexAuthConfig(auth_path="...", codex_home="...")`. Per-call selection is
+context-local, so concurrent use cases do not need to mutate process-wide
+environment variables.
+
+Named profiles live under `~/.cache/brrragent/profiles/<profile>/`. Run device
+login separately for every profile; copying an auth file also copies its
+rotating refresh token and does not provide isolation. `BRRRAGENT_PROFILE_ROOT`
+can move the profile directory. A named profile also takes precedence over a
+generic `CODEX_HOME` value.
+
+## Prompt caching
+
+Keep reusable tools and system instructions before request-specific content.
+Use one versioned key per stable prompt without user IDs, timestamps, URLs, or
+prompt text:
+
+```python
+from brrragent import PromptCacheConfig
+
+cache = PromptCacheConfig(key="workflow:v2", ttl="1h")
+```
+
+Pass `prompt_cache=cache` to `run_agent`. brrragent maps it to supported cache
+keys, explicit breakpoints, provider affinity, and Anthropic cache controls.
+Gemini uses its stable system-first prefix for implicit caching. An optional
+`on_usage` callback receives normalized token and cache usage for each request.
+
+## MCP servers
+
+One caller can combine multiple endpoints:
+
+```python
+from brrragent import McpToolCaller
+
+mcp = McpToolCaller(
+    endpoints=[
+        "https://mcp.example.com/one",
+        "https://mcp.example.com/two",
+    ],
+    allowed_tools={"*"},
+    excluded_tools={"internal_*"},
+)
+```
+
+Use explicit server configuration to mix transports or prefix tool names:
+
+```python
+from brrragent import McpServerConfig, McpToolCaller
+
+mcp = McpToolCaller(
+    servers=[
+        McpServerConfig(
+            name="remote",
+            url="https://mcp.example.com/mcp",
+            tool_prefix="remote_",
+        ),
+        McpServerConfig(
+            name="local",
+            transport="stdio",
+            command="uvx",
+            args=("example-mcp-server",),
+            tool_prefix="local_",
+        ),
+    ]
+)
+```
+
+`transport="auto"` tries Streamable HTTP, legacy HTTP+SSE, then raw JSON-RPC
+POST compatibility. Standard transports use MCP initialization, version
+negotiation, persistent sessions, and clean shutdown. Duplicate visible tool
+names require `tool_prefix` configuration.
+
+HTTP auth objects in `McpServerConfig` use `httpx2.Auth`, matching MCP SDK v2.
+HTTP transports use the operating system trust store; set `SSL_CERT_FILE` or
+`SSL_CERT_DIR` for custom certificate authorities.
+
+`BRRRAGENT_MCP_URL` configures one default endpoint. `BRRRAGENT_MCP_URLS`
+accepts comma-separated endpoints.
+
+Tool filters accept exact names and case-sensitive shell patterns such as
+`*_search`. Exclusions apply during discovery and execution.
+
+## Public API
+
+```python
+from brrragent import (
+    AgentUsage,
+    KeyPool,
+    McpServerConfig,
+    McpToolCaller,
+    PromptCacheConfig,
+    RateLimitExhausted,
+    get_default_caller,
+    pick_env_key,
+    pick_key,
+    run_agent,
+)
+```
+
+## Requirements
+
+- Python 3.12 or newer
+- `httpx>=0.27.1,<1`
+- `httpx2>=2.5,<3`
+- `mcp>=2.0.0,<3`
+- `openai>=2.45.0,<3`
+- `google-genai>=1.0.0,<3` for the `gemini` extra
+
+## License
+
+MIT

brrragent-0.4.2/README.md

@@ -0,0 +1,206 @@
+# brrragent
+
+`brrragent` is a Python package for running a synchronous model/tool loop. It
+provides a common entry point for several model APIs and converts MCP tools into
+the function-calling formats expected by those APIs.
+
+## Overview
+
+Main components:
+
+- `run_agent`: executes model responses and tool calls until completion.
+- `McpToolCaller`: discovers, filters, routes, and executes tools across one or
+  more MCP servers.
+- `McpServerConfig`: configures Streamable HTTP, legacy HTTP+SSE, stdio, or raw
+  JSON-RPC compatibility connections.
+- `KeyPool`: selects API keys and removes rate-limited keys from rotation.
+
+Model adapters cover OpenAI, OpenAI-compatible APIs, Google Gemini, OpenRouter,
+and the optional Codex OAuth backend. Structured outputs, retry handling, tool
+result truncation, and provider routing are handled by the package.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+uv add brrragent
+```
+
+Gemini support uses an optional dependency:
+
+```bash
+uv add "brrragent[gemini]"
+```
+
+Use `uv pip install` instead when installing into an existing environment.
+
+## Basic use
+
+```python
+from brrragent import McpToolCaller, run_agent
+
+with McpToolCaller(endpoint="https://mcp.example.com/mcp") as mcp:
+    result = run_agent(
+        system_prompt="Follow the request and use available tools when needed.",
+        user_prompt="Return a short response.",
+        model="openai/gpt-5.5",
+        mcp=mcp,
+    )
+
+print(result)
+```
+
+Provider credentials are read from the caller's environment. Common variables
+are `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `GEMINI_API_KEY`.
+
+## Codex OAuth
+
+Create brrragent-owned Codex credentials with device login:
+
+```bash
+uv run brrragent-auth login
+```
+
+This writes direct OAuth credentials to `~/.cache/brrragent/codex-auth.json`
+and Codex CLI credentials to `~/.cache/brrragent/codex-home/auth.json`, both
+with `0600` permissions. Default routing does not read shared OpenCode auth or
+`~/.codex/auth.json`.
+
+Override locations with `BRRRAGENT_AUTH_PATH`, `BRRRAGENT_CODEX_HOME`, or
+command flags. Existing callers can still use `BRRRAGENT_OPENCODE_AUTH_PATH`
+and explicit `CODEX_HOME` values.
+
+Use one independently issued profile per application or worker group to avoid
+refresh-token rotation conflicts:
+
+```bash
+uv run brrragent-auth login --profile content-worker
+BRRRAGENT_PROFILE=content-worker uv run your-application
+```
+
+Prefer per-call selection when one process handles multiple use cases:
+
+```python
+from brrragent import CodexAuthConfig, run_agent
+
+result = run_agent(
+    system_prompt="Return a concise answer.",
+    user_prompt="Summarize this input.",
+    model="codex/gpt-5.6-luna:medium",
+    codex_auth=CodexAuthConfig(profile="content-worker"),
+)
+```
+
+Explicit paths are also supported with
+`CodexAuthConfig(auth_path="...", codex_home="...")`. Per-call selection is
+context-local, so concurrent use cases do not need to mutate process-wide
+environment variables.
+
+Named profiles live under `~/.cache/brrragent/profiles/<profile>/`. Run device
+login separately for every profile; copying an auth file also copies its
+rotating refresh token and does not provide isolation. `BRRRAGENT_PROFILE_ROOT`
+can move the profile directory. A named profile also takes precedence over a
+generic `CODEX_HOME` value.
+
+## Prompt caching
+
+Keep reusable tools and system instructions before request-specific content.
+Use one versioned key per stable prompt without user IDs, timestamps, URLs, or
+prompt text:
+
+```python
+from brrragent import PromptCacheConfig
+
+cache = PromptCacheConfig(key="workflow:v2", ttl="1h")
+```
+
+Pass `prompt_cache=cache` to `run_agent`. brrragent maps it to supported cache
+keys, explicit breakpoints, provider affinity, and Anthropic cache controls.
+Gemini uses its stable system-first prefix for implicit caching. An optional
+`on_usage` callback receives normalized token and cache usage for each request.
+
+## MCP servers
+
+One caller can combine multiple endpoints:
+
+```python
+from brrragent import McpToolCaller
+
+mcp = McpToolCaller(
+    endpoints=[
+        "https://mcp.example.com/one",
+        "https://mcp.example.com/two",
+    ],
+    allowed_tools={"*"},
+    excluded_tools={"internal_*"},
+)
+```
+
+Use explicit server configuration to mix transports or prefix tool names:
+
+```python
+from brrragent import McpServerConfig, McpToolCaller
+
+mcp = McpToolCaller(
+    servers=[
+        McpServerConfig(
+            name="remote",
+            url="https://mcp.example.com/mcp",
+            tool_prefix="remote_",
+        ),
+        McpServerConfig(
+            name="local",
+            transport="stdio",
+            command="uvx",
+            args=("example-mcp-server",),
+            tool_prefix="local_",
+        ),
+    ]
+)
+```
+
+`transport="auto"` tries Streamable HTTP, legacy HTTP+SSE, then raw JSON-RPC
+POST compatibility. Standard transports use MCP initialization, version
+negotiation, persistent sessions, and clean shutdown. Duplicate visible tool
+names require `tool_prefix` configuration.
+
+HTTP auth objects in `McpServerConfig` use `httpx2.Auth`, matching MCP SDK v2.
+HTTP transports use the operating system trust store; set `SSL_CERT_FILE` or
+`SSL_CERT_DIR` for custom certificate authorities.
+
+`BRRRAGENT_MCP_URL` configures one default endpoint. `BRRRAGENT_MCP_URLS`
+accepts comma-separated endpoints.
+
+Tool filters accept exact names and case-sensitive shell patterns such as
+`*_search`. Exclusions apply during discovery and execution.
+
+## Public API
+
+```python
+from brrragent import (
+    AgentUsage,
+    KeyPool,
+    McpServerConfig,
+    McpToolCaller,
+    PromptCacheConfig,
+    RateLimitExhausted,
+    get_default_caller,
+    pick_env_key,
+    pick_key,
+    run_agent,
+)
+```
+
+## Requirements
+
+- Python 3.12 or newer
+- `httpx>=0.27.1,<1`
+- `httpx2>=2.5,<3`
+- `mcp>=2.0.0,<3`
+- `openai>=2.45.0,<3`
+- `google-genai>=1.0.0,<3` for the `gemini` extra
+
+## License
+
+MIT

brrragent-0.4.2/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes target latest published release.
+
+## Reporting a vulnerability
+
+Use [GitHub private vulnerability reporting](https://github.com/bvolpato/brrragent/security/advisories/new).
+Do not open public issue for undisclosed vulnerabilities.
+
+Include affected version, impact, reproduction steps, and any suggested fix.
+Redact credentials, access tokens, private prompts, and customer data.

brrragent-0.4.2/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "brrragent"
+version = "0.4.2"
+description = "Reusable agent loop with multi-provider routing and MCP tool calling"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27.1,<1",
+    "httpx2>=2.5,<3",
+    "mcp>=2.0.0,<3",
+    "openai>=2.45.0,<3",
+]
+
+[project.scripts]
+brrragent-auth = "brrragent.auth_cli:main"
+
+[project.optional-dependencies]
+gemini = ["google-genai>=1.0.0,<3"]
+
+[project.urls]
+Homepage = "https://github.com/bvolpato/brrragent"
+Repository = "https://github.com/bvolpato/brrragent"
+Issues = "https://github.com/bvolpato/brrragent/issues"
+
+[dependency-groups]
+dev = [
+    "check-wheel-contents>=0.6,<0.7",
+    "pytest>=8.0.0",
+    "pytest-cov>=7,<8",
+    "ruff>=0.16.1,<0.17",
+    "twine>=7.0.0,<8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/brrragent"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/.gitignore"]
+include = [
+    "/LICENSE",
+    "/README.md",
+    "/SECURITY.md",
+    "/pyproject.toml",
+    "/src",
+    "/tests",
+]
+
+[tool.pytest.ini_options]
+addopts = ["--strict-config", "--strict-markers"]
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
+
+[tool.coverage.run]
+branch = true
+source = ["brrragent"]
+
+[tool.coverage.report]
+fail_under = 75
+show_missing = true
+skip_covered = true

brrragent-0.4.2/src/brrragent/__init__.py

@@ -0,0 +1,40 @@
+"""
+brrragent — Reusable agentic react loop with MCP tool calling.
+
+Provides:
+  - McpToolCaller: Multi-server MCP bridge (OpenAI + Gemini formats)
+  - McpServerConfig: Streamable HTTP, SSE, stdio, or legacy JSON configuration
+  - run_agent: Smart-routed agentic loop (Gemini direct, OpenAI direct, Codex OAuth, OpenRouter)
+  - get_default_caller: Singleton McpToolCaller instance
+  - pick_key / pick_env_key: Handle comma-separated API keys
+  - KeyPool: Thread-safe key pool with 429 eviction (works for any provider)
+  - RateLimitExhausted: Exception when all keys are rate-limited
+
+Backends (importable individually):
+  - brrragent.openrouter: OpenRouter/OpenAI-compatible backend
+  - brrragent.openai_direct: OpenAI native backend
+  - brrragent.codex_oauth: ChatGPT/Codex OAuth backend via isolated auth
+  - brrragent.gemini: Google Gemini direct backend
+  - brrragent.keys: API key utilities
+"""
+
+from brrragent.agent import run_agent
+from brrragent.codex_oauth import CodexAuthConfig, codex_auth_context
+from brrragent.keys import KeyPool, RateLimitExhausted, pick_env_key, pick_key
+from brrragent.mcp_tools import McpServerConfig, McpToolCaller, get_default_caller
+from brrragent.prompt_cache import AgentUsage, PromptCacheConfig
+
+__all__ = [
+    "AgentUsage",
+    "CodexAuthConfig",
+    "KeyPool",
+    "McpServerConfig",
+    "McpToolCaller",
+    "PromptCacheConfig",
+    "RateLimitExhausted",
+    "get_default_caller",
+    "codex_auth_context",
+    "pick_env_key",
+    "pick_key",
+    "run_agent",
+]

brrragent-0.4.2/src/brrragent/_errors.py

@@ -0,0 +1,7 @@
+def safe_error_summary(error: BaseException) -> str:
+    """Describe an error without copying provider-controlled response text."""
+    name = type(error).__name__
+    status = getattr(error, "status_code", None)
+    if isinstance(status, int):
+        return f"{name} (HTTP {status})"
+    return name