Metadata-Version: 2.4
Name: langchain-proxyclaw
Version: 0.1.0
Summary: LangChain integration for ProxyClaw - residential proxy network
Project-URL: Homepage, https://proxyclaw.ai
Project-URL: Documentation, https://docs.proxyclaw.ai
Project-URL: Repository, https://github.com/iploop/langchain-proxyclaw
Project-URL: Bug Tracker, https://github.com/iploop/langchain-proxyclaw/issues
Author-email: IPLoop Team <support@iploop.io>
License: MIT
License-File: LICENSE
Keywords: iploop,langchain,proxy,proxyclaw,residential,scraping
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: iploop-sdk>=1.8.0
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'dev'
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# LangChain ProxyClaw Integration

[![PyPI version](https://badge.fury.io/py/langchain-proxyclaw.svg)](https://badge.fury.io/py/langchain-proxyclaw)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official LangChain integration for [ProxyClaw](https://proxyclaw.ai) - a residential proxy network with 10M+ IPs across 111+ countries.

## Overview

This package provides LangChain Tools for routing HTTP requests through ProxyClaw's residential proxy network, enabling AI agents to scrape websites with:

- 🌍 **Global IP coverage** - 111+ countries
- 🔄 **Automatic rotation** - Fresh IPs per request or sticky sessions
- 🛡️ **Anti-detection** - Built-in fingerprint spoofing
- ⚡ **High success rate** - Residential IPs bypass most blocks

## Installation

```bash
pip install langchain-proxyclaw
```

For development:

```bash
pip install langchain-proxyclaw[dev]
```

## Quick Start

```python
from langchain_proxyclaw import ProxyClawTool
from langchain.agents import AgentType, initialize_agent
from langchain_openai import ChatOpenAI

# Initialize the tool
tool = ProxyClawTool(api_key="your_api_key")

# Use with an agent
llm = ChatOpenAI(temperature=0)
agent = initialize_agent(
    [tool],
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# Ask the agent to scrape a website
agent.run("Get the content from https://example.com using a US proxy")
```

## Tools

### 1. ProxyClawTool

Basic HTTP requests through ProxyClaw proxies.

```python
from langchain_proxyclaw import ProxyClawTool

tool = ProxyClawTool(api_key="your_api_key")

# Simple GET request
result = tool.invoke({
    "url": "https://example.com",
    "country": "US"
})

# POST request with data
result = tool.invoke({
    "url": "https://api.example.com/data",
    "method": "POST",
    "data": {"key": "value"},
    "headers": {"Authorization": "Bearer token"},
    "country": "GB"
})
```

**Parameters:**
- `url` (str, required): Target URL
- `method` (str): HTTP method (GET, POST, PUT, DELETE) - default: GET
- `headers` (dict): Optional HTTP headers
- `data` (str/dict): Request body data
- `country` (str): Country code for proxy location (e.g., "US", "GB", "DE")
- `session_id` (str): Session ID for sticky sessions

### 2. ProxyClawSessionTool

Sticky proxy sessions for multi-step workflows.

```python
from langchain_proxyclaw import ProxyClawSessionTool

tool = ProxyClawSessionTool(api_key="your_api_key")

# Scrape multiple pages with the same IP
result = tool.invoke({
    "urls": [
        "https://site.com/login",
        "https://site.com/dashboard",
        "https://site.com/profile"
    ],
    "country": "US"
})
```

**Parameters:**
- `urls` (list[str], required): List of URLs to fetch
- `country` (str): Country code
- `session_lifetime` (int): Session duration in minutes - default: 30

### 3. ProxyClawScraperTool

Advanced scraper with retries and auto-rotation.

```python
from langchain_proxyclaw import ProxyClawScraperTool

tool = ProxyClawScraperTool(api_key="your_api_key")

# Scrape with retries and link extraction
result = tool.invoke({
    "url": "https://example.com/products",
    "country": "US",
    "retries": 3,
    "timeout": 30,
    "extract_links": True
})
```

**Parameters:**
- `url` (str, required): Target URL
- `country` (str): Country code
- `retries` (int): Number of retry attempts - default: 3
- `timeout` (int): Request timeout in seconds - default: 30
- `extract_links` (bool): Extract all links from the page - default: False

## Authentication

Get your API key from [ProxyClaw Dashboard](https://platform.proxyclaw.ai):

```python
api_key = "pk_live_xxxxxxxxxxxxxxxx"
```

## Country Codes

Common country codes:
- `US` - United States
- `GB` - United Kingdom
- `DE` - Germany
- `FR` - France
- `JP` - Japan
- `IN` - India
- `BR` - Brazil

Full list: 111+ countries supported. Use ISO 3166-1 alpha-2 codes.

## Use Cases

### Web Scraping for AI Agents

```python
from langchain_proxyclaw import ProxyClawScraperTool
from langchain.agents import AgentType, initialize_agent

scraper = ProxyClawScraperTool(api_key="your_api_key")

agent = initialize_agent(
    [scraper],
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION
)

# Agent can now scrape without being blocked
agent.run("Find pricing information from https://competitor.com/pricing")
```

### E-commerce Monitoring

```python
session_tool = ProxyClawSessionTool(api_key="your_api_key")

# Same IP for login + price check
result = session_tool.invoke({
    "urls": [
        "https://shop.com/login",
        "https://shop.com/product/123"
    ],
    "country": "US"
})
```

### Market Research

```python
from langchain_proxyclaw import ProxyClawTool

tool = ProxyClawTool(api_key="your_api_key")

# Check how a site appears from different countries
for country in ["US", "GB", "DE", "JP"]:
    result = tool.invoke({
        "url": "https://global-site.com",
        "country": country
    })
    print(f"{country}: {result}")
```

## LangChain Integration Tests

To run LangChain's standard integration tests:

```bash
pip install langchain-proxyclaw[dev]
pytest tests/ -v
```

## Documentation

Full documentation: [docs.proxyclaw.ai](https://docs.proxyclaw.ai)

LangChain docs: [python.langchain.com](https://python.langchain.com)

## API Reference

See [ProxyClaw API Docs](https://docs.proxyclaw.ai/api) for details on:
- Authentication formats
- Country targeting
- Session management
- Bandwidth tracking

## Pricing

ProxyClaw uses pay-as-you-go pricing:
- $0.35/GB under 10TB
- $0.25/GB over 10TB

No minimums, no commitments. [Sign up](https://proxyclaw.ai)

## Support

- 📧 Email: support@iploop.io
- 💬 Discord: [discord.gg/clawd](https://discord.gg/clawd)
- 📖 Docs: [docs.proxyclaw.ai](https://docs.proxyclaw.ai)

## License

MIT License - see [LICENSE](LICENSE) file.

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

Built with ❤️ by the [IPLoop](https://iploop.io) team.
