Metadata-Version: 2.4
Name: postbridge-core
Version: 0.1.0
Summary: PostBridge core — shared tool catalog, HTTP dispatcher, and Pydantic schema generator. Depended on by postbridge-crewai, postbridge-langchain, and postbridge-llamaindex.
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: postbridge,postal,letter,ai-agent,tool-catalog,schema
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: httpx>=0.27
Requires-Dist: pydantic>=2.0

# postbridge-core

Shared tool catalog, HTTP dispatcher, and Pydantic schema generator for [PostBridge](https://postbridge.ai). Depended on by the framework-specific wrappers — you usually won't install this directly.

## Install

```bash
pip install postbridge-core
```

Already installed as a dependency if you picked up `postbridge-crewai`, `postbridge-langchain`, or `postbridge-llamaindex`.

## What's inside

| Module | Purpose |
|--------|---------|
| `tools.json` | Canonical 8-tool catalog — the single source of truth |
| `loader.py` | Load, filter, lookup catalog entries |
| `dispatcher.py` | `execute(tool_name, args)` → live HTTP call to api.postbridge.ai |
| `pydantic_gen.py` | JSON Schema → Pydantic model generator |

## Public API

```python
from postbridge_core import (
    get_tools_raw,      # list[dict]  — raw catalog entries
    get_tool,           # dict        — single entry by name
    api_base_url,       # str         — https://api.postbridge.ai
    execute,            # callable    — run a tool against the live API
    build_args_model,   # callable    — JSON Schema → Pydantic model
    load_catalog,       # dict        — full catalog
)
```

## Dispatching a tool call

```python
from postbridge_core import execute
import os

os.environ["POSTBRIDGE_API_KEY"] = "pb_live_..."

# Path-param tool
status = execute("track_letter", {"letter_id": "abc-123"})

# Body-only tool
quote = execute("quote_letter", {
    "to_name": "Marie Dupont",
    "to_line1": "15 Rue de Rivoli",
    "to_city": "Paris",
    "to_postal_code": "75001",
    "to_country": "FR",
    "service": "fr_lettre_verte",
})
```

## Building a Pydantic model for a tool

```python
from postbridge_core import get_tool, build_args_model

send = get_tool("send_letter")
SendLetterArgs = build_args_model("send_letter", send["parameters"])

# SendLetterArgs is a full Pydantic v2 BaseModel:
args = SendLetterArgs(to_name="...", ...)
```

## For users of the framework wrappers

You probably don't need this package directly. See instead:

- `postbridge-crewai` — [CrewAI](https://crewai.com) tools
- `postbridge-langchain` — [LangChain](https://langchain.com) and LangGraph tools
- `postbridge-llamaindex` — [LlamaIndex](https://docs.llamaindex.ai) tools

Each of those uses `postbridge-core` under the hood — same catalog, same dispatcher, same validation.

## Tool catalog (as of v0.1.0)

| Tool | Method | Path |
|------|--------|------|
| `list_services` | GET | `/api/services/{country}` |
| `quote_letter` | POST | `/api/quote` |
| `send_letter` | POST | `/api/send` |
| `track_letter` | GET | `/api/track/{letter_id}` |
| `get_proof` | GET | `/api/proof/{letter_id}` |
| `get_balance` | GET | `/api/balance` |
| `negotiate_pricing` | POST | `/api/anp/offer` |
| `accept_offer` | POST | `/api/anp/accept` |

Full developer reference: [postbridge.ai/developers.html](https://postbridge.ai/developers.html).
