overwing 0.1.0__py3-none-any.whl

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/_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/_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/_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", [])],
+        )

overwing/langchain.py

@@ -0,0 +1,255 @@
+"""Overwing guardrails for LangChain.
+
+Two ways to use it:
+
+1. A runnable you pipe after your model. It scores the model's answer and,
+   on `fail`, raises or replaces it. This is the one to reach for.
+
+       from overwing.langchain import overwing_guard
+       chain = prompt | llm | overwing_guard(on_fail="replace")
+
+2. A callback handler that scores every LLM output (and optionally every
+   prompt) as it happens. Use it to log verdicts across an application or to
+   abort a run on `fail` without changing the chain.
+
+       from overwing.langchain import OverwingCallbackHandler
+       llm.invoke("...", config={"callbacks": [OverwingCallbackHandler()]})
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Literal
+from uuid import UUID
+
+from langchain_core.callbacks import AsyncCallbackHandler, BaseCallbackHandler
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import LLMResult
+from langchain_core.runnables import RunnableLambda
+
+from ._client import AsyncOverwing, Overwing
+from ._errors import OverwingError
+from ._types import Evaluation
+
+Action = Literal["raise", "replace", "annotate"]
+DEFAULT_REPLACEMENT = "I can't share that response."
+
+
+class OverwingGuardrailError(Exception):
+    """Raised when a verdict trips the configured action."""
+
+    def __init__(self, evaluation: Evaluation, phase: str) -> None:
+        detail = ", ".join(f"{r.rule}={r.verdict}" for r in evaluation.results if r.verdict != "pass") or "no rule detail"
+        super().__init__(f"Overwing {evaluation.verdict.upper()} on {phase} ({detail}) · {evaluation.id}")
+        self.evaluation = evaluation
+        self.phase = phase
+
+
+def text_of(value: Any) -> str:
+    """Text from a string, a message, a list of messages, or anything else LangChain hands us."""
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, BaseMessage):
+        content = value.content
+        if isinstance(content, str):
+            return content.strip()
+        if isinstance(content, list):
+            return "\n".join(p.get("text", "") if isinstance(p, dict) else str(p) for p in content).strip()
+        return str(content).strip()
+    if isinstance(value, list):
+        return "\n".join(t for t in (text_of(v) for v in value) if t).strip()
+    if value is None:
+        return ""
+    try:
+        return json.dumps(value, default=str)
+    except Exception:  # noqa: BLE001
+        return str(value)
+
+
+def _decide(evaluation: Evaluation, on_fail: Action, on_review: Action) -> Action | Literal["pass"]:
+    if evaluation.verdict == "fail":
+        return on_fail
+    if evaluation.verdict == "review":
+        return on_review
+    return "pass"
+
+
+def _annotate(value: Any, evaluation: Evaluation) -> Any:
+    meta = {
+        "id": evaluation.id,
+        "verdict": evaluation.verdict,
+        "aggregate_score": evaluation.aggregate_score,
+        "confidence": evaluation.confidence,
+        "failed_rules": evaluation.failed_rules,
+        "review_rules": evaluation.review_rules,
+    }
+    if isinstance(value, BaseMessage):
+        value.response_metadata = {**(value.response_metadata or {}), "overwing": meta}
+    return value
+
+
+def _replace(value: Any, replacement: str) -> Any:
+    if isinstance(value, BaseMessage):
+        return AIMessage(content=replacement, response_metadata={**(value.response_metadata or {})})
+    return replacement
+
+
+def overwing_guard(
+    *,
+    client: Overwing | None = None,
+    rule_set: str = "content-safety",
+    on_fail: Action = "raise",
+    on_review: Action = "annotate",
+    replacement: str | Callable[[Evaluation], str] = DEFAULT_REPLACEMENT,
+    metadata: dict[str, Any] | None = None,
+    on_verdict: Callable[[Evaluation, str], None] | None = None,
+    fail_open: bool = False,
+) -> RunnableLambda:
+    """A runnable that scores whatever flows through it (string, AIMessage, or list) and acts on the verdict.
+
+    - fail    -> `on_fail`: "raise" (default) raises OverwingGuardrailError; "replace" swaps the text; "annotate" passes it through with the verdict on `response_metadata["overwing"]`.
+    - review  -> `on_review`: "annotate" (default) | "raise" | "replace".
+    - pass    -> passed through, annotated when the value is a message.
+    """
+    ow = client or Overwing()
+
+    def run(value: Any) -> Any:
+        text = text_of(value)
+        if not text:
+            return value
+        try:
+            evaluation = ow.evaluate(text, rule_set=rule_set, metadata={**(metadata or {}), "phase": "output", "source": "langchain"})
+        except OverwingError:
+            if fail_open:
+                return value
+            raise
+        if on_verdict:
+            on_verdict(evaluation, "output")
+        action = _decide(evaluation, on_fail, on_review)
+        if action == "raise":
+            raise OverwingGuardrailError(evaluation, "output")
+        if action == "replace":
+            return _annotate(_replace(value, replacement(evaluation) if callable(replacement) else replacement), evaluation)
+        return _annotate(value, evaluation)
+
+    return RunnableLambda(run, name="overwing_guard")
+
+
+class OverwingCallbackHandler(BaseCallbackHandler):
+    """Scores every LLM output (and prompts when `check_input=True`).
+
+    On `fail` the handler raises OverwingGuardrailError, which aborts the run
+    because `raise_error` is True. Set `on_fail="log"` to only record verdicts.
+    """
+
+    raise_error = True
+
+    def __init__(
+        self,
+        *,
+        client: Overwing | None = None,
+        rule_set: str = "content-safety",
+        on_fail: Literal["raise", "log"] = "raise",
+        on_review: Literal["raise", "log"] = "log",
+        check_input: bool = False,
+        metadata: dict[str, Any] | None = None,
+        on_verdict: Callable[[Evaluation, str], None] | None = None,
+        fail_open: bool = False,
+    ) -> None:
+        super().__init__()
+        self.client = client or Overwing()
+        self.rule_set = rule_set
+        self.on_fail = on_fail
+        self.on_review = on_review
+        self.check_input = check_input
+        self.metadata = metadata or {}
+        self.on_verdict = on_verdict
+        self.fail_open = fail_open
+        self.verdicts: list[tuple[str, Evaluation]] = []
+
+    def _score(self, text: str, phase: str) -> None:
+        if not text:
+            return
+        try:
+            evaluation = self.client.evaluate(text, rule_set=self.rule_set, metadata={**self.metadata, "phase": phase, "source": "langchain-callback"})
+        except OverwingError:
+            if self.fail_open:
+                return
+            raise
+        self.verdicts.append((phase, evaluation))
+        if self.on_verdict:
+            self.on_verdict(evaluation, phase)
+        if (evaluation.verdict == "fail" and self.on_fail == "raise") or (evaluation.verdict == "review" and self.on_review == "raise"):
+            raise OverwingGuardrailError(evaluation, phase)
+
+    def on_llm_start(self, serialized: dict[str, Any], prompts: list[str], *, run_id: UUID, **kwargs: Any) -> None:
+        if self.check_input:
+            self._score("\n".join(prompts).strip(), "input")
+
+    def on_chat_model_start(self, serialized: dict[str, Any], messages: list[list[BaseMessage]], *, run_id: UUID, **kwargs: Any) -> None:
+        if self.check_input:
+            last = [m for batch in messages for m in batch if getattr(m, "type", "") == "human"]
+            self._score(text_of(last[-1]) if last else "", "input")
+
+    def on_llm_end(self, response: LLMResult, *, run_id: UUID, **kwargs: Any) -> None:
+        for batch in response.generations:
+            for gen in batch:
+                self._score(gen.text.strip() if gen.text else text_of(getattr(gen, "message", None)), "output")
+
+
+class AsyncOverwingCallbackHandler(AsyncCallbackHandler):
+    """Async twin of OverwingCallbackHandler."""
+
+    raise_error = True
+
+    def __init__(
+        self,
+        *,
+        client: AsyncOverwing | None = None,
+        rule_set: str = "content-safety",
+        on_fail: Literal["raise", "log"] = "raise",
+        on_review: Literal["raise", "log"] = "log",
+        check_input: bool = False,
+        metadata: dict[str, Any] | None = None,
+        on_verdict: Callable[[Evaluation, str], None] | None = None,
+        fail_open: bool = False,
+    ) -> None:
+        super().__init__()
+        self.client = client or AsyncOverwing()
+        self.rule_set = rule_set
+        self.on_fail = on_fail
+        self.on_review = on_review
+        self.check_input = check_input
+        self.metadata = metadata or {}
+        self.on_verdict = on_verdict
+        self.fail_open = fail_open
+        self.verdicts: list[tuple[str, Evaluation]] = []
+
+    async def _score(self, text: str, phase: str) -> None:
+        if not text:
+            return
+        try:
+            evaluation = await self.client.evaluate(text, rule_set=self.rule_set, metadata={**self.metadata, "phase": phase, "source": "langchain-callback"})
+        except OverwingError:
+            if self.fail_open:
+                return
+            raise
+        self.verdicts.append((phase, evaluation))
+        if self.on_verdict:
+            self.on_verdict(evaluation, phase)
+        if (evaluation.verdict == "fail" and self.on_fail == "raise") or (evaluation.verdict == "review" and self.on_review == "raise"):
+            raise OverwingGuardrailError(evaluation, phase)
+
+    async def on_llm_start(self, serialized: dict[str, Any], prompts: list[str], *, run_id: UUID, **kwargs: Any) -> None:
+        if self.check_input:
+            await self._score("\n".join(prompts).strip(), "input")
+
+    async def on_chat_model_start(self, serialized: dict[str, Any], messages: list[list[BaseMessage]], *, run_id: UUID, **kwargs: Any) -> None:
+        if self.check_input:
+            last = [m for batch in messages for m in batch if getattr(m, "type", "") == "human"]
+            await self._score(text_of(last[-1]) if last else "", "input")
+
+    async def on_llm_end(self, response: LLMResult, *, run_id: UUID, **kwargs: Any) -> None:
+        for batch in response.generations:
+            for gen in batch:
+                await self._score(gen.text.strip() if gen.text else text_of(getattr(gen, "message", None)), "output")

overwing/openai_agents.py

@@ -0,0 +1,137 @@
+"""Overwing guardrails for the OpenAI Agents SDK (Python).
+
+    from agents import Agent, Runner
+    from overwing.openai_agents import overwing_input_guardrail, overwing_output_guardrail
+
+    agent = Agent(
+        name="Support",
+        instructions="Help the customer.",
+        input_guardrails=[overwing_input_guardrail()],
+        output_guardrails=[overwing_output_guardrail()],
+    )
+
+A tripped guardrail makes the SDK raise InputGuardrailTripwireTriggered or
+OutputGuardrailTripwireTriggered; the Overwing evaluation is on
+``exc.guardrail_result.output.output_info["evaluation"]``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Literal
+
+from agents import Agent, GuardrailFunctionOutput, InputGuardrail, OutputGuardrail, RunContextWrapper
+
+from ._client import AsyncOverwing
+from ._errors import OverwingError
+from ._types import Evaluation
+
+TripOn = Literal["fail", "fail-or-review"]
+
+
+def text_from_input(value: Any) -> str:
+    """Pull user-facing text out of the SDK's input shape (a string or a list of input items)."""
+    if isinstance(value, str):
+        return value.strip()
+    if not isinstance(value, list):
+        return ""
+    texts: list[str] = []
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        role = item.get("role")
+        if role is not None and role != "user":
+            continue
+        content = item.get("content")
+        if isinstance(content, str):
+            texts.append(content)
+        elif isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict) and isinstance(part.get("text"), str) and part.get("type") in (None, "input_text", "text"):
+                    texts.append(part["text"])
+        elif isinstance(item.get("text"), str):
+            texts.append(item["text"])
+    return "\n".join(texts).strip()
+
+
+def text_from_output(value: Any) -> str:
+    if isinstance(value, str):
+        return value.strip()
+    if value is None:
+        return ""
+    for attr in ("model_dump", "dict"):
+        fn = getattr(value, attr, None)
+        if callable(fn):
+            try:
+                return json.dumps(fn(), default=str)
+            except Exception:  # noqa: BLE001
+                break
+    try:
+        return json.dumps(value, default=str)
+    except Exception:  # noqa: BLE001
+        return str(value)
+
+
+class _Runner:
+    def __init__(self, *, client: AsyncOverwing | None, rule_set: str, trip_on: TripOn, metadata: dict[str, Any] | Callable[[], dict[str, Any]] | None, on_verdict: Callable[[Evaluation, str], None] | None, fail_open: bool) -> None:
+        self.client = client or AsyncOverwing()
+        self.rule_set = rule_set
+        self.trip_on = trip_on
+        self.metadata = metadata
+        self.on_verdict = on_verdict
+        self.fail_open = fail_open
+
+    async def run(self, text: str, phase: str) -> GuardrailFunctionOutput:
+        if not text:
+            return GuardrailFunctionOutput(output_info={"evaluation": None, "skipped": "empty"}, tripwire_triggered=False)
+        meta = self.metadata() if callable(self.metadata) else dict(self.metadata or {})
+        meta.update({"phase": phase, "source": "openai-agents"})
+        try:
+            evaluation = await self.client.evaluate(text, rule_set=self.rule_set, metadata=meta)
+        except OverwingError:
+            if self.fail_open:
+                return GuardrailFunctionOutput(output_info={"evaluation": None, "skipped": "unreachable"}, tripwire_triggered=False)
+            raise
+        if self.on_verdict:
+            self.on_verdict(evaluation, phase)
+        tripped = evaluation.verdict == "fail" or (self.trip_on == "fail-or-review" and evaluation.verdict == "review")
+        return GuardrailFunctionOutput(output_info={"evaluation": evaluation}, tripwire_triggered=tripped)
+
+
+def overwing_input_guardrail(
+    *,
+    client: AsyncOverwing | None = None,
+    rule_set: str = "content-safety",
+    trip_on: TripOn = "fail",
+    name: str = "overwing-input",
+    metadata: dict[str, Any] | Callable[[], dict[str, Any]] | None = None,
+    on_verdict: Callable[[Evaluation, str], None] | None = None,
+    fail_open: bool = False,
+    run_in_parallel: bool = True,
+) -> InputGuardrail[Any]:
+    """Scores the user's input before (or alongside) the agent run."""
+    runner = _Runner(client=client, rule_set=rule_set, trip_on=trip_on, metadata=metadata, on_verdict=on_verdict, fail_open=fail_open)
+
+    async def guardrail(ctx: RunContextWrapper[Any], agent: Agent[Any], input: Any) -> GuardrailFunctionOutput:  # noqa: A002
+        return await runner.run(text_from_input(input), "input")
+
+    return InputGuardrail(guardrail_function=guardrail, name=name, run_in_parallel=run_in_parallel)
+
+
+def overwing_output_guardrail(
+    *,
+    client: AsyncOverwing | None = None,
+    rule_set: str = "content-safety",
+    trip_on: TripOn = "fail",
+    name: str = "overwing-output",
+    metadata: dict[str, Any] | Callable[[], dict[str, Any]] | None = None,
+    on_verdict: Callable[[Evaluation, str], None] | None = None,
+    fail_open: bool = False,
+) -> OutputGuardrail[Any]:
+    """Scores the agent's final output before it is returned."""
+    runner = _Runner(client=client, rule_set=rule_set, trip_on=trip_on, metadata=metadata, on_verdict=on_verdict, fail_open=fail_open)
+
+    async def guardrail(ctx: RunContextWrapper[Any], agent: Agent[Any], output: Any) -> GuardrailFunctionOutput:
+        return await runner.run(text_from_output(output), "output")
+
+    return OutputGuardrail(guardrail_function=guardrail, name=name)

overwing-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+overwing/__init__.py,sha256=yjoApvQWTDbKPu9nSRlqL-BU26Ah_HDvN5zLkPILiqE,343
+overwing/_client.py,sha256=7irHyp_t6V7rQvYmwG9ynZLR9CSnaWYSL-gi8sTjdZA,8870
+overwing/_errors.py,sha256=daQrWoYNGduhq2oSXItUwv4gCjKGKlHGHgMllb20JWE,369
+overwing/_types.py,sha256=pEzHS4eVydUyDfyrt9XgKTMAVQg54ZnrFkLBIKUqTck,2290
+overwing/langchain.py,sha256=XtDFgPJbjuhQmPXZrZMrV4fXCzShHJTTQ8QkOdIRS-I,10262
+overwing/openai_agents.py,sha256=cTu3CJxfiUKgJbxGcrbYLDNZsRjBuwzaOfhmeOggVrs,5596
+overwing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+overwing-0.1.0.dist-info/METADATA,sha256=WXcgKaR-WnVhfrpWMtKdA-A90iSH8XfZBOVCQ7AzOxk,6785
+overwing-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+overwing-0.1.0.dist-info/licenses/LICENSE,sha256=OrKI5tjJZ3skIwOkce1ypaRMFLKKYH7VfdfHi0NN9oY,1079
+overwing-0.1.0.dist-info/RECORD,,

overwing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

overwing-0.1.0.dist-info/licenses/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.