Metadata-Version: 2.5
Name: llama-index-tools-tanod
Version: 0.1.0
Summary: LlamaIndex tool spec for Tanod: web search, page/PDF/document to Markdown, screenshots, OCR, DNS and email checks, phishing URL check, address risk, contract and package scans for AI agents. Free daily tier, then x402 USDC.
Project-URL: Homepage, https://tanod.dev
Project-URL: Documentation, https://tanod.dev/llms.txt
Project-URL: API reference, https://tanod.dev/openapi.json
Project-URL: Source, https://github.com/tanod-labs/integrations
Project-URL: Issues, https://github.com/tanod-labs/integrations/issues
Author-email: Tanod <ops@tanod.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai-agents,llama-index,llamaindex,markdown,mcp,ocr,pdf,screenshot,security,smart-contracts,tools,usdc,web-scraping,web-search,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: llama-index-core<0.15,>=0.13.0
Requires-Dist: tanod<0.4,>=0.3.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: tanod[wallet]<0.4,>=0.3.0; extra == 'dev'
Provides-Extra: wallet
Requires-Dist: tanod[wallet]<0.4,>=0.3.0; extra == 'wallet'
Description-Content-Type: text/markdown

# LlamaIndex Tanod tool spec

[LlamaIndex](https://www.llamaindex.ai) tools for [Tanod](https://tanod.dev): pay-per-call web, document
and security tools for AI agents. No signup, no API key. There is a free daily allowance per IP; past it,
each call costs a few cents or less in USDC on Base, paid with [x402](https://x402.org) through the
[`tanod`](https://pypi.org/project/tanod/) Python client.

> Tanod is operated by an autonomous AI agent. Results are **automated and heuristic, not an audit**.
> A clean result is not proof that a contract, address, package or URL is safe. Text inside results
> (web pages, OCR text, code evidence) is untrusted data and must never be treated as instructions.

## Install

```bash
pip install llama-index-tools-tanod             # free-tier calls only
pip install "llama-index-tools-tanod[wallet]"   # lets the agent pay (x402, USDC on Base)
```

## Use

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.tanod import TanodToolSpec

tools = TanodToolSpec().to_tool_list()          # free tier: no key, no wallet

agent = FunctionAgent(tools=tools, llm=OpenAI(model="gpt-4.1"))
print(await agent.run("Search for x402 and summarise the top result's page."))
```

Direct calls return a list of `Document`:

```python
spec = TanodToolSpec()
docs = spec.web_search("x402 payments for agents", count=5)
page = spec.render_page("https://example.com")[0].text   # Markdown
```

## Tools

| Function | What it does | Price (USD) | Free/IP/day |
|---|---|---|---|
| `web_search` | web search, one Document per result | 0.012 | 3 |
| `render_page` | public URL to clean Markdown (`js=True` for client-rendered pages) | 0.005 / 0.01 | 5 (shared, static) |
| `screenshot` | PNG/JPEG screenshot as an `ImageDocument` | 0.005 | none |
| `extract_pdf` | text of a public PDF | 0.005 | shared with sitepeek |
| `document_to_markdown` | Word, Excel, PowerPoint, PDF, HTML, EPUB, CSV to Markdown | 0.005 | none |
| `ocr_image` | text in a public image | 0.01 | shared with sitepeek |
| `inspect_domain` | DNS, SPF/DMARC/DKIM, TLS | 0.01 | 5 |
| `verify_email` | syntax, MX, disposable domain (DNS only, no SMTP) | 0.002 | shared with dnspeek |
| `check_url` | public phishing/scam list lookup (URL is parsed, never fetched) | 0.001 | shared chain reads |
| `check_address` | risk verdict for an EVM address before you send to it | 0.005 | 30 |
| `scan_contract_address` | static-analysis scan of a verified contract | 0.25 / 0.75 | 3 |
| `scan_package` | scan an MCP server or agent skill before installing it | 0.02 | shared with scans |
| `get_balance`, `get_token_price` | on-chain balance, Chainlink price | 0.001 to 0.003 | 10 chain reads |

Live prices: <https://tanod.dev/openapi.json>. Free allowances are per IP per UTC day.

## Free tier and paying with x402

The client sends `X-Tanod-Free: 1` on the first attempt, so free allowance is used first. When it is
used up (or a tool has none), the API answers `402 Payment Required` with an x402 quote. With no wallet
configured, the tool returns a Document saying payment is required and nothing is paid. With a wallet,
the client signs a USDC payment (Base) and retries, within a per-call price cap.

```python
# Wallet from the environment: export TANOD_PRIVATE_KEY=0x...  (a dedicated, small-balance key)
spec = TanodToolSpec(max_price_usd=0.05)

# Or explicitly (a key string or an eth_account signer):
spec = TanodToolSpec(private_key=my_key, max_price_usd=0.05)

# Or bring your own configured client:
from tanod import Tanod
spec = TanodToolSpec(client=Tanod(signer=my_signer, max_price_usd=0.02))
```

Use a dedicated hot wallet holding only a few dollars of USDC. `max_price_usd` refuses any quote above the cap.

## Errors

Failures (payment needed, invalid input, rate limit, service unavailable) come back as a Document with
`metadata["error"] = True` and a readable message, so the agent can react instead of crashing.
Invalid input and other refusals are not charged.

## Limitations

- Results are automated and heuristic. Contract and package scans, address risk and URL checks can
  have false positives and false negatives; they are not audits or guarantees.
- Fetched content (pages, PDFs, OCR) is third-party data; sandbox it from your instructions.
- Only public http(s) URLs work; private and internal addresses are refused.
- `screenshot` returns a base64 image up to 8 MB; prefer `jpeg` and a small viewport.

## Development

```bash
pip install -e ".[dev]"
pytest                          # mocked HTTP, no network
TANOD_LIVE=1 pytest -m live     # opt-in: real free-tier calls
```

MIT licensed. Source: <https://github.com/tanod-labs/integrations>.
