agenttool-sdk 0.1.0__tar.gz

agenttool_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: agenttool-sdk
+Version: 0.1.0
+Summary: Python SDK for agenttool.dev — memory and tools for AI agents
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agenttool
+
+Python SDK for [agenttool.dev](https://agenttool.dev) — memory and tools for AI agents.
+
+```bash
+pip install agenttool
+```
+
+```python
+from agenttool import AgentTool
+
+at = AgentTool()  # reads AT_API_KEY from env
+at.memory.store("learned something new")
+results = at.memory.search("what did I learn?")
+hits = at.tools.search("latest AI news")
+page = at.tools.scrape("https://example.com")
+out = at.tools.execute("print(1 + 1)")
+```
+
+Set your key: `export AT_API_KEY=your-key-here`

agenttool_sdk-0.1.0/README.md

@@ -0,0 +1,20 @@
+# agenttool
+
+Python SDK for [agenttool.dev](https://agenttool.dev) — memory and tools for AI agents.
+
+```bash
+pip install agenttool
+```
+
+```python
+from agenttool import AgentTool
+
+at = AgentTool()  # reads AT_API_KEY from env
+at.memory.store("learned something new")
+results = at.memory.search("what did I learn?")
+hits = at.tools.search("latest AI news")
+page = at.tools.scrape("https://example.com")
+out = at.tools.execute("print(1 + 1)")
+```
+
+Set your key: `export AT_API_KEY=your-key-here`

agenttool_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agenttool-sdk"
+version = "0.1.0"
+description = "Python SDK for agenttool.dev — memory and tools for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agenttool"]

agenttool_sdk-0.1.0/src/agenttool/__init__.py

@@ -0,0 +1,17 @@
+"""AgentTool SDK — memory and tools for AI agents."""
+
+from .client import AgentTool
+from .exceptions import AgentToolError
+from .models import ExecuteResult, Memory, ScrapeResult, SearchResult, UsageStats
+
+__all__ = [
+    "AgentTool",
+    "AgentToolError",
+    "ExecuteResult",
+    "Memory",
+    "ScrapeResult",
+    "SearchResult",
+    "UsageStats",
+]
+
+__version__ = "0.1.0"

agenttool_sdk-0.1.0/src/agenttool/client.py

@@ -0,0 +1,85 @@
+"""Main AgentTool client — the single entry point."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import httpx
+
+from .exceptions import AgentToolError
+from .memory import MemoryClient
+from .tools import ToolsClient
+
+
+class AgentTool:
+    """Unified client for the agenttool.dev platform.
+
+    Usage::
+
+        from agenttool import AgentTool
+
+        at = AgentTool()                          # reads AT_API_KEY from env
+        at.memory.store("just a string")           # store a memory
+        results = at.memory.search("what I said")  # semantic search
+        hits = at.tools.search("latest AI news")   # web search
+        page = at.tools.scrape("https://x.com")    # scrape a URL
+        out = at.tools.execute("print(42)")         # run sandboxed code
+
+    Args:
+        api_key: API key. Falls back to ``AT_API_KEY`` env var.
+        base_url: Override the API base URL.
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = "https://api.agenttool.dev",
+        timeout: float = 30.0,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("AT_API_KEY")
+        if not resolved_key:
+            raise AgentToolError(
+                "No API key provided.",
+                hint="Pass api_key= or set the AT_API_KEY environment variable.",
+            )
+
+        self._http = httpx.Client(
+            headers={
+                "Authorization": f"Bearer {resolved_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+        self._base_url = base_url.rstrip("/")
+        self._memory: Optional[MemoryClient] = None
+        self._tools: Optional[ToolsClient] = None
+
+    @property
+    def memory(self) -> MemoryClient:
+        """Access the Memory API."""
+        if self._memory is None:
+            self._memory = MemoryClient(self._http, self._base_url)
+        return self._memory
+
+    @property
+    def tools(self) -> ToolsClient:
+        """Access the Tools API."""
+        if self._tools is None:
+            self._tools = ToolsClient(self._http, self._base_url)
+        return self._tools
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._http.close()
+
+    def __enter__(self) -> AgentTool:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"AgentTool(base_url={self._base_url!r})"

agenttool_sdk-0.1.0/src/agenttool/exceptions.py

@@ -0,0 +1,22 @@
+"""Exceptions for the AgentTool SDK."""
+
+from __future__ import annotations
+
+
+class AgentToolError(Exception):
+    """Base error for all AgentTool SDK operations.
+
+    Attributes:
+        message: Human-readable error description.
+        hint: Actionable suggestion for fixing the error.
+    """
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        self.message = message
+        self.hint = hint
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        if self.hint:
+            return f"{self.message} (hint: {self.hint})"
+        return self.message

agenttool_sdk-0.1.0/src/agenttool/memory.py

@@ -0,0 +1,132 @@
+"""Memory client for agent-memory API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+import httpx
+
+from .exceptions import AgentToolError
+from .models import Memory, UsageStats
+
+if TYPE_CHECKING:
+    pass
+
+
+class MemoryClient:
+    """Client for the agent-memory API.
+
+    Usage::
+
+        at = AgentTool()
+        at.memory.store("just a string")
+        results = at.memory.search("what did I learn?")
+    """
+
+    def __init__(self, http: httpx.Client, base_url: str) -> None:
+        self._http = http
+        self._base = base_url.rstrip("/")
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}{path}"
+
+    def store(
+        self,
+        content: str,
+        *,
+        type: str = "semantic",
+        agent_id: Optional[str] = None,
+        key: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        importance: float = 0.5,
+    ) -> Memory:
+        """Store a memory. Only ``content`` is required.
+
+        Args:
+            content: The memory content string.
+            type: One of semantic, episodic, procedural, working.
+            agent_id: Optional agent identifier.
+            key: Optional dedup/lookup key.
+            metadata: Arbitrary metadata dict.
+            importance: 0.0–1.0 importance score.
+
+        Returns:
+            The created Memory object.
+        """
+        body: Dict[str, Any] = {"content": content, "type": type, "importance": importance}
+        if agent_id is not None:
+            body["agent_id"] = agent_id
+        if key is not None:
+            body["key"] = key
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        resp = self._http.post(self._url("/v1/memories"), json=body)
+        self._check(resp)
+        return Memory.from_dict(resp.json())
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int = 10,
+        type: Optional[str] = None,
+        agent_id: Optional[str] = None,
+    ) -> List[Memory]:
+        """Semantic search over stored memories.
+
+        Args:
+            query: Natural-language search query.
+            limit: Max results to return.
+            type: Filter by memory type.
+            agent_id: Filter by agent.
+
+        Returns:
+            List of matching Memory objects.
+        """
+        body: Dict[str, Any] = {"query": query, "limit": limit}
+        if type is not None:
+            body["type"] = type
+        if agent_id is not None:
+            body["agent_id"] = agent_id
+
+        resp = self._http.post(self._url("/v1/memories/search"), json=body)
+        self._check(resp)
+        data = resp.json()
+        results = data if isinstance(data, list) else data.get("results", [])
+        return [Memory.from_dict(m) for m in results]
+
+    def get(self, memory_id: str) -> Memory:
+        """Retrieve a single memory by ID.
+
+        Args:
+            memory_id: The memory's unique identifier.
+
+        Returns:
+            The Memory object.
+        """
+        resp = self._http.get(self._url(f"/v1/memories/{memory_id}"))
+        self._check(resp)
+        return Memory.from_dict(resp.json())
+
+    def usage(self) -> UsageStats:
+        """Get usage statistics.
+
+        Returns:
+            UsageStats with current counters.
+        """
+        resp = self._http.get(self._url("/v1/usage"))
+        self._check(resp)
+        return UsageStats.from_dict(resp.json())
+
+    @staticmethod
+    def _check(resp: httpx.Response) -> None:
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise AgentToolError(
+                f"Memory API error ({resp.status_code}): {detail}",
+                hint="Check your API key and request parameters.",
+            )

agenttool_sdk-0.1.0/src/agenttool/models.py

@@ -0,0 +1,103 @@
+"""Data models for the AgentTool SDK — plain dataclasses, no pydantic."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class Memory:
+    """A stored memory."""
+
+    id: str
+    content: str
+    type: str = "semantic"
+    agent_id: Optional[str] = None
+    key: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    importance: float = 0.5
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Memory:
+        return cls(
+            id=data.get("id", ""),
+            content=data.get("content", ""),
+            type=data.get("type", "semantic"),
+            agent_id=data.get("agent_id"),
+            key=data.get("key"),
+            metadata=data.get("metadata", {}),
+            importance=data.get("importance", 0.5),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+        )
+
+
+@dataclass
+class SearchResult:
+    """A web search result."""
+
+    title: str
+    url: str
+    snippet: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SearchResult:
+        return cls(
+            title=data.get("title", ""),
+            url=data.get("url", ""),
+            snippet=data.get("snippet", ""),
+        )
+
+
+@dataclass
+class ScrapeResult:
+    """Result of scraping a URL."""
+
+    url: str
+    content: str
+    status_code: int = 200
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ScrapeResult:
+        return cls(
+            url=data.get("url", ""),
+            content=data.get("content", ""),
+            status_code=data.get("status_code", 200),
+        )
+
+
+@dataclass
+class ExecuteResult:
+    """Result of sandboxed code execution."""
+
+    output: str
+    error: str = ""
+    exit_code: int = 0
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ExecuteResult:
+        return cls(
+            output=data.get("output", ""),
+            error=data.get("error", ""),
+            exit_code=data.get("exit_code", 0),
+        )
+
+
+@dataclass
+class UsageStats:
+    """API usage statistics."""
+
+    memories_stored: int = 0
+    searches_performed: int = 0
+    api_calls: int = 0
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> UsageStats:
+        return cls(
+            memories_stored=data.get("memories_stored", 0),
+            searches_performed=data.get("searches_performed", 0),
+            api_calls=data.get("api_calls", 0),
+        )

agenttool_sdk-0.1.0/src/agenttool/tools.py

@@ -0,0 +1,87 @@
+"""Tools client for agent-tools API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+import httpx
+
+from .exceptions import AgentToolError
+from .models import ExecuteResult, ScrapeResult, SearchResult
+
+
+class ToolsClient:
+    """Client for the agent-tools API.
+
+    Usage::
+
+        at = AgentTool()
+        results = at.tools.search("latest AI news")
+        page = at.tools.scrape("https://example.com")
+        out = at.tools.execute("print(1+1)")
+    """
+
+    def __init__(self, http: httpx.Client, base_url: str) -> None:
+        self._http = http
+        self._base = base_url.rstrip("/")
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}{path}"
+
+    def search(self, query: str, *, num_results: int = 5) -> List[SearchResult]:
+        """Web search.
+
+        Args:
+            query: Search query string.
+            num_results: Number of results to return.
+
+        Returns:
+            List of SearchResult objects.
+        """
+        body: Dict[str, Any] = {"query": query, "num_results": num_results}
+        resp = self._http.post(self._url("/v1/search"), json=body)
+        self._check(resp)
+        data = resp.json()
+        results = data if isinstance(data, list) else data.get("results", [])
+        return [SearchResult.from_dict(r) for r in results]
+
+    def scrape(self, url: str) -> ScrapeResult:
+        """Scrape a URL and return its content.
+
+        Args:
+            url: The URL to scrape.
+
+        Returns:
+            ScrapeResult with the page content.
+        """
+        body: Dict[str, Any] = {"url": url}
+        resp = self._http.post(self._url("/v1/scrape"), json=body)
+        self._check(resp)
+        return ScrapeResult.from_dict(resp.json())
+
+    def execute(self, code: str, *, language: str = "python") -> ExecuteResult:
+        """Execute code in a sandbox.
+
+        Args:
+            code: Source code to execute.
+            language: "python" or "javascript".
+
+        Returns:
+            ExecuteResult with output, error, and exit code.
+        """
+        body: Dict[str, Any] = {"code": code, "language": language}
+        resp = self._http.post(self._url("/v1/execute"), json=body)
+        self._check(resp)
+        return ExecuteResult.from_dict(resp.json())
+
+    @staticmethod
+    def _check(resp: httpx.Response) -> None:
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise AgentToolError(
+                f"Tools API error ({resp.status_code}): {detail}",
+                hint="Check your API key and request parameters.",
+            )

agenttool_sdk-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+# tests

agenttool_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,251 @@
+"""Unit tests for the AgentTool SDK — all HTTP mocked, no network needed."""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from agenttool import AgentTool, AgentToolError, Memory, SearchResult
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _mock_response(status_code: int = 200, json_data: object = None, text: str = "") -> MagicMock:
+    """Create a fake httpx.Response."""
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.json.return_value = json_data if json_data is not None else {}
+    resp.text = text or ""
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Client init
+# ---------------------------------------------------------------------------
+
+class TestClientInit:
+    def test_reads_env_var(self) -> None:
+        with patch.dict(os.environ, {"AT_API_KEY": "test-key-123"}):
+            at = AgentTool()
+            assert repr(at) == "AgentTool(base_url='https://api.agenttool.dev')"
+            at.close()
+
+    def test_explicit_key_overrides_env(self) -> None:
+        with patch.dict(os.environ, {"AT_API_KEY": "env-key"}):
+            at = AgentTool(api_key="explicit-key")
+            # Check the header was set with the explicit key
+            assert at._http.headers["authorization"] == "Bearer explicit-key"
+            at.close()
+
+    def test_missing_key_raises(self) -> None:
+        with patch.dict(os.environ, {}, clear=True):
+            # Also need to remove AT_API_KEY if it exists
+            env = os.environ.copy()
+            env.pop("AT_API_KEY", None)
+            with patch.dict(os.environ, env, clear=True):
+                with pytest.raises(AgentToolError) as exc_info:
+                    AgentTool()
+                assert "No API key" in exc_info.value.message
+                assert exc_info.value.hint is not None
+
+    def test_context_manager(self) -> None:
+        with patch.dict(os.environ, {"AT_API_KEY": "k"}):
+            with AgentTool() as at:
+                assert at is not None
+
+
+# ---------------------------------------------------------------------------
+# Memory
+# ---------------------------------------------------------------------------
+
+class TestMemory:
+    @pytest.fixture()
+    def at(self) -> AgentTool:
+        with patch.dict(os.environ, {"AT_API_KEY": "test-key"}):
+            client = AgentTool()
+        return client
+
+    def test_store_minimal(self, at: AgentTool) -> None:
+        """at.memory.store('just a string') must work."""
+        mock_resp = _mock_response(200, {
+            "id": "mem-1",
+            "content": "just a string",
+            "type": "semantic",
+            "importance": 0.5,
+        })
+        with patch.object(at._http, "post", return_value=mock_resp) as mock_post:
+            mem = at.memory.store("just a string")
+
+            assert isinstance(mem, Memory)
+            assert mem.id == "mem-1"
+            assert mem.content == "just a string"
+            # Verify the POST body
+            call_kwargs = mock_post.call_args
+            body = call_kwargs.kwargs.get("json") or call_kwargs[1].get("json")
+            assert body["content"] == "just a string"
+            assert body["type"] == "semantic"
+
+    def test_store_full(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "id": "mem-2",
+            "content": "hello",
+            "type": "episodic",
+            "agent_id": "agent-1",
+            "key": "greeting",
+            "metadata": {"source": "test"},
+            "importance": 0.9,
+        })
+        with patch.object(at._http, "post", return_value=mock_resp):
+            mem = at.memory.store(
+                "hello",
+                type="episodic",
+                agent_id="agent-1",
+                key="greeting",
+                metadata={"source": "test"},
+                importance=0.9,
+            )
+            assert mem.type == "episodic"
+            assert mem.agent_id == "agent-1"
+            assert mem.importance == 0.9
+
+    def test_search(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "results": [
+                {"id": "m1", "content": "hello world", "type": "semantic"},
+                {"id": "m2", "content": "goodbye", "type": "semantic"},
+            ]
+        })
+        with patch.object(at._http, "post", return_value=mock_resp):
+            results = at.memory.search("hello")
+            assert len(results) == 2
+            assert all(isinstance(r, Memory) for r in results)
+
+    def test_search_list_response(self, at: AgentTool) -> None:
+        """Handle APIs that return a raw list instead of {results: [...]}."""
+        mock_resp = _mock_response(200, [
+            {"id": "m1", "content": "item", "type": "semantic"},
+        ])
+        with patch.object(at._http, "post", return_value=mock_resp):
+            results = at.memory.search("item")
+            assert len(results) == 1
+
+    def test_get(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "id": "mem-42",
+            "content": "remembered",
+            "type": "procedural",
+        })
+        with patch.object(at._http, "get", return_value=mock_resp):
+            mem = at.memory.get("mem-42")
+            assert mem.id == "mem-42"
+            assert mem.content == "remembered"
+
+    def test_usage(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "memories_stored": 100,
+            "searches_performed": 50,
+            "api_calls": 200,
+        })
+        with patch.object(at._http, "get", return_value=mock_resp):
+            usage = at.memory.usage()
+            assert usage.memories_stored == 100
+            assert usage.api_calls == 200
+
+    def test_error_raises(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(401, {"detail": "Unauthorized"}, "Unauthorized")
+        with patch.object(at._http, "post", return_value=mock_resp):
+            with pytest.raises(AgentToolError) as exc_info:
+                at.memory.store("fail")
+            assert "401" in exc_info.value.message
+            assert exc_info.value.hint is not None
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+class TestTools:
+    @pytest.fixture()
+    def at(self) -> AgentTool:
+        with patch.dict(os.environ, {"AT_API_KEY": "test-key"}):
+            client = AgentTool()
+        return client
+
+    def test_search(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "results": [
+                {"title": "AI News", "url": "https://ai.com", "snippet": "Latest..."},
+            ]
+        })
+        with patch.object(at._http, "post", return_value=mock_resp) as mock_post:
+            results = at.tools.search("AI news", num_results=3)
+            assert len(results) == 1
+            assert isinstance(results[0], SearchResult)
+            assert results[0].title == "AI News"
+            body = mock_post.call_args.kwargs.get("json") or mock_post.call_args[1].get("json")
+            assert body["num_results"] == 3
+
+    def test_scrape(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "url": "https://example.com",
+            "content": "<h1>Hello</h1>",
+            "status_code": 200,
+        })
+        with patch.object(at._http, "post", return_value=mock_resp):
+            result = at.tools.scrape("https://example.com")
+            assert result.url == "https://example.com"
+            assert "<h1>" in result.content
+
+    def test_execute_python(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "output": "42\n",
+            "error": "",
+            "exit_code": 0,
+        })
+        with patch.object(at._http, "post", return_value=mock_resp) as mock_post:
+            result = at.tools.execute("print(42)")
+            assert result.output == "42\n"
+            assert result.exit_code == 0
+            body = mock_post.call_args.kwargs.get("json") or mock_post.call_args[1].get("json")
+            assert body["language"] == "python"
+
+    def test_execute_javascript(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(200, {
+            "output": "hello\n",
+            "error": "",
+            "exit_code": 0,
+        })
+        with patch.object(at._http, "post", return_value=mock_resp) as mock_post:
+            result = at.tools.execute("console.log('hello')", language="javascript")
+            assert result.output == "hello\n"
+            body = mock_post.call_args.kwargs.get("json") or mock_post.call_args[1].get("json")
+            assert body["language"] == "javascript"
+
+    def test_error_raises(self, at: AgentTool) -> None:
+        mock_resp = _mock_response(500, {"detail": "Internal error"}, "Internal error")
+        with patch.object(at._http, "post", return_value=mock_resp):
+            with pytest.raises(AgentToolError) as exc_info:
+                at.tools.search("fail")
+            assert "500" in exc_info.value.message
+
+
+# ---------------------------------------------------------------------------
+# AgentToolError
+# ---------------------------------------------------------------------------
+
+class TestAgentToolError:
+    def test_message_and_hint(self) -> None:
+        err = AgentToolError("something broke", hint="try again")
+        assert err.message == "something broke"
+        assert err.hint == "try again"
+        assert "hint: try again" in str(err)
+
+    def test_no_hint(self) -> None:
+        err = AgentToolError("oops")
+        assert err.hint is None
+        assert str(err) == "oops"