Metadata-Version: 2.4
Name: postbridge-langchain
Version: 0.1.0
Summary: PostBridge postal tools for LangChain and LangGraph — send physical letters to 5 countries from any LangChain agent.
Author-email: PostBridge AI <agent@postbridge.ai>
License: Proprietary
Project-URL: Homepage, https://postbridge.ai
Project-URL: Documentation, https://postbridge.ai/developers.html
Project-URL: Repository, https://github.com/zimoh/PostBridge-AI
Project-URL: Issues, https://github.com/zimoh/PostBridge-AI/issues
Keywords: langchain,langgraph,postbridge,postal,letter,ai-agent,tool-use,function-calling,x402,anp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: postbridge-core>=0.1
Requires-Dist: langchain-core>=0.3
Requires-Dist: pydantic>=2.0
Provides-Extra: agents
Requires-Dist: langchain>=0.3; extra == "agents"
Requires-Dist: langchain-openai>=0.2; extra == "agents"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == "langgraph"
Requires-Dist: langchain-openai>=0.2; extra == "langgraph"

# postbridge-langchain

Drop-in PostBridge tools for [LangChain](https://www.langchain.com/) and [LangGraph](https://langchain-ai.github.io/langgraph/) — send physical letters to US, France, UK, Canada, and Germany from any LangChain agent, chain, or LangGraph node.

## Install

```bash
# Core — tools + args validation only
pip install postbridge-langchain

# With AgentExecutor + OpenAI chat support
pip install "postbridge-langchain[agents]"

# With LangGraph
pip install "postbridge-langchain[langgraph]"
```

## Quickstart — `llm.bind_tools()`

```python
from langchain_openai import ChatOpenAI
from postbridge_langchain import postbridge_tools

llm = ChatOpenAI(model="gpt-4o-mini")
tools = postbridge_tools()                       # all 8 tools
llm_with_tools = llm.bind_tools(tools)

response = llm_with_tools.invoke("Send a letter to Paris saying hello")
# response.tool_calls → [{"name": "send_letter", "args": {...}}, ...]
```

## Quickstart — LangChain 1.x `create_agent`

```python
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from postbridge_langchain import postbridge_tools

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=postbridge_tools(),
    system_prompt="You are a postal assistant. Use tools to send letters.",
)

result = agent.invoke({"messages": [("human", "Send a letter to Paris saying hello")]})
print(result["messages"][-1].content)
```

## Quickstart — LangChain 0.3.x (AgentExecutor, legacy)

```python
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from postbridge_langchain import postbridge_tools

llm = ChatOpenAI(model="gpt-4o-mini")
tools = postbridge_tools()
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a postal assistant..."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
result = executor.invoke({"input": "Send a letter to Paris..."})
```

## Quickstart — LangGraph

```python
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from postbridge_langchain import postbridge_tools

llm = ChatOpenAI(model="gpt-4o-mini")
graph = create_react_agent(llm, tools=postbridge_tools())

result = graph.invoke({"messages": [("human", "Send a letter to Paris saying hello")]})
```

## Tools available

| Tool | HTTP | Purpose |
|------|------|---------|
| `list_services` | `GET /api/services/{country}` | Discover services per country |
| `quote_letter` | `POST /api/quote` | Price a letter |
| `send_letter` | `POST /api/send` | Mail it |
| `track_letter` | `GET /api/track/{letter_id}` | Live status |
| `get_proof` | `GET /api/proof/{letter_id}` | Signed PostalProof VC |
| `get_balance` | `GET /api/balance` | Wallet + ledger |
| `negotiate_pricing` | `POST /api/anp/offer` | ANP tiered offer |
| `accept_offer` | `POST /api/anp/accept` | Lock in tier |

## Subset selection

```python
# Read-only agent
tools = postbridge_tools(only=["list_services", "quote_letter", "track_letter", "get_proof"])

# Send-only dispatcher
tools = postbridge_tools(only=["send_letter", "track_letter"])

# Full ANP flow
tools = postbridge_tools(only=["negotiate_pricing", "accept_offer", "send_letter"])
```

## Async support

Every tool implements both `_run` (sync) and `_arun` (async), so LangGraph's async nodes and LangChain's `ainvoke` work out of the box:

```python
result = await llm_with_tools.ainvoke("Quote a letter to Berlin")
```

## Authentication

Tools call `https://api.postbridge.ai` and read `POSTBRIDGE_API_KEY` from the environment. Three ways to get a key:

**1. Auto-provision (no signup):**
```bash
curl -X POST https://api.postbridge.ai/auth/agent \
  -H 'Content-Type: application/json' \
  -d '{"agent_id": "my-agent", "agent_name": "My LangChain Agent"}'
```

**2. Register with email:** [postbridge.ai/developers.html](https://postbridge.ai/developers.html)

**3. Pay-per-request with x402 USDC (no API key needed):** see [postbridge.ai](https://postbridge.ai).

## How it works

Every tool is a `langchain_core.tools.BaseTool` subclass generated from the shared `tools.json` catalog that also powers PostBridge's OpenAI / Anthropic / Gemini / Mistral adapters. JSON Schema → Pydantic `args_schema` conversion catches bad inputs before they hit the API.

Tool execution delegates to the shared `dispatcher.execute()` — one HTTP path for all provider integrations, with path-param resolution, auth injection, and error surfacing.

## Design rules (enforced by the API)

- **Rate-table pricing** — no LLM-estimated prices
- **API-validated addresses** — no LLM-composed addresses
- **Recipient-country routing** — postal service matches the destination
- **Digital-only proof** — certified-mail receipts are webhook/API/email
- **Pricing confidentiality** — internal pricing fields scrubbed from every response

## Related

- Main API docs: [postbridge.ai/developers.html](https://postbridge.ai/developers.html)
- Agent metadata: [postbridge.ai/.well-known/agent.json](https://postbridge.ai/.well-known/agent.json)
- Source of truth catalog: `integrations/schemas/tools.json`
- Sister packages: `postbridge-crewai` (CrewAI), adapters for OpenAI / Anthropic / Gemini / Mistral
- Example agent: `examples/langchain_sendletter.py`
