agentnode-sdk 0.3.0__tar.gz → 0.4.1__tar.gz

{agentnode_sdk-0.3.0 → agentnode_sdk-0.4.1}/.env.example

@@ -1,8 +1,8 @@
-# AgentNode SDK — Environment Variables (optional)
-# These can be passed to AgentNode() constructor instead.
-
-# API endpoint
-AGENTNODE_API_URL=https://api.agentnode.net
-
-# API key
-AGENTNODE_API_KEY=ank_your-api-key-here
+# AgentNode SDK — Environment Variables (optional)
+# These can be passed to AgentNode() constructor instead.
+
+# API endpoint
+AGENTNODE_API_URL=https://api.agentnode.net
+
+# API key
+AGENTNODE_API_KEY=ank_your-api-key-here

{agentnode_sdk-0.3.0 → agentnode_sdk-0.4.1}/.gitignore

@@ -40,6 +40,9 @@ htmlcov/
 *.tar.gz
 *.whl
 
+# Test score artifacts
+.artifacts/
+
 # Spec documents
 *.docx
 
@@ -65,3 +68,12 @@ packages_dump.json
 snapshot_nonowner.txt
 seo/
 backend/scripts/enrichment_*.json
+
+# Internal documentation (not for GitHub)
+internal/
+
+# Internal ops scripts (crawl, enrichment, import)
+scripts/crawl_*.py
+scripts/enrich_*.py
+scripts/import_candidates.py
+candidates*.json

agentnode_sdk-0.4.1/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.4.1 — Security & Correctness
+
+**Behavioral change:** `run_tool(mode="auto")` now always executes via
+subprocess isolation, regardless of trust level. This makes the
+documented isolation guarantee true by default. `mode="direct"` remains
+available as an explicit opt-in for performance-critical workloads that
+knowingly share in-process globals.
+
+**Migration note:** Tools that rely on shared in-process state
+(module-level globals, process-wide singletons) should explicitly pass
+`mode="direct"` going forward.
+
+### Fixes
+
+- **AsyncAgentNode /v1 base URL** — the async client now appends `/v1` to
+  `base_url` when missing, matching `AgentNode` (sync). Previously all
+  `AsyncAgentNode` calls hit `/packages/...` and 404ed against
+  production. (P0-04)
+- **AgentNodeClient.install()** now POSTs
+  `POST /v1/packages/{slug}/install` so the backend tracks the install
+  event. Previously installs went untracked. (P0-05)
+- **run_tool(mode="auto") always uses subprocess** — see behavioral
+  change above. (P0-06)
+- **Response parsing hardening** — `_handle`/`_request` no longer crash
+  on non-dict JSON error bodies or HTML/plain-text 2xx responses; both
+  are now surfaced as `AgentNodeError`. (P1-SDK3, P1-SDK4)
+- **run_tool reserved kwargs** — passing the internal `entry` kwarg via
+  `**kwargs` now raises `TypeError` instead of silently shadowing the
+  dispatcher's forwarding path. (P1-SDK5)
+- **Installer download ceiling** — `download_artifact` now enforces a
+  500 MB hard ceiling (`MAX_DOWNLOAD_BYTES`). Declared
+  `Content-Length` is checked up front; streamed bytes are checked per
+  chunk. Oversized downloads are aborted and the partial file removed.
+  (P1-SDK6)
+- **run_tool dispatch logging** — `runner.run_tool` now emits an `INFO`
+  log line with the resolved runtime and mode, so callers can confirm
+  what mode `auto` actually picked without inspecting the
+  `RunToolResult` after the fact. (P1-SDK10)

agentnode_sdk-0.4.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: agentnode-sdk
+Version: 0.4.1
+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
+Project-URL: Documentation, https://agentnode.net/docs
+License-Expression: MIT
+Keywords: agent,agentnode,ai,capabilities,langchain,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentnode-sdk
+
+Python SDK for [AgentNode](https://agentnode.net) — the open upgrade and discovery infrastructure for AI agents.
+
+## Installation
+
+```bash
+pip install agentnode-sdk
+```
+
+## Quick Start — LLM Agent Runtime
+
+Connect any LLM agent to AgentNode in three lines. The Runtime provides tool definitions, system prompt, and a tool-loop engine. Tested across 22 models — works with OpenAI, Anthropic, Gemini, Mistral, DeepSeek, Qwen, Llama, and more.
+
+```python
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+
+# Get tools + system prompt for your provider
+bundle = runtime.tool_bundle()
+# → { "tools": [...], "system_prompt": "..." }
+```
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = OpenAI()
+
+result = runtime.run(
+    provider="openai",
+    client=client,
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Count the words in 'Hello world'"}],
+)
+print(result.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = Anthropic()
+
+result = runtime.run(
+    provider="anthropic",
+    client=client,
+    model="claude-sonnet-4-6",
+    messages=[{"role": "user", "content": "Search for PDF tools on AgentNode"}],
+)
+```
+
+### Gemini
+
+```python
+from google import genai
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = genai.Client()
+
+result = runtime.run(
+    provider="gemini",
+    client=client,
+    model="gemini-2.5-flash",
+    messages=[{"role": "user", "content": "What AgentNode tools are available?"}],
+)
+```
+
+### OpenRouter (Mistral, DeepSeek, Qwen, Llama, and more)
+
+Use any OpenAI-compatible provider by passing a custom `base_url`:
+
+```python
+from openai import OpenAI
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = OpenAI(
+    api_key="sk-or-...",
+    base_url="https://openrouter.ai/api/v1",
+)
+
+result = runtime.run(
+    provider="openai",
+    client=client,
+    model="mistralai/mistral-large",  # or deepseek/deepseek-chat, qwen/qwen-plus, etc.
+    messages=[{"role": "user", "content": "Find and install a PDF reader tool"}],
+)
+```
+
+### Generic / Manual Tool Calling
+
+For any provider that supports tool calling, use `handle()` to dispatch calls manually:
+
+```python
+runtime = AgentNodeRuntime()
+
+# Get tool definitions in your provider's format
+tools = runtime.as_openai_tools()   # OpenAI format
+tools = runtime.as_anthropic_tools() # Anthropic format
+tools = runtime.as_gemini_tools()    # Gemini format
+tools = runtime.as_generic_tools()   # Generic format
+
+# When the LLM makes a tool call, dispatch it:
+result = runtime.handle("agentnode_search", {"query": "pdf extraction"})
+# → {"success": true, "result": {"total": 5, "results": [...]}}
+```
+
+## Three Surfaces
+
+```
+CLI           → for humans (search, install, publish)
+SDK / Client  → for programmatic access (search, resolve, install, run)
+Runtime       → for LLM agents (tool registration, dispatch, auto-loop)
+```
+
+## API Reference
+
+### `AgentNodeRuntime`
+
+Zero-config LLM agent integration.
+
+| Method | Description |
+|--------|-------------|
+| `tool_specs()` | Internal typed tool definitions (`list[ToolSpec]`) |
+| `as_openai_tools()` | Tools in OpenAI function-calling format |
+| `as_anthropic_tools()` | Tools in Anthropic format |
+| `as_generic_tools()` | Tools in generic/baseline format |
+| `system_prompt()` | AgentNode system prompt block (append to yours) |
+| `tool_bundle()` | Combined `{"tools": [...], "system_prompt": "..."}` |
+| `handle(tool_name, arguments)` | Dispatch a tool call. Returns dict. Never throws. |
+| `run(provider, client, messages, model, ...)` | Auto-loop with tool dispatch. Never throws. |
+
+**Constructor:**
+
+```python
+AgentNodeRuntime(
+    client=None,                     # Optional AgentNodeClient
+    api_key=None,                    # Optional API key
+    minimum_trust_level="verified",  # "verified" | "trusted" | "curated"
+)
+```
+
+**5 Meta-Tools** (automatically registered):
+
+| Tool | Description |
+|------|-------------|
+| `agentnode_capabilities` | List installed packages (local, no API call) |
+| `agentnode_search` | Search the registry (max 5 results) |
+| `agentnode_install` | Install a package by slug |
+| `agentnode_run` | Execute an installed tool |
+| `agentnode_acquire` | Search + install in one step |
+
+### `AgentNodeClient`
+
+The programmatic client with typed return models.
+
+| Method | Description |
+|--------|-------------|
+| `search(query, ...)` | Search packages by keyword or capability |
+| `resolve(capabilities, ...)` | Resolve capability gaps to ranked packages |
+| `install(slug, ...)` | Download, verify, and install locally |
+| `resolve_and_install(capabilities, ...)` | Resolve + install in one call |
+| `run_tool(slug, tool_name=, ...)` | Run a tool with trust-aware isolation |
+| `smart_run(fn, ...)` | Wrap logic with auto-detect, install, retry |
+| `detect_and_install(error, ...)` | Detect capability gap and install |
+
+### `run_tool()` (standalone)
+
+Top-level function for running tools with process isolation.
+
+```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
+```
+
+**Isolation contract.** `mode="auto"` always resolves to `subprocess`,
+regardless of the package's trust level. This makes the isolation
+guarantee true by default. If you need in-process execution (for
+example, to share module-level state with the tool), pass
+`mode="direct"` explicitly — that is an opt-in performance trade-off,
+not a default.
+
+## License
+
+MIT

agentnode_sdk-0.4.1/README.md

@@ -0,0 +1,196 @@
+# agentnode-sdk
+
+Python SDK for [AgentNode](https://agentnode.net) — the open upgrade and discovery infrastructure for AI agents.
+
+## Installation
+
+```bash
+pip install agentnode-sdk
+```
+
+## Quick Start — LLM Agent Runtime
+
+Connect any LLM agent to AgentNode in three lines. The Runtime provides tool definitions, system prompt, and a tool-loop engine. Tested across 22 models — works with OpenAI, Anthropic, Gemini, Mistral, DeepSeek, Qwen, Llama, and more.
+
+```python
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+
+# Get tools + system prompt for your provider
+bundle = runtime.tool_bundle()
+# → { "tools": [...], "system_prompt": "..." }
+```
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = OpenAI()
+
+result = runtime.run(
+    provider="openai",
+    client=client,
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Count the words in 'Hello world'"}],
+)
+print(result.content)
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = Anthropic()
+
+result = runtime.run(
+    provider="anthropic",
+    client=client,
+    model="claude-sonnet-4-6",
+    messages=[{"role": "user", "content": "Search for PDF tools on AgentNode"}],
+)
+```
+
+### Gemini
+
+```python
+from google import genai
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = genai.Client()
+
+result = runtime.run(
+    provider="gemini",
+    client=client,
+    model="gemini-2.5-flash",
+    messages=[{"role": "user", "content": "What AgentNode tools are available?"}],
+)
+```
+
+### OpenRouter (Mistral, DeepSeek, Qwen, Llama, and more)
+
+Use any OpenAI-compatible provider by passing a custom `base_url`:
+
+```python
+from openai import OpenAI
+from agentnode_sdk import AgentNodeRuntime
+
+runtime = AgentNodeRuntime()
+client = OpenAI(
+    api_key="sk-or-...",
+    base_url="https://openrouter.ai/api/v1",
+)
+
+result = runtime.run(
+    provider="openai",
+    client=client,
+    model="mistralai/mistral-large",  # or deepseek/deepseek-chat, qwen/qwen-plus, etc.
+    messages=[{"role": "user", "content": "Find and install a PDF reader tool"}],
+)
+```
+
+### Generic / Manual Tool Calling
+
+For any provider that supports tool calling, use `handle()` to dispatch calls manually:
+
+```python
+runtime = AgentNodeRuntime()
+
+# Get tool definitions in your provider's format
+tools = runtime.as_openai_tools()   # OpenAI format
+tools = runtime.as_anthropic_tools() # Anthropic format
+tools = runtime.as_gemini_tools()    # Gemini format
+tools = runtime.as_generic_tools()   # Generic format
+
+# When the LLM makes a tool call, dispatch it:
+result = runtime.handle("agentnode_search", {"query": "pdf extraction"})
+# → {"success": true, "result": {"total": 5, "results": [...]}}
+```
+
+## Three Surfaces
+
+```
+CLI           → for humans (search, install, publish)
+SDK / Client  → for programmatic access (search, resolve, install, run)
+Runtime       → for LLM agents (tool registration, dispatch, auto-loop)
+```
+
+## API Reference
+
+### `AgentNodeRuntime`
+
+Zero-config LLM agent integration.
+
+| Method | Description |
+|--------|-------------|
+| `tool_specs()` | Internal typed tool definitions (`list[ToolSpec]`) |
+| `as_openai_tools()` | Tools in OpenAI function-calling format |
+| `as_anthropic_tools()` | Tools in Anthropic format |
+| `as_generic_tools()` | Tools in generic/baseline format |
+| `system_prompt()` | AgentNode system prompt block (append to yours) |
+| `tool_bundle()` | Combined `{"tools": [...], "system_prompt": "..."}` |
+| `handle(tool_name, arguments)` | Dispatch a tool call. Returns dict. Never throws. |
+| `run(provider, client, messages, model, ...)` | Auto-loop with tool dispatch. Never throws. |
+
+**Constructor:**
+
+```python
+AgentNodeRuntime(
+    client=None,                     # Optional AgentNodeClient
+    api_key=None,                    # Optional API key
+    minimum_trust_level="verified",  # "verified" | "trusted" | "curated"
+)
+```
+
+**5 Meta-Tools** (automatically registered):
+
+| Tool | Description |
+|------|-------------|
+| `agentnode_capabilities` | List installed packages (local, no API call) |
+| `agentnode_search` | Search the registry (max 5 results) |
+| `agentnode_install` | Install a package by slug |
+| `agentnode_run` | Execute an installed tool |
+| `agentnode_acquire` | Search + install in one step |
+
+### `AgentNodeClient`
+
+The programmatic client with typed return models.
+
+| Method | Description |
+|--------|-------------|
+| `search(query, ...)` | Search packages by keyword or capability |
+| `resolve(capabilities, ...)` | Resolve capability gaps to ranked packages |
+| `install(slug, ...)` | Download, verify, and install locally |
+| `resolve_and_install(capabilities, ...)` | Resolve + install in one call |
+| `run_tool(slug, tool_name=, ...)` | Run a tool with trust-aware isolation |
+| `smart_run(fn, ...)` | Wrap logic with auto-detect, install, retry |
+| `detect_and_install(error, ...)` | Detect capability gap and install |
+
+### `run_tool()` (standalone)
+
+Top-level function for running tools with process isolation.
+
+```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
+```
+
+**Isolation contract.** `mode="auto"` always resolves to `subprocess`,
+regardless of the package's trust level. This makes the isolation
+guarantee true by default. If you need in-process execution (for
+example, to share module-level state with the tool), pass
+`mode="direct"` explicitly — that is an opt-in performance trade-off,
+not a default.
+
+## License
+
+MIT

{agentnode_sdk-0.3.0 → agentnode_sdk-0.4.1}/agentnode.lock

@@ -1,23 +1,23 @@
-{
-  "lockfile_version": "0.1",
-  "updated_at": "2026-03-18T02:18:53.827839+00:00",
-  "packages": {
-    "word-counter-pack": {
-      "version": "1.0.0",
-      "package_type": "toolpack",
-      "entrypoint": "word_counter_pack.tool",
-      "capability_ids": [
-        "data_cleaning"
-      ],
-      "tools": [
-        {
-          "name": "count_words",
-          "entrypoint": "word_counter_pack.tool:count_words"
-        }
-      ],
-      "artifact_hash": "sha256:445388c86aa2b20c3e748f58b2d221548f1f3f71ff5c715a64cdc80966fab03c",
-      "installed_at": "2026-03-18T02:18:53.827396+00:00",
-      "source": "sdk"
-    }
-  }
-}
+{
+  "lockfile_version": "0.1",
+  "updated_at": "2026-03-18T02:18:53.827839+00:00",
+  "packages": {
+    "word-counter-pack": {
+      "version": "1.0.0",
+      "package_type": "toolpack",
+      "entrypoint": "word_counter_pack.tool",
+      "capability_ids": [
+        "data_cleaning"
+      ],
+      "tools": [
+        {
+          "name": "count_words",
+          "entrypoint": "word_counter_pack.tool:count_words"
+        }
+      ],
+      "artifact_hash": "sha256:445388c86aa2b20c3e748f58b2d221548f1f3f71ff5c715a64cdc80966fab03c",
+      "installed_at": "2026-03-18T02:18:53.827396+00:00",
+      "source": "sdk"
+    }
+  }
+}

{agentnode_sdk-0.3.0 → agentnode_sdk-0.4.1}/agentnode_sdk/__init__.py

@@ -2,6 +2,8 @@
 
 from agentnode_sdk.async_client import AsyncAgentNode
 from agentnode_sdk.client import AgentNode, AgentNodeClient
+from agentnode_sdk.config import load_config, config_path, installation_behavior_label
+from agentnode_sdk.detect import detect_gap
 from agentnode_sdk.exceptions import (
     AgentNodeError,
     AgentNodeToolError,
@@ -13,6 +15,8 @@ from agentnode_sdk.exceptions import (
 from agentnode_sdk.installer import load_tool
 from agentnode_sdk.models import (
     CanInstallResult,
+    DetectAndInstallResult,
+    DetectedGap,
     InstallMetadata,
     InstallResult,
     PackageDetail,
@@ -21,19 +25,26 @@ from agentnode_sdk.models import (
     RunToolResult,
     SearchHit,
     SearchResult,
+    SmartRunResult,
 )
+from agentnode_sdk.compatibility import recommend_model
 from agentnode_sdk.runner import run_tool
+from agentnode_sdk.runtime import AgentNodeRuntime
 
 # Convenience aliases
 Client = AgentNodeClient
 ToolError = AgentNodeToolError
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",
     "AgentNodeClient",
     "Client",
+    "load_config",
+    "config_path",
+    "installation_behavior_label",
+    "detect_gap",
     "load_tool",
     "run_tool",
     "AgentNodeError",
@@ -52,4 +63,9 @@ __all__ = [
     "InstallResult",
     "CanInstallResult",
     "RunToolResult",
+    "DetectedGap",
+    "DetectAndInstallResult",
+    "SmartRunResult",
+    "AgentNodeRuntime",
+    "recommend_model",
 ]