agentnode-sdk 0.1.0__tar.gz

agentnode_sdk-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# Node
+node_modules/
+cli/dist/
+
+# Next.js
+web/.next/
+web/out/
+
+# Environment
+.env
+.env.local
+.env.production
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+*.tar.gz
+*.whl
+
+# Spec documents
+*.docx
+
+# Claude Code
+.claude/

agentnode_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: agentnode-sdk
+Version: 0.1.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
+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 — the open upgrade and discovery infrastructure for AI agents.

agentnode_sdk-0.1.0/README.md

@@ -0,0 +1,3 @@
+# agentnode-sdk
+
+Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents.

agentnode_sdk-0.1.0/agentnode_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""AgentNode Python SDK — discover, resolve, and install AI agent capabilities."""
+
+from agentnode_sdk.client import AgentNode, AgentNodeClient
+from agentnode_sdk.exceptions import (
+    AgentNodeError,
+    AuthError,
+    NotFoundError,
+    ValidationError,
+)
+from agentnode_sdk.models import (
+    InstallMetadata,
+    PackageDetail,
+    ResolvedPackage,
+    ResolveResult,
+    SearchHit,
+    SearchResult,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "AgentNode",
+    "AgentNodeClient",
+    "AgentNodeError",
+    "NotFoundError",
+    "AuthError",
+    "ValidationError",
+    "PackageDetail",
+    "SearchResult",
+    "SearchHit",
+    "ResolveResult",
+    "ResolvedPackage",
+    "InstallMetadata",
+]

agentnode_sdk-0.1.0/agentnode_sdk/client.py

@@ -0,0 +1,371 @@
+"""AgentNode API client. Spec §14."""
+from __future__ import annotations
+
+import httpx
+
+from agentnode_sdk.exceptions import (
+    AgentNodeError,
+    AuthError,
+    NotFoundError,
+    ValidationError,
+)
+from agentnode_sdk.models import (
+    ArtifactInfo,
+    CapabilityInfo,
+    DependencyInfo,
+    InstallMetadata,
+    PackageDetail,
+    PermissionsInfo,
+    ResolvedPackage,
+    ResolveResult,
+    ScoreBreakdown,
+    SearchHit,
+    SearchResult,
+)
+
+DEFAULT_BASE_URL = "https://api.agentnode.net/v1"
+
+ERROR_CLASS_MAP = {
+    401: AuthError,
+    403: AuthError,
+    404: NotFoundError,
+    422: ValidationError,
+}
+
+
+class AgentNode:
+    """Spec-compliant SDK client (§14.3). Returns plain dicts."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key},
+            timeout=30,
+        )
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # --- Public API ---
+
+    def search(
+        self,
+        query: str = "",
+        capability_id: str = "",
+        framework: str = "",
+        sort_by: str = "relevance",
+        page: int = 1,
+    ) -> dict:
+        body = {k: v for k, v in {
+            "q": query,
+            "capability_id": capability_id,
+            "framework": framework,
+            "sort_by": sort_by,
+            "page": page,
+        }.items() if v}
+        return self._handle(self._client.post("/search", json=body))
+
+    def resolve_upgrade(
+        self,
+        missing_capability: str,
+        framework: str = "",
+        runtime: str = "",
+        current_capabilities: list[str] | None = None,
+        policy: dict | None = None,
+    ) -> dict:
+        return self._post(
+            "/resolve-upgrade",
+            missing_capability=missing_capability,
+            current_capabilities=current_capabilities or [],
+            framework=framework,
+            runtime=runtime,
+            policy=policy or {},
+        )
+
+    def check_policy(
+        self,
+        package_slug: str,
+        framework: str = "",
+        policy: dict | None = None,
+    ) -> dict:
+        return self._post(
+            "/check-policy",
+            package_slug=package_slug,
+            framework=framework,
+            policy=policy or {},
+        )
+
+    def get_install_metadata(self, package_slug: str, version: str = "") -> dict:
+        """Read-only install metadata. Does NOT create installation records."""
+        params = {"version": version} if version else {}
+        return self._handle(
+            self._client.get(f"/packages/{package_slug}/install-info", params=params)
+        )
+
+    def get_package(self, slug: str) -> dict:
+        return self._handle(self._client.get(f"/packages/{slug}"))
+
+    def validate(self, manifest: dict) -> dict:
+        return self._handle(
+            self._client.post("/packages/validate", json={"manifest": manifest})
+        )
+
+    def install(
+        self,
+        package_slug: str,
+        version: str = "",
+        source: str = "sdk",
+        event_type: str = "install",
+    ) -> dict:
+        """Create installation record and get artifact URL."""
+        body: dict = {"source": source, "event_type": event_type}
+        if version:
+            body["version"] = version
+        return self._handle(
+            self._client.post(f"/packages/{package_slug}/install", json=body)
+        )
+
+    def recommend(
+        self,
+        missing_capabilities: list[str],
+        framework: str = "",
+        runtime: str = "",
+    ) -> dict:
+        return self._post(
+            "/recommend",
+            missing_capabilities=missing_capabilities,
+            framework=framework,
+            runtime=runtime,
+        )
+
+    # --- Internal ---
+
+    def _post(self, path: str, **kwargs) -> dict:
+        # Keep lists/dicts even if empty; only filter out None and empty strings
+        body = {k: v for k, v in kwargs.items() if v is not None and v != ""}
+        return self._handle(self._client.post(path, json=body))
+
+    def _handle(self, response: httpx.Response) -> dict:
+        """Parse response. Raise typed AgentNodeError on API errors."""
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                err = body.get("error", {})
+                code = err.get("code", "UNKNOWN")
+                message = err.get("message", response.text)
+            except (ValueError, KeyError):
+                code, message = "UNKNOWN", response.text
+            exc_class = ERROR_CLASS_MAP.get(response.status_code, AgentNodeError)
+            raise exc_class(code, message)
+        return response.json()
+
+
+class AgentNodeClient:
+    """Extended client returning typed dataclass models. Backward-compatible."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        token: str | None = None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        elif token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(
+            base_url=self.base_url, headers=headers, timeout=timeout
+        )
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        resp = self._client.request(method, path, **kwargs)
+        if resp.status_code >= 400:
+            data = resp.json()
+            err = data.get("error", {})
+            exc_class = ERROR_CLASS_MAP.get(resp.status_code, AgentNodeError)
+            raise exc_class(
+                code=err.get("code", "UNKNOWN"),
+                message=err.get("message", resp.text),
+            )
+        return resp.json()
+
+    # --- Search ---
+
+    def search(
+        self,
+        query: str = "",
+        package_type: str | None = None,
+        capability_id: str | None = None,
+        framework: str | None = None,
+        sort_by: str | None = None,
+        page: int = 1,
+        per_page: int = 20,
+    ) -> SearchResult:
+        body: dict = {"q": query, "page": page, "per_page": per_page}
+        if package_type:
+            body["package_type"] = package_type
+        if capability_id:
+            body["capability_id"] = capability_id
+        if framework:
+            body["framework"] = framework
+        if sort_by:
+            body["sort_by"] = sort_by
+
+        data = self._request("POST", "/search", json=body)
+        hits = [
+            SearchHit(
+                slug=h["slug"],
+                name=h["name"],
+                package_type=h["package_type"],
+                summary=h["summary"],
+                publisher_slug=h.get("publisher_slug", ""),
+                trust_level=h.get("trust_level", "unverified"),
+                latest_version=h.get("latest_version"),
+                runtime=h.get("runtime"),
+                capability_ids=h.get("capability_ids", []),
+                download_count=h.get("download_count", 0),
+            )
+            for h in data.get("hits", [])
+        ]
+        return SearchResult(query=data["query"], hits=hits, total=data["total"])
+
+    # --- Resolve ---
+
+    def resolve(
+        self,
+        capabilities: list[str],
+        framework: str | None = None,
+        runtime: str | None = None,
+        package_type: str | None = None,
+        limit: int = 10,
+    ) -> ResolveResult:
+        body: dict = {"capabilities": capabilities, "limit": limit}
+        if framework:
+            body["framework"] = framework
+        if runtime:
+            body["runtime"] = runtime
+        if package_type:
+            body["package_type"] = package_type
+
+        data = self._request("POST", "/resolve", json=body)
+        results = [
+            ResolvedPackage(
+                slug=r["slug"],
+                name=r["name"],
+                package_type=r["package_type"],
+                summary=r["summary"],
+                version=r["version"],
+                publisher_slug=r["publisher_slug"],
+                trust_level=r["trust_level"],
+                score=r["score"],
+                breakdown=ScoreBreakdown(**r["breakdown"]),
+                matched_capabilities=r.get("matched_capabilities", []),
+            )
+            for r in data.get("results", [])
+        ]
+        return ResolveResult(results=results, total=data["total"])
+
+    # --- Package detail ---
+
+    def get_package(self, slug: str) -> PackageDetail:
+        data = self._request("GET", f"/packages/{slug}")
+        lv = data.get("latest_version")
+        return PackageDetail(
+            slug=data["slug"],
+            name=data["name"],
+            package_type=data["package_type"],
+            summary=data["summary"],
+            description=data.get("description"),
+            download_count=data["download_count"],
+            is_deprecated=data["is_deprecated"],
+            latest_version=lv["version_number"] if lv else None,
+        )
+
+    # --- Install metadata ---
+
+    def get_install_metadata(
+        self, slug: str, version: str | None = None
+    ) -> InstallMetadata:
+        params = {}
+        if version:
+            params["version"] = version
+        data = self._request("GET", f"/packages/{slug}/install-info", params=params)
+
+        artifact = None
+        if data.get("artifact"):
+            a = data["artifact"]
+            artifact = ArtifactInfo(
+                url=a.get("url"),
+                hash_sha256=a.get("hash_sha256"),
+                size_bytes=a.get("size_bytes"),
+            )
+
+        caps = [
+            CapabilityInfo(
+                name=c["name"],
+                capability_id=c["capability_id"],
+                capability_type=c["capability_type"],
+            )
+            for c in data.get("capabilities", [])
+        ]
+        deps = [
+            DependencyInfo(
+                package_slug=d["package_slug"],
+                role=d.get("role"),
+                is_required=d["is_required"],
+                min_version=d.get("min_version"),
+            )
+            for d in data.get("dependencies", [])
+        ]
+        perms = None
+        if data.get("permissions"):
+            p = data["permissions"]
+            perms = PermissionsInfo(
+                network_level=p["network_level"],
+                filesystem_level=p["filesystem_level"],
+                code_execution_level=p["code_execution_level"],
+                data_access_level=p["data_access_level"],
+                user_approval_level=p["user_approval_level"],
+            )
+
+        return InstallMetadata(
+            slug=data["slug"],
+            version=data["version"],
+            package_type=data["package_type"],
+            install_mode=data["install_mode"],
+            hosting_type=data["hosting_type"],
+            runtime=data["runtime"],
+            entrypoint=data.get("entrypoint"),
+            artifact=artifact,
+            capabilities=caps,
+            dependencies=deps,
+            permissions=perms,
+        )
+
+    # --- Download ---
+
+    def download(self, slug: str, version: str | None = None) -> str | None:
+        """Track download and return artifact URL."""
+        params = {}
+        if version:
+            params["version"] = version
+        data = self._request("POST", f"/packages/{slug}/download", params=params)
+        return data.get("download_url")

agentnode_sdk-0.1.0/agentnode_sdk/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception hierarchy for AgentNode SDK. Spec §14.1."""
+
+
+class AgentNodeError(Exception):
+    """Base error for all AgentNode API errors."""
+
+    def __init__(self, code: str, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")
+
+
+class NotFoundError(AgentNodeError):
+    """Package or resource not found (404)."""
+    pass
+
+
+class AuthError(AgentNodeError):
+    """Authentication or authorization failure (401/403)."""
+    pass
+
+
+class ValidationError(AgentNodeError):
+    """Manifest or input validation failure (422)."""
+    pass

agentnode_sdk-0.1.0/agentnode_sdk/models.py

@@ -0,0 +1,112 @@
+"""Data models for the AgentNode SDK."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SearchHit:
+    slug: str
+    name: str
+    package_type: str
+    summary: str
+    publisher_slug: str
+    trust_level: str
+    latest_version: str | None = None
+    runtime: str | None = None
+    capability_ids: list[str] = field(default_factory=list)
+    download_count: int = 0
+
+
+@dataclass
+class SearchResult:
+    query: str
+    hits: list[SearchHit]
+    total: int
+
+
+@dataclass
+class ScoreBreakdown:
+    capability: float
+    framework: float
+    runtime: float
+    trust: float
+    permissions: float
+
+
+@dataclass
+class ResolvedPackage:
+    slug: str
+    name: str
+    package_type: str
+    summary: str
+    version: str
+    publisher_slug: str
+    trust_level: str
+    score: float
+    breakdown: ScoreBreakdown
+    matched_capabilities: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ResolveResult:
+    results: list[ResolvedPackage]
+    total: int
+
+
+@dataclass
+class ArtifactInfo:
+    url: str | None
+    hash_sha256: str | None
+    size_bytes: int | None
+
+
+@dataclass
+class CapabilityInfo:
+    name: str
+    capability_id: str
+    capability_type: str
+
+
+@dataclass
+class DependencyInfo:
+    package_slug: str
+    role: str | None
+    is_required: bool
+    min_version: str | None = None
+
+
+@dataclass
+class PermissionsInfo:
+    network_level: str
+    filesystem_level: str
+    code_execution_level: str
+    data_access_level: str
+    user_approval_level: str
+
+
+@dataclass
+class InstallMetadata:
+    slug: str
+    version: str
+    package_type: str
+    install_mode: str
+    hosting_type: str
+    runtime: str
+    entrypoint: str | None
+    artifact: ArtifactInfo | None
+    capabilities: list[CapabilityInfo] = field(default_factory=list)
+    dependencies: list[DependencyInfo] = field(default_factory=list)
+    permissions: PermissionsInfo | None = None
+
+
+@dataclass
+class PackageDetail:
+    slug: str
+    name: str
+    package_type: str
+    summary: str
+    description: str | None
+    download_count: int
+    is_deprecated: bool
+    latest_version: str | None = None

agentnode_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentnode-sdk"
+version = "0.1.0"
+description = "Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["ai", "agent", "capabilities", "agentnode", "mcp", "langchain"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.25",
+]
+
+[project.urls]
+Homepage = "https://agentnode.net"
+Repository = "https://github.com/agentnode-ai/agentnode"
+Documentation = "https://agentnode.net/docs"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "respx"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentnode_sdk"]

agentnode_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,152 @@
+"""Unit tests for AgentNode SDK client."""
+import json
+
+import httpx
+import pytest
+import respx
+
+from agentnode_sdk import AgentNodeClient
+
+BASE = "https://api.agentnode.net"
+
+
+@respx.mock
+def test_search():
+    respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json={
+        "query": "pdf",
+        "hits": [{
+            "slug": "pdf-reader",
+            "name": "PDF Reader",
+            "package_type": "toolpack",
+            "summary": "Read PDFs",
+            "publisher_slug": "test",
+            "trust_level": "verified",
+            "latest_version": "1.0.0",
+            "runtime": "python",
+            "capability_ids": ["pdf_extraction"],
+            "download_count": 100,
+        }],
+        "total": 1,
+        "limit": 20,
+        "offset": 0,
+    }))
+
+    with AgentNodeClient() as client:
+        result = client.search("pdf")
+        assert result.total == 1
+        assert result.hits[0].slug == "pdf-reader"
+        assert result.hits[0].capability_ids == ["pdf_extraction"]
+
+
+@respx.mock
+def test_resolve():
+    respx.post(f"{BASE}/v1/resolve").mock(return_value=httpx.Response(200, json={
+        "results": [{
+            "slug": "pdf-reader",
+            "name": "PDF Reader",
+            "package_type": "toolpack",
+            "summary": "Read PDFs",
+            "version": "1.0.0",
+            "publisher_slug": "test",
+            "trust_level": "verified",
+            "score": 0.85,
+            "breakdown": {
+                "capability": 1.0,
+                "framework": 1.0,
+                "runtime": 1.0,
+                "trust": 0.5,
+                "permissions": 0.9,
+            },
+            "matched_capabilities": ["pdf_extraction"],
+        }],
+        "total": 1,
+    }))
+
+    with AgentNodeClient() as client:
+        result = client.resolve(["pdf_extraction"])
+        assert result.total == 1
+        assert result.results[0].score == 0.85
+        assert result.results[0].breakdown.capability == 1.0
+
+
+@respx.mock
+def test_get_package():
+    respx.get(f"{BASE}/v1/packages/pdf-reader").mock(return_value=httpx.Response(200, json={
+        "slug": "pdf-reader",
+        "name": "PDF Reader",
+        "package_type": "toolpack",
+        "summary": "Read PDFs",
+        "description": "A great PDF reader",
+        "download_count": 42,
+        "is_deprecated": False,
+        "latest_version": {"version_number": "1.0.0", "channel": "stable", "published_at": "2026-01-01T00:00:00Z"},
+        "publisher": {"slug": "test", "display_name": "Test", "trust_level": "verified"},
+        "blocks": {},
+    }))
+
+    with AgentNodeClient() as client:
+        pkg = client.get_package("pdf-reader")
+        assert pkg.slug == "pdf-reader"
+        assert pkg.latest_version == "1.0.0"
+        assert pkg.download_count == 42
+
+
+@respx.mock
+def test_get_install_metadata():
+    respx.get(f"{BASE}/v1/packages/pdf-reader/install").mock(return_value=httpx.Response(200, json={
+        "slug": "pdf-reader",
+        "version": "1.0.0",
+        "package_type": "toolpack",
+        "install_mode": "package",
+        "hosting_type": "agentnode_hosted",
+        "runtime": "python",
+        "entrypoint": "pdf_reader.tool",
+        "artifact": {"url": "https://s3.example.com/artifact.tar.gz", "hash_sha256": "abc123", "size_bytes": 1000},
+        "capabilities": [{"name": "extract", "capability_id": "pdf_extraction", "capability_type": "tool"}],
+        "dependencies": [],
+        "permissions": {
+            "network_level": "none",
+            "filesystem_level": "temp",
+            "code_execution_level": "none",
+            "data_access_level": "input_only",
+            "user_approval_level": "never",
+        },
+        "published_at": "2026-01-01T00:00:00Z",
+    }))
+
+    with AgentNodeClient() as client:
+        meta = client.get_install_metadata("pdf-reader")
+        assert meta.slug == "pdf-reader"
+        assert meta.entrypoint == "pdf_reader.tool"
+        assert meta.artifact.url == "https://s3.example.com/artifact.tar.gz"
+        assert len(meta.capabilities) == 1
+        assert meta.permissions.network_level == "none"
+
+
+@respx.mock
+def test_error_handling():
+    respx.get(f"{BASE}/v1/packages/nonexistent").mock(return_value=httpx.Response(404, json={
+        "error": {"code": "PACKAGE_NOT_FOUND", "message": "Not found", "details": {}}
+    }))
+
+    with AgentNodeClient() as client:
+        with pytest.raises(Exception) as exc_info:
+            client.get_package("nonexistent")
+        assert "PACKAGE_NOT_FOUND" in str(exc_info.value)
+
+
+@respx.mock
+def test_api_key_auth():
+    route = respx.get(f"{BASE}/v1/packages/test").mock(return_value=httpx.Response(200, json={
+        "slug": "test", "name": "Test", "package_type": "toolpack",
+        "summary": "Test", "description": None, "download_count": 0,
+        "is_deprecated": False, "latest_version": None,
+        "publisher": {"slug": "t", "display_name": "T", "trust_level": "unverified"},
+        "blocks": {},
+    }))
+
+    with AgentNodeClient(api_key="ank_test123") as client:
+        client.get_package("test")
+
+    assert route.called
+    assert route.calls[0].request.headers["x-api-key"] == "ank_test123"