Metadata-Version: 2.4
Name: langchain-helve
Version: 0.1.0
Summary: LangChain toolkit for Helve — pay-per-call AI tool gateway (313 tools, 255 providers) with spend_limit_usd caps and zero-cost failed-call escrow.
Author-email: Helve <daniel.foster@helve.dev>
License-Expression: MIT
Project-URL: Homepage, https://helve.dev
Project-URL: Documentation, https://docs.helve.dev
Project-URL: llms.txt, https://helve.dev/llms.txt
Project-URL: Repository, https://github.com/helve-dev/helve-mcp
Keywords: langchain,langgraph,helve,ai-agents,tools,mcp,api-gateway
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Dynamic: license-file

# langchain-helve

LangChain and LangGraph toolkit for [Helve](https://helve.dev) — one API key and one prepaid balance for 313 tools across 255 providers (web search, crawling/extraction, LLMs, audio transcription, PDFs, email, browser automation, finance, and free public utilities).

- **No monthly subscriptions:** start with prepaid credit packs (10 / 25 / 100 USD, never expire).
- **Deterministic spend caps:** per-key `spend_limit_usd` enforcement (`402 spend_limit_exceeded`).
- **Failed-call escrow:** upstream 5xx errors and timeouts automatically refund to 0 USD.
- **Free tool discovery:** `helve_search_tools` works without authentication so agents can discover `tool_id`, `input_schema`, and pricing before calling.

## Installation

```bash
pip install langchain-helve
```

## Quickstart

```python
import os
from langchain_helve import HelveToolkit

toolkit = HelveToolkit(api_key=os.environ.get("HELVE_API_KEY"))
tools = toolkit.get_tools()
# [HelveSearchTools, HelveCallTool, HelveRequestTool]

# 1. Discover tools dynamically (no auth required)
search_tool = tools[0]
print(search_tool.invoke({"query": "web extraction", "limit": 3}))

# 2. Bind to any LangChain / LangGraph agent
# agent = create_react_agent(model, tools)
```

## Direct Client Usage

```python
from langchain_helve import HelveGatewayClient

client = HelveGatewayClient(api_key="sk_live_...")

# Search available tools
matches = client.search_tools("web extraction", limit=5)

# Execute any discovered tool_id with its native arguments
result = client.call_tool(
    "helve.web_extract",
    {"urls": ["https://docs.helve.dev"], "content": {"max_chars": 4000}},
)
```

## Links

- Website: https://helve.dev
- Documentation: https://docs.helve.dev
- MCP Server & Skills: https://github.com/helve-dev/helve-mcp
- OpenAPI 3.1 Spec: https://helve.dev/openapi.json
