helix-agent-sdk 0.1.0__tar.gz

helix_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: helix-agent-sdk
+Version: 0.1.0
+Summary: Python SDK for Helix — self-healing infrastructure for AI agent payments
+Author: Helix Team
+License: MIT
+Project-URL: Homepage, https://github.com/adrianhihi/helix
+Project-URL: Repository, https://github.com/adrianhihi/helix
+Keywords: helix,ai-agents,self-healing,payments,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# helix-agent
+
+Python SDK for [Helix](https://github.com/adrianhihi/helix) — self-healing infrastructure for AI agent payments.
+
+## Install
+
+```bash
+pip install helix-agent
+```
+
+Requires a running Helix server:
+
+```bash
+npm install -g @helix-agent/core
+npx helix serve --port 7842
+```
+
+## Quick Start
+
+### Method 1: Client
+
+```python
+from helix_agent import HelixClient
+
+client = HelixClient(platform="coinbase")
+result = client.repair("AA25 invalid account nonce")
+print(f"Strategy: {result.strategy}")  # refresh_nonce
+print(f"Immune: {result.immune}")      # True on 2nd call
+```
+
+### Method 2: Decorator
+
+```python
+from helix_agent import helix_wrap
+
+@helix_wrap(platform="coinbase", max_retries=3)
+def send_payment(to: str, amount: float):
+    return agent.transfer(to, amount)
+
+result = send_payment("0x...", 1.5)
+```
+
+### Method 3: Context Manager
+
+```python
+from helix_agent import helix_guard
+
+with helix_guard("tempo") as guard:
+    try:
+        result = agent.transfer(to, amount)
+    except Exception as e:
+        repair = guard.repair(str(e))
+        if repair.immune:
+            result = agent.transfer(to, amount)
+```
+
+## Configuration
+
+```python
+HELIX_URL=http://localhost:7842  # env var
+
+client = HelixClient(
+    base_url="http://localhost:7842",
+    platform="coinbase",
+    agent_id="my-agent-1",
+)
+```
+
+## Supported Platforms
+
+- `tempo` — Tempo L1 blockchain
+- `privy` — Privy embedded wallets
+- `coinbase` — Coinbase CDP + AgentKit
+- `generic` — Any HTTP/RPC service

helix_agent_sdk-0.1.0/README.md

@@ -0,0 +1,74 @@
+# helix-agent
+
+Python SDK for [Helix](https://github.com/adrianhihi/helix) — self-healing infrastructure for AI agent payments.
+
+## Install
+
+```bash
+pip install helix-agent
+```
+
+Requires a running Helix server:
+
+```bash
+npm install -g @helix-agent/core
+npx helix serve --port 7842
+```
+
+## Quick Start
+
+### Method 1: Client
+
+```python
+from helix_agent import HelixClient
+
+client = HelixClient(platform="coinbase")
+result = client.repair("AA25 invalid account nonce")
+print(f"Strategy: {result.strategy}")  # refresh_nonce
+print(f"Immune: {result.immune}")      # True on 2nd call
+```
+
+### Method 2: Decorator
+
+```python
+from helix_agent import helix_wrap
+
+@helix_wrap(platform="coinbase", max_retries=3)
+def send_payment(to: str, amount: float):
+    return agent.transfer(to, amount)
+
+result = send_payment("0x...", 1.5)
+```
+
+### Method 3: Context Manager
+
+```python
+from helix_agent import helix_guard
+
+with helix_guard("tempo") as guard:
+    try:
+        result = agent.transfer(to, amount)
+    except Exception as e:
+        repair = guard.repair(str(e))
+        if repair.immune:
+            result = agent.transfer(to, amount)
+```
+
+## Configuration
+
+```python
+HELIX_URL=http://localhost:7842  # env var
+
+client = HelixClient(
+    base_url="http://localhost:7842",
+    platform="coinbase",
+    agent_id="my-agent-1",
+)
+```
+
+## Supported Platforms
+
+- `tempo` — Tempo L1 blockchain
+- `privy` — Privy embedded wallets
+- `coinbase` — Coinbase CDP + AgentKit
+- `generic` — Any HTTP/RPC service

helix_agent_sdk-0.1.0/helix_agent/__init__.py

@@ -0,0 +1,13 @@
+"""
+Helix Agent — Python SDK for self-healing AI agent payments.
+
+Usage:
+    from helix_agent import HelixClient, helix_wrap, helix_guard
+"""
+
+from .client import HelixClient
+from .decorator import helix_wrap
+from .guard import helix_guard
+
+__version__ = "0.1.0"
+__all__ = ["HelixClient", "helix_wrap", "helix_guard"]

helix_agent_sdk-0.1.0/helix_agent/client.py

@@ -0,0 +1,146 @@
+"""
+HelixClient — Core client for Helix REST API.
+"""
+
+import os
+import time
+import logging
+from typing import Optional
+from dataclasses import dataclass, field
+
+import requests
+
+logger = logging.getLogger("helix")
+
+
+@dataclass
+class RepairResult:
+    """Result of a repair attempt."""
+    success: bool
+    immune: bool = False
+    strategy: Optional[str] = None
+    strategy_params: dict = field(default_factory=dict)
+    confidence: float = 0.0
+    q_value: float = 0.0
+    llm_used: bool = False
+    repair_time_ms: float = 0.0
+    error: Optional[str] = None
+    raw: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: dict) -> "RepairResult":
+        strategy = data.get("strategy") or {}
+        failure = data.get("failure") or {}
+        return cls(
+            success=True,
+            immune=data.get("immune", False),
+            strategy=strategy.get("name") if strategy else None,
+            strategy_params=strategy.get("params", {}) if strategy else {},
+            confidence=strategy.get("confidence", 0) if strategy else 0,
+            llm_used=failure.get("llmClassified", False),
+            repair_time_ms=data.get("repairMs", 0),
+            raw=data,
+        )
+
+    @classmethod
+    def failed(cls, error: str) -> "RepairResult":
+        return cls(success=False, error=error)
+
+
+class HelixClient:
+    """
+    Client for Helix self-healing server.
+
+    Args:
+        base_url: Helix server URL. Default: http://localhost:7842
+        timeout: Request timeout in seconds. Default: 10
+        agent_id: Identifier for this agent instance.
+        platform: Default platform (tempo/privy/coinbase/generic).
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        timeout: int = 10,
+        agent_id: Optional[str] = None,
+        platform: str = "generic",
+    ):
+        self.base_url = (
+            base_url or os.environ.get("HELIX_URL") or "http://localhost:7842"
+        )
+        self.timeout = timeout
+        self.agent_id = agent_id or f"py-{os.getpid()}"
+        self.platform = platform
+        self._session = requests.Session()
+        self._session.headers.update({"Content-Type": "application/json"})
+
+    def repair(
+        self,
+        error: str,
+        *,
+        platform: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        context: Optional[dict] = None,
+    ) -> RepairResult:
+        """Send an error to Helix for diagnosis and repair strategy."""
+        start = time.monotonic()
+        try:
+            payload = {
+                "error": error,
+                "platform": platform or self.platform,
+                "agentId": agent_id or self.agent_id,
+            }
+            if context:
+                payload["context"] = context
+
+            resp = self._session.post(
+                f"{self.base_url}/repair", json=payload, timeout=self.timeout
+            )
+            resp.raise_for_status()
+            result = RepairResult.from_api(resp.json())
+            result.repair_time_ms = (time.monotonic() - start) * 1000
+
+            status = "IMMUNE" if result.immune else f"REPAIR -> {result.strategy}"
+            logger.info(f"[helix] {status} ({result.repair_time_ms:.0f}ms)")
+            return result
+
+        except requests.RequestException as e:
+            logger.warning(f"[helix] Server unreachable: {e}")
+            return RepairResult.failed(f"Server unreachable: {e}")
+        except Exception as e:
+            logger.warning(f"[helix] Repair failed: {e}")
+            return RepairResult.failed(str(e))
+
+    def health(self) -> dict:
+        """Check Helix server health."""
+        try:
+            return self._session.get(f"{self.base_url}/health", timeout=self.timeout).json()
+        except Exception as e:
+            return {"status": "unreachable", "error": str(e)}
+
+    def genes(self) -> dict:
+        """List all genes in the Gene Map."""
+        try:
+            return self._session.get(f"{self.base_url}/genes", timeout=self.timeout).json()
+        except Exception as e:
+            return {"error": str(e)}
+
+    def status(self) -> dict:
+        """Get full server status."""
+        try:
+            return self._session.get(f"{self.base_url}/status", timeout=self.timeout).json()
+        except Exception as e:
+            return {"error": str(e)}
+
+    def is_healthy(self) -> bool:
+        """Quick check if server is reachable."""
+        return self.health().get("status") in ("ok", "running")
+
+    def close(self):
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

helix_agent_sdk-0.1.0/helix_agent/decorator.py

@@ -0,0 +1,75 @@
+"""
+@helix_wrap — Decorator for automatic error repair.
+
+Catches exceptions, sends to Helix, applies repair strategy, retries.
+"""
+
+import functools
+import logging
+import time
+from typing import Optional, Callable, Any
+
+from .client import HelixClient, RepairResult
+
+logger = logging.getLogger("helix")
+
+
+def helix_wrap(
+    platform: str = "generic",
+    *,
+    base_url: Optional[str] = None,
+    max_retries: int = 3,
+    retry_delay: float = 1.0,
+    on_repair: Optional[Callable[[RepairResult], None]] = None,
+    on_failure: Optional[Callable[[Exception, RepairResult], Any]] = None,
+):
+    """
+    Decorator that adds self-healing to any function.
+
+    Example:
+        @helix_wrap(platform="coinbase", max_retries=3)
+        def send_payment(to, amount):
+            return agent.transfer(to, amount)
+    """
+    client = HelixClient(base_url=base_url, platform=platform)
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            last_error = None
+            repair = RepairResult.failed("no repair attempted")
+            for attempt in range(1, max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    last_error = e
+                    logger.info(f"[helix] Attempt {attempt}/{max_retries} failed: {str(e)[:100]}")
+
+                    repair = client.repair(str(e))
+
+                    if not repair.success:
+                        time.sleep(retry_delay * attempt)
+                        continue
+
+                    if on_repair:
+                        on_repair(repair)
+
+                    if repair.strategy == "backoff_retry":
+                        delay = retry_delay * (2 ** attempt)
+                    elif repair.immune:
+                        delay = 0.1
+                    else:
+                        delay = retry_delay * attempt
+
+                    time.sleep(delay)
+
+            if on_failure:
+                result = on_failure(last_error, repair)
+                if result is not None:
+                    return result
+            raise last_error
+
+        wrapper.helix_client = client
+        return wrapper
+
+    return decorator

helix_agent_sdk-0.1.0/helix_agent/guard.py

@@ -0,0 +1,60 @@
+"""
+helix_guard — Context manager for block-level protection.
+"""
+
+import logging
+from typing import Optional, List
+
+from .client import HelixClient, RepairResult
+
+logger = logging.getLogger("helix")
+
+
+class helix_guard:
+    """
+    Context manager for Helix self-healing.
+
+    Example:
+        with helix_guard("coinbase") as guard:
+            try:
+                result = agent.transfer(to, amount)
+            except Exception as e:
+                repair = guard.repair(str(e))
+                if repair.immune:
+                    result = agent.transfer(to, amount)
+    """
+
+    def __init__(
+        self,
+        platform: str = "generic",
+        *,
+        base_url: Optional[str] = None,
+        agent_id: Optional[str] = None,
+    ):
+        self._client = HelixClient(
+            base_url=base_url, platform=platform, agent_id=agent_id
+        )
+        self.repairs: List[RepairResult] = []
+
+    def repair(self, error: str, **kwargs) -> RepairResult:
+        result = self._client.repair(error, **kwargs)
+        self.repairs.append(result)
+        return result
+
+    def health(self) -> dict:
+        return self._client.health()
+
+    @property
+    def total_repairs(self) -> int:
+        return len(self.repairs)
+
+    @property
+    def immune_count(self) -> int:
+        return sum(1 for r in self.repairs if r.immune)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._client.close()
+        return False

helix_agent_sdk-0.1.0/helix_agent_sdk.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: helix-agent-sdk
+Version: 0.1.0
+Summary: Python SDK for Helix — self-healing infrastructure for AI agent payments
+Author: Helix Team
+License: MIT
+Project-URL: Homepage, https://github.com/adrianhihi/helix
+Project-URL: Repository, https://github.com/adrianhihi/helix
+Keywords: helix,ai-agents,self-healing,payments,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# helix-agent
+
+Python SDK for [Helix](https://github.com/adrianhihi/helix) — self-healing infrastructure for AI agent payments.
+
+## Install
+
+```bash
+pip install helix-agent
+```
+
+Requires a running Helix server:
+
+```bash
+npm install -g @helix-agent/core
+npx helix serve --port 7842
+```
+
+## Quick Start
+
+### Method 1: Client
+
+```python
+from helix_agent import HelixClient
+
+client = HelixClient(platform="coinbase")
+result = client.repair("AA25 invalid account nonce")
+print(f"Strategy: {result.strategy}")  # refresh_nonce
+print(f"Immune: {result.immune}")      # True on 2nd call
+```
+
+### Method 2: Decorator
+
+```python
+from helix_agent import helix_wrap
+
+@helix_wrap(platform="coinbase", max_retries=3)
+def send_payment(to: str, amount: float):
+    return agent.transfer(to, amount)
+
+result = send_payment("0x...", 1.5)
+```
+
+### Method 3: Context Manager
+
+```python
+from helix_agent import helix_guard
+
+with helix_guard("tempo") as guard:
+    try:
+        result = agent.transfer(to, amount)
+    except Exception as e:
+        repair = guard.repair(str(e))
+        if repair.immune:
+            result = agent.transfer(to, amount)
+```
+
+## Configuration
+
+```python
+HELIX_URL=http://localhost:7842  # env var
+
+client = HelixClient(
+    base_url="http://localhost:7842",
+    platform="coinbase",
+    agent_id="my-agent-1",
+)
+```
+
+## Supported Platforms
+
+- `tempo` — Tempo L1 blockchain
+- `privy` — Privy embedded wallets
+- `coinbase` — Coinbase CDP + AgentKit
+- `generic` — Any HTTP/RPC service

helix_agent_sdk-0.1.0/helix_agent_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+helix_agent/__init__.py
+helix_agent/client.py
+helix_agent/decorator.py
+helix_agent/guard.py
+helix_agent/py.typed
+helix_agent_sdk.egg-info/PKG-INFO
+helix_agent_sdk.egg-info/SOURCES.txt
+helix_agent_sdk.egg-info/dependency_links.txt
+helix_agent_sdk.egg-info/requires.txt
+helix_agent_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_decorator.py
+tests/test_guard.py

helix_agent_sdk-0.1.0/helix_agent_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

helix_agent_sdk-0.1.0/helix_agent_sdk.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.28.0
+
+[dev]
+pytest>=7.0
+responses>=0.23

helix_agent_sdk-0.1.0/helix_agent_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+helix_agent

helix_agent_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "helix-agent-sdk"
+version = "0.1.0"
+description = "Python SDK for Helix — self-healing infrastructure for AI agent payments"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Helix Team"}
+]
+keywords = ["helix", "ai-agents", "self-healing", "payments", "web3"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "responses>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/adrianhihi/helix"
+Repository = "https://github.com/adrianhihi/helix"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["helix_agent*"]

helix_agent_sdk-0.1.0/setup.cfg

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

helix_agent_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,46 @@
+"""Tests for HelixClient — uses a real running server."""
+import pytest
+from helix_agent import HelixClient
+
+SERVER_PORT = 17842
+
+
+@pytest.fixture
+def client():
+    return HelixClient(base_url=f"http://localhost:{SERVER_PORT}", platform="tempo")
+
+
+class TestHelixClient:
+    def test_health(self, client):
+        h = client.health()
+        assert h.get("status") in ("ok", "running")
+
+    def test_repair_known_error(self, client):
+        result = client.repair("nonce mismatch: expected 5, got 3")
+        assert result.success
+        assert result.strategy is not None
+
+    def test_immune_on_repeat(self, client):
+        r1 = client.repair("session expired, please re-authenticate")
+        assert r1.success
+        r2 = client.repair("session expired, please re-authenticate")
+        assert r2.success
+        assert r2.immune
+
+    def test_genes_list(self, client):
+        genes = client.genes()
+        assert "genes" in genes or "total" in genes
+
+    def test_platform_override(self, client):
+        result = client.repair("AA25 invalid account nonce", platform="coinbase")
+        assert result.success
+
+    def test_unreachable_server(self):
+        bad_client = HelixClient(base_url="http://localhost:19999", timeout=2)
+        result = bad_client.repair("test error")
+        assert not result.success
+        assert "unreachable" in result.error.lower()
+
+    def test_context_manager(self):
+        with HelixClient(base_url=f"http://localhost:{SERVER_PORT}") as c:
+            assert c.is_healthy()

helix_agent_sdk-0.1.0/tests/test_decorator.py

@@ -0,0 +1,58 @@
+"""Tests for @helix_wrap decorator."""
+import pytest
+from helix_agent import helix_wrap
+
+SERVER_PORT = 17842
+
+
+class TestHelixWrap:
+    def test_decorator_retries_on_error(self):
+        call_count = 0
+
+        @helix_wrap(platform="tempo", base_url=f"http://localhost:{SERVER_PORT}", max_retries=3, retry_delay=0.1)
+        def flaky_function():
+            nonlocal call_count
+            call_count += 1
+            if call_count < 3:
+                raise Exception("nonce mismatch: expected 5, got 3")
+            return "success"
+
+        result = flaky_function()
+        assert result == "success"
+        assert call_count == 3
+
+    def test_decorator_exposes_client(self):
+        @helix_wrap(platform="tempo", base_url=f"http://localhost:{SERVER_PORT}")
+        def my_func():
+            pass
+
+        assert hasattr(my_func, "helix_client")
+        assert my_func.helix_client.is_healthy()
+
+    def test_decorator_raises_after_max_retries(self):
+        @helix_wrap(platform="tempo", base_url=f"http://localhost:{SERVER_PORT}", max_retries=2, retry_delay=0.1)
+        def always_fails():
+            raise Exception("permanent error that never resolves")
+
+        with pytest.raises(Exception, match="permanent error"):
+            always_fails()
+
+    def test_on_repair_callback(self):
+        repairs = []
+
+        @helix_wrap(
+            platform="tempo",
+            base_url=f"http://localhost:{SERVER_PORT}",
+            max_retries=2,
+            retry_delay=0.1,
+            on_repair=lambda r: repairs.append(r),
+        )
+        def fails_once():
+            if len(repairs) == 0:
+                raise Exception("nonce mismatch: expected 1, got 0")
+            return "ok"
+
+        result = fails_once()
+        assert result == "ok"
+        assert len(repairs) >= 1
+        assert repairs[0].success

helix_agent_sdk-0.1.0/tests/test_guard.py

@@ -0,0 +1,24 @@
+"""Tests for helix_guard context manager."""
+from helix_agent import helix_guard
+
+SERVER_PORT = 17842
+
+
+class TestHelixGuard:
+    def test_basic_guard(self):
+        with helix_guard("tempo", base_url=f"http://localhost:{SERVER_PORT}") as guard:
+            result = guard.repair("nonce mismatch: expected 5, got 3")
+            assert result.success
+            assert result.strategy is not None
+
+    def test_repair_count(self):
+        with helix_guard("tempo", base_url=f"http://localhost:{SERVER_PORT}") as guard:
+            guard.repair("error 1")
+            guard.repair("error 2")
+            assert guard.total_repairs == 2
+
+    def test_immune_tracking(self):
+        with helix_guard("tempo", base_url=f"http://localhost:{SERVER_PORT}") as guard:
+            guard.repair("session expired, please re-authenticate")
+            guard.repair("session expired, please re-authenticate")
+            assert guard.immune_count >= 1