Metadata-Version: 2.4
Name: b4n1-web
Version: 0.1.1
Summary: Python SDK for B4n1Web Agentic Browser Engine - Requires explicit binary installation
Author-email: Bani Montoya <banimontoya@gmail.com>
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/B4N1-com/b4n1-web
Project-URL: Repository, https://github.com/B4N1-com/b4n1-web
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# B4n1Web Python SDK

Python bindings for B4n1Web: The Agentic Browser Engine.

## Installation

### 1. Install the B4n1Web Binary

```bash
curl -sL https://b4n1-web.b4n1.com/install | bash
```

### 2. Install the Python SDK

```bash
pip install b4n1-web
```

On Ubuntu 23.04+ or other externally-managed environments, use a virtual environment:

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install b4n1-web
```

Or with pipx:

```bash
pipx install b4n1-web
```

## Quick Start

```python
from b4n1web import BrowserMode, AgentBrowser

# Create a browser instance
browser = AgentBrowser(mode=BrowserMode.LIGHT)

# Navigate to a page
page = browser.goto("https://example.com")

# Access structured data
print("Page content:")
print(page.markdown)

print(f"Found {len(page.links)} links")
print("First 5 links:", page.links[:5])

# Extract main content
main_content = page.get_main_content()
print("Main content preview:", main_content[:200] + "...")

# Find specific links
github_links = page.find_links_by_text("github")
print("GitHub links:", github_links)

# Close browser when done
browser.close()
```

## Browser Modes

### Light Mode (Default)

- **Use case**: Reading articles, scraping static content, extracting links
- **Performance**: < 15MB RAM, instant startup
- **Capabilities**: HTML parsing, markdown conversion, link extraction
- **Limitations**: No JavaScript execution

```python
browser = AgentBrowser(mode=BrowserMode.LIGHT)
```

### Render Mode

- **Use case**: SPAs, form filling, visual verification
- **Performance**: Higher memory usage, slower startup
- **Capabilities**: Full JavaScript execution, screenshots, interaction

```python
browser = AgentBrowser(mode=BrowserMode.RENDER)
```

## API Reference

### AgentBrowser

Main browser class for web automation.

#### Methods

- `goto(url: str) -> Page`: Navigate to URL and return structured page data
- `close()`: Close the browser session

#### Parameters

- `mode`: BrowserMode.LIGHT or BrowserMode.RENDER
- `timeout`: Request timeout in seconds (default: 30)
- `user_agent`: Custom user agent string

### Page

Structured data from a web page.

#### Attributes

- `url: str`: The page URL
- `markdown: str`: Clean markdown content
- `links: List[str]`: Extracted links
- `screenshot: Optional[str]`: Base64-encoded screenshot (render mode only)

#### Methods

- `get_main_content() -> str`: Extract main content, skipping headers/footers
- `find_links_by_text(text: str) -> List[str]`: Find links containing specific text

## Context Manager

Use the browser as a context manager for automatic cleanup:

```python
from b4n1web import BrowserMode, AgentBrowser

with AgentBrowser(mode=BrowserMode.LIGHT) as browser:
    page = browser.goto("https://example.com")
    print(page.markdown)
# Browser automatically closed
```

## Security

- All HTTP requests use TLS
- No arbitrary code execution
- Input validation and sanitization
- **Explicit Installation**: Binary must be installed separately via `curl -sL https://b4n1-web.b4n1.com/install | bash` — no automatic downloads

## License

MIT OR Apache-2.0
