overwing 0.1.0__tar.gz

overwing-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run pytest -q

overwing-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: Release to PyPI
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write   # PyPI trusted publishing, no token stored anywhere
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

overwing-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv
+dist
+__pycache__
+*.egg-info
+.pytest_cache
+.mypy_cache
+.DS_Store

overwing-0.1.0/LICENSE

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

overwing-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: overwing
+Version: 0.1.0
+Summary: Overwing SDK: guardrails for LLM output. Typed client for the Overwing API plus OpenAI Agents SDK guardrails and LangChain runnables/callbacks that check every message before it ships.
+Project-URL: Homepage, https://overwing.ai
+Project-URL: Documentation, https://overwing.ai/docs
+Project-URL: Repository, https://github.com/frod27/overwing-python
+Project-URL: Issues, https://github.com/frod27/overwing-python/issues
+Author-email: Overwing <support@overwing.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-safety,content-moderation,guardrails,langchain,llm,openai-agents,overwing,pii,toxicity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: agents
+Requires-Dist: openai-agents>=0.1; extra == 'agents'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://overwing.ai">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/frod27/overwing-python/main/assets/wordmark-dark.svg">
+      <img src="https://raw.githubusercontent.com/frod27/overwing-python/main/assets/wordmark.svg" alt="Overwing" width="220">
+    </picture>
+  </a>
+</p>
+
+<p align="center"><strong>Guardrails for LLM output, in one line.</strong><br>
+OpenAI Agents SDK guardrails, LangChain runnables and callbacks, and a typed client. Every message gets a <code>pass</code> / <code>fail</code> / <code>review</code> verdict with calibrated confidence before it reaches your user.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/overwing/"><img alt="PyPI" src="https://img.shields.io/pypi/v/overwing?color=0B1220&label=overwing"></a>
+  <a href="https://github.com/frod27/overwing-python/actions"><img alt="CI" src="https://github.com/frod27/overwing-python/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://overwing.ai/docs"><img alt="API reference" src="https://img.shields.io/badge/API-reference-0B1220"></a>
+  <a href="https://overwing.ai"><img alt="agents welcome" src="https://overwing.ai/badge.svg"></a>
+</p>
+
+---
+
+```bash
+pip install "overwing[agents]"      # OpenAI Agents SDK guardrails
+pip install "overwing[langchain]"   # LangChain guard runnable + callbacks
+```
+
+Get a free API key at [overwing.ai](https://overwing.ai/login) (250 evaluations a day), or let your agent sign itself up with one `POST` to `/api/v1/signup`. Try it first with no key: paste anything into the console at [overwing.ai](https://overwing.ai).
+
+## OpenAI Agents SDK guardrails
+
+```python
+from agents import Agent, Runner, InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered
+from overwing.openai_agents import overwing_input_guardrail, overwing_output_guardrail
+
+agent = Agent(
+    name="Support",
+    instructions="Help the customer.",
+    input_guardrails=[overwing_input_guardrail()],     # scores the user's message
+    output_guardrails=[overwing_output_guardrail()],   # scores the agent's final answer
+)
+
+try:
+    result = await Runner.run(agent, "Reach me at dana@example.com to sort out the refund.")
+except (InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered) as exc:
+    evaluation = exc.guardrail_result.output.output_info["evaluation"]
+    print(evaluation.verdict, evaluation.failed_rules)   # "fail" ["pii_detected"]
+```
+
+Both accept `rule_set`, `trip_on="fail" | "fail-or-review"`, `metadata`, `on_verdict`, and `fail_open`. Input guardrails run in parallel with the agent by default; pass `run_in_parallel=False` to block before the model is called. Reads `OVERWING_API_KEY` from the environment, or pass `client=AsyncOverwing(api_key=...)`.
+
+## LangChain
+
+Pipe a guard after your model. It scores the answer and acts on the verdict before anything downstream sees it.
+
+```python
+from overwing.langchain import overwing_guard, OverwingGuardrailError
+
+chain = prompt | llm | overwing_guard(on_fail="replace")   # or on_fail="raise" (default) / "annotate"
+msg = chain.invoke({"question": "..."})
+msg.response_metadata["overwing"]   # {"verdict": "pass", "confidence": 0.97, "failed_rules": [], ...}
+```
+
+Or observe every LLM call with a callback handler, which aborts the run on `fail`:
+
+```python
+from overwing.langchain import OverwingCallbackHandler
+
+handler = OverwingCallbackHandler(check_input=True)   # also scores the user's prompt
+llm.invoke("...", config={"callbacks": [handler]})
+handler.verdicts   # [("input", Evaluation), ("output", Evaluation), ...]
+```
+
+Both accept `rule_set`, `metadata`, `on_verdict`, and `fail_open`. There is an `AsyncOverwingCallbackHandler` too.
+
+## Client
+
+```python
+from overwing import Overwing, AsyncOverwing
+
+ow = Overwing()   # or Overwing(api_key="ow_live_...")
+
+e = ow.evaluate("Reach me at dana@example.com to sort out the refund.")
+e.verdict            # "fail"
+e.failed_rules       # ["pii_detected"]
+e.results[1]         # RuleResult(rule="pii_detected", answer=True, confidence=0.98, verdict="fail", ...)
+
+batch = ow.evaluate_batch([{"id": "a", "input": "..."}, {"id": "b", "input": "..."}])
+ow.create_rule_set(name="Support tone", slug="support-tone", rules=[...])
+ow.usage()
+
+async with AsyncOverwing() as aow:
+    e = await aow.evaluate("...")
+```
+
+`OverwingError` carries `status` and `retry_after_seconds`. 429s with a short `Retry-After` and 5xx are retried automatically. Pass `idempotency_key=` to make retries safe. Python 3.10+.
+
+## How verdicts work
+
+Each rule has a fail condition, an optional review threshold, and a weight. The prebuilt `content-safety` set checks toxicity, personal data, self-harm, sexual content, and severity. **fail** means a rule matched. **review** means a rule was unsure. **pass** is everything else. Full guide: [overwing.ai/llms.txt](https://overwing.ai/llms.txt). Reference: [overwing.ai/docs](https://overwing.ai/docs).
+
+## Also from Overwing
+
+- [`overwing`](https://github.com/frod27/overwing-js) on npm: the same client, a Vercel AI SDK middleware, and Agents SDK guardrails for JavaScript.
+- [`overwing-mcp`](https://github.com/frod27/overwing-mcp): the guardrails as MCP tools for Claude, Cursor, and any MCP client.
+
+MIT © Overwing. Verdicts are produced by TypeSafe's Jev System One model; Overwing is not affiliated with TypeSafe.

overwing-0.1.0/README.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <a href="https://overwing.ai">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/frod27/overwing-python/main/assets/wordmark-dark.svg">
+      <img src="https://raw.githubusercontent.com/frod27/overwing-python/main/assets/wordmark.svg" alt="Overwing" width="220">
+    </picture>
+  </a>
+</p>
+
+<p align="center"><strong>Guardrails for LLM output, in one line.</strong><br>
+OpenAI Agents SDK guardrails, LangChain runnables and callbacks, and a typed client. Every message gets a <code>pass</code> / <code>fail</code> / <code>review</code> verdict with calibrated confidence before it reaches your user.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/overwing/"><img alt="PyPI" src="https://img.shields.io/pypi/v/overwing?color=0B1220&label=overwing"></a>
+  <a href="https://github.com/frod27/overwing-python/actions"><img alt="CI" src="https://github.com/frod27/overwing-python/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://overwing.ai/docs"><img alt="API reference" src="https://img.shields.io/badge/API-reference-0B1220"></a>
+  <a href="https://overwing.ai"><img alt="agents welcome" src="https://overwing.ai/badge.svg"></a>
+</p>
+
+---
+
+```bash
+pip install "overwing[agents]"      # OpenAI Agents SDK guardrails
+pip install "overwing[langchain]"   # LangChain guard runnable + callbacks
+```
+
+Get a free API key at [overwing.ai](https://overwing.ai/login) (250 evaluations a day), or let your agent sign itself up with one `POST` to `/api/v1/signup`. Try it first with no key: paste anything into the console at [overwing.ai](https://overwing.ai).
+
+## OpenAI Agents SDK guardrails
+
+```python
+from agents import Agent, Runner, InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered
+from overwing.openai_agents import overwing_input_guardrail, overwing_output_guardrail
+
+agent = Agent(
+    name="Support",
+    instructions="Help the customer.",
+    input_guardrails=[overwing_input_guardrail()],     # scores the user's message
+    output_guardrails=[overwing_output_guardrail()],   # scores the agent's final answer
+)
+
+try:
+    result = await Runner.run(agent, "Reach me at dana@example.com to sort out the refund.")
+except (InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered) as exc:
+    evaluation = exc.guardrail_result.output.output_info["evaluation"]
+    print(evaluation.verdict, evaluation.failed_rules)   # "fail" ["pii_detected"]
+```
+
+Both accept `rule_set`, `trip_on="fail" | "fail-or-review"`, `metadata`, `on_verdict`, and `fail_open`. Input guardrails run in parallel with the agent by default; pass `run_in_parallel=False` to block before the model is called. Reads `OVERWING_API_KEY` from the environment, or pass `client=AsyncOverwing(api_key=...)`.
+
+## LangChain
+
+Pipe a guard after your model. It scores the answer and acts on the verdict before anything downstream sees it.
+
+```python
+from overwing.langchain import overwing_guard, OverwingGuardrailError
+
+chain = prompt | llm | overwing_guard(on_fail="replace")   # or on_fail="raise" (default) / "annotate"
+msg = chain.invoke({"question": "..."})
+msg.response_metadata["overwing"]   # {"verdict": "pass", "confidence": 0.97, "failed_rules": [], ...}
+```
+
+Or observe every LLM call with a callback handler, which aborts the run on `fail`:
+
+```python
+from overwing.langchain import OverwingCallbackHandler
+
+handler = OverwingCallbackHandler(check_input=True)   # also scores the user's prompt
+llm.invoke("...", config={"callbacks": [handler]})
+handler.verdicts   # [("input", Evaluation), ("output", Evaluation), ...]
+```
+
+Both accept `rule_set`, `metadata`, `on_verdict`, and `fail_open`. There is an `AsyncOverwingCallbackHandler` too.
+
+## Client
+
+```python
+from overwing import Overwing, AsyncOverwing
+
+ow = Overwing()   # or Overwing(api_key="ow_live_...")
+
+e = ow.evaluate("Reach me at dana@example.com to sort out the refund.")
+e.verdict            # "fail"
+e.failed_rules       # ["pii_detected"]
+e.results[1]         # RuleResult(rule="pii_detected", answer=True, confidence=0.98, verdict="fail", ...)
+
+batch = ow.evaluate_batch([{"id": "a", "input": "..."}, {"id": "b", "input": "..."}])
+ow.create_rule_set(name="Support tone", slug="support-tone", rules=[...])
+ow.usage()
+
+async with AsyncOverwing() as aow:
+    e = await aow.evaluate("...")
+```
+
+`OverwingError` carries `status` and `retry_after_seconds`. 429s with a short `Retry-After` and 5xx are retried automatically. Pass `idempotency_key=` to make retries safe. Python 3.10+.
+
+## How verdicts work
+
+Each rule has a fail condition, an optional review threshold, and a weight. The prebuilt `content-safety` set checks toxicity, personal data, self-harm, sexual content, and severity. **fail** means a rule matched. **review** means a rule was unsure. **pass** is everything else. Full guide: [overwing.ai/llms.txt](https://overwing.ai/llms.txt). Reference: [overwing.ai/docs](https://overwing.ai/docs).
+
+## Also from Overwing
+
+- [`overwing`](https://github.com/frod27/overwing-js) on npm: the same client, a Vercel AI SDK middleware, and Agents SDK guardrails for JavaScript.
+- [`overwing-mcp`](https://github.com/frod27/overwing-mcp): the guardrails as MCP tools for Claude, Cursor, and any MCP client.
+
+MIT © Overwing. Verdicts are produced by TypeSafe's Jev System One model; Overwing is not affiliated with TypeSafe.

overwing-0.1.0/assets/wordmark-dark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="220" height="44" viewBox="0 0 220 44" role="img" aria-label="Overwing">
+  <g fill="#E8EDF4" transform="translate(4,6)">
+    <path d="M4 8h24l-6 5H4z"/><path d="M4 15h16l-5 5H4z"/><path d="M4 22h8l-3 4H4z"/><rect x="4" y="28" width="24" height="2" rx="1"/>
+  </g>
+  <text x="46" y="30" font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="24" font-weight="700" letter-spacing="-0.5" fill="#E8EDF4">Overwing</text>
+</svg>

overwing-0.1.0/assets/wordmark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="220" height="44" viewBox="0 0 220 44" role="img" aria-label="Overwing">
+  <g fill="#0B1220" transform="translate(4,6)">
+    <path d="M4 8h24l-6 5H4z"/><path d="M4 15h16l-5 5H4z"/><path d="M4 22h8l-3 4H4z"/><rect x="4" y="28" width="24" height="2" rx="1"/>
+  </g>
+  <text x="46" y="30" font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="24" font-weight="700" letter-spacing="-0.5" fill="#0B1220">Overwing</text>
+</svg>

overwing-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "overwing"
+version = "0.1.0"
+description = "Overwing SDK: guardrails for LLM output. Typed client for the Overwing API plus OpenAI Agents SDK guardrails and LangChain runnables/callbacks that check every message before it ships."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Overwing", email = "support@overwing.ai" }]
+keywords = ["overwing", "guardrails", "llm", "ai-safety", "content-moderation", "pii", "toxicity", "openai-agents", "langchain", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+agents = ["openai-agents>=0.1"]
+langchain = ["langchain-core>=0.3"]
+
+[project.urls]
+Homepage = "https://overwing.ai"
+Documentation = "https://overwing.ai/docs"
+Repository = "https://github.com/frod27/overwing-python"
+Issues = "https://github.com/frod27/overwing-python/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "openai-agents>=0.1",
+    "mypy>=1.11",
+    "langchain-core>=1.6.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/overwing"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

overwing-0.1.0/src/overwing/__init__.py

@@ -0,0 +1,8 @@
+"""Overwing: guardrails for LLM output. https://overwing.ai"""
+
+from ._client import AsyncOverwing, Overwing
+from ._errors import OverwingError
+from ._types import BatchResult, Evaluation, RuleResult, Verdict
+
+__all__ = ["AsyncOverwing", "BatchResult", "Evaluation", "Overwing", "OverwingError", "RuleResult", "Verdict"]
+__version__ = "0.1.0"

overwing-0.1.0/src/overwing/_client.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+from ._errors import OverwingError
+from ._types import BatchResult, Evaluation
+
+DEFAULT_BASE_URL = "https://overwing.ai"
+_USER_AGENT = "overwing-python/0.1.0"
+
+
+def _resolve(api_key: str | None, base_url: str | None) -> tuple[str, str]:
+    key = api_key or os.environ.get("OVERWING_API_KEY")
+    if not key:
+        raise OverwingError("Overwing API key missing. Pass api_key= or set OVERWING_API_KEY. Get one at https://overwing.ai/login")
+    return key, (base_url or os.environ.get("OVERWING_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _error_from(res: httpx.Response) -> OverwingError:
+    try:
+        message = str(res.json().get("error", f"HTTP {res.status_code}"))
+    except ValueError:
+        message = f"HTTP {res.status_code}"
+    ra = res.headers.get("retry-after")
+    return OverwingError(message, res.status_code, float(ra) if ra else None)
+
+
+def _retryable(res: httpx.Response) -> bool:
+    if res.status_code == 429:
+        ra = res.headers.get("retry-after")
+        return ra is None or float(ra) <= 5
+    return res.status_code >= 500
+
+
+class _Base:
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, timeout: float = 15.0, max_retries: int = 2) -> None:
+        self._api_key, self.base_url = _resolve(api_key, base_url)
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    def _headers(self, idempotency_key: str | None = None, json_body: bool = False) -> dict[str, str]:
+        h = {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json", "User-Agent": _USER_AGENT}
+        if json_body:
+            h["Content-Type"] = "application/json"
+        if idempotency_key:
+            h["Idempotency-Key"] = idempotency_key
+        return h
+
+
+class Overwing(_Base):
+    """Synchronous client for the Overwing API."""
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, timeout: float = 15.0, max_retries: int = 2, transport: httpx.BaseTransport | None = None) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Overwing":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, *, json: Any = None, idempotency_key: str | None = None, accept: tuple[int, ...] = ()) -> Any:
+        attempt = 0
+        while True:
+            try:
+                res = self._http.request(method, path, json=json, headers=self._headers(idempotency_key, json is not None))
+            except httpx.HTTPError as e:
+                if attempt < self._max_retries:
+                    attempt += 1
+                    time.sleep(0.25 * attempt)
+                    continue
+                raise OverwingError(f"Overwing API unreachable: {e}") from e
+            if res.status_code in accept:
+                return res.json()
+            if _retryable(res) and attempt < self._max_retries:
+                attempt += 1
+                ra = res.headers.get("retry-after")
+                time.sleep(float(ra) if ra else 0.3 * attempt)
+                continue
+            if res.is_error:
+                raise _error_from(res)
+            return res.json() if res.content else None
+
+    def evaluate(self, text: str, *, rule_set: str = "content-safety", metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> Evaluation:
+        """Score one text. Raises OverwingError on any non-2xx."""
+        return Evaluation.from_dict(self._request("POST", "/api/v1/evaluate", json={"input": text, "rule_set": rule_set, "metadata": metadata}, idempotency_key=idempotency_key))
+
+    def evaluate_batch(self, items: list[dict[str, Any]], *, rule_set: str = "content-safety", idempotency_key: str | None = None) -> BatchResult:
+        """Score up to 50 texts. Each item: {"input": str, "id"?: str, "metadata"?: dict}."""
+        return BatchResult.from_dict(self._request("POST", "/api/v1/evaluate/batch", json={"rule_set": rule_set, "items": items}, idempotency_key=idempotency_key, accept=(502,)))
+
+    def get_evaluation(self, evaluation_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/evaluations/{evaluation_id}")
+
+    def list_rule_sets(self, include_inactive: bool = False) -> list[dict[str, Any]]:
+        return self._request("GET", "/api/v1/rule-sets" + ("?include_inactive=true" if include_inactive else ""))["rule_sets"]
+
+    def get_rule_set(self, slug: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/rule-sets/{slug}")
+
+    def create_rule_set(self, *, name: str, slug: str, rules: list[dict[str, Any]], description: str | None = None) -> dict[str, Any]:
+        return self._request("POST", "/api/v1/rule-sets", json={"name": name, "slug": slug, "rules": rules, "description": description})
+
+    def usage(self, days: int | None = None) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/usage" + (f"?days={days}" if days else ""))
+
+    def me(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/me")
+
+
+class AsyncOverwing(_Base):
+    """Asynchronous client for the Overwing API."""
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, timeout: float = 15.0, max_retries: int = 2, transport: httpx.AsyncBaseTransport | None = None) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self._http = httpx.AsyncClient(base_url=self.base_url, timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncOverwing":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, *, json: Any = None, idempotency_key: str | None = None, accept: tuple[int, ...] = ()) -> Any:
+        import asyncio
+
+        attempt = 0
+        while True:
+            try:
+                res = await self._http.request(method, path, json=json, headers=self._headers(idempotency_key, json is not None))
+            except httpx.HTTPError as e:
+                if attempt < self._max_retries:
+                    attempt += 1
+                    await asyncio.sleep(0.25 * attempt)
+                    continue
+                raise OverwingError(f"Overwing API unreachable: {e}") from e
+            if res.status_code in accept:
+                return res.json()
+            if _retryable(res) and attempt < self._max_retries:
+                attempt += 1
+                ra = res.headers.get("retry-after")
+                await asyncio.sleep(float(ra) if ra else 0.3 * attempt)
+                continue
+            if res.is_error:
+                raise _error_from(res)
+            return res.json() if res.content else None
+
+    async def evaluate(self, text: str, *, rule_set: str = "content-safety", metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> Evaluation:
+        return Evaluation.from_dict(await self._request("POST", "/api/v1/evaluate", json={"input": text, "rule_set": rule_set, "metadata": metadata}, idempotency_key=idempotency_key))
+
+    async def evaluate_batch(self, items: list[dict[str, Any]], *, rule_set: str = "content-safety", idempotency_key: str | None = None) -> BatchResult:
+        return BatchResult.from_dict(await self._request("POST", "/api/v1/evaluate/batch", json={"rule_set": rule_set, "items": items}, idempotency_key=idempotency_key, accept=(502,)))
+
+    async def get_evaluation(self, evaluation_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/api/v1/evaluations/{evaluation_id}")
+
+    async def list_rule_sets(self, include_inactive: bool = False) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/api/v1/rule-sets" + ("?include_inactive=true" if include_inactive else "")))["rule_sets"]
+
+    async def get_rule_set(self, slug: str) -> dict[str, Any]:
+        return await self._request("GET", f"/api/v1/rule-sets/{slug}")
+
+    async def create_rule_set(self, *, name: str, slug: str, rules: list[dict[str, Any]], description: str | None = None) -> dict[str, Any]:
+        return await self._request("POST", "/api/v1/rule-sets", json={"name": name, "slug": slug, "rules": rules, "description": description})
+
+    async def usage(self, days: int | None = None) -> dict[str, Any]:
+        return await self._request("GET", "/api/v1/usage" + (f"?days={days}" if days else ""))
+
+    async def me(self) -> dict[str, Any]:
+        return await self._request("GET", "/api/v1/me")

overwing-0.1.0/src/overwing/_errors.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+class OverwingError(Exception):
+    """Any non-2xx answer from the Overwing API, or a transport failure."""
+
+    def __init__(self, message: str, status: int = 0, retry_after_seconds: float | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.retry_after_seconds = retry_after_seconds

overwing-0.1.0/src/overwing/_types.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Verdict = Literal["pass", "fail", "review"]
+
+
+@dataclass(frozen=True)
+class RuleResult:
+    rule: str
+    type: Literal["choice", "score", "noul"]
+    answer: str | float | bool
+    probability: float
+    confidence: float
+    verdict: Verdict
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "RuleResult":
+        return cls(rule=d["rule"], type=d["type"], answer=d["answer"], probability=float(d["probability"]), confidence=float(d["confidence"]), verdict=d["verdict"])
+
+
+@dataclass(frozen=True)
+class Evaluation:
+    id: str
+    verdict: Verdict
+    aggregate_score: float
+    confidence: float
+    latency_ms: int
+    results: list[RuleResult] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def failed_rules(self) -> list[str]:
+        return [r.rule for r in self.results if r.verdict == "fail"]
+
+    @property
+    def review_rules(self) -> list[str]:
+        return [r.rule for r in self.results if r.verdict == "review"]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Evaluation":
+        return cls(
+            id=d["id"],
+            verdict=d["verdict"],
+            aggregate_score=float(d["aggregate_score"]),
+            confidence=float(d["confidence"]),
+            latency_ms=int(d["latency_ms"]),
+            results=[RuleResult.from_dict(r) for r in d.get("results", [])],
+            raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class BatchItemResult:
+    id: str | None
+    index: int
+    evaluation: Evaluation | None
+    error: str | None
+
+
+@dataclass(frozen=True)
+class BatchResult:
+    total: int
+    passed: int
+    failed: int
+    review: int
+    errors: int
+    results: list[BatchItemResult]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "BatchResult":
+        s = d["summary"]
+        return cls(
+            total=s["total"], passed=s["pass"], failed=s["fail"], review=s["review"], errors=s["errors"],
+            results=[BatchItemResult(id=r.get("id"), index=r["index"], evaluation=Evaluation.from_dict(r["evaluation"]) if r.get("evaluation") else None, error=r.get("error")) for r in d.get("results", [])],
+        )