Metadata-Version: 2.4
Name: paybond-kit
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.27,<1
Requires-Dist: openai-agents>=0.14.2,<0.15 ; extra == 'agents'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
Requires-Dist: respx>=0.21 ; extra == 'dev'
Requires-Dist: langgraph>=0.2.50 ; extra == 'dev'
Requires-Dist: langchain-core>=0.3.0 ; extra == 'dev'
Requires-Dist: langgraph>=0.2.50 ; extra == 'langgraph'
Requires-Dist: langchain-core>=0.3.0 ; extra == 'langgraph'
Provides-Extra: agents
Provides-Extra: dev
Provides-Extra: langgraph
License-File: LICENSE
Summary: Paybond Kit for Python: tenant-bound Harbor sessions, evidence signing, and agent-runtime hooks.
Keywords: paybond,harbor,agents,python,escrow,capabilities
Home-Page: https://github.com/nonameuserd/paybond-kit-python
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/nonameuserd/paybond-kit-python
Project-URL: Homepage, https://github.com/nonameuserd/paybond-kit-python
Project-URL: Issues, https://github.com/nonameuserd/paybond-kit-python/issues
Project-URL: Repository, https://github.com/nonameuserd/paybond-kit-python.git

# `paybond-kit`

Paybond Kit for Python provides a tenant-bound Harbor client, gateway-authenticated service-account sessions, canonical signing for intent creation and evidence submission, tenant-scoped ledger provenance reads, plus first-party hooks for the OpenAI Agents SDK and LangGraph.

It does **not** currently expose a first-class Signal client or Signal analytics/reputation API surface. Signal remains a separate platform surface today.

Install the public package with:

```bash
pip install "paybond-kit[agents,langgraph]"
```

## Open source

`paybond-kit` is distributed as open-source software under the Apache 2.0 license. The source repo and published artifacts include the full license text in `LICENSE`.

## Requirements

- Python 3.11+
- A `paybond_sk_...` service-account API key
- Reachable Gateway and Harbor base URLs

Published wheels bundle the `paybond_kit._native` extension. `maturin develop` is only required when building from a local checkout.

## Tenant isolation

Every session is bound to the tenant realm echoed by the gateway `POST /v1/auth/harbor-access` exchange.

- Do not pass tenant ids by hand for normal SDK usage.
- Construct one `Paybond` session per tenant/service account.
- Treat any tenant or intent echo mismatch from Harbor as a severity-zero defect.

## Quick start

```python
import asyncio
import os
from uuid import UUID

from paybond_kit import Paybond


async def main() -> None:
    paybond = await Paybond.open(
        gateway_base_url="https://gateway.example.com",
        api_key=os.environ["PAYBOND_API_KEY"],
        harbor_base_url="https://harbor.example.com",
    )
    try:
        verified = await paybond.harbor.verify_capability(
            intent_id=UUID(os.environ["PAYBOND_INTENT_ID"]),
            token=os.environ["PAYBOND_CAPABILITY"],
            operation="payments.capture",
            requested_spend_cents=18_700,
        )
        if not verified.allow:
            raise RuntimeError(f"verify denied: {verified.code or 'deny'} {verified.message or ''}")
    finally:
        await paybond.aclose()


asyncio.run(main())
```

## What the package includes

- `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
- `HarborClient` for capability verification, intent creation, evidence submission, and ledger reads
- `PaybondIntents` helpers for principal-side and payee-side signing flows
- Optional extras for `agents` and `langgraph`

`allowed_tools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.

## What it does not include

- No first-class `SignalClient`
- No Signal reputation or analytics fetch API
- No operator-tier settlement or console workflows

## Source build

For local development from this directory:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
maturin develop
```

Use this path when you are editing the package itself or rebuilding the bundled native extension locally.

## Docs

- Long-form docs: `docs/kit/`
- Python quickstart: `docs/kit/quickstart-python.md`
- Python SDK reference: `docs/kit/sdk-reference-python.md`
- OpenAI Agents example: `examples/paybond-kit-openai-agents-python/`
- LangGraph example: `examples/paybond-kit-langgraph-python/`

## Release verification

From `kit/python`:

```bash
python3 scripts/verify_release.py
```

This builds wheel and sdist artifacts, inspects them for stray local files, validates metadata/extras, and smoke-installs the built wheel in a temporary virtual environment.

## Publish to PyPI

From `kit/python`:

```bash
export MATURIN_PYPI_TOKEN="pypi-..."
./scripts/publish_release.sh
```

This reruns release verification and then publishes the sdist and wheel with `maturin publish --non-interactive`.

