htbp-sdk 0.1.0__py3-none-any.whl

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/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})

htbp/describe.py

@@ -0,0 +1,55 @@
+"""Node -> help payload projection (mirror of core/describe.ts).
+
+Payload dicts preserve the TypeScript key order so serialized output matches
+across the two SDKs. Tool leaves are emitted as kind ``http`` for wire
+compatibility with tool-bridge's remote-node sanitizer."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .tree import AppNode, DirectoryNode, RemoteNode, ToolNode
+
+
+def describe_directory(node: DirectoryNode) -> dict[str, Any]:
+    resources = []
+    for child in node.children.values():
+        ref: dict[str, Any] = {
+            "name": child.id,
+            # INVARIANT: relative path, so the subtree stays mountable anywhere.
+            "path": f"./{quote(child.id, safe='')}",
+        }
+        description = _child_description(child)
+        if description is not None:
+            ref["description"] = description
+        resources.append(ref)
+    payload: dict[str, Any] = {"htbp": "draft", "kind": "directory", "title": node.title}
+    if node.description is not None:
+        payload["description"] = node.description
+    payload["resources"] = resources
+    return payload
+
+
+def _child_description(child: AppNode) -> str | None:
+    if child.description:
+        return child.description
+    if isinstance(child, RemoteNode):
+        return "Remote HTBP server."
+    return None
+
+
+def describe_tool(node: ToolNode) -> dict[str, Any]:
+    endpoint: dict[str, Any] = {"method": "POST"}
+    if node.input_schema is not None:
+        endpoint["inputSchema"] = node.input_schema
+    if node.output_schema is not None:
+        endpoint["outputSchema"] = node.output_schema
+    if node.example is not None:
+        endpoint["example"] = node.example
+    endpoint["effect"] = node.effect
+    payload: dict[str, Any] = {"htbp": "draft", "kind": "http", "title": node.title}
+    if node.description is not None:
+        payload["description"] = node.description
+    payload["endpoint"] = endpoint
+    return payload

htbp/errors.py

@@ -0,0 +1,35 @@
+"""Error hierarchy mapped to the HTBP error envelope
+``{"error":{"code","message","details?"}}`` with an HTTP status."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class HtbpError(Exception):
+    def __init__(self, status: int, code: str, message: str, details: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details
+
+
+class NotFoundError(HtbpError):
+    def __init__(self, message: str) -> None:
+        super().__init__(404, "not_found", message)
+
+
+class MethodNotAllowedError(HtbpError):
+    def __init__(self, message: str) -> None:
+        super().__init__(405, "method_not_allowed", message)
+
+
+class BadRequestError(HtbpError):
+    def __init__(self, message: str, details: Any = None) -> None:
+        super().__init__(400, "bad_request", message, details)
+
+
+class UpstreamError(HtbpError):
+    def __init__(self, message: str, details: Any = None) -> None:
+        super().__init__(502, "upstream_error", message, details)

htbp/http.py

@@ -0,0 +1,55 @@
+"""HTTP plumbing shared by the ASGI handler and the remote client — mirror of
+the TypeScript SDK's core/http.ts."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json as _json
+import re
+from typing import Any
+
+MAX_JSON_BYTES = 1_000_000
+REMOTE_FETCH_TIMEOUT_S = 5.0
+
+CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type, Accept, If-None-Match",
+}
+
+
+def dump_json(data: Any) -> str:
+    # Matches JSON.stringify(data, null, 2): 2-space indent, ": " separator,
+    # no ASCII escaping of non-ASCII characters.
+    return _json.dumps(data, indent=2, ensure_ascii=False)
+
+
+def error_body(code: str, message: str, details: Any = None) -> str:
+    error: dict[str, Any] = {"code": code, "message": message}
+    if details is not None:
+        error["details"] = details
+    return dump_json({"error": error})
+
+
+def etag_of(body: str) -> str:
+    digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    return f'"{digest[:16]}"'
+
+
+def if_none_match_matches(header: str, etag: str) -> bool:
+    candidates = [candidate.strip() for candidate in header.split(",")]
+    return any(candidate == etag or candidate == "*" for candidate in candidates)
+
+
+def constant_time_equal(a: str, b: str) -> bool:
+    hash_a = hashlib.sha256(a.encode("utf-8")).hexdigest()
+    hash_b = hashlib.sha256(b.encode("utf-8")).hexdigest()
+    return hmac.compare_digest(hash_a, hash_b)
+
+
+def get_bearer_token(authorization: str | None) -> str | None:
+    if not authorization:
+        return None
+    match = re.match(r"^Bearer\s+(.+)$", authorization.strip(), re.IGNORECASE)
+    return match.group(1) if match else None

htbp/remote.py

@@ -0,0 +1,188 @@
+"""Remote HTBP node: pass through ``~help`` for any sub-path and proxy calls,
+never forwarding local credentials — mirror of the TypeScript SDK's
+core/remote.ts. Requires the ``htbp-sdk[remote]`` extra (httpx)."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+from .errors import HtbpError, NotFoundError, UpstreamError
+from .http import MAX_JSON_BYTES, REMOTE_FETCH_TIMEOUT_S
+from .tree import EFFECTS, RemoteNode
+
+_VALID_KINDS = ("directory", "http", "remote")
+
+
+def _httpx():
+    try:
+        import httpx
+    except ImportError as error:  # pragma: no cover
+        raise RuntimeError(
+            "Remote nodes require httpx; install the extra: pip install 'htbp-sdk[remote]'."
+        ) from error
+    return httpx
+
+
+def remote_base_url(help_url: str) -> str:
+    return re.sub(r"/?~help/?$", "", help_url).rstrip("/")
+
+
+def _require_secure_url(node: RemoteNode, raw: str) -> str:
+    parts = urlsplit(raw)
+    if parts.scheme not in ("http", "https"):
+        raise UpstreamError(f"Remote URL '{raw}' must be http(s).")
+    host = parts.hostname or ""
+    is_local = host in ("localhost", "127.0.0.1", "::1")
+    if parts.scheme != "https" and not (node.allow_insecure or is_local):
+        raise UpstreamError(f"Remote URL '{raw}' must use https (set allow_insecure for development).")
+    return raw
+
+
+def _remote_target(node: RemoteNode, sub: list[str]) -> str:
+    for segment in sub:
+        if segment in (".", "..") or not segment:
+            raise NotFoundError(f"Invalid remote sub-path segment '{segment}'.")
+    base = remote_base_url(node.help_url)
+    suffix = "/".join(quote(segment, safe="") for segment in sub)
+    return _require_secure_url(node, f"{base}/{suffix}" if suffix else base)
+
+
+def _remote_headers(node: RemoteNode, extra: dict[str, str]) -> dict[str, str]:
+    # Only the per-remote configured headers ever go upstream; the inbound
+    # Authorization header is deliberately never forwarded.
+    headers = dict(node.headers or {})
+    headers.update(extra)
+    return headers
+
+
+async def _bounded_request(method: str, url: str, headers: dict[str, str], content: str | None, timeout: float) -> tuple[int, str]:
+    httpx = _httpx()
+    async with httpx.AsyncClient(follow_redirects=False, timeout=timeout) as client:
+        response = await client.request(method, url, headers=headers, content=content)
+        if 300 <= response.status_code < 400:
+            raise UpstreamError(f"Remote '{url}' responded with a redirect ({response.status_code}); redirects are not followed.")
+        body = response.text
+        if len(body.encode("utf-8")) > MAX_JSON_BYTES:
+            raise UpstreamError("Remote response body exceeded the maximum size.")
+        return response.status_code, body
+
+
+async def remote_describe(node: RemoteNode, sub: list[str]) -> dict[str, Any]:
+    target = _remote_target(node, sub)
+    help_url = f"{target.rstrip('/')}/~help"
+    try:
+        status, body = await _bounded_request(
+            "GET", help_url, _remote_headers(node, {"Accept": "application/json"}), None, REMOTE_FETCH_TIMEOUT_S
+        )
+    except HtbpError:
+        raise
+    except Exception as error:
+        raise UpstreamError(f"Failed to fetch remote help: {error}") from error
+    if status == 404:
+        raise NotFoundError(f"Remote resource '/{'/'.join(sub)}' not found.")
+    if status != 200:
+        raise UpstreamError(f"Remote help returned {status}.", body[:2000] or None)
+    try:
+        payload = parse_help_payload(body)
+    except Exception as error:
+        raise UpstreamError(f"Invalid remote help payload: {error}") from error
+    if not sub:
+        payload["kind"] = "remote"
+        payload["title"] = node.title or payload["title"]
+        if node.description is not None:
+            payload["description"] = node.description
+    return payload
+
+
+async def remote_call(node: RemoteNode, sub: list[str], input_value: Any) -> Any:
+    target = _remote_target(node, sub)
+    try:
+        status, body = await _bounded_request(
+            "POST",
+            target,
+            _remote_headers(node, {"Content-Type": "application/json", "Accept": "application/json"}),
+            json.dumps(input_value if input_value is not None else {}),
+            REMOTE_FETCH_TIMEOUT_S,
+        )
+    except HtbpError:
+        raise
+    except Exception as error:
+        raise UpstreamError(f"Remote call failed: {error}") from error
+    try:
+        parsed = json.loads(body) if body else None
+    except json.JSONDecodeError:
+        raise UpstreamError(f"Remote call returned non-JSON (status {status}).") from None
+    if status != 200:
+        if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
+            error = parsed["error"]
+            if isinstance(error.get("code"), str) and isinstance(error.get("message"), str):
+                raise HtbpError(status, error["code"], error["message"], error.get("details"))
+        raise UpstreamError(f"Remote call returned {status}.", parsed)
+    if isinstance(parsed, dict) and "result" in parsed and "resource" in parsed:
+        return parsed["result"]
+    return parsed
+
+
+async def fetch_remote_summary(node: RemoteNode, timeout: float = 1.5) -> dict[str, Any] | None:
+    """Best-effort title/description for directory listings; None on failure."""
+    try:
+        help_url = f"{remote_base_url(node.help_url)}/~help"
+        _require_secure_url(node, help_url)
+        status, body = await _bounded_request(
+            "GET", help_url, _remote_headers(node, {"Accept": "application/json"}), None, timeout
+        )
+        if status != 200:
+            return None
+        payload = parse_help_payload(body)
+        return {"title": payload.get("title"), "description": payload.get("description")}
+    except Exception:
+        return None
+
+
+def parse_help_payload(body: str) -> dict[str, Any]:
+    """Tolerantly validate an untrusted JSON help payload into our shape."""
+    parsed = json.loads(body)
+    if not isinstance(parsed, dict):
+        raise ValueError("Remote help payload is not a JSON object.")
+    kind = parsed.get("kind") if parsed.get("kind") in _VALID_KINDS else "directory"
+    payload: dict[str, Any] = {
+        "htbp": "draft",
+        "kind": kind,
+        "title": parsed["title"] if isinstance(parsed.get("title"), str) else "Remote HTBP server",
+    }
+    if isinstance(parsed.get("description"), str):
+        payload["description"] = parsed["description"]
+    if isinstance(parsed.get("cachable"), bool):
+        payload["cachable"] = parsed["cachable"]
+    resources = _parse_resources(parsed.get("resources"))
+    if resources is not None:
+        payload["resources"] = resources
+    if isinstance(parsed.get("endpoint"), dict):
+        payload["endpoint"] = _sanitize_endpoint(parsed["endpoint"])
+    return payload
+
+
+def _parse_resources(value: Any) -> list[dict[str, Any]] | None:
+    if not isinstance(value, list):
+        return None
+    refs = []
+    for item in value:
+        if isinstance(item, dict) and isinstance(item.get("name"), str) and isinstance(item.get("path"), str):
+            ref: dict[str, Any] = {"name": item["name"], "path": item["path"]}
+            if isinstance(item.get("description"), str):
+                ref["description"] = item["description"]
+            refs.append(ref)
+    return refs
+
+
+def _sanitize_endpoint(value: dict[str, Any]) -> dict[str, Any]:
+    endpoint: dict[str, Any] = {"method": value["method"] if isinstance(value.get("method"), str) else "POST"}
+    for key in ("inputSchema", "outputSchema", "example"):
+        if key in value:
+            endpoint[key] = value[key]
+    if value.get("effect") in EFFECTS:
+        endpoint["effect"] = value["effect"]
+    return endpoint

htbp/schema.py

@@ -0,0 +1,122 @@
+"""Function signature -> pydantic model -> JSON Schema, FastAPI-style.
+
+Rules:
+- Every regular parameter becomes an input field; type hints map to pydantic
+  field types (missing hints default to Any), defaults make fields optional.
+- A parameter annotated with ``ToolContext`` is injected at call time and
+  excluded from the schema.
+- Exactly one non-context parameter annotated with a ``BaseModel`` subclass
+  makes that model the input schema directly (the "body model" style).
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel, ValidationError, create_model
+
+
+@dataclass
+class ToolContext:
+    """Request context injected into ToolContext-annotated parameters."""
+
+    path: str
+    headers: dict[str, str]
+    scope: dict[str, Any]
+
+
+@dataclass
+class CompiledTool:
+    json_schema: dict[str, Any] | None
+    validate: Any  # (input) -> (ok, value_or_issues)
+    bind: Any  # (validated_value, ctx) -> kwargs dict for fn
+
+
+def compile_function(fn: Any) -> CompiledTool:
+    signature = inspect.signature(fn)
+    try:
+        hints = get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    ctx_params: list[str] = []
+    field_params: list[inspect.Parameter] = []
+    for param in signature.parameters.values():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            raise TypeError(f"Tool '{fn.__name__}' cannot use *args/**kwargs parameters.")
+        annotation = hints.get(param.name, param.annotation)
+        if annotation is ToolContext:
+            ctx_params.append(param.name)
+        else:
+            field_params.append(param)
+
+    body_model = _single_body_model(field_params, hints)
+    if body_model is not None:
+        model, body_param = body_model
+        return CompiledTool(
+            json_schema=model.model_json_schema(),
+            validate=_model_validator(model),
+            bind=lambda value, ctx: {body_param: value, **{name: ctx for name in ctx_params}},
+        )
+
+    fields: dict[str, Any] = {}
+    for param in field_params:
+        annotation = hints.get(param.name, param.annotation)
+        if annotation is inspect.Parameter.empty:
+            annotation = Any
+        default = ... if param.default is inspect.Parameter.empty else param.default
+        fields[param.name] = (annotation, default)
+
+    if not fields:
+        return CompiledTool(
+            json_schema=None,
+            validate=lambda value: (True, value),
+            bind=lambda value, ctx: {name: ctx for name in ctx_params},
+        )
+
+    model = create_model(f"{_camel(fn.__name__)}Input", **fields)
+    field_names = list(fields)
+    return CompiledTool(
+        json_schema=model.model_json_schema(),
+        validate=_model_validator(model),
+        bind=lambda value, ctx: {
+            **{name: getattr(value, name) for name in field_names},
+            **{name: ctx for name in ctx_params},
+        },
+    )
+
+
+def _single_body_model(
+    params: list[inspect.Parameter], hints: dict[str, Any]
+) -> tuple[type[BaseModel], str] | None:
+    if len(params) != 1:
+        return None
+    annotation = hints.get(params[0].name, params[0].annotation)
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation, params[0].name
+    return None
+
+
+def _model_validator(model: type[BaseModel]):
+    def validate(value: Any) -> tuple[bool, Any]:
+        if not isinstance(value, dict):
+            return False, [{"type": "model_type", "msg": "Input must be a JSON object."}]
+        try:
+            return True, model.model_validate(value)
+        except ValidationError as error:
+            return False, error.errors(include_url=False)
+
+    return validate
+
+
+def output_json_schema(annotation: Any) -> dict[str, Any] | None:
+    """Documentation-only output schema from a BaseModel return annotation."""
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation.model_json_schema()
+    return None
+
+
+def _camel(name: str) -> str:
+    return "".join(part.capitalize() for part in name.split("_"))

htbp/text_help.py

@@ -0,0 +1,74 @@
+"""Text/plain HTBP DSL rendering of a JSON help payload — mirror of the
+TypeScript SDK's protocol/text-help.ts (RFC-0001 §8)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+MAX_SHAPE_LENGTH = 120
+_SIMPLE_TYPES = {"string", "integer", "number", "boolean", "object", "array"}
+
+
+def one_line(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def build_text_help(payload: dict[str, Any], resource_path: str, auth: str, has_skill: bool) -> str:
+    lines = [
+        "htbp draft",
+        f"resource {resource_path}",
+        f"title {one_line(payload['title'])}",
+    ]
+    if payload.get("description"):
+        lines.append(f"summary {one_line(payload['description'])}")
+    if has_skill:
+        lines.append("skill ./~skill")
+    lines.append(f"auth {auth}")
+    lines.append("")
+
+    endpoint = payload.get("endpoint")
+    if endpoint:
+        lines.append(f"cmd call {endpoint['method']} {resource_path}")
+        lines.append(f"  body application/json {compact_shape(endpoint.get('inputSchema'))}")
+        lines.append(f"  auth {auth}")
+        lines.append(f"  effect {endpoint.get('effect') or 'unknown'}")
+        lines.append("  returns 200 application/json")
+
+    for resource in payload.get("resources") or []:
+        lines.append(f"link child {join_relative(resource_path, resource['path'])}/~help")
+        if resource.get("description"):
+            lines.append(f"  note {one_line(resource['description'])}")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def compact_shape(schema: Any) -> str:
+    """Render a JSON Schema as the RFC §8.6 compact body shape, e.g.
+    ``{"a":integer,"b":integer?}``; fall back to ``object`` when it would not
+    stay compact."""
+    if not isinstance(schema, dict) or schema.get("type") != "object" or not isinstance(schema.get("properties"), dict):
+        return "object"
+    required = schema.get("required") if isinstance(schema.get("required"), list) else []
+    fields = []
+    for name, prop in schema["properties"].items():
+        optional = "" if name in required else "?"
+        fields.append(f'"{name}":{_shape_type(prop)}{optional}')
+    shape = "{" + ",".join(fields) + "}"
+    return "object" if len(shape) > MAX_SHAPE_LENGTH else shape
+
+
+def _shape_type(prop: Any) -> str:
+    if isinstance(prop, dict) and prop.get("type") in _SIMPLE_TYPES:
+        return prop["type"]
+    return "json"
+
+
+def join_relative(base: str, relative: str) -> str:
+    prefix = "" if base == "/" else base.rstrip("/")
+    if relative.startswith("./"):
+        return f"{prefix}/{relative[2:]}"
+    if relative.startswith("../"):
+        parent = "/".join(prefix.split("/")[:-1])
+        return f"{parent}/{relative[3:]}"
+    return f"{prefix}/{relative}"

htbp/tree.py

@@ -0,0 +1,112 @@
+"""In-memory app tree and path resolution — line-for-line mirror of the
+TypeScript SDK's core/tree.ts (itself a reduction of tool-bridge's
+registry.ts)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Union
+
+Effect = str  # 'read' | 'write' | 'delete' | 'external' | 'unknown'
+EFFECTS = ("read", "write", "delete", "external", "unknown")
+
+# validate(input) -> (ok, value_or_issues)
+Validator = Callable[[Any], tuple[bool, Any]]
+Handler = Callable[..., Any]
+
+
+@dataclass
+class DirectoryNode:
+    id: str
+    title: str
+    description: str | None = None
+    skill: str | None = None
+    children: dict[str, "AppNode"] = field(default_factory=dict)
+
+    kind = "directory"
+
+
+@dataclass
+class ToolNode:
+    id: str
+    title: str
+    validate: Validator
+    call: Callable[[Any, Any], Awaitable[Any]]  # (validated_input, ctx) -> result
+    description: str | None = None
+    skill: str | None = None
+    effect: Effect = "unknown"
+    example: Any = None
+    input_schema: Any = None
+    output_schema: Any = None
+
+    kind = "tool"
+
+
+@dataclass
+class RemoteNode:
+    id: str
+    title: str
+    help_url: str
+    description: str | None = None
+    headers: dict[str, str] | None = None
+    allow_insecure: bool = False
+
+    kind = "remote"
+
+
+AppNode = Union[DirectoryNode, ToolNode, RemoteNode]
+
+_SEGMENT_PATTERN = re.compile(r"^[^/?#]+$")
+
+
+def assert_valid_segment(segment: str, context: str) -> None:
+    if not _SEGMENT_PATTERN.match(segment) or segment in (".", "..") or segment.startswith("~"):
+        raise ValueError(f"{context}: '{segment}' is not a valid path segment.")
+
+
+def add_child(parent: DirectoryNode, node: AppNode) -> None:
+    assert_valid_segment(node.id, "Node id")
+    if node.id in parent.children:
+        raise ValueError(f"Duplicate sibling id '{node.id}'.")
+    parent.children[node.id] = node
+
+
+def path_segments(path: str) -> list[str]:
+    segments = [segment for segment in path.split("/") if segment]
+    if not segments:
+        raise ValueError(f"Mount path '{path}' must contain at least one segment.")
+    for segment in segments:
+        assert_valid_segment(segment, f"Mount path '{path}'")
+    return segments
+
+
+def ensure_directory(root: DirectoryNode, segments: list[str]) -> DirectoryNode:
+    current = root
+    for segment in segments:
+        existing = current.children.get(segment)
+        if existing is not None:
+            if not isinstance(existing, DirectoryNode):
+                raise ValueError(f"Cannot create directory '{segment}': a {existing.kind} node already uses that id.")
+            current = existing
+        else:
+            created = DirectoryNode(id=segment, title=segment)
+            current.children[segment] = created
+            current = created
+    return current
+
+
+def resolve(root: DirectoryNode, segments: list[str]) -> tuple[AppNode, list[str]] | None:
+    """Walk directory children by URL segments; a tool/remote node stops
+    descent and the leftover segments become its sub-path."""
+    current: AppNode = root
+    index = 0
+    while index < len(segments):
+        if not isinstance(current, DirectoryNode):
+            break
+        nxt = current.children.get(segments[index])
+        if nxt is None:
+            return None
+        current = nxt
+        index += 1
+    return current, segments[index:]

htbp_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+htbp/__init__.py,sha256=ghRZBHn8lYI0S6cyTDPhJSJOJBtd4tRqmsQqELENgJI,737
+htbp/app.py,sha256=kbrOfBuAqxNYB0zEu4YELvOIx5Nz2DmCHVz-FLZRSeQ,15911
+htbp/describe.py,sha256=w0klUShz53Iknoi96KWN58XwdZtgv2UVyFRrGx7qS6k,1984
+htbp/errors.py,sha256=EMRfwh7dj38vhbM9MlAPQtDyZB5NlwOVNtQ12zsBro4,1066
+htbp/http.py,sha256=NVlM8VOjzx1C2DbdO2hNKx6Du9Xde7rMjI3mv1C5xUc,1748
+htbp/remote.py,sha256=2SVYWg_MGowlZ7yKiaO98qb_-BxLCMrLMMmyS0Zwq9c,7776
+htbp/schema.py,sha256=74qIwz-gJ8SC3VEkfkaJjlZnwQBpQBDjWRJPNvTFT_U,4169
+htbp/text_help.py,sha256=r3q246yWKAIkvpKRhuEvTkEDCsZjc090rpOs2prdJZw,2747
+htbp/tree.py,sha256=EY526r7Hx8ZVWni0NhUOABlaTe-Ik_hMmUzWqYDdSzU,3383
+htbp_sdk-0.1.0.dist-info/METADATA,sha256=29ZIdBn-MX6Psi35oXRqh_Kg3TUSNGeuh8n-gbnHuCM,2382
+htbp_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+htbp_sdk-0.1.0.dist-info/RECORD,,

htbp_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any