htbp-sdk 0.1.0__tar.gz

htbp_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+uv.lock
+.DS_Store

htbp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+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
+)
+```

htbp_sdk-0.1.0/README.md

@@ -0,0 +1,73 @@
+# 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
+)
+```

htbp_sdk-0.1.0/examples/server.py

@@ -0,0 +1,32 @@
+"""Runnable example: `uv run uvicorn examples.server:app --port 8788`.
+
+Serves an HTBP tree on http://127.0.0.1:8788.
+"""
+
+from htbp import Htbp
+
+app = Htbp(
+    title="Example tools",
+    description="HTBP example server (Python SDK).",
+    skill="# Example tools\n\nCall `add` with `{\"a\": 1, \"b\": 2}`.\n",
+)
+
+
+@app.tool(effect="read")
+def add(a: int, b: int = 0) -> int:
+    """Add two integers."""
+    return a + b
+
+
+docs = Htbp(title="Docs tools", description="Documentation helpers.")
+
+
+@docs.tool(description="Search documents.")
+def search(q: str) -> dict:
+    return {"hits": [f"result for {q}"]}
+
+
+app.mount("/docs", docs)
+
+# Federate to another HTBP server (TS or Python) — cascading across processes:
+# app.remote("/ext", "https://other.example.com/~help")

htbp_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "htbp-sdk"
+version = "0.1.0"
+description = "HTBP (HTTP Tool Bridge Protocol) server SDK: expose functions as self-describing HTTP tool endpoints, FastAPI-style."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "TokenRoll AI" }]
+keywords = ["htbp", "tool", "agent", "http", "sdk", "asgi"]
+dependencies = ["pydantic>=2.7"]
+
+[project.optional-dependencies]
+remote = ["httpx>=0.27"]
+
+[project.urls]
+Repository = "https://github.com/TokenRollAI/http-tool-bridge"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+    "uvicorn>=0.30",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/htbp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

htbp_sdk-0.1.0/src/htbp/__init__.py

@@ -0,0 +1,37 @@
+"""htbp — HTBP (HTTP Tool Bridge Protocol) server SDK.
+
+Expose functions as self-describing HTTP tool endpoints, FastAPI-style::
+
+    from htbp import Htbp
+
+    app = Htbp(title="Math tools")
+
+    @app.tool()
+    def add(a: int, b: int = 0) -> int:
+        \"\"\"Add two integers.\"\"\"
+        return a + b
+
+    # uvicorn main:app
+"""
+
+from .app import Htbp
+from .errors import (
+    BadRequestError,
+    HtbpError,
+    MethodNotAllowedError,
+    NotFoundError,
+    UpstreamError,
+)
+from .schema import ToolContext
+from .text_help import build_text_help
+
+__all__ = [
+    "Htbp",
+    "ToolContext",
+    "HtbpError",
+    "NotFoundError",
+    "BadRequestError",
+    "MethodNotAllowedError",
+    "UpstreamError",
+    "build_text_help",
+]

htbp_sdk-0.1.0/src/htbp/app.py

@@ -0,0 +1,402 @@
+"""The Htbp application: FastAPI-style tool registration on a self-describing
+HTBP tree, served as a pure-ASGI app — mirror of the TypeScript SDK's
+core/app.ts dispatch."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from typing import Any, Callable
+from urllib.parse import quote, unquote
+
+from .describe import describe_directory, describe_tool
+from .errors import BadRequestError, HtbpError, MethodNotAllowedError, NotFoundError
+from .http import (
+    CORS_HEADERS,
+    MAX_JSON_BYTES,
+    constant_time_equal,
+    dump_json,
+    error_body,
+    etag_of,
+    get_bearer_token,
+    if_none_match_matches,
+)
+from .schema import CompiledTool, ToolContext, compile_function, output_json_schema
+from .text_help import build_text_help
+from .tree import (
+    EFFECTS,
+    DirectoryNode,
+    RemoteNode,
+    ToolNode,
+    add_child,
+    ensure_directory,
+    path_segments,
+    resolve,
+)
+
+
+class Htbp:
+    def __init__(
+        self,
+        title: str,
+        description: str | None = None,
+        *,
+        auth: dict[str, str] | None = None,
+        skill: str | None = None,
+        cors: bool = True,
+        base_path: str | None = None,
+    ) -> None:
+        if auth is not None and "bearer_token" not in auth:
+            raise ValueError("auth must be {'bearer_token': '...'}.")
+        self._auth = auth
+        self._cors = cors
+        self._base_path = _normalize_base_path(base_path)
+        self.root = DirectoryNode(id="", title=title, description=description, skill=skill)
+
+    # -- registration -----------------------------------------------------
+
+    def tool(
+        self,
+        fn: Callable[..., Any] | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        effect: str = "unknown",
+        example: Any = None,
+        skill: str | None = None,
+    ):
+        """Decorator: register a plain function as an HTBP tool.
+
+        Usable bare (``@app.tool``) or with options (``@app.tool(...)``).
+        """
+        if effect not in EFFECTS:
+            raise ValueError(f"effect must be one of {EFFECTS}.")
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            compiled = compile_function(func)
+            tool_name = name or func.__name__
+            doc = inspect.getdoc(func)
+            tool_description = description or (doc.split("\n\n")[0].strip() if doc else None)
+            return_annotation = inspect.signature(func).return_annotation
+            add_child(
+                self.root,
+                ToolNode(
+                    id=tool_name,
+                    title=tool_name,
+                    description=tool_description,
+                    skill=skill,
+                    effect=effect,
+                    example=example,
+                    input_schema=compiled.json_schema,
+                    output_schema=output_json_schema(return_annotation),
+                    validate=compiled.validate,
+                    call=_make_caller(func, compiled),
+                ),
+            )
+            return func
+
+        if fn is not None:
+            return decorator(fn)
+        return decorator
+
+    def mount(self, path: str, sub: "Htbp") -> "Htbp":
+        """Graft a sub-app's tree under ``path`` (cascading)."""
+        if sub is self:
+            raise ValueError("Cannot mount an app into itself.")
+        segments = path_segments(path)
+        parent = ensure_directory(self.root, segments[:-1])
+        child = DirectoryNode(
+            id=segments[-1],
+            title=sub.root.title,
+            description=sub.root.description,
+            skill=sub.root.skill,
+            children=sub.root.children,
+        )
+        add_child(parent, child)
+        return self
+
+    def remote(
+        self,
+        path: str,
+        help_url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        allow_insecure: bool = False,
+    ) -> "Htbp":
+        segments = path_segments(path)
+        parent = ensure_directory(self.root, segments[:-1])
+        add_child(
+            parent,
+            RemoteNode(
+                id=segments[-1],
+                title=title or segments[-1],
+                description=description,
+                help_url=help_url,
+                headers=headers,
+                allow_insecure=allow_insecure,
+            ),
+        )
+        return self
+
+    # -- ASGI -------------------------------------------------------------
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope["type"] == "lifespan":
+            await _lifespan(receive, send)
+            return
+        if scope["type"] != "http":
+            raise RuntimeError(f"Unsupported ASGI scope type '{scope['type']}'.")
+        try:
+            status, headers, body = await self._dispatch(scope, receive)
+        except HtbpError as error:
+            status, headers, body = self._error_response(error)
+        except Exception as error:  # noqa: BLE001 - handler errors become 500 envelopes
+            status, headers, body = self._error_response(HtbpError(500, "internal_error", str(error)))
+        if self._cors:
+            for key, value in CORS_HEADERS.items():
+                headers.setdefault(key, value)
+        await _send_response(send, status, headers, body)
+
+    def _error_response(self, error: HtbpError) -> tuple[int, dict[str, str], bytes]:
+        headers = {"Content-Type": "application/json; charset=utf-8"}
+        if error.status == 401:
+            headers["WWW-Authenticate"] = "Bearer"
+        return error.status, headers, error_body(error.code, error.message, error.details).encode("utf-8")
+
+    async def _dispatch(self, scope: dict[str, Any], receive: Any) -> tuple[int, dict[str, str], bytes]:
+        method = scope["method"]
+        headers = {key.decode("latin-1").lower(): value.decode("latin-1") for key, value in scope.get("headers", [])}
+
+        if method == "OPTIONS" and self._cors:
+            return 204, {**CORS_HEADERS, "Access-Control-Max-Age": "86400"}, b""
+
+        self._authenticate(headers)
+
+        segments, base = self._request_segments(scope)
+        control = None
+        if segments and segments[-1] in ("~help", "~skill"):
+            control = segments.pop()
+
+        found = resolve(self.root, segments)
+        if found is None:
+            raise NotFoundError(f"No HTBP resource at '/{'/'.join(segments)}'.")
+        node, sub = found
+        resource_path = _resource_path(base, segments)
+
+        if control == "~skill":
+            return await self._serve_skill(method, headers, node, sub, resource_path)
+        if control == "~help" or (method == "GET" and not segments):
+            return await self._serve_help(method, headers, node, sub, resource_path)
+
+        if method == "POST":
+            return await self._serve_call(scope, receive, headers, node, sub, resource_path)
+        if method == "GET":
+            raise MethodNotAllowedError(f"GET is not supported here; fetch '{resource_path}/~help' for usage.")
+        raise MethodNotAllowedError(f"Method {method} is not supported.")
+
+    def _authenticate(self, headers: dict[str, str]) -> None:
+        if self._auth is None:
+            return
+        token = get_bearer_token(headers.get("authorization"))
+        if not token or not constant_time_equal(token, self._auth["bearer_token"]):
+            raise HtbpError(401, "unauthorized", "A valid bearer token is required.")
+
+    def _request_segments(self, scope: dict[str, Any]) -> tuple[list[str], str]:
+        # root_path covers being mounted inside FastAPI/Starlette; an explicit
+        # base_path is for serving under a prefix without a mounting frame.
+        root_path = scope.get("root_path", "") or ""
+        base = _join_base(root_path, self._base_path)
+        path = scope["path"]
+        rest = path
+        if self._base_path:
+            inner = path[len(root_path):] if root_path and path.startswith(root_path) else path
+            if inner != self._base_path and not inner.startswith(self._base_path + "/"):
+                raise NotFoundError(f"No HTBP resource at '{path}'.")
+            rest = inner[len(self._base_path):]
+        elif root_path and path.startswith(root_path):
+            rest = path[len(root_path):]
+        segments = [unquote(segment) for segment in rest.split("/") if segment]
+        return segments, base
+
+    async def _serve_help(
+        self, method: str, headers: dict[str, str], node: Any, sub: list[str], resource_path: str
+    ) -> tuple[int, dict[str, str], bytes]:
+        if method != "GET":
+            raise MethodNotAllowedError("~help only supports GET.")
+        has_skill = False
+        if isinstance(node, DirectoryNode):
+            payload = describe_directory(node)
+            await self._enrich_remote_children(node, payload)
+            has_skill = node.skill is not None
+        elif isinstance(node, ToolNode):
+            if sub:
+                raise NotFoundError(f"No HTBP resource at '{resource_path}'.")
+            payload = describe_tool(node)
+            has_skill = node.skill is not None
+        else:
+            from .remote import remote_describe
+
+            payload = await remote_describe(node, sub)
+
+        auth_label = "bearer" if self._auth else "none"
+        cache_control = (
+            "no-store"
+            if payload.get("cachable") is False
+            else f"{'private' if self._auth else 'public'}, max-age=300"
+        )
+        accept = headers.get("accept", "")
+        if _prefers_text(accept):
+            body = build_text_help(payload, resource_path, auth_label, has_skill)
+            content_type = "text/plain; charset=utf-8"
+        else:
+            body = dump_json(payload) + "\n"
+            content_type = "application/json; charset=utf-8"
+        if cache_control == "no-store":
+            return 200, {"Content-Type": content_type, "Cache-Control": cache_control}, body.encode("utf-8")
+        return _cached_document(body, content_type, cache_control, headers.get("if-none-match"))
+
+    async def _enrich_remote_children(self, node: DirectoryNode, payload: dict[str, Any]) -> None:
+        remotes = [child for child in node.children.values() if isinstance(child, RemoteNode) and not child.description]
+        if not remotes:
+            return
+        from .remote import fetch_remote_summary
+
+        refs = {ref["name"]: ref for ref in payload.get("resources", [])}
+        summaries = await asyncio.gather(*(fetch_remote_summary(child) for child in remotes))
+        for child, summary in zip(remotes, summaries):
+            ref = refs.get(child.id)
+            if ref is None or summary is None:
+                continue
+            enriched = summary.get("description") or (f"Remote: {summary['title']}" if summary.get("title") else None)
+            if enriched:
+                ref["description"] = enriched
+
+    async def _serve_skill(
+        self, method: str, headers: dict[str, str], node: Any, sub: list[str], resource_path: str
+    ) -> tuple[int, dict[str, str], bytes]:
+        if method != "GET":
+            raise MethodNotAllowedError("~skill only supports GET.")
+        skill = None if isinstance(node, RemoteNode) or sub else getattr(node, "skill", None)
+        if skill is None:
+            raise NotFoundError(f"No skill document at '{resource_path}/~skill'.")
+        cache_control = f"{'private' if self._auth else 'public'}, max-age=300"
+        return _cached_document(skill, "text/markdown; charset=utf-8", cache_control, headers.get("if-none-match"))
+
+    async def _serve_call(
+        self, scope: dict[str, Any], receive: Any, headers: dict[str, str], node: Any, sub: list[str], resource_path: str
+    ) -> tuple[int, dict[str, str], bytes]:
+        if isinstance(node, DirectoryNode):
+            raise HtbpError(405, "not_callable", f"'{resource_path}' is a directory; descend to an end-path resource.")
+        input_value = await _read_json_body(receive)
+        if isinstance(node, RemoteNode):
+            from .remote import remote_call
+
+            result = await remote_call(node, sub, input_value)
+            return _json_response({"resource": resource_path, "result": result})
+        if sub:
+            raise NotFoundError(f"No HTBP resource at '{resource_path}'.")
+        ok, value = node.validate(input_value)
+        if not ok:
+            raise BadRequestError("Input validation failed.", value)
+        ctx = ToolContext(path=resource_path, headers=headers, scope=scope)
+        result = await node.call(value, ctx)
+        return _json_response({"resource": resource_path, "result": result})
+
+
+def _make_caller(fn: Callable[..., Any], compiled: CompiledTool):
+    is_async = inspect.iscoroutinefunction(fn)
+
+    async def call(value: Any, ctx: ToolContext) -> Any:
+        kwargs = compiled.bind(value, ctx)
+        if is_async:
+            return await fn(**kwargs)
+        return await asyncio.to_thread(fn, **kwargs)
+
+    return call
+
+
+def _prefers_text(accept: str) -> bool:
+    value = accept.lower()
+    if "application/json" in value:
+        return False
+    return "text/plain" in value or "text/markdown" in value
+
+
+def _normalize_base_path(base_path: str | None) -> str:
+    if not base_path or base_path == "/":
+        return ""
+    trimmed = base_path.rstrip("/")
+    return trimmed if trimmed.startswith("/") else f"/{trimmed}"
+
+
+def _join_base(root_path: str, base_path: str) -> str:
+    combined = f"{root_path.rstrip('/')}{base_path}"
+    return combined if combined else ""
+
+
+def _resource_path(base: str, segments: list[str]) -> str:
+    joined = "/".join(quote(segment, safe="") for segment in segments)
+    if not joined:
+        return base or "/"
+    return f"{base}/{joined}"
+
+
+def _cached_document(
+    body: str, content_type: str, cache_control: str, if_none_match: str | None
+) -> tuple[int, dict[str, str], bytes]:
+    etag = etag_of(body)
+    headers = {"ETag": etag, "Cache-Control": cache_control}
+    if if_none_match and if_none_match_matches(if_none_match, etag):
+        return 304, headers, b""
+    return 200, {**headers, "Content-Type": content_type}, body.encode("utf-8")
+
+
+def _json_response(data: Any) -> tuple[int, dict[str, str], bytes]:
+    return 200, {"Content-Type": "application/json; charset=utf-8"}, dump_json(data).encode("utf-8")
+
+
+async def _read_json_body(receive: Any):
+    chunks: list[bytes] = []
+    total = 0
+    while True:
+        message = await receive()
+        if message["type"] != "http.request":
+            raise BadRequestError("Unexpected ASGI message while reading the body.")
+        chunk = message.get("body", b"")
+        total += len(chunk)
+        if total > MAX_JSON_BYTES:
+            raise BadRequestError("Request body exceeds the maximum size.")
+        chunks.append(chunk)
+        if not message.get("more_body", False):
+            break
+    body = b"".join(chunks).decode("utf-8", errors="replace")
+    if not body.strip():
+        return {}
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        raise BadRequestError("Request body is not valid JSON.") from None
+
+
+async def _lifespan(receive: Any, send: Any) -> None:
+    while True:
+        message = await receive()
+        if message["type"] == "lifespan.startup":
+            await send({"type": "lifespan.startup.complete"})
+        elif message["type"] == "lifespan.shutdown":
+            await send({"type": "lifespan.shutdown.complete"})
+            return
+
+
+async def _send_response(send: Any, status: int, headers: dict[str, str], body: bytes) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [(key.encode("latin-1"), value.encode("latin-1")) for key, value in headers.items()],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})