Metadata-Version: 2.5
Name: crewai-piloterr
Version: 0.1.0
Summary: CrewAI tools for Piloterr: Google search and website scraping with JavaScript rendering and unblocking.
Project-URL: Homepage, https://www.piloterr.com
Project-URL: Documentation, https://github.com/piloterr/crewai-piloterr#readme
Project-URL: Repository, https://github.com/piloterr/crewai-piloterr
Project-URL: Issues, https://github.com/piloterr/crewai-piloterr/issues
Author-email: Piloterr <contact@piloterr.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,crewai,piloterr,tools,web-search
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.10
Requires-Dist: crewai>=0.150
Requires-Dist: httpx<1,>=0.27
Provides-Extra: test
Requires-Dist: pytest>=8.3; extra == 'test'
Requires-Dist: ruff<1,>=0.8; extra == 'test'
Description-Content-Type: text/markdown

# crewai-piloterr

[CrewAI](https://www.crewai.com) tools for [Piloterr](https://www.piloterr.com), a web data API.

- `PiloterrGoogleSearchTool` searches Google.
- `PiloterrScrapeWebsiteTool` reads a web page and returns its title and readable text. Piloterr fetches the page on its own infrastructure, in one of three ways:
  - `crawler`: plain HTTP, the default;
  - `rendering`: a headless browser, for JavaScript pages;
  - `webunlocker`: for pages behind anti-bot protection.

## Installation

```bash
pip install crewai-piloterr
```

Get an API key at [app.piloterr.com](https://app.piloterr.com) and set it in the environment:

```bash
export PILOTERR_API_KEY="your-api-key"
```

## Usage

```python
from crewai import Agent, Crew, Task
from crewai_piloterr import PiloterrGoogleSearchTool, PiloterrScrapeWebsiteTool

researcher = Agent(
    role="Researcher",
    goal="Find and read sources on the web",
    backstory="You search, then read the best pages before answering.",
    tools=[PiloterrGoogleSearchTool(n_results=5), PiloterrScrapeWebsiteTool(engine="rendering")],
)
task = Task(description="Summarize what piloterr.com offers.", expected_output="A short summary", agent=researcher)
Crew(agents=[researcher], tasks=[task]).kickoff()
```

### PiloterrGoogleSearchTool

Returns a JSON list of results with `title`, `link`, `snippet` and `position`.

| Option | Default | Description |
| --- | --- | --- |
| `n_results` | `10` | Results requested, 1 to 100 |
| `country` | | Two-letter country code, such as `us` |
| `language` | | Language code, optionally with a region, such as `en-gb` |
| `location` | | City or region to search from |

### PiloterrScrapeWebsiteTool

Returns the page title as a heading, followed by the readable text. Scripts and styles are removed.

| Option | Default | Description |
| --- | --- | --- |
| `engine` | `crawler` | `crawler`, `rendering` or `webunlocker` |
| `wait_in_seconds` | | Rendering only: extra wait after the page loads, 0 to 30 |
| `max_characters` | `20000` | Truncate the text; `None` keeps it all |
| `timeout` | `120` | Seconds to wait for Piloterr |

Both tools take `api_key` (default `PILOTERR_API_KEY`). They return API errors to the agent as text, and the key never appears in them.

## Development

```bash
pip install -e ".[test]"
pytest
```

## License

MIT
