guardloop 0.2.0__tar.gz

guardloop-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Build package
+        run: uv build --sdist --wheel
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/project/guardloop/
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

guardloop-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv

guardloop-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 awesome-pro
+
+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.

guardloop-0.2.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: guardloop
+Version: 0.2.0
+Summary: A production runtime guardrail for AI agents: budget caps, timeouts, tool limits, and OpenTelemetry traces.
+Project-URL: Homepage, https://github.com/awesome-pro/guardloop
+Project-URL: Documentation, https://github.com/awesome-pro/guardloop#readme
+Project-URL: Repository, https://github.com/awesome-pro/guardloop
+Project-URL: Issues, https://github.com/awesome-pro/guardloop/issues
+Project-URL: Changelog, https://github.com/awesome-pro/guardloop/releases
+Author-email: awesome-pro <147910430+awesome-pro@users.noreply.github.com>
+Maintainer-email: awesome-pro <147910430+awesome-pro@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic-ai,ai-agents,ai-safety,anthropic,circuit-breaker,llm,mlops,openai,opentelemetry,runtime-guardrails
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anthropic<1,>=0.97.0
+Requires-Dist: openai<3,>=2.33.0
+Requires-Dist: opentelemetry-api<2,>=1.41.1
+Requires-Dist: pydantic<3,>=2.13.3
+Requires-Dist: tiktoken<1,>=0.12.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.41.1; extra == 'otel'
+Requires-Dist: opentelemetry-sdk<2,>=1.41.1; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# GuardLoop
+
+GuardLoop is a production runtime guardrail for AI agents. It wraps model
+clients and tools with hard budget caps, timeout control, tool-call limits, and
+per-tool circuit breakers, with OpenTelemetry traces for every protected call.
+Runaway agent loops can be stopped before they burn through money, and flaky
+tools can be cut off before an agent retries them into a bigger incident.
+
+The v0.2 focus is intentionally sharp: **runtime guardrails for async Python
+agents** using direct OpenAI and Anthropic wrappers plus protected tool calls.
+
+```python
+from guardloop import (
+    GuardLoop,
+    BudgetConfig,
+    CircuitBreakerConfig,
+    CircuitBreakerPolicy,
+    RunContext,
+)
+
+runtime = GuardLoop(
+    budget=BudgetConfig(
+        cost_limit_usd="0.10",
+        token_limit=10_000,
+        time_limit_seconds=60,
+        tool_call_limit=20,
+    ),
+    circuit_breakers=CircuitBreakerConfig(
+        default=CircuitBreakerPolicy(
+            failure_threshold=3,
+            recovery_timeout_seconds=30,
+        )
+    ),
+)
+
+
+async def agent(ctx: RunContext, prompt: str) -> str:
+    response = await ctx.openai.responses.create(
+        model="gpt-5.2",
+        input=prompt,
+        max_output_tokens=300,
+    )
+    return str(response.output_text)
+
+
+result = await runtime.run(agent, "research agent runtime safety")
+print(result.model_dump_json(indent=2))
+```
+
+## Why This Exists
+
+Agents are loops around probabilistic systems. When they go wrong, they can call
+the same model or tool repeatedly, spend unexpected money, and fail without a
+clear trace. GuardLoop puts an explicit execution layer around that loop:
+
+```mermaid
+flowchart LR
+    U["User code"] --> R["GuardLoop"]
+    R --> B["BudgetController"]
+    R --> CB["CircuitBreakerRegistry"]
+    R --> T["OpenTelemetry spans"]
+    R --> C["RunContext"]
+    C --> O["Wrapped OpenAI client"]
+    C --> A["Wrapped Anthropic client"]
+    C --> W["Wrapped tools"]
+```
+
+## Install
+
+After the first PyPI release is published:
+
+```bash
+pip install guardloop
+```
+
+For local development:
+
+```bash
+uv sync
+```
+
+Optional OpenTelemetry exporters are available through the `otel` extra:
+
+```bash
+pip install "guardloop[otel]"
+```
+
+For local development with the extra:
+
+```bash
+uv sync --extra otel
+```
+
+## Try the No-Key Demo
+
+```bash
+uv run python examples/runaway_cost_prevention.py
+```
+
+The demo uses a fake OpenAI-compatible client and intentionally loops forever.
+GuardLoop stops it when the next model request would exceed the cost cap.
+
+```bash
+uv run python examples/tool_circuit_breaker.py
+```
+
+This demo uses a failing fake tool. GuardLoop allows the first failures,
+opens the circuit breaker, then rejects the next call without invoking the tool.
+
+## Live Provider Smoke Tests
+
+```bash
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+
+uv run python examples/live_openai_basic.py
+uv run python examples/live_anthropic_basic.py
+```
+
+Both live examples can be customized with `OPENAI_MODEL` or `ANTHROPIC_MODEL`.
+
+## Quality Gates
+
+```bash
+uv run pytest
+uv run pytest --cov=guardloop
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+```
+
+## v0.2 Scope
+
+- Async Python runtime with `src/` package layout.
+- Hard caps for cost, tokens, time, and tool calls.
+- Per-tool circuit breakers with closed, open, and half-open states.
+- Global default breaker policy plus per-tool overrides.
+- Direct wrappers for `AsyncOpenAI.responses.create`.
+- Direct wrappers for `AsyncAnthropic.messages.create`.
+- OpenTelemetry spans for agent runs, LLM calls, and tools.
+- Fake-client tests and demos that do not require API keys.
+
+## Roadmap
+
+- v0.2: per-tool circuit breakers.
+- v0.3: verifier/self-healing retry loop.
+- v0.4: LangGraph and OpenAI Agents SDK adapters.
+- v0.5: Jaeger/Phoenix trace screenshots, blog post, and GitHub release.

guardloop-0.2.0/README.md

@@ -0,0 +1,148 @@
+# GuardLoop
+
+GuardLoop is a production runtime guardrail for AI agents. It wraps model
+clients and tools with hard budget caps, timeout control, tool-call limits, and
+per-tool circuit breakers, with OpenTelemetry traces for every protected call.
+Runaway agent loops can be stopped before they burn through money, and flaky
+tools can be cut off before an agent retries them into a bigger incident.
+
+The v0.2 focus is intentionally sharp: **runtime guardrails for async Python
+agents** using direct OpenAI and Anthropic wrappers plus protected tool calls.
+
+```python
+from guardloop import (
+    GuardLoop,
+    BudgetConfig,
+    CircuitBreakerConfig,
+    CircuitBreakerPolicy,
+    RunContext,
+)
+
+runtime = GuardLoop(
+    budget=BudgetConfig(
+        cost_limit_usd="0.10",
+        token_limit=10_000,
+        time_limit_seconds=60,
+        tool_call_limit=20,
+    ),
+    circuit_breakers=CircuitBreakerConfig(
+        default=CircuitBreakerPolicy(
+            failure_threshold=3,
+            recovery_timeout_seconds=30,
+        )
+    ),
+)
+
+
+async def agent(ctx: RunContext, prompt: str) -> str:
+    response = await ctx.openai.responses.create(
+        model="gpt-5.2",
+        input=prompt,
+        max_output_tokens=300,
+    )
+    return str(response.output_text)
+
+
+result = await runtime.run(agent, "research agent runtime safety")
+print(result.model_dump_json(indent=2))
+```
+
+## Why This Exists
+
+Agents are loops around probabilistic systems. When they go wrong, they can call
+the same model or tool repeatedly, spend unexpected money, and fail without a
+clear trace. GuardLoop puts an explicit execution layer around that loop:
+
+```mermaid
+flowchart LR
+    U["User code"] --> R["GuardLoop"]
+    R --> B["BudgetController"]
+    R --> CB["CircuitBreakerRegistry"]
+    R --> T["OpenTelemetry spans"]
+    R --> C["RunContext"]
+    C --> O["Wrapped OpenAI client"]
+    C --> A["Wrapped Anthropic client"]
+    C --> W["Wrapped tools"]
+```
+
+## Install
+
+After the first PyPI release is published:
+
+```bash
+pip install guardloop
+```
+
+For local development:
+
+```bash
+uv sync
+```
+
+Optional OpenTelemetry exporters are available through the `otel` extra:
+
+```bash
+pip install "guardloop[otel]"
+```
+
+For local development with the extra:
+
+```bash
+uv sync --extra otel
+```
+
+## Try the No-Key Demo
+
+```bash
+uv run python examples/runaway_cost_prevention.py
+```
+
+The demo uses a fake OpenAI-compatible client and intentionally loops forever.
+GuardLoop stops it when the next model request would exceed the cost cap.
+
+```bash
+uv run python examples/tool_circuit_breaker.py
+```
+
+This demo uses a failing fake tool. GuardLoop allows the first failures,
+opens the circuit breaker, then rejects the next call without invoking the tool.
+
+## Live Provider Smoke Tests
+
+```bash
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+
+uv run python examples/live_openai_basic.py
+uv run python examples/live_anthropic_basic.py
+```
+
+Both live examples can be customized with `OPENAI_MODEL` or `ANTHROPIC_MODEL`.
+
+## Quality Gates
+
+```bash
+uv run pytest
+uv run pytest --cov=guardloop
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+```
+
+## v0.2 Scope
+
+- Async Python runtime with `src/` package layout.
+- Hard caps for cost, tokens, time, and tool calls.
+- Per-tool circuit breakers with closed, open, and half-open states.
+- Global default breaker policy plus per-tool overrides.
+- Direct wrappers for `AsyncOpenAI.responses.create`.
+- Direct wrappers for `AsyncAnthropic.messages.create`.
+- OpenTelemetry spans for agent runs, LLM calls, and tools.
+- Fake-client tests and demos that do not require API keys.
+
+## Roadmap
+
+- v0.2: per-tool circuit breakers.
+- v0.3: verifier/self-healing retry loop.
+- v0.4: LangGraph and OpenAI Agents SDK adapters.
+- v0.5: Jaeger/Phoenix trace screenshots, blog post, and GitHub release.

guardloop-0.2.0/docs/design.md

@@ -0,0 +1,48 @@
+# GuardLoop v0.2 Design
+
+GuardLoop is a wrapper, not an agent framework. A user passes an async agent
+callable to `runtime.run()`. The runtime creates a `RunContext` containing
+wrapped provider clients and tool helpers. The agent still owns its loop; the
+runtime owns enforcement.
+
+## Enforcement Points
+
+- Before each LLM request, the runtime estimates input tokens, reserves the
+  declared maximum output tokens, and checks cost/token caps.
+- After each LLM response, the runtime records actual usage from provider
+  metadata.
+- Before each tool call, the runtime checks the tool's circuit breaker, then
+  checks and increments the tool-call count.
+- The full run is bounded by `asyncio.timeout()` and monotonic clock checks.
+
+## Circuit Breakers
+
+Circuit breaker state lives on the `GuardLoop` instance, so it persists
+across multiple `runtime.run()` calls without becoming process-global. Each
+tool name gets an independent state machine:
+
+```mermaid
+stateDiagram-v2
+    [*] --> closed
+    closed --> open: failure threshold reached
+    open --> half_open: cooldown elapsed
+    half_open --> closed: trial successes reached
+    half_open --> open: trial failure
+```
+
+When a breaker is open, the tool call is rejected before the tool-call budget is
+incremented and before user code is invoked. Normal tool exceptions count as
+failures. Controlled runtime stops, cancellations, timeouts, and open-breaker
+rejections do not count as tool failures.
+
+## Pricing
+
+Built-in prices are defaults, not truth forever. Callers can pass
+`ModelPricing` entries to override or add models as providers update pricing.
+
+## Telemetry
+
+Provider wrappers emit OpenTelemetry spans through a small conventions module.
+This keeps GenAI semantic convention names isolated while the standard evolves.
+Tool spans also include circuit breaker state, failure count, and whether a
+call was blocked.

guardloop-0.2.0/docs/pypi-publishing.md

@@ -0,0 +1,66 @@
+# Publishing GuardLoop to PyPI
+
+GuardLoop is configured for PyPI Trusted Publishing from GitHub Actions.
+This avoids long-lived PyPI API tokens and gives GitHub a visible `pypi`
+deployment in the repository sidebar after a successful publish.
+
+## One-Time PyPI Setup
+
+Create or log in to your PyPI account at https://pypi.org. The package name is
+`guardloop`.
+
+Because the project does not exist on PyPI yet, add a pending trusted publisher:
+
+- Go to your PyPI account sidebar and open **Publishing**.
+- Add a new GitHub pending publisher.
+- Use owner `awesome-pro`.
+- Use repository `guardloop`.
+- Use workflow filename `publish-pypi.yml`.
+- Leave environment blank so PyPI shows `Environment name: (Any)`.
+- Use project name `guardloop`.
+
+Pending publishers do not reserve the package name until the first successful
+publish, so run the first publish soon after creating it.
+
+The GitHub workflow still uses a GitHub environment named `pypi` so the
+repository sidebar shows a clean `pypi` deployment after publishing. A PyPI
+publisher configured with `Environment name: (Any)` accepts that workflow.
+
+## First Publish
+
+After the pending publisher exists on PyPI, run the GitHub workflow manually:
+
+```bash
+gh workflow run publish-pypi.yml --repo awesome-pro/guardloop --ref main
+```
+
+Then watch it:
+
+```bash
+gh run list --repo awesome-pro/guardloop --workflow publish-pypi.yml --limit 1
+```
+
+When the run succeeds, PyPI should show:
+
+```text
+https://pypi.org/project/guardloop/
+```
+
+The package can then be installed with:
+
+```bash
+pip install guardloop
+```
+
+## Future Releases
+
+For future versions:
+
+1. Bump `version` in `pyproject.toml`.
+2. Build and test locally.
+3. Commit and tag the release.
+4. Create a GitHub release.
+
+The `Publish to PyPI` workflow also runs automatically when a GitHub release is
+published, so normal releases will publish to PyPI without a manual workflow
+dispatch.

guardloop-0.2.0/docs/roadmap.md

@@ -0,0 +1,27 @@
+# GuardLoop Roadmap
+
+## v0.1: Runtime Guardrails
+
+The first release proves the most interview-friendly production failure mode:
+a runaway agent loop is stopped before the next LLM call would exceed the
+configured budget.
+
+## v0.2: Circuit Breakers
+
+Implemented per-tool state machines with closed, open, and half-open states.
+Tool calls that repeatedly fail are rejected immediately during the open period.
+
+## v0.3: Verifier Retry Loop
+
+Next, add deterministic and LLM-based verifiers that can reject final outputs
+and send bounded feedback into a retry attempt.
+
+## v0.4: Framework Adapters
+
+Add adapters for LangGraph and OpenAI Agents SDK without changing the core
+runtime model.
+
+## v0.5: Portfolio Polish
+
+Add Jaeger/Phoenix trace screenshots, a demo video, a blog post, and release
+packaging for GitHub and PyPI.

guardloop-0.2.0/examples/live_anthropic_basic.py

@@ -0,0 +1,47 @@
+"""Optional live Anthropic smoke test."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from guardloop import BudgetConfig, GuardLoop, RunContext
+
+
+def _content_text(message: object) -> str:
+    blocks = getattr(message, "content", [])
+    texts: list[str] = []
+    for block in blocks:
+        text = getattr(block, "text", None)
+        if isinstance(text, str):
+            texts.append(text)
+    return "\n".join(texts)
+
+
+async def agent(ctx: RunContext, prompt: str) -> str:
+    message = await ctx.anthropic.messages.create(
+        model=os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-20250514"),
+        max_tokens=120,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return _content_text(message)
+
+
+async def main() -> None:
+    if not os.getenv("ANTHROPIC_API_KEY"):
+        raise SystemExit("Set ANTHROPIC_API_KEY before running this live example.")
+
+    runtime = GuardLoop(
+        budget=BudgetConfig(
+            cost_limit_usd="0.05",
+            token_limit=5_000,
+            time_limit_seconds=60,
+            tool_call_limit=5,
+        )
+    )
+    result = await runtime.run(agent, "Explain agent runtime budget caps in two sentences.")
+    print(result.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

guardloop-0.2.0/examples/live_openai_basic.py

@@ -0,0 +1,42 @@
+"""Optional live OpenAI smoke test."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Protocol, cast
+
+from guardloop import BudgetConfig, GuardLoop, RunContext
+
+
+class HasOutputText(Protocol):
+    output_text: str
+
+
+async def agent(ctx: RunContext, prompt: str) -> str:
+    response = await ctx.openai.responses.create(
+        model=os.getenv("OPENAI_MODEL", "gpt-5.2"),
+        input=prompt,
+        max_output_tokens=120,
+    )
+    return cast(HasOutputText, response).output_text
+
+
+async def main() -> None:
+    if not os.getenv("OPENAI_API_KEY"):
+        raise SystemExit("Set OPENAI_API_KEY before running this live example.")
+
+    runtime = GuardLoop(
+        budget=BudgetConfig(
+            cost_limit_usd="0.05",
+            token_limit=5_000,
+            time_limit_seconds=60,
+            tool_call_limit=5,
+        )
+    )
+    result = await runtime.run(agent, "Explain agent runtime budget caps in two sentences.")
+    print(result.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())