agentnode-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{agentnode_sdk-0.2.0 → agentnode_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentnode-sdk
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents.
 Project-URL: Homepage, https://agentnode.net
 Project-URL: Repository, https://github.com/agentnode-ai/agentnode
@@ -34,8 +34,7 @@ pip install agentnode-sdk
 ## Quick Start
 
 ```python
-from agentnode_sdk import AgentNodeClient
-from agentnode_sdk.installer import load_tool
+from agentnode_sdk import AgentNodeClient, run_tool
 
 client = AgentNodeClient(api_key="ank_...")
 
@@ -50,13 +49,14 @@ resolved = client.resolve(
     framework="langchain",
 )
 
-# v0.2: Load specific tools from multi-tool packs
-describe = load_tool("csv-analyzer-pack", tool_name="describe")
-result = describe({"file_path": "data.csv"})
+# v0.3: Run tools with trust-aware isolation
+# trusted/curated → direct (in-process), verified/unverified → subprocess
+result = run_tool("pdf-reader-pack", file_path="report.pdf")
+print(result.result)  # tool output
+print(result.mode_used)  # "direct" or "subprocess"
 
-# Single-tool packs — no tool_name needed
-extract = load_tool("pdf-reader-pack")
-pdf = extract({"file_path": "report.pdf"})
+# Multi-tool packs — specify tool_name
+result = run_tool("csv-analyzer-pack", tool_name="describe", file_path="data.csv")
 ```
 
 ## API Reference
@@ -72,8 +72,28 @@ The main client with typed return models.
 | `get_package(slug)` | Get package details |
 | `get_install_metadata(slug)` | Get install info (artifact, permissions, deps) |
 | `download(slug)` | Track download and get artifact URL |
+| `run_tool(slug, tool_name=, mode=, timeout=, **kwargs)` | Run a tool with optional subprocess isolation (v0.3) |
 | `load_tool(slug, tool_name=)` | Load a tool function from an installed pack (v0.2) |
 
+### `run_tool()` (standalone)
+
+Top-level function for running tools with trust-aware execution mode.
+
+```python
+from agentnode_sdk import run_tool
+
+result = run_tool("pdf-reader-pack", mode="auto", file_path="report.pdf")
+# result.success, result.result, result.error, result.mode_used, result.duration_ms
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `slug` | str | required | Package slug |
+| `tool_name` | str \| None | None | Tool name for multi-tool packs |
+| `mode` | str | `"auto"` | `"direct"`, `"subprocess"`, or `"auto"` |
+| `timeout` | float | 30.0 | Subprocess timeout in seconds |
+| `**kwargs` | Any | — | Arguments forwarded to the tool function |
+
 ### `AgentNode`
 
 Lightweight client returning raw dicts.

{agentnode_sdk-0.2.0 → agentnode_sdk-0.4.0}/README.md

@@ -11,8 +11,7 @@ pip install agentnode-sdk
 ## Quick Start
 
 ```python
-from agentnode_sdk import AgentNodeClient
-from agentnode_sdk.installer import load_tool
+from agentnode_sdk import AgentNodeClient, run_tool
 
 client = AgentNodeClient(api_key="ank_...")
 
@@ -27,13 +26,14 @@ resolved = client.resolve(
     framework="langchain",
 )
 
-# v0.2: Load specific tools from multi-tool packs
-describe = load_tool("csv-analyzer-pack", tool_name="describe")
-result = describe({"file_path": "data.csv"})
+# v0.3: Run tools with trust-aware isolation
+# trusted/curated → direct (in-process), verified/unverified → subprocess
+result = run_tool("pdf-reader-pack", file_path="report.pdf")
+print(result.result)  # tool output
+print(result.mode_used)  # "direct" or "subprocess"
 
-# Single-tool packs — no tool_name needed
-extract = load_tool("pdf-reader-pack")
-pdf = extract({"file_path": "report.pdf"})
+# Multi-tool packs — specify tool_name
+result = run_tool("csv-analyzer-pack", tool_name="describe", file_path="data.csv")
 ```
 
 ## API Reference
@@ -49,8 +49,28 @@ The main client with typed return models.
 | `get_package(slug)` | Get package details |
 | `get_install_metadata(slug)` | Get install info (artifact, permissions, deps) |
 | `download(slug)` | Track download and get artifact URL |
+| `run_tool(slug, tool_name=, mode=, timeout=, **kwargs)` | Run a tool with optional subprocess isolation (v0.3) |
 | `load_tool(slug, tool_name=)` | Load a tool function from an installed pack (v0.2) |
 
+### `run_tool()` (standalone)
+
+Top-level function for running tools with trust-aware execution mode.
+
+```python
+from agentnode_sdk import run_tool
+
+result = run_tool("pdf-reader-pack", mode="auto", file_path="report.pdf")
+# result.success, result.result, result.error, result.mode_used, result.duration_ms
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `slug` | str | required | Package slug |
+| `tool_name` | str \| None | None | Tool name for multi-tool packs |
+| `mode` | str | `"auto"` | `"direct"`, `"subprocess"`, or `"auto"` |
+| `timeout` | float | 30.0 | Subprocess timeout in seconds |
+| `**kwargs` | Any | — | Arguments forwarded to the tool function |
+
 ### `AgentNode`
 
 Lightweight client returning raw dicts.

{agentnode_sdk-0.2.0 → agentnode_sdk-0.4.0}/agentnode_sdk/__init__.py

@@ -2,6 +2,7 @@
 
 from agentnode_sdk.async_client import AsyncAgentNode
 from agentnode_sdk.client import AgentNode, AgentNodeClient
+from agentnode_sdk.detect import detect_gap
 from agentnode_sdk.exceptions import (
     AgentNodeError,
     AgentNodeToolError,
@@ -13,26 +14,33 @@ from agentnode_sdk.exceptions import (
 from agentnode_sdk.installer import load_tool
 from agentnode_sdk.models import (
     CanInstallResult,
+    DetectAndInstallResult,
+    DetectedGap,
     InstallMetadata,
     InstallResult,
     PackageDetail,
     ResolvedPackage,
     ResolveResult,
+    RunToolResult,
     SearchHit,
     SearchResult,
+    SmartRunResult,
 )
+from agentnode_sdk.runner import run_tool
 
 # Convenience aliases
 Client = AgentNodeClient
 ToolError = AgentNodeToolError
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",
     "AgentNodeClient",
     "Client",
+    "detect_gap",
     "load_tool",
+    "run_tool",
     "AgentNodeError",
     "AgentNodeToolError",
     "ToolError",
@@ -48,4 +56,8 @@ __all__ = [
     "InstallMetadata",
     "InstallResult",
     "CanInstallResult",
+    "RunToolResult",
+    "DetectedGap",
+    "DetectAndInstallResult",
+    "SmartRunResult",
 ]

{agentnode_sdk-0.2.0 → agentnode_sdk-0.4.0}/agentnode_sdk/client.py

@@ -1,6 +1,10 @@
 """AgentNode API client. Spec §14."""
 from __future__ import annotations
 
+import time
+from collections.abc import Callable
+from typing import Any
+
 import httpx
 
 from agentnode_sdk.exceptions import (
@@ -11,10 +15,12 @@ from agentnode_sdk.exceptions import (
     ValidationError,
 )
 from agentnode_sdk.installer import install_package, load_tool as _load_tool
+from agentnode_sdk.detect import detect_gap
 from agentnode_sdk.models import (
     ArtifactInfo,
     CanInstallResult,
     CapabilityInfo,
+    DetectAndInstallResult,
     DependencyInfo,
     InstallMetadata,
     InstallResult,
@@ -22,9 +28,11 @@ from agentnode_sdk.models import (
     PermissionsInfo,
     ResolvedPackage,
     ResolveResult,
+    RunToolResult,
     ScoreBreakdown,
     SearchHit,
     SearchResult,
+    SmartRunResult,
 )
 
 DEFAULT_BASE_URL = "https://api.agentnode.net/v1"
@@ -41,6 +49,40 @@ ERROR_CLASS_MAP = {
 }
 
 
+def _resolve_auto_upgrade_policy(
+    policy: str | None,
+    *,
+    auto_install: bool,
+    require_verified: bool,
+    require_trusted: bool,
+    allow_low_confidence: bool,
+) -> tuple[bool, bool, bool, bool]:
+    """Resolve named policy to concrete parameters. Policy overrides individual params."""
+    if policy is None:
+        return (auto_install, require_verified, require_trusted, allow_low_confidence)
+    p = policy.lower()
+    if p == "off":
+        return (False, True, False, False)
+    if p == "safe":
+        return (True, True, False, False)
+    if p == "strict":
+        return (True, False, True, False)
+    raise ValueError("auto_upgrade_policy must be 'off', 'safe', or 'strict'")
+
+
+def _permissions_to_dict(perms: PermissionsInfo | None) -> dict | None:
+    """Convert PermissionsInfo to a plain dict for lockfile storage."""
+    if perms is None:
+        return None
+    return {
+        "network_level": perms.network_level,
+        "filesystem_level": perms.filesystem_level,
+        "code_execution_level": perms.code_execution_level,
+        "data_access_level": perms.data_access_level,
+        "user_approval_level": perms.user_approval_level,
+    }
+
+
 class AgentNode:
     """Spec-compliant SDK client (§14.3). Returns plain dicts."""
 
@@ -479,6 +521,8 @@ class AgentNodeClient:
             capability_ids=cap_ids,
             tools=tools,
             verbose=verbose,
+            trust_level=trust_level,
+            permissions=_permissions_to_dict(meta.permissions),
         )
 
         return InstallResult(
@@ -608,6 +652,28 @@ class AgentNodeClient:
         """
         return _load_tool(slug, tool_name=tool_name)
 
+    def run_tool(
+        self,
+        slug: str,
+        tool_name: str | None = None,
+        *,
+        mode: str = "auto",
+        timeout: float = 30.0,
+        **kwargs,
+    ) -> RunToolResult:
+        """Run an installed tool with optional process isolation.
+
+        Args:
+            slug: Package slug.
+            tool_name: Tool name for multi-tool packs.
+            mode: ``"direct"``, ``"subprocess"``, or ``"auto"``.
+            timeout: Timeout in seconds (subprocess mode only).
+            **kwargs: Arguments forwarded to the tool function.
+        """
+        from agentnode_sdk.runner import run_tool as _run_tool
+
+        return _run_tool(slug, tool_name, mode=mode, timeout=timeout, **kwargs)
+
     def resolve_and_install(
         self,
         capabilities: list[str],
@@ -666,3 +732,209 @@ class AgentNodeClient:
             )
 
         return self.install(best.slug, verbose=verbose)
+
+    def detect_and_install(
+        self,
+        error: BaseException,
+        *,
+        auto_upgrade_policy: str | None = None,
+        context: dict[str, str] | None = None,
+        auto_install: bool = True,
+        require_verified: bool = True,
+        require_trusted: bool = False,
+        allow_low_confidence: bool = False,
+        on_detect: Callable[[str, str, str], None] | None = None,
+        on_install: Callable[[str], None] | None = None,
+    ) -> DetectAndInstallResult:
+        """Detect a capability gap from an error and optionally install.
+
+        This is the product-level API: your agent failed? AgentNode knows
+        what's missing and can acquire it.
+
+        Args:
+            error: The exception that triggered gap detection.
+            auto_upgrade_policy: Named policy ('off', 'safe', 'strict').
+                Overrides individual params when set.
+            context: Optional context hints (e.g. ``{"file": "report.pdf"}``).
+            auto_install: Whether to install on detection. Default True.
+            require_verified: Only install verified+ packages. Default True.
+            require_trusted: Only install trusted+ packages. Default False.
+            allow_low_confidence: Allow install on low-confidence detections.
+            on_detect: Callback(capability, confidence, error_msg) on detection.
+            on_install: Callback(slug) on successful install.
+        """
+        resolved = _resolve_auto_upgrade_policy(
+            auto_upgrade_policy,
+            auto_install=auto_install,
+            require_verified=require_verified,
+            require_trusted=require_trusted,
+            allow_low_confidence=allow_low_confidence,
+        )
+        r_auto_install, r_require_verified, r_require_trusted, r_allow_low = resolved
+
+        gap = detect_gap(error, context)
+        if gap is None:
+            return DetectAndInstallResult(
+                detected=False,
+                auto_upgrade_policy=auto_upgrade_policy,
+                error="No capability gap detected",
+            )
+
+        if on_detect is not None:
+            on_detect(gap.capability, gap.confidence, str(error))
+
+        if gap.confidence == "low" and not r_allow_low:
+            return DetectAndInstallResult(
+                detected=True,
+                capability=gap.capability,
+                confidence=gap.confidence,
+                installed=False,
+                auto_upgrade_policy=auto_upgrade_policy,
+                error="Low-confidence detection blocked",
+            )
+
+        if not r_auto_install:
+            return DetectAndInstallResult(
+                detected=True,
+                capability=gap.capability,
+                confidence=gap.confidence,
+                installed=False,
+                auto_upgrade_policy=auto_upgrade_policy,
+            )
+
+        install_result = self.resolve_and_install(
+            [gap.capability],
+            require_trusted=r_require_trusted,
+            require_verified=r_require_verified,
+        )
+
+        if install_result.installed and on_install is not None:
+            on_install(install_result.slug)
+
+        return DetectAndInstallResult(
+            detected=True,
+            capability=gap.capability,
+            confidence=gap.confidence,
+            installed=install_result.installed,
+            install_result=install_result,
+            auto_upgrade_policy=auto_upgrade_policy,
+        )
+
+    def smart_run(
+        self,
+        fn: Callable[[], Any],
+        *,
+        auto_upgrade_policy: str | None = None,
+        auto_install: bool = True,
+        require_verified: bool = True,
+        require_trusted: bool = False,
+        allow_low_confidence: bool = False,
+        context: dict[str, str] | None = None,
+        on_detect: Callable[[str, str, str], None] | None = None,
+        on_install: Callable[[str], None] | None = None,
+    ) -> SmartRunResult:
+        """Run a callable with automatic gap detection and retry.
+
+        Wraps your logic: if it fails due to a missing capability,
+        AgentNode detects the gap, installs the skill, and retries once.
+
+        Args:
+            fn: Zero-argument callable to execute.
+            auto_upgrade_policy: Named policy ('off', 'safe', 'strict').
+            auto_install: Whether to auto-install on detection.
+            require_verified: Only install verified+ packages.
+            require_trusted: Only install trusted+ packages.
+            allow_low_confidence: Allow install on low-confidence detections.
+            context: Optional context hints for detection.
+            on_detect: Callback(capability, confidence, error_msg) on detection.
+            on_install: Callback(slug) on successful install.
+        """
+        start = time.monotonic()
+
+        # Attempt 1
+        caught: Exception | None = None
+        try:
+            result = fn()
+            elapsed = (time.monotonic() - start) * 1000
+            return SmartRunResult(
+                success=True,
+                result=result,
+                duration_ms=elapsed,
+                auto_upgrade_policy=auto_upgrade_policy,
+            )
+        except Exception as exc:
+            caught = exc
+            original_error = str(exc)
+
+        # Detect and install
+        detect_result = self.detect_and_install(
+            caught,
+            auto_upgrade_policy=auto_upgrade_policy,
+            context=context,
+            auto_install=auto_install,
+            require_verified=require_verified,
+            require_trusted=require_trusted,
+            allow_low_confidence=allow_low_confidence,
+            on_detect=on_detect,
+            on_install=on_install,
+        )
+
+        if not detect_result.detected:
+            elapsed = (time.monotonic() - start) * 1000
+            return SmartRunResult(
+                success=False,
+                error=original_error,
+                original_error=original_error,
+                duration_ms=elapsed,
+                auto_upgrade_policy=auto_upgrade_policy,
+            )
+
+        if not detect_result.installed:
+            elapsed = (time.monotonic() - start) * 1000
+            return SmartRunResult(
+                success=False,
+                error=detect_result.error or original_error,
+                detected_capability=detect_result.capability,
+                detection_confidence=detect_result.confidence,
+                original_error=original_error,
+                duration_ms=elapsed,
+                auto_upgrade_policy=auto_upgrade_policy,
+            )
+
+        # Attempt 2 (exactly once)
+        installed_slug = (
+            detect_result.install_result.slug if detect_result.install_result else None
+        )
+        installed_version = (
+            detect_result.install_result.version if detect_result.install_result else None
+        )
+
+        try:
+            result = fn()
+            elapsed = (time.monotonic() - start) * 1000
+            return SmartRunResult(
+                success=True,
+                result=result,
+                upgraded=True,
+                installed_slug=installed_slug,
+                installed_version=installed_version,
+                detected_capability=detect_result.capability,
+                detection_confidence=detect_result.confidence,
+                duration_ms=elapsed,
+                original_error=original_error,
+                auto_upgrade_policy=auto_upgrade_policy,
+            )
+        except Exception as retry_exc:
+            elapsed = (time.monotonic() - start) * 1000
+            return SmartRunResult(
+                success=False,
+                error=str(retry_exc),
+                upgraded=True,
+                installed_slug=installed_slug,
+                installed_version=installed_version,
+                detected_capability=detect_result.capability,
+                detection_confidence=detect_result.confidence,
+                duration_ms=elapsed,
+                original_error=original_error,
+                auto_upgrade_policy=auto_upgrade_policy,
+            )