py

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

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

Quickstart

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

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

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:

fastapi_app.mount("/tools", app)

Options

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
)