Metadata-Version: 2.4
Name: langchain-alterlab
Version: 0.1.0
Summary: LangChain integration for AlterLab web scraping API
License: MIT
License-File: LICENSE
Keywords: langchain,alterlab,web-scraping,document-loader,ai-agents
Author: AlterLab
Author-email: dev@alterlab.io
Requires-Python: >=3.9,<4.0
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: alterlab (>=2.4.0)
Requires-Dist: langchain-core (>=0.3.0,<1.0)
Project-URL: Documentation, https://docs.alterlab.io/integrations/langchain
Project-URL: Homepage, https://alterlab.io
Project-URL: Repository, https://github.com/RapierCraftStudios/AlterLab
Description-Content-Type: text/markdown

# langchain-alterlab

LangChain integration for the [AlterLab](https://alterlab.io) web scraping API.

## Installation

```bash
pip install langchain-alterlab
```

## Setup

Set your AlterLab API key:

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

Get your API key at [alterlab.io/dashboard](https://alterlab.io/dashboard).

## Document Loader

Load web pages as LangChain `Document` objects with structured metadata:

```python
from langchain_alterlab import AlterLabLoader

# Single URL
loader = AlterLabLoader(url="https://example.com/article")
docs = loader.load()

print(docs[0].page_content[:200])
print(docs[0].metadata)
# {'source': 'https://example.com/article', 'title': '...', 'author': '...', ...}
```

### Multiple URLs

```python
loader = AlterLabLoader(
    urls=[
        "https://example.com/page1",
        "https://example.com/page2",
    ],
)
docs = loader.load()
```

### Custom Parameters

```python
loader = AlterLabLoader(
    url="https://example.com",
    params={
        "formats": ["markdown", "json"],
        "mode": "js",  # JavaScript rendering
        "extraction_profile": "article",
    },
)
```

### Async Loading

```python
docs = await loader.aload()
```

## Agent Tool

Use `AlterLabScrapeTool` with LangChain agents to scrape pages on demand:

```python
from langchain_alterlab import AlterLabScrapeTool

tool = AlterLabScrapeTool()

# Direct use
result = tool.invoke("https://example.com")
print(result)
```

### With an Agent

```python
from langchain_openai import ChatOpenAI
from langchain_alterlab import AlterLabScrapeTool

llm = ChatOpenAI()
tools = [AlterLabScrapeTool()]
agent = llm.bind_tools(tools)
```

### With Metadata

```python
tool = AlterLabScrapeTool(include_metadata=True)
result = tool.invoke("https://example.com")
# Output includes title, author, source before content
```

## Metadata Fields

Documents and tool results include structured metadata:

| Field | Description |
|-------|-------------|
| `source` | URL that was scraped |
| `title` | Page title (if detected) |
| `author` | Content author (if detected) |
| `published_at` | Publication date (if detected) |
| `status_code` | HTTP response status code |
| `extraction_method` | How content was extracted |
| `response_time_ms` | API response time |
| `credits_used` | AlterLab credits consumed |
| `tier_used` | Scraping tier (1=curl, 2=http, 3=stealth, 4=browser) |

## API Reference

See [docs.alterlab.io](https://docs.alterlab.io) for the full AlterLab API documentation.

## Search Tool

Use `AlterLabSearchTool` to let agents run web searches (numbered title, URL and snippet):

```python
from langchain_alterlab import AlterLabSearchTool

tool = AlterLabSearchTool(num_results=5, params={"engine": "google"})
print(tool.invoke("web scraping api"))
```

