Metadata-Version: 2.4
Name: agenttool-sdk
Version: 0.5.1
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-sdk · Python

> Persistent memory, reasoning traces, fact verification, tool access, and agent-to-agent payments — one API key.

[![PyPI](https://img.shields.io/pypi/v/agenttool-sdk)](https://pypi.org/project/agenttool-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/agenttool-sdk)](https://pypi.org/project/agenttool-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![API Status](https://img.shields.io/badge/API-live-brightgreen)](https://api.agenttool.dev/health)

```bash
pip install agenttool-sdk
```

## What is this?

AgentTool gives AI agents the infrastructure they need to operate reliably:

| Service | What it does |
|---------|-------------|
| **agent-memory** | Persistent semantic memory — store facts, retrieve by similarity |
| **agent-tools** | Web search, page scraping, sandboxed code execution |
| **agent-verify** | Fact-check claims with AI-powered evidence gathering |
| **agent-economy** | Wallets, spending policies, escrow, agent-to-agent payments |
| **agent-trace** | Reasoning provenance — log and search decision traces |

All five services, one API key, one SDK.

## Quick start (60 seconds)

**1. Get your API key** — create a free project at [app.agenttool.dev](https://app.agenttool.dev)

**2. Set your key:**
```bash
export AT_API_KEY=at_your_key_here
```

**3. Store and retrieve a memory:**
```python
from agenttool import AgentTool

at = AgentTool()  # reads AT_API_KEY from env

# Store a memory
memory = at.memory.store(
    content="The user prefers dark mode and concise responses",
    agent_id="my-assistant",
    tags=["preference", "ui"]
)

# Retrieve it later (semantic search)
results = at.memory.search("what does the user prefer?", limit=5)
for r in results:
    print(f"{r.score:.2f}  {r.content}")
```

## Usage

### Memory

```python
at = AgentTool(api_key="at_...")  # or use AT_API_KEY env var

# Store
mem = at.memory.store("User is based in London, timezone Europe/London")

# Semantic search
results = at.memory.search("where is the user?", limit=5)
for r in results:
    print(f"{r.score:.2f}  {r.content}")

# Retrieve by ID
mem = at.memory.get(memory_id="mem_abc123")

# Usage stats
stats = at.memory.usage()
print(stats.memories_stored, stats.searches_performed)
```

### Tools

```python
# Web search
results = at.tools.search("latest papers on RAG", num_results=5)
for r in results:
    print(r.title, r.url, r.snippet)

# Scrape a page
page = at.tools.scrape("https://example.com")
print(page.content)   # HTML/text content
print(page.status_code)

# Execute code (sandboxed — Python, JavaScript, Bash)
result = at.tools.execute("import math; print(math.pi)", language="python")
print(result.output)      # stdout
print(result.error)       # stderr
print(result.exit_code)   # 0 = success
```

### Verify

```python
# Fact-check a claim with AI-powered evidence gathering
result = at.verify.check("The Eiffel Tower is 330 metres tall.")
print(result.verdict)      # "verified" | "false" | "disputed" | "unverifiable"
print(result.confidence)   # 0.0 – 1.0
print(result.caveats)      # list of nuances

# With domain hint for better evidence
result = at.verify.check(
    "Bitcoin was created in 2009.",
    domain="finance",           # "finance" | "science" | "medical" | "legal" | "general"
    context="On the Bitcoin whitepaper date"
)
print(result.is_verified)  # True / False

# Batch verify (up to 10 claims in parallel)
results = at.verify.batch([
    {"claim": "Water boils at 100°C at sea level."},
    {"claim": "The moon is made of cheese.", "domain": "science"},
])
for r in results:
    print(r.verdict, r.confidence)
```

### Economy (wallets & escrows)

```python
# Create a wallet for an agent
wallet = at.economy.create_wallet("agent-wallet", agent_id="agent-42")

# Fund it from your project's credit balance
at.economy.fund_wallet(wallet.id, amount=500, description="Weekly budget")

# Spend credits (subject to spending policy)
at.economy.spend(
    wallet.id,
    amount=10,
    counterparty="wal_target_id",
    description="Payment for research task"
)

# Set a spending policy (keep agents within bounds)
at.economy.set_policy(wallet.id,
    max_per_transaction=50,
    max_per_hour=200,
    max_per_day=1000,
)

# Escrow: lock credits until work is done
escrow = at.economy.create_escrow(
    creator_wallet_id=wallet.id,
    amount=100,
    description="Summarise 50 research papers",
    deadline="2026-03-14T12:00:00Z",
)
# Worker accepts:
at.economy.accept_escrow(escrow.id, worker_wallet_id="wal_worker")
# Release on completion:
at.economy.release_escrow(escrow.id)
```

### Traces (reasoning provenance)

```python
# Store a reasoning trace
trace = at.traces.store(
    observations=[
        "User asked about climate solutions",
        "Searched web: found 3 relevant papers",
        "Papers focus on renewable energy + carbon capture",
    ],
    conclusion="Renewable energy is the most actionable near-term solution",
    decision_type="decision",       # decision | tool_call | plan | verification | other
    confidence=0.87,
    tags=["climate", "research"],
    agent_id="research-agent",
)
print(trace.trace_id)  # "tr_a1b2c3d4e5f6"

# Retrieve by trace_id
trace = at.traces.get(trace.trace_id)

# Semantic search across traces
results = at.traces.search("decisions about climate data", limit=5)

# Get a chain of reasoning steps
chain = at.traces.chain(trace.trace_id)

# Delete
at.traces.delete(trace.trace_id)
```

## Integration example — LangChain

```python
from langchain.tools import tool
from agenttool import AgentTool

at = AgentTool()

@tool
def remember(content: str) -> str:
    """Store a memory for later retrieval."""
    mem = at.memory.store(content, agent_id="langchain-agent")
    return f"Stored memory {mem.id}"

@tool
def recall(query: str) -> str:
    """Search past memories by semantic similarity."""
    results = at.memory.search(query, limit=3)
    return "\n".join(r.content for r in results)

@tool
def fact_check(claim: str) -> str:
    """Verify whether a factual claim is true."""
    result = at.verify.check(claim)
    return f"{result.verdict} (confidence: {result.confidence:.0%})"
```

## Integration example — agent loop with memory

```python
from agenttool import AgentTool

at = AgentTool()

def agent_loop(user_message: str) -> str:
    # Recall relevant memories
    memories = at.memory.search(user_message, limit=5)
    context = "\n".join(m.content for m in memories)

    # Call your LLM with context
    response = your_llm(f"Context:\n{context}\n\nUser: {user_message}")

    # Store the exchange
    at.memory.store(f"User: {user_message}\nAgent: {response}")

    return response
```

## Free tier

| Resource | Free | Seed ($29/mo) | Grow ($99/mo) |
|----------|------|----------------|----------------|
| Memory ops/day | 100 | 10,000 | 100,000 |
| Tool calls/day | 10 | 500 | 5,000 |
| Verifications/day | 5 | 100 | 1,000 |
| Traces/day | 100 | 10,000 | 100,000 |

[Upgrade at app.agenttool.dev/billing](https://app.agenttool.dev/billing)

## Configuration

```python
from agenttool import AgentTool

at = AgentTool(
    api_key="at_...",          # default: AT_API_KEY env var
    base_url="https://api.agenttool.dev",  # default
    timeout=30.0,              # seconds
)
```

## Links

- 🏠 [agenttool.dev](https://agenttool.dev)
- 📖 [docs.agenttool.dev](https://docs.agenttool.dev)
- 🎛️ [app.agenttool.dev](https://app.agenttool.dev) — dashboard + API key
- 📦 [PyPI](https://pypi.org/project/agenttool-sdk/)
- 🟦 [TypeScript SDK](https://github.com/mynameisyou-cmyk/agenttool-sdk-ts)

## License

MIT
