Metadata-Version: 2.4
Name: langchain-quercle
Version: 0.1.3
Summary: LangChain tools for Quercle web search and URL fetching
Project-URL: Homepage, https://github.com/quercledev/quercle-langchain
Project-URL: Documentation, https://quercle.dev/docs
Project-URL: Repository, https://github.com/quercledev/quercle-langchain
Author-email: Quercle <support@quercle.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,langchain,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: langchain-core>=0.2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: quercle>=0.1.3
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'
Description-Content-Type: text/markdown

# quercle-langchain

LangChain tools for [Quercle](https://quercle.dev) web search and URL fetching.

## Installation

```bash
uv add langchain-quercle
```

Or with pip:

```bash
pip install langchain-quercle
```

## Quick Start

```python
from quercle_langchain import QuercleSearchTool, QuercleFetchTool

# Initialize tools (uses QUERCLE_API_KEY env var by default)
search = QuercleSearchTool()
fetch = QuercleFetchTool()

# Or with explicit API key
search = QuercleSearchTool(api_key="qk_...")
fetch = QuercleFetchTool(api_key="qk_...")
```

## Standalone Tool Usage

Use the tools directly without any LLM:

### Search

```python
from quercle_langchain import QuercleSearchTool

search = QuercleSearchTool()

# Basic search
result = search.invoke({"query": "What is TypeScript?"})
print(result)

# With domain filtering
result = search.invoke({
    "query": "machine learning tutorials",
    "allowed_domains": ["*.edu", "*.org"],
    "blocked_domains": ["ads.com"],
})
```

### Fetch

```python
from quercle_langchain import QuercleFetchTool

fetch = QuercleFetchTool()

result = fetch.invoke({
    "url": "https://docs.python.org/3/whatsnew/3.12.html",
    "prompt": "Summarize the key new features in bullet points",
})
print(result)
```

### Async Usage

Both tools support async operations:

```python
import asyncio
from quercle_langchain import QuercleSearchTool, QuercleFetchTool

async def main():
    search = QuercleSearchTool()
    fetch = QuercleFetchTool()

    # Async search
    result = await search.ainvoke({"query": "async Python programming"})
    print(result)

    # Async fetch
    result = await fetch.ainvoke({
        "url": "https://example.com",
        "prompt": "Extract main topics",
    })
    print(result)

asyncio.run(main())
```

## Usage with LangChain Chat Models

### Using `bind_tools()` for Single Interactions

Bind tools directly to a chat model for single-turn tool calling:

```python
from langchain_openai import ChatOpenAI
from quercle_langchain import QuercleSearchTool, QuercleFetchTool

# Initialize tools and model
tools = [QuercleSearchTool(), QuercleFetchTool()]
llm = ChatOpenAI(model="gpt-4o")

# Bind tools to the model
llm_with_tools = llm.bind_tools(tools)

# Invoke - the model will decide whether to use tools
response = llm_with_tools.invoke("Search for the latest Python 3.13 features")

# Access tool calls from the response
if response.tool_calls:
    for tool_call in response.tool_calls:
        print(f"Tool: {tool_call['name']}")
        print(f"Args: {tool_call['args']}")
```

### Using Agents for Multi-Step Tasks

For autonomous multi-step tasks, use `create_agent`:

```python
from langchain.agents import create_agent
from quercle_langchain import QuercleSearchTool, QuercleFetchTool

# Initialize tools
tools = [QuercleSearchTool(), QuercleFetchTool()]

# Create the agent
agent = create_agent(
    model="gpt-4o",  # or "claude-sonnet-4-5-20250929", "gemini-2.0-flash", etc.
    tools=tools,
    system_prompt="You are a helpful research assistant.",
)

# Run the agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "Search for the latest Python release and summarize the key features"}]
})

# Print the final response
print(result["messages"][-1].content)
```

### With Other LLM Providers

Both `bind_tools()` and `create_agent()` work with any LangChain-compatible chat model:

```python
# With Anthropic
from langchain_anthropic import ChatAnthropic
llm = ChatAnthropic(model="claude-sonnet-4-20250514")
llm_with_tools = llm.bind_tools(tools)

# With Google
from langchain_google_genai import ChatGoogleGenerativeAI
llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash")
llm_with_tools = llm.bind_tools(tools)

# Or use create_agent with model strings directly
from langchain.agents import create_agent
agent = create_agent(model="claude-sonnet-4-5-20250929", tools=tools)
agent = create_agent(model="gemini-2.0-flash", tools=tools)
```

## Configuration

### Environment Variable

Set your API key as an environment variable:

```bash
export QUERCLE_API_KEY=qk_your_api_key_here
```

### Tool Parameters

Both tools accept these optional parameters:

- `api_key`: Your Quercle API key (falls back to `QUERCLE_API_KEY` env var)
- `timeout`: Request timeout in seconds

```python
tool = QuercleSearchTool(
    api_key="qk_...",
    timeout=60.0,
)
```

## Tool Descriptions

### QuercleSearchTool

- **Name**: `search`
- **Description**: Search the web and get AI-synthesized answers with citations
- **Arguments**:
  - `query` (required): The search query
  - `allowed_domains` (optional): List of domains to include (e.g., `["*.edu"]`)
  - `blocked_domains` (optional): List of domains to exclude

### QuercleFetchTool

- **Name**: `fetch`
- **Description**: Fetch a URL and analyze its content with AI
- **Arguments**:
  - `url` (required): The URL to fetch
  - `prompt` (required): Instructions for content analysis

## License

MIT
