agentrx-sdk 0.1.0__tar.gz

agentrx_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: agentrx-sdk
+Version: 0.1.0
+Summary: Drop-in recovery and resilience layer for AI agents
+Author: Chain Assets LLC
+License: MIT
+Project-URL: Homepage, https://chainassetslab.com
+Project-URL: Repository, https://github.com/chainassetslab/agentrx-python
+Keywords: ai,agents,llm,recovery,mcp,langchain,crewai
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+
+# agentrx-python
+
+Make your AI agents bulletproof in two lines.
+
+## Installation
+
+pip install agentrx-sdk
+
+## Quick Start
+
+from agentrx import with_recovery
+
+@with_recovery(api_key="your_key", agent_id="my_agent")
+async def call_my_tool(payload: dict) -> dict:
+    return await some_api.call(payload)
+
+When call_my_tool raises an exception, AgentRx diagnoses it and
+automatically retries, corrects the payload, or tells you exactly
+what went wrong.
+
+## Environment Variables
+
+AGENTRX_API_KEY  — Your API key (required)
+AGENTRX_BASE_URL — AgentRx server URL (default: http://localhost:8000)
+OTEL_TRACE_ID    — OpenTelemetry trace ID (optional)
+LANGSMITH_RUN_ID — LangSmith run ID (optional)
+
+## License
+
+MIT

agentrx_sdk-0.1.0/README.md

@@ -0,0 +1,30 @@
+# agentrx-python
+
+Make your AI agents bulletproof in two lines.
+
+## Installation
+
+pip install agentrx-sdk
+
+## Quick Start
+
+from agentrx import with_recovery
+
+@with_recovery(api_key="your_key", agent_id="my_agent")
+async def call_my_tool(payload: dict) -> dict:
+    return await some_api.call(payload)
+
+When call_my_tool raises an exception, AgentRx diagnoses it and
+automatically retries, corrects the payload, or tells you exactly
+what went wrong.
+
+## Environment Variables
+
+AGENTRX_API_KEY  — Your API key (required)
+AGENTRX_BASE_URL — AgentRx server URL (default: http://localhost:8000)
+OTEL_TRACE_ID    — OpenTelemetry trace ID (optional)
+LANGSMITH_RUN_ID — LangSmith run ID (optional)
+
+## License
+
+MIT

agentrx_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentrx-sdk"
+version = "0.1.0"
+description = "Drop-in recovery and resilience layer for AI agents"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Chain Assets LLC" }
+]
+keywords = ["ai", "agents", "llm", "recovery", "mcp", "langchain", "crewai"]
+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",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21.0",
+]
+
+[project.urls]
+Homepage   = "https://chainassetslab.com"
+Repository = "https://github.com/chainassetslab/agentrx-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths    = ["tests"]

agentrx_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentrx_sdk-0.1.0/src/agentrx/__init__.py

@@ -0,0 +1,28 @@
+"""
+agentrx — Python SDK for the AgentRx Metacognitive Recovery API
+"""
+
+from .client    import AgentRxClient
+from .decorator import with_recovery
+from .models    import (
+    ActionType,
+    AgentRxError,
+    FailureSignature,
+    HumanHandoffRequired,
+    PreflightResult,
+    RecoveryAction,
+    RecoveryException,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "with_recovery",
+    "AgentRxClient",
+    "HumanHandoffRequired",
+    "RecoveryException",
+    "AgentRxError",
+    "RecoveryAction",
+    "PreflightResult",
+    "ActionType",
+    "FailureSignature",
+]

agentrx_sdk-0.1.0/src/agentrx/client.py

@@ -0,0 +1,217 @@
+"""
+agentrx.client
+==============
+Async HTTP client for the AgentRx API.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .models import (
+    AgentRxError,
+    PreflightResult,
+    RecoveryAction,
+)
+
+_DEFAULT_BASE_URL = "http://localhost:8000"
+
+# Global schema cache — persists across client instances for the
+# lifetime of the Python process. Prevents re-uploading the same
+# schema on every tool failure when the decorator creates a new
+# client instance each call.
+_GLOBAL_SCHEMA_CACHE: Dict[str, bool] = {}
+
+
+class AgentRxClient:
+    """
+    Async HTTP client for the AgentRx API.
+
+    Usage as async context manager (recommended):
+        async with AgentRxClient(api_key="...") as rx:
+            action = await rx.diagnose(...)
+
+    Args:
+        api_key:  Your AgentRx API key. Falls back to AGENTRX_API_KEY env var.
+        base_url: AgentRx API base URL. Falls back to AGENTRX_BASE_URL env var.
+        timeout:  HTTP timeout in seconds. Default 10.
+        trace_id: Optional trace ID to propagate to AgentRx logs.
+    """
+
+    def __init__(
+        self,
+        api_key:  Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout:  float = 10.0,
+        trace_id: Optional[str] = None,
+    ) -> None:
+        self._api_key  = api_key  or os.environ.get("AGENTRX_API_KEY", "")
+        self._base_url = (base_url or os.environ.get("AGENTRX_BASE_URL", _DEFAULT_BASE_URL)).rstrip("/")
+        self._timeout  = timeout
+        self._trace_id = trace_id
+        self._schema_cache = _GLOBAL_SCHEMA_CACHE
+        self._http: Optional[httpx.AsyncClient] = None
+
+    async def open(self) -> None:
+        if not self._api_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= or set AGENTRX_API_KEY env var."
+            )
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers=self._build_headers(),
+        )
+
+    async def close(self) -> None:
+        if self._http:
+            await self._http.aclose()
+            self._http = None
+
+    async def __aenter__(self) -> "AgentRxClient":
+        await self.open()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def diagnose(
+        self,
+        agent_id:          str,
+        goal:              str,
+        tool_name:         str,
+        payload:           Dict[str, Any],
+        error_response:    Dict[str, Any],
+        latency_ms:        int                   = 0,
+        execution_history: List[Dict[str, Any]]  = None,
+        active_plan:       List[str]             = None,
+        tool_schema:       Optional[Dict[str, Any]] = None,
+    ) -> RecoveryAction:
+        self._ensure_open()
+
+        schema_hash = None
+        if tool_schema is not None:
+            schema_hash = await self._ensure_schema_cached(tool_schema)
+
+        body = {
+            "state": {
+                "agent_id":          agent_id,
+                "goal":              goal,
+                "active_plan":       active_plan or [],
+                "execution_history": execution_history or [],
+            },
+            "failure": {
+                "mcp_tool_name":     tool_name,
+                "attempted_payload": payload,
+                "error_response":    error_response,
+                "latency_ms":        latency_ms,
+            },
+        }
+        if schema_hash:
+            body["schema_hash"] = schema_hash
+
+        response = await self._post("/v1/diagnose_and_recover", body)
+        return RecoveryAction.from_dict(response)
+
+    async def preflight(
+        self,
+        agent_id:    str,
+        tool_name:   str,
+        payload:     Dict[str, Any],
+        tool_schema: Dict[str, Any],
+    ) -> PreflightResult:
+        self._ensure_open()
+
+        schema_hash = await self._ensure_schema_cached(tool_schema)
+
+        body = {
+            "agent_id":         agent_id,
+            "mcp_tool_name":    tool_name,
+            "intended_payload": payload,
+            "schema_hash":      schema_hash,
+        }
+
+        response = await self._post("/v1/preflight", body)
+        return PreflightResult.from_dict(response)
+
+    async def register_schema(self, tool_schema: Dict[str, Any]) -> str:
+        self._ensure_open()
+        response    = await self._post("/v1/schema/register", {"tool_schema": tool_schema})
+        schema_hash = response["schema_hash"]
+        _GLOBAL_SCHEMA_CACHE[schema_hash] = True
+        return schema_hash
+
+    async def clear_agent_state(self, agent_id: str) -> Dict[str, Any]:
+        self._ensure_open()
+        resp = await self._http.delete(f"/v1/state/{agent_id}")
+        return self._handle_response(resp)
+
+    def _build_headers(self) -> Dict[str, str]:
+        headers: Dict[str, str] = {
+            "X-API-Key":    self._api_key,
+            "Content-Type": "application/json",
+            "User-Agent":   "agentrx-python/0.1.0",
+        }
+        trace_id = (
+            self._trace_id
+            or os.environ.get("OTEL_TRACE_ID")
+            or os.environ.get("LANGSMITH_RUN_ID")
+        )
+        if trace_id:
+            headers["X-Trace-Id"] = trace_id
+        return headers
+
+    async def _ensure_schema_cached(self, tool_schema: Dict[str, Any]) -> str:
+        serialized  = json.dumps(tool_schema, sort_keys=True, separators=(",", ":"))
+        schema_hash = hashlib.sha256(serialized.encode()).hexdigest()
+
+        if not _GLOBAL_SCHEMA_CACHE.get(schema_hash):
+            await self.register_schema(tool_schema)
+
+        return schema_hash
+
+    async def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        resp = await self._http.post(path, json=body)
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp: httpx.Response) -> Dict[str, Any]:
+        try:
+            data = resp.json()
+        except Exception:
+            raise AgentRxError(
+                status_code=resp.status_code,
+                detail=f"Non-JSON response from AgentRx: {resp.text[:200]}",
+            )
+
+        if resp.status_code in (200, 503):
+            return data
+
+        if resp.status_code == 428:
+            raise AgentRxError(
+                status_code=428,
+                detail=(
+                    "Schema not cached on AgentRx server. "
+                    f"Detail: {data.get('detail', data)}"
+                ),
+                trace_id=data.get("trace_id"),
+            )
+
+        detail = data.get("detail") or data.get("message") or str(data)
+        raise AgentRxError(
+            status_code=resp.status_code,
+            detail=str(detail),
+            trace_id=data.get("trace_id"),
+        )
+
+    def _ensure_open(self) -> None:
+        if self._http is None:
+            raise RuntimeError(
+                "AgentRxClient is not open. "
+                "Use 'async with AgentRxClient(...) as rx:' or call await rx.open() first."
+            )

agentrx_sdk-0.1.0/src/agentrx/decorator.py

@@ -0,0 +1,259 @@
+"""
+agentrx.decorator
+=================
+The @with_recovery decorator — the primary entry point for the SDK.
+
+    from agentrx import with_recovery
+
+    @with_recovery(api_key="your_key", agent_id="my_agent")
+    async def call_my_tool(payload: dict) -> dict:
+        return await some_api.call(payload)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import time
+from typing import Any, Callable, Dict, Optional
+
+from .client import AgentRxClient
+from .models import (
+    ActionType,
+    AgentRxError,
+    HumanHandoffRequired,
+    RecoveryAction,
+    RecoveryException,
+)
+
+
+def with_recovery(
+    api_key:           Optional[str]      = None,
+    agent_id:          str                = "default_agent",
+    goal:              str                = "Complete the current task",
+    tool_schema:       Optional[Dict]     = None,
+    max_retries:       int                = 2,
+    base_url:          Optional[str]      = None,
+    on_handoff:        Optional[Callable] = None,
+    on_recovery:       Optional[Callable] = None,
+    ignore_exceptions: tuple              = (),
+) -> Callable:
+    """
+    Decorator that wraps an agent tool function with AgentRx recovery.
+    Works on both async and sync functions.
+
+    Args:
+        api_key:           Your AgentRx API key.
+        agent_id:          Stable identifier for this agent instance.
+        goal:              The agent's current high-level goal.
+        tool_schema:       JSON Schema dict for the wrapped tool.
+        max_retries:       Maximum automatic retry attempts. Default 2.
+        base_url:          AgentRx API URL.
+        on_handoff:        Callback fired on HUMAN_HANDOFF.
+        on_recovery:       Callback fired after every diagnosis.
+        ignore_exceptions: Exception types to pass through without diagnosis.
+    """
+    def decorator(func: Callable) -> Callable:
+        is_async = asyncio.iscoroutinefunction(func)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await _execute(
+                func, args, kwargs, is_async=True,
+                api_key=api_key, agent_id=agent_id, goal=goal,
+                tool_schema=tool_schema, max_retries=max_retries,
+                base_url=base_url, on_handoff=on_handoff,
+                on_recovery=on_recovery, ignore_exceptions=ignore_exceptions,
+            )
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(
+                    asyncio.run,
+                    _execute(
+                        func, args, kwargs, is_async=False,
+                        api_key=api_key, agent_id=agent_id, goal=goal,
+                        tool_schema=tool_schema, max_retries=max_retries,
+                        base_url=base_url, on_handoff=on_handoff,
+                        on_recovery=on_recovery, ignore_exceptions=ignore_exceptions,
+                    )
+                )
+                return future.result()
+
+        return async_wrapper if is_async else sync_wrapper
+
+    return decorator
+
+async def _execute(
+    func:              Callable,
+    args:              tuple,
+    kwargs:            dict,
+    is_async:          bool,
+    api_key:           Optional[str],
+    agent_id:          str,
+    goal:              str,
+    tool_schema:       Optional[Dict],
+    max_retries:       int,
+    base_url:          Optional[str],
+    on_handoff:        Optional[Callable],
+    on_recovery:       Optional[Callable],
+    ignore_exceptions: tuple,
+) -> Any:
+    current_payload = _extract_payload(func, args, kwargs)
+
+    async with AgentRxClient(api_key=api_key, base_url=base_url) as rx:
+        attempt = 0
+
+        while attempt <= max_retries:
+            start_ms = int(time.monotonic() * 1000)
+
+            try:
+                if is_async:
+                    return await func(*args, **kwargs)
+                else:
+                    return await asyncio.get_event_loop().run_in_executor(
+                        None, functools.partial(func, *args, **kwargs)
+                    )
+
+            except ignore_exceptions:
+                raise
+
+            except (KeyboardInterrupt, SystemExit):
+                raise
+
+            except Exception as exc:
+                latency_ms     = int(time.monotonic() * 1000) - start_ms
+                error_response = _extract_error_response(exc)
+
+                try:
+                    action = await rx.diagnose(
+                        agent_id=agent_id,
+                        goal=goal,
+                        tool_name=func.__name__,
+                        payload=current_payload or {},
+                        error_response=error_response,
+                        latency_ms=latency_ms,
+                        tool_schema=tool_schema,
+                    )
+                except AgentRxError as rx_err:
+                    raise type(exc)(
+                        f"{exc} [AgentRx unavailable: {rx_err}]"
+                    ) from exc
+
+                if on_recovery:
+                    await _call_maybe_async(on_recovery, action)
+
+                if action.action_type == ActionType.RETRY_WITH_BACKOFF:
+                    if attempt >= max_retries:
+                        raise exc
+                    wait_s = (action.retry_after_ms or 2000) / 1000
+                    await asyncio.sleep(wait_s)
+                    attempt += 1
+                    continue
+
+                elif action.action_type == ActionType.RELAX_SCHEMA:
+                    if attempt >= max_retries:
+                        raise exc
+                    if action.corrected_payload:
+                        args, kwargs = _inject_payload(
+                            func, args, kwargs, action.corrected_payload
+                        )
+                        current_payload = action.corrected_payload
+                    attempt += 1
+                    continue
+
+                elif action.action_type == ActionType.HUMAN_HANDOFF:
+                    if on_handoff:
+                        await _call_maybe_async(on_handoff, action)
+                        return None
+                    raise HumanHandoffRequired(
+                        action=action,
+                        agent_id=agent_id,
+                        tool_name=func.__name__,
+                    )
+
+                elif action.action_type == ActionType.SKIP_AND_CONTINUE:
+                    return None
+
+                elif action.action_type == ActionType.ABORT:
+                    raise exc
+
+                else:
+                    raise RecoveryException(
+                        action=action,
+                        original_error=exc,
+                        agent_id=agent_id,
+                        tool_name=func.__name__,
+                    ) from exc
+
+        raise RuntimeError("AgentRx decorator: retry loop exited unexpectedly")
+
+def _extract_payload(
+    func:   Callable,
+    args:   tuple,
+    kwargs: dict,
+) -> Optional[Dict[str, Any]]:
+    for name in ("payload", "params", "data", "body", "inputs"):
+        if name in kwargs and isinstance(kwargs[name], dict):
+            return kwargs[name]
+
+    sig    = inspect.signature(func)
+    params = list(sig.parameters.keys())
+    offset = 1 if params and params[0] in ("self", "cls") else 0
+
+    for arg in args[offset:]:
+        if isinstance(arg, dict):
+            return arg
+
+    return None
+
+
+def _inject_payload(
+    func:              Callable,
+    args:              tuple,
+    kwargs:            dict,
+    corrected_payload: Dict[str, Any],
+) -> tuple[tuple, dict]:
+    for name in ("payload", "params", "data", "body", "inputs"):
+        if name in kwargs and isinstance(kwargs[name], dict):
+            return args, {**kwargs, name: corrected_payload}
+
+    sig    = inspect.signature(func)
+    params = list(sig.parameters.keys())
+    offset = 1 if params and params[0] in ("self", "cls") else 0
+
+    new_args = list(args)
+    for i, arg in enumerate(args[offset:], start=offset):
+        if isinstance(arg, dict):
+            new_args[i] = corrected_payload
+            return tuple(new_args), kwargs
+
+    return args, kwargs
+
+
+def _extract_error_response(exc: Exception) -> Dict[str, Any]:
+    response = getattr(exc, "response", None)
+    if response is not None:
+        status_code = getattr(response, "status_code", 0)
+        try:
+            body    = response.json()
+            message = body.get("message") or body.get("detail") or str(body)
+        except Exception:
+            message = getattr(response, "text", str(exc))[:500]
+        return {"status_code": status_code, "message": message}
+
+    status_code = getattr(exc, "status_code", getattr(exc, "code", 0))
+    return {
+        "status_code": int(status_code) if status_code else 0,
+        "message":     str(exc)[:500],
+    }
+
+
+async def _call_maybe_async(callback: Callable, *args: Any) -> None:
+    if asyncio.iscoroutinefunction(callback):
+        await callback(*args)
+    else:
+        callback(*args)

agentrx_sdk-0.1.0/src/agentrx/models.py

@@ -0,0 +1,136 @@
+"""
+agentrx.models
+==============
+Typed dataclasses matching the AgentRx API response shapes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class ActionType(str, Enum):
+    RELAX_SCHEMA       = "RELAX_SCHEMA"
+    INJECT_KNOWLEDGE   = "INJECT_KNOWLEDGE"
+    RETRY_WITH_BACKOFF = "RETRY_WITH_BACKOFF"
+    HUMAN_HANDOFF      = "HUMAN_HANDOFF"
+    REFRESH_AUTH       = "REFRESH_AUTH"
+    SKIP_AND_CONTINUE  = "SKIP_AND_CONTINUE"
+    ABORT              = "ABORT"
+
+
+class FailureSignature(str, Enum):
+    SCHEMA_MISMATCH     = "SCHEMA_MISMATCH"
+    RESOURCE_MISSING    = "RESOURCE_MISSING"
+    NETWORK_LATENCY     = "NETWORK_LATENCY"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+    AUTH_FAILURE        = "AUTH_FAILURE"
+    TOOL_DEPRECATED     = "TOOL_DEPRECATED"
+    HALLUCINATED_PARAM  = "HALLUCINATED_PARAM"
+    HALLUCINATED_VALUE  = "HALLUCINATED_VALUE"
+    AGENT_LOOP          = "AGENT_LOOP"
+    UNKNOWN             = "UNKNOWN"
+
+
+@dataclass
+class RecoveryAction:
+    action_type:        ActionType
+    failure_signature:  FailureSignature
+    confidence_score:   float
+    trace_id:           str
+    recovery_prompt:    Optional[str]            = None
+    corrected_payload:  Optional[Dict[str, Any]] = None
+    retry_after_ms:     Optional[int]            = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "RecoveryAction":
+        return cls(
+            action_type       = ActionType(data["action_type"]),
+            failure_signature = FailureSignature(data["failure_signature"]),
+            confidence_score  = float(data["confidence_score"]),
+            trace_id          = data["trace_id"],
+            recovery_prompt   = data.get("recovery_prompt"),
+            corrected_payload = data.get("corrected_payload"),
+            retry_after_ms    = data.get("retry_after_ms"),
+        )
+
+    @property
+    def should_retry(self) -> bool:
+        return self.action_type == ActionType.RETRY_WITH_BACKOFF
+
+    @property
+    def should_handoff(self) -> bool:
+        return self.action_type == ActionType.HUMAN_HANDOFF
+
+    @property
+    def should_skip(self) -> bool:
+        return self.action_type == ActionType.SKIP_AND_CONTINUE
+
+
+@dataclass
+class PreflightResult:
+    proceed:              bool
+    risk_score:           float
+    warnings:             List[str]
+    trace_id:             str
+    suggested_correction: Optional[Dict[str, Any]]   = None
+    predicted_signature:  Optional[FailureSignature] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PreflightResult":
+        sig = data.get("predicted_signature")
+        return cls(
+            proceed              = bool(data["proceed"]),
+            risk_score           = float(data["risk_score"]),
+            warnings             = data.get("warnings", []),
+            trace_id             = data["trace_id"],
+            suggested_correction = data.get("suggested_correction"),
+            predicted_signature  = FailureSignature(sig) if sig else None,
+        )
+
+@dataclass
+class AgentRxError(Exception):
+    status_code: int
+    detail:      str
+    trace_id:    Optional[str] = None
+
+    def __str__(self) -> str:
+        tid = f" [trace_id={self.trace_id}]" if self.trace_id else ""
+        return f"AgentRxError {self.status_code}: {self.detail}{tid}"
+
+
+@dataclass
+class HumanHandoffRequired(Exception):
+    action:    RecoveryAction
+    agent_id:  str
+    tool_name: str
+
+    def __str__(self) -> str:
+        return (
+            f"Agent '{self.agent_id}' requires human review. "
+            f"Tool: '{self.tool_name}'. "
+            f"Reason: {self.action.recovery_prompt or self.action.failure_signature}. "
+            f"trace_id={self.action.trace_id}"
+        )
+
+
+@dataclass
+class RecoveryException(Exception):
+    action:         RecoveryAction
+    original_error: Exception
+    agent_id:       str
+    tool_name:      str
+
+    def __post_init__(self) -> None:
+        self.__cause__ = self.original_error
+
+    def __str__(self) -> str:
+        return (
+            f"AgentRx recovery required for agent '{self.agent_id}' "
+            f"tool '{self.tool_name}': {self.action.action_type.value}. "
+            f"Recovery prompt: {self.action.recovery_prompt or 'none'}. "
+            f"Original error: {self.original_error}. "
+            f"trace_id={self.action.trace_id}"
+        )

agentrx_sdk-0.1.0/src/agentrx_sdk.egg-info/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: agentrx-sdk
+Version: 0.1.0
+Summary: Drop-in recovery and resilience layer for AI agents
+Author: Chain Assets LLC
+License: MIT
+Project-URL: Homepage, https://chainassetslab.com
+Project-URL: Repository, https://github.com/chainassetslab/agentrx-python
+Keywords: ai,agents,llm,recovery,mcp,langchain,crewai
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+
+# agentrx-python
+
+Make your AI agents bulletproof in two lines.
+
+## Installation
+
+pip install agentrx-sdk
+
+## Quick Start
+
+from agentrx import with_recovery
+
+@with_recovery(api_key="your_key", agent_id="my_agent")
+async def call_my_tool(payload: dict) -> dict:
+    return await some_api.call(payload)
+
+When call_my_tool raises an exception, AgentRx diagnoses it and
+automatically retries, corrects the payload, or tells you exactly
+what went wrong.
+
+## Environment Variables
+
+AGENTRX_API_KEY  — Your API key (required)
+AGENTRX_BASE_URL — AgentRx server URL (default: http://localhost:8000)
+OTEL_TRACE_ID    — OpenTelemetry trace ID (optional)
+LANGSMITH_RUN_ID — LangSmith run ID (optional)
+
+## License
+
+MIT

agentrx_sdk-0.1.0/src/agentrx_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/agentrx/__init__.py
+src/agentrx/client.py
+src/agentrx/decorator.py
+src/agentrx/models.py
+src/agentrx_sdk.egg-info/PKG-INFO
+src/agentrx_sdk.egg-info/SOURCES.txt
+src/agentrx_sdk.egg-info/dependency_links.txt
+src/agentrx_sdk.egg-info/requires.txt
+src/agentrx_sdk.egg-info/top_level.txt
+tests/test_sdk.py

agentrx_sdk-0.1.0/src/agentrx_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentrx_sdk-0.1.0/src/agentrx_sdk.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx>=0.27.0
+pydantic>=2.0.0
+
+[dev]
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+respx>=0.21.0

agentrx_sdk-0.1.0/src/agentrx_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentrx