Metadata-Version: 2.4
Name: nomad-sdk
Version: 0.1.0
Summary: Nomad headless browser engine — Python SDK
License: AGPL-3.0-only
Keywords: nomad,headless,browser,automation,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: requires-python

# Nomad SDK — Python

**Nomad** is a zero-overhead headless browser engine. 5 MB binary, 6 MB RSS,
550 req/s. This package connects to a running Nomad daemon over a Unix Domain
Socket.

```bash
pip install nomad-sdk
```

## Quickstart

Make sure the Nomad daemon is running:

```bash
MALLOC_ARENA_MAX=1 nomad-daemon &
```

Then scrape a page in 2 lines:

```python
from nomad_sdk import NomadClient

with NomadClient() as client:
    page = client.navigate("https://news.ycombinator.com")
    print(f"Title: {page.title}")
    print(f"Links: {len(page.find_all(tag='a'))}")
```

## API

### `NomadClient(socket_path="/tmp/nomad-daemon.sock")`

| Method | Description |
|--------|-------------|
| `navigate(url, fmt=3)` | Fetch and parse a page |
| `snapshot(tab_id)` | Get current page state without re-fetching |
| `click(entity_id)` | Click an element by entity ID |
| `input_text(entity_id, value)` | Type text into an input field |
| `find(query)` | Find elements by role, tag, intent, text |
| `evaluate(js)` | Execute arbitrary JavaScript |
| `scroll(dx, dy)` | Scroll the viewport |
| `resize(w, h)` | Resize the viewport |
| `health()` | Daemon health info |
| `get_action_log(tab_id)` | Tab action history |

### Output formats (`fmt`)

| ID | Name | Use |
|----|------|-----|
| 0 | RawBincode | Machine IPC |
| 1 | JSON | Debug |
| 2 | Markdown | Human read |
| 3 | AgentJson | LLM (full entities) |
| 4 | Summary | LLM (~150 bytes) |
| 5 | TokenMinimal | LLM (shortest) |
| 6--10 | Section/Accessibility/Reader/Form | Specialized |

### `Page` methods

```python
page.find_one(role="button", text="Sign In")  # first match
page.find_all(tag="a", intent="navigation")    # all matches
```

## Example — Click a button

```python
from nomad_sdk import NomadClient

with NomadClient() as client:
    page = client.navigate("https://example.com/login")
    btn = page.find_one(role="button", text="Submit")
    if btn:
        client.click(btn.id)
```

## Requirements

- Python ≥ 3.10
- Nomad daemon running (UDS socket at `/tmp/nomad-daemon.sock`)
