Metadata-Version: 2.4
Name: webspeed
Version: 0.1.0
Summary: Python SDK for the Web Speed API — machine-readable maps of any web page for AI agents.
Project-URL: Homepage, https://getwebspeed.io
Project-URL: Documentation, https://api.getwebspeed.io/docs
License: MIT
Keywords: agents,ai,automation,browser,llm,mcp,scraping,web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Description-Content-Type: text/markdown

# Web Speed — Python SDK

The machine-readable layer for the web. Give your AI agent a clean, structured
**map** of any page — what it is, what's on it, and what it can *do* (search,
add-to-cart, log in, paginate) — instead of dumping raw HTML or screenshots.

```bash
pip install webspeed
```

## Quickstart

```python
from webspeed import WebSpeed

ws = WebSpeed(api_key="wsp_...")          # or set the WEBSPEED_API_KEY env var

page = ws.map("https://example.com/product")
print(page["page_type"])                   # e.g. "product"
for action in page.get("actions", []):     # what the agent can do here
    print(action["intent"], action["selector"])   # e.g. "add_to_cart" "#add-btn"
```

That's the whole integration. Get a key at **https://getwebspeed.io**.

## What you can call

```python
ws.map(url, js=None, fresh=False, max_age=None)   # structured map of a page
ws.site_map(root_url, max_pages=25)               # crawl + combined map
ws.extract(html, base_url="")                     # map raw HTML you already have
ws.click(url, selector)                           # click, return the resulting map
ws.fill_and_submit(url, fields, submit_selector=None)
ws.submit_form(url, method="GET", fields={...})
ws.evaluate(url, js)                              # run JS, return the result
ws.inspect(url, selector)                         # structured data for a selector
ws.usage()                                        # credit balance + lifetime usage
```

`js=None` lets your account default decide; pass `js=True` for SPA/React sites.

## Errors are typed

```python
from webspeed import (
    WebSpeedError, AuthError, PaymentRequiredError, RateLimitError,
    FetchError, NetworkError,
)

try:
    page = ws.map("https://example.com")
except PaymentRequiredError as e:
    print("Out of credits / over plan limit:", e.code)   # e.g. "out_of_credits"
except FetchError as e:
    print("The target page couldn't be mapped (you're not charged):", e.code)
except WebSpeedError as e:
    print("API error:", e.status, e.message)
```

Transient errors (429 / 5xx / network) are retried automatically with backoff.

## Use it as an agent tool

**OpenAI / Anthropic function-calling:**

```python
from webspeed import WebSpeed, tools

ws = WebSpeed()
resp = openai_client.chat.completions.create(
    model="gpt-4o", messages=[...], tools=tools.openai_tools(),
)
# when the model calls a tool:
result = tools.call_tool(ws, tool_call.function.name,
                         json.loads(tool_call.function.arguments))
```

**LangChain:**

```python
from webspeed import WebSpeed, tools
agent_tool = tools.make_langchain_tool(WebSpeed())   # pip install 'webspeed[langchain]'
```

## Notes
- Auth is sent as a header (`X-Web-Speed-Key`) — your key never appears in a URL.
- Works with any MCP-less stack. (For MCP-native hosts like Claude/Cursor, add the
  Web Speed MCP server instead — same engine, zero code.)

Docs: https://api.getwebspeed.io/docs
