Metadata-Version: 2.4
Name: quercle-crewai
Version: 1.0.0
Summary: CrewAI tools for Quercle web search and URL fetching
Project-URL: Homepage, https://github.com/quercledev/quercle-crewai
Project-URL: Documentation, https://quercle.dev/docs
Project-URL: Repository, https://github.com/quercledev/quercle-crewai
Author-email: Quercle <support@quercle.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,crewai,llm,quercle,tools,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: crewai>=0.100.0
Requires-Dist: pydantic>=2.0
Requires-Dist: quercle>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Description-Content-Type: text/markdown

# quercle-crewai

Quercle web search and fetch tools for [CrewAI](https://docs.crewai.com/).

## Installation

```bash
uv add quercle-crewai
# or
pip install quercle-crewai
```

## Setup

Set your API key as an environment variable:

```bash
export QUERCLE_API_KEY=qk_...
```

Get your API key at [quercle.dev](https://quercle.dev).

## Quick Start

```python
from crewai import Agent, Task, Crew
from quercle_crewai import QuercleSearchTool, QuercleFetchTool

researcher = Agent(
    role="Research Analyst",
    goal="Find and analyze the latest information",
    backstory="You are an expert research analyst.",
    tools=[QuercleSearchTool(), QuercleFetchTool()],
)

task = Task(
    description="Research the latest developments in AI agents",
    expected_output="A summary of key developments",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
print(result)
```

## Tools

| Tool | Description |
|---|---|
| `QuercleSearchTool` | AI-synthesized web search with citations |
| `QuercleFetchTool` | Fetch a URL and analyze its content with AI |
| `QuercleRawSearchTool` | Raw web search results without AI synthesis |
| `QuercleRawFetchTool` | Raw URL content (markdown/HTML) without AI processing |
| `QuercleExtractTool` | Extract content chunks relevant to a query from a URL |

## Direct Tool Usage

### Sync

```python
from quercle_crewai import (
    QuercleSearchTool,
    QuercleFetchTool,
    QuercleRawSearchTool,
    QuercleRawFetchTool,
    QuercleExtractTool,
)

# AI-synthesized search
search = QuercleSearchTool()
result = search._run(query="best practices for building AI agents")
print(result)

# Search with domain filtering
result = search._run(
    query="Python documentation",
    allowed_domains=["docs.python.org"],
)

# Fetch and analyze a page with AI
fetch = QuercleFetchTool()
result = fetch._run(
    url="https://en.wikipedia.org/wiki/Python_(programming_language)",
    prompt="Summarize the key features of Python",
)
print(result)

# Raw search results (no AI synthesis)
raw_search = QuercleRawSearchTool()
result = raw_search._run(query="Python web frameworks", format="markdown")
print(result)

# Raw URL content (no AI processing)
raw_fetch = QuercleRawFetchTool()
result = raw_fetch._run(url="https://example.com", format="markdown")
print(result)

# Extract relevant content from a URL
extract = QuercleExtractTool()
result = extract._run(
    url="https://example.com/pricing",
    query="pricing details",
    format="markdown",
)
print(result)
```

### Async

```python
import asyncio
from quercle_crewai import (
    QuercleSearchTool,
    QuercleFetchTool,
    QuercleRawSearchTool,
    QuercleRawFetchTool,
    QuercleExtractTool,
)

async def main():
    # AI-synthesized search
    search = QuercleSearchTool()
    result = await search._arun(query="latest AI agent frameworks")
    print(result)

    # Fetch and analyze with AI
    fetch = QuercleFetchTool()
    result = await fetch._arun(
        url="https://en.wikipedia.org/wiki/TypeScript",
        prompt="What is TypeScript?",
    )
    print(result)

    # Raw search results
    raw_search = QuercleRawSearchTool()
    result = await raw_search._arun(query="Python web frameworks")
    print(result)

    # Raw URL content
    raw_fetch = QuercleRawFetchTool()
    result = await raw_fetch._arun(url="https://example.com")
    print(result)

    # Extract relevant content
    extract = QuercleExtractTool()
    result = await extract._arun(
        url="https://example.com/docs",
        query="authentication setup",
    )
    print(result)

asyncio.run(main())
```

### Custom API Key

```python
search = QuercleSearchTool(api_key="qk_...")
fetch = QuercleFetchTool(api_key="qk_...")
raw_search = QuercleRawSearchTool(api_key="qk_...")
raw_fetch = QuercleRawFetchTool(api_key="qk_...")
extract = QuercleExtractTool(api_key="qk_...")
```

## Agentic Usage

### Multi-Agent Crew

```python
from crewai import Agent, Task, Crew
from quercle_crewai import (
    QuercleSearchTool,
    QuercleFetchTool,
    QuercleRawSearchTool,
    QuercleRawFetchTool,
    QuercleExtractTool,
)

search = QuercleSearchTool()
fetch = QuercleFetchTool()
raw_search = QuercleRawSearchTool()
raw_fetch = QuercleRawFetchTool()
extract = QuercleExtractTool()

researcher = Agent(
    role="Web Researcher",
    goal="Find the most relevant and up-to-date information on {topic}",
    backstory="You are a skilled web researcher who finds authoritative sources.",
    tools=[search, fetch, raw_search, raw_fetch, extract],
)

writer = Agent(
    role="Content Writer",
    goal="Write a clear, concise summary of the research on {topic}",
    backstory="You are a technical writer who distills complex topics into readable summaries.",
)

research_task = Task(
    description="Search the web for the latest information about {topic}. "
    "Find the most relevant pages and analyze their content.",
    expected_output="Detailed research findings with sources",
    agent=researcher,
)

writing_task = Task(
    description="Based on the research, write a concise summary about {topic}.",
    expected_output="A well-structured summary in 3-5 paragraphs",
    agent=writer,
    context=[research_task],
)

crew = Crew(agents=[researcher, writer], tasks=[research_task, writing_task])
result = crew.kickoff(inputs={"topic": "WebAssembly in 2025"})
print(result)
```

## API Reference

| Tool | Parameters |
|---|---|
| `QuercleSearchTool` | `query`, `allowed_domains?`, `blocked_domains?` |
| `QuercleFetchTool` | `url`, `prompt` |
| `QuercleRawSearchTool` | `query`, `format?`, `use_safeguard?` |
| `QuercleRawFetchTool` | `url`, `format?`, `use_safeguard?` |
| `QuercleExtractTool` | `url`, `query`, `format?`, `use_safeguard?` |

## Configuration

| Parameter | Default | Description |
|---|---|---|
| `api_key` | `QUERCLE_API_KEY` env var | Your Quercle API key |
| `timeout` | `None` | Request timeout in seconds |

## License

MIT
