hollow-sdk 0.1.0

Python SDK for Hollow — serverless web perception for AI agents

hollow-sdk (Python)

Python SDK for Hollow — serverless web perception for AI agents.

Gives any Python application a browser that runs without a machine: no Chromium, no BaaS, no GPU.

Install

pip install hollow-sdk

Usage

Single page

from hollow import HollowClient

client = HollowClient()
page = client.perceive("https://news.ycombinator.com")

print(page.gdg_map)
# → [TEXT: news.ycombinator.com]
#   [Stories:]
#     [1] "Ask HN: Who is hiring? (March 2026)"  comments:834
#     ...

print(page.tier)        # 'text'
print(page.confidence)  # 0.95

Agent task

from hollow import HollowClient, run_agent

client = HollowClient()

result = run_agent(
    client,
    task="What are the top 3 stories on Hacker News right now?",
    on_step=lambda s: print(f"Step {s.step}: {s.tier} ({s.confidence:.2f})"),
)

print(result)

Requires ANTHROPIC_API_KEY in your environment.

Custom endpoint

client = HollowClient(endpoint="https://my-hollow-instance.vercel.app")
# or: export HOLLOW_ENDPOINT=https://my-hollow-instance.vercel.app

Context manager

with HollowClient() as client:
    page = client.perceive("https://example.com")
    print(page.gdg_map)
# httpx client is closed automatically

API

HollowClient(endpoint?)

Param	Default
endpoint	https://hollow-tan-omega.vercel.app

Also reads HOLLOW_ENDPOINT from the environment.

client.perceive(url, session_id?, state_id?) → PerceiveResult

Load a URL. Returns a PerceiveResult.

client.act(session_id, action, intervention?) → PerceiveResult

Interact with the current page.

from hollow.types import Action

client.act(page.session_id, Action(type="click", element_id=3))
client.act(page.session_id, Action(type="fill", element_id=4, value="query"))
client.act(page.session_id, Action(type="scroll", direction="down"))

client.get_session(session_id) → dict

Get current session state without acting.

client.close_session(session_id) → None

Free a session's Redis state. Idempotent.

run_agent(client, task, *, max_steps?, start_url?, model?, on_step?) → str

Param	Default
max_steps	15
start_url	https://www.startpage.com
model	claude-sonnet-4-20250514
on_step	None

Types

from hollow.types import Action, PerceiveResult, AgentStep

# PerceiveResult
page.session_id   # str
page.gdg_map      # str — the spatial map
page.confidence   # float 0.0–1.0
page.tier         # 'hollow'|'vdom'|'text'|'cache'|'mobile'|'partial'
page.js_errors    # list[str]

# AgentStep (from on_step callback)
step.step         # int
step.gdg_map      # str
step.action       # Action | None
step.confidence   # float
step.tier         # Tier

Deploy your own Hollow

This SDK points at the public demo by default (10 req/min rate limit per IP). For production use, deploy your own instance:

git clone https://github.com/Badgerion/hollow
cd hollow && npm install && vercel deploy

License

Apache 2.0