Metadata-Version: 2.4
Name: htbp-sdk
Version: 0.1.0
Summary: HTBP (HTTP Tool Bridge Protocol) server SDK: expose functions as self-describing HTTP tool endpoints, FastAPI-style.
Project-URL: Repository, https://github.com/TokenRollAI/http-tool-bridge
Author: TokenRoll AI
License-Expression: MIT
Keywords: agent,asgi,htbp,http,sdk,tool
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.7
Provides-Extra: remote
Requires-Dist: httpx>=0.27; extra == 'remote'
Description-Content-Type: text/markdown

# htbp-sdk

HTBP (HTTP Tool Bridge Protocol) server SDK for Python. Expose functions as
self-describing HTTP tool endpoints, FastAPI-style. Pure ASGI — runs under
uvicorn/hypercorn and mounts inside FastAPI or Starlette.

## Install

```sh
pip install htbp-sdk            # import name: htbp
pip install 'htbp-sdk[remote]'  # + httpx, needed only for app.remote()
```

## Quickstart

```python
from htbp import Htbp

app = Htbp(title="Math tools")

@app.tool(effect="read")
def add(a: int, b: int = 0) -> int:
    """Add two integers."""
    return a + b
```

```sh
uvicorn main:app
```

Input schemas are derived from type hints via pydantic (FastAPI-style); a
single parameter annotated with a `BaseModel` subclass uses that model as the
body schema directly. Async functions are awaited; sync functions run in a
thread. A `ToolContext`-annotated parameter receives request context.

Every node answers `GET {path}/~help` (JSON by default, RFC-0001 text DSL with
`Accept: text/plain`); tools are invoked with `POST {path}` and respond with
`{"resource", "result"}`.

## Cascading

```python
docs = Htbp(title="Docs tools")

@docs.tool()
def search(q: str) -> dict:
    return {"hits": [q]}

app.mount("/docs", docs)                                # local nesting
app.remote("/ext", "https://other.example.com/~help")   # federate a remote HTBP server
```

Remote nodes pass through `~help` for any sub-path and proxy calls; the inbound
`Authorization` header is never forwarded upstream.

Mount inside FastAPI:

```python
fastapi_app.mount("/tools", app)
```

## Options

```python
Htbp(
    title="My tools",
    description="...",
    auth={"bearer_token": "..."},   # 401 + WWW-Authenticate without it
    skill="# Markdown served at /~skill",
    base_path="/htbp",               # serve under a path prefix
    cors=False,                      # CORS is on by default
)
```
