Metadata-Version: 2.4
Name: postbridge-crewai
Version: 0.1.0
Summary: PostBridge postal tools for CrewAI — send physical letters to 5 countries from any CrewAI 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: crewai,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: crewai>=0.80.0
Requires-Dist: pydantic>=2.0

# postbridge-crewai

Drop-in PostBridge tools for [CrewAI](https://crewai.com) — send physical letters to US, France, UK, Canada, and Germany from any CrewAI agent.

## Install

```bash
pip install postbridge-crewai
# Or from the monorepo:
pip install -e integrations/postbridge_crewai
```

## Quickstart

```python
from crewai import Agent, Crew, Task, Process
from postbridge_crewai import postbridge_tools

postal_clerk = Agent(
    role="Postal Clerk",
    goal="Send physical letters via PostBridge",
    tools=postbridge_tools(),        # all 8 tools
    verbose=True,
)

task = Task(
    description="Send a letter to Marie Dupont, 15 Rue de Rivoli, 75001 Paris...",
    expected_output="Confirmation with letter_id, price, and status.",
    agent=postal_clerk,
)

crew = Crew(agents=[postal_clerk], tasks=[task], process=Process.sequential)
result = crew.kickoff()
```

## 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

Most crews don't need every tool. Filter:

```python
# Read-only reporter
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 negotiation crew
tools = postbridge_tools(only=["negotiate_pricing", "accept_offer", "send_letter"])
```

## Authentication

The 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-crew", "agent_name": "My CrewAI Crew"}'
```
Response includes `api_key`. Export it:
```bash
export POSTBRIDGE_API_KEY=pb_live_...
```

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

**3. Pay-per-request with x402 USDC:** skip auth entirely, pay from an EVM wallet (Base L2) per call. See [postbridge.ai](https://postbridge.ai) for x402 setup.

## How it works

Under the hood, every tool is a `BaseTool` subclass generated from the shared `tools.json` catalog that also powers PostBridge's OpenAI / Anthropic / Gemini / Mistral adapters. The catalog's JSON Schema is converted into a Pydantic `args_schema` so CrewAI's built-in validation 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

The tools enforce PostBridge's determinism rules automatically because validation and routing happen server-side:

- **Rate-table pricing** — no LLM-estimated prices
- **API-validated addresses** — no LLM-composed addresses
- **Recipient-country routing** — postal service matches the destination, never the sender
- **Digital-only proof** — certified-mail receipts are webhook/API/email (never physical)
- **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`
- Other adapters: OpenAI, Anthropic, Gemini, Mistral under `integrations/schemas/`
- Example crew: `examples/crewai_sendletter.py`
