xyberos-http-api 0.1.0__py3-none-any.whl

xyberos_http_api/__init__.py

@@ -0,0 +1,30 @@
+"""Generic HTTP/API connector plugin (RFC-0019, M2).
+
+"Point at any REST API, get typed tools." A declarative spec (JSON / YAML /
+Python ``dict``) describes a ``base_url``, optional auth, optional rate
+limiting, and one *operation* per endpoint. Each operation becomes a typed
+:class:`~xyberos.contracts.Tool` whose parameters are validated and coerced
+through :class:`~xyberos.tools.FunctionTool`.
+
+Everything here builds on the public ``xyberos`` API only — no runtime
+dependencies beyond the standard library.
+"""
+
+from .builder import build_operation_tool
+from .client import HttpClient
+from .errors import HttpApiError
+from .plugin import HttpApiPlugin
+from .spec import AuthSpec, HttpApiSpec, Operation, Param, RateLimitSpec, load_spec
+
+__all__ = [
+    "AuthSpec",
+    "HttpApiError",
+    "HttpApiPlugin",
+    "HttpApiSpec",
+    "HttpClient",
+    "Operation",
+    "Param",
+    "RateLimitSpec",
+    "build_operation_tool",
+    "load_spec",
+]

xyberos_http_api/auth.py

@@ -0,0 +1,136 @@
+"""Authentication strategies for the HTTP/API connector.
+
+Secrets are resolved from environment variables first (``*_env`` fields), then
+fall back to literal values. ``api_key``, ``bearer`` and ``basic`` are
+stateless; ``oauth2`` (client_credentials) fetches a token from ``token_url``
+and caches it for reuse.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import HttpApiError
+from .spec import AuthSpec
+
+#: Injectable ``urlopen``-shaped transport for tests (no network needed).
+UrlOpen = Callable[..., Any]
+
+
+def _default_urlopen(request: Any, timeout: float) -> Any:
+    return urllib.request.urlopen(request, timeout=timeout)
+
+
+@dataclass
+class ResolvedAuth:
+    """Headers and query params produced by resolving an auth strategy."""
+
+    headers: dict[str, str] = field(default_factory=dict)
+    query: dict[str, str] = field(default_factory=dict)
+
+
+class AuthResolver:
+    """Resolves an :class:`AuthSpec` into concrete headers/query params."""
+
+    def __init__(
+        self,
+        auth: AuthSpec,
+        *,
+        urlopen: UrlOpen | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._auth = auth
+        self._urlopen = urlopen or _default_urlopen
+        self._timeout = timeout
+        self._token: str | None = None
+        self._token_url: str | None = None
+
+    def resolve(self) -> ResolvedAuth:
+        """Return the auth headers/query for the current request."""
+        kind = self._auth.type or "none"
+        if kind == "none":
+            return ResolvedAuth()
+        if kind == "api_key":
+            return self._api_key()
+        if kind == "bearer":
+            return self._bearer()
+        if kind == "basic":
+            return self._basic()
+        if kind == "oauth2":
+            return self._oauth2()
+        raise HttpApiError(status=None, body=f"unsupported auth type: {kind}")
+
+    # -- helpers ------------------------------------------------------------
+
+    @staticmethod
+    def _secret(literal: str | None, env: str | None) -> str | None:
+        if env:
+            value = os.getenv(env)
+            if value is not None:
+                return value
+        return literal
+
+    def _api_key(self) -> ResolvedAuth:
+        value = self._secret(self._auth.value, self._auth.env)
+        if not value:
+            return ResolvedAuth()
+        if self._auth.key_in == "query":
+            return ResolvedAuth(query={self._auth.key_name: value})
+        return ResolvedAuth(headers={self._auth.key_name: value})
+
+    def _bearer(self) -> ResolvedAuth:
+        token = self._secret(self._auth.token, self._auth.token_env)
+        if not token:
+            return ResolvedAuth()
+        return ResolvedAuth(headers={"Authorization": f"Bearer {token}"})
+
+    def _basic(self) -> ResolvedAuth:
+        username = self._secret(self._auth.username, self._auth.username_env) or ""
+        password = self._secret(self._auth.password, self._auth.password_env) or ""
+        raw = f"{username}:{password}".encode("utf-8")
+        encoded = base64.b64encode(raw).decode("ascii")
+        return ResolvedAuth(headers={"Authorization": f"Basic {encoded}"})
+
+    def _oauth2(self) -> ResolvedAuth:
+        auth = self._auth
+        token_url = auth.token_url
+        if not token_url:
+            raise HttpApiError(status=None, body="oauth2 auth requires a 'token_url'")
+        if self._token and self._token_url == token_url:
+            return ResolvedAuth(headers={"Authorization": f"Bearer {self._token}"})
+        client_id = self._secret(auth.client_id, auth.client_id_env) or ""
+        client_secret = self._secret(auth.client_secret, auth.client_secret_env) or ""
+        form = {
+            "grant_type": "client_credentials",
+            "client_id": client_id,
+            "client_secret": client_secret,
+        }
+        if auth.scope:
+            form["scope"] = auth.scope
+        data = urllib.parse.urlencode(form).encode("utf-8")
+        request = urllib.request.Request(
+            token_url,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            method="POST",
+        )
+        try:
+            with self._urlopen(request, self._timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as exc:
+            raise HttpApiError(exc.code, exc.read().decode("utf-8", errors="replace")) from exc
+        payload = json.loads(raw.decode("utf-8", errors="replace"))
+        token = payload.get("access_token")
+        if not token:
+            raise HttpApiError(status=None, body="oauth2 token response had no access_token")
+        self._token = str(token)
+        self._token_url = token_url
+        return ResolvedAuth(headers={"Authorization": f"Bearer {self._token}"})

xyberos_http_api/builder.py

@@ -0,0 +1,138 @@
+"""Turn declared operations into typed :class:`~xyberos.contracts.Tool`s.
+
+Each operation becomes a :class:`~xyberos.tools.FunctionTool` whose signature
+is derived from the declared parameters. ``FunctionTool`` then handles JSON
+schema generation, argument validation, and coercion through
+``coerce_arguments`` — so an LLM (or a user) passing ``"10.5"`` for a ``number``
+parameter gets it coerced to ``10.5``.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any
+
+from xyberos.contracts import Tool
+from xyberos.tools import FunctionTool
+
+from .client import HttpClient
+from .spec import HttpApiSpec, Operation, Param
+
+_TOKEN_RE = re.compile(r"\[(\d+)\]")
+
+
+def _safe_identifier(name: str) -> str:
+    """Turn an arbitrary param/header name into a valid Python identifier."""
+    ident = re.sub(r"\W", "_", name)
+    if not ident:
+        ident = "param"
+    if ident[0].isdigit():
+        ident = "_" + ident
+    return ident
+
+
+def make_typed_callable(name: str, params: list[Param], impl: Any) -> Any:
+    """Build a callable whose ``__signature__`` matches the declared params.
+
+    ``impl(kwargs)`` receives the validated/coerced arguments as a dict keyed
+    by the **declared** param names. ``inspect.signature`` honors
+    ``__signature__``, so both :func:`~xyberos.tools.build_json_schema` and
+    :func:`~xyberos.tools.coerce_arguments` see the declared, typed signature.
+    Parameter names that are not valid Python identifiers (e.g. header names
+    like ``X-Trace``) are sanitized for the signature and mapped back.
+    """
+    mapping: dict[str, str] = {}
+    signature_params: list[inspect.Parameter] = []
+    for param in params:
+        sig_name = param.name if param.name.isidentifier() else _safe_identifier(param.name)
+        mapping[sig_name] = param.name
+        if param.required:
+            signature_params.append(
+                inspect.Parameter(
+                    sig_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=param.python_type,
+                )
+            )
+        else:
+            signature_params.append(
+                inspect.Parameter(
+                    sig_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=param.default,
+                    annotation=param.python_type,
+                )
+            )
+    signature = inspect.Signature(parameters=signature_params)
+
+    def _call(**kwargs: Any) -> Any:
+        real = {mapping.get(key, key): value for key, value in kwargs.items()}
+        return impl(real)
+
+    _call.__name__ = name
+    _call.__qualname__ = name
+    _call.__signature__ = signature
+    return _call
+
+
+def extract_path(data: Any, path: str | None) -> Any:
+    """Extract a dotted path (with optional ``[index]`` steps) from JSON data."""
+    if not path:
+        return data
+    current = data
+    for part in path.split("."):
+        match = _TOKEN_RE.search(part)
+        key = _TOKEN_RE.sub("", part) if match else part
+        if key and isinstance(current, dict):
+            current = current.get(key)
+        elif key and not isinstance(current, dict):
+            return None
+        if match and isinstance(current, list):
+            try:
+                current = current[int(match.group(1))]
+            except (IndexError, ValueError):
+                return None
+    return current
+
+
+def build_operation_tool(
+    spec: HttpApiSpec,
+    operation: Operation,
+    client: HttpClient,
+    *,
+    prefix: str = "",
+) -> Tool:
+    """Build one typed tool for ``operation`` backed by ``client``."""
+
+    def _impl(arguments: dict[str, Any]) -> Any:
+        path = operation.path
+        query: dict[str, Any] = {}
+        body: Any = None
+        extra_headers: dict[str, str] = {}
+        for param in operation.params:
+            if param.name not in arguments:
+                continue
+            value = arguments[param.name]
+            if param.in_ == "path":
+                path = path.replace("{" + param.name + "}", str(value))
+            elif param.in_ == "query":
+                query[param.name] = value
+            elif param.in_ == "header":
+                extra_headers[param.name] = str(value)
+            elif param.in_ == "body":
+                body = value
+        result = client.request(
+            operation.method,
+            path,
+            query=query,
+            body=body,
+            headers=extra_headers,
+        )
+        if operation.response_format == "text":
+            return result
+        return extract_path(result, operation.response_path)
+
+    name = f"{prefix}{operation.name}" if prefix else operation.name
+    callable_func = make_typed_callable(name, list(operation.params), _impl)
+    return FunctionTool(name, callable_func, description=operation.description)

xyberos_http_api/client.py

@@ -0,0 +1,126 @@
+"""Minimal dependency-free HTTP client used by generated operation tools.
+
+Uses only the standard library (``urllib``), applies the declared auth, merges
+the declared headers, and optionally throttles calls with the core's
+:class:`~xyberos.utils.resilience.RateLimiter`. The ``urlopen`` transport is
+injectable so tests can run without a network.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from xyberos.utils.resilience import RateLimiter
+
+from .auth import AuthResolver, ResolvedAuth, UrlOpen
+from .errors import HttpApiError
+from .spec import AuthSpec, RateLimitSpec
+
+#: Injectable ``urlopen``-shaped transport (defaults to the stdlib opener).
+UrlOpenCallable = Callable[..., Any]
+
+
+def _default_urlopen(request: Any, timeout: float) -> Any:
+    return urllib.request.urlopen(request, timeout=timeout)
+
+
+class HttpClient:
+    """A tiny typed-over-JSON HTTP client for one API base URL."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        auth: AuthSpec | None = None,
+        rate_limit: RateLimitSpec | None = None,
+        timeout: float = 30.0,
+        urlopen: UrlOpen | None = None,
+    ) -> None:
+        self._base_url = str(base_url).rstrip("/")
+        self._headers = dict(headers or {})
+        self._auth_resolver = AuthResolver(auth, urlopen=urlopen, timeout=timeout) if auth else None
+        self._timeout = timeout
+        self._urlopen = urlopen or _default_urlopen
+        self._limiter: RateLimiter | None = None
+        if rate_limit is not None:
+            self._limiter = RateLimiter(
+                calls_per_second=rate_limit.calls_per_second,
+                burst=rate_limit.burst,
+            )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Send one request and return the decoded body (JSON dict/list or text)."""
+        resolved = self._auth_resolver.resolve() if self._auth_resolver else ResolvedAuth()
+
+        url = self._base_url + (path or "/")
+        query_params = dict(resolved.query)
+        query_params.update({k: v for k, v in (query or {}).items() if v is not None})
+        if query_params:
+            separator = "&" if "?" in url else "?"
+            url += separator + urllib.parse.urlencode(query_params)
+
+        request_headers = dict(self._headers)
+        request_headers.update(resolved.headers)
+        request_headers.update(headers or {})
+
+        data: bytes | None = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            request_headers.setdefault("Content-Type", "application/json")
+
+        if self._limiter is not None:
+            self._limiter.acquire()
+
+        request = urllib.request.Request(url, data=data, headers=request_headers, method=method)
+        try:
+            with self._urlopen(request, self._timeout) as response:
+                status = int(getattr(response, "status", 200))
+                raw = response.read()
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            raw = exc.read()
+
+        text = raw.decode("utf-8", errors="replace") if raw else ""
+        if not 200 <= status < 300:
+            raise HttpApiError(status, text)
+        if not text:
+            return None
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return text
+
+    # -- convenience verbs --------------------------------------------------
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)

xyberos_http_api/errors.py

@@ -0,0 +1,19 @@
+"""Errors raised by the HTTP/API connector."""
+
+from __future__ import annotations
+
+
+class HttpApiError(Exception):
+    """Raised when an API request fails (non-2xx status or transport error).
+
+    ``status`` is the HTTP status code (or ``None`` for transport errors) and
+    ``body`` carries the raw response text when one was returned.
+    """
+
+    def __init__(self, status: int | None = None, body: str = "") -> None:
+        self.status = status
+        self.body = body
+        message = f"HTTP {status}" if status is not None else "transport error"
+        if body:
+            message += f": {body[:200]}"
+        super().__init__(message)

xyberos_http_api/plugin.py

@@ -0,0 +1,134 @@
+"""Generic HTTP/API connector plugin (RFC-0019, M2).
+
+Ships as a plugin using only the public ``xyberos`` API — the ``Plugin``
+contract plus ``Tool`` / ``FunctionTool``. A declarative spec (passed directly,
+or loaded from ``HTTP_API_SPEC`` / ``HTTP_API_SPEC_JSON``) yields one typed
+:class:`~xyberos.contracts.Tool` per declared operation.
+
+The module-level ``plugin`` instance is safe to auto-discover via the
+``xyberos.plugins`` entry-point group: when no spec is configured it registers
+nothing and logs a warning instead of raising.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, cast
+
+from xyberos.contracts import Plugin, Tool
+
+from .builder import build_operation_tool
+from .client import HttpClient
+from .spec import HttpApiSpec, load_spec
+
+
+def _pop_tool(registry: Any, name: str) -> None:
+    """Best-effort removal of a tool (ToolRegistry has no public unregister)."""
+    unregister = getattr(registry, "unregister", None)
+    if callable(unregister):
+        unregister(name)
+        return
+    store = getattr(registry, "_tools", None)
+    if isinstance(store, dict):
+        cast(dict[str, Any], store).pop(name, None)
+
+
+def _normalize_specs(spec: Any) -> list[HttpApiSpec]:
+    loaded = load_spec(spec)
+    return loaded if isinstance(loaded, list) else [loaded]
+
+
+class HttpApiPlugin(Plugin):
+    """Registers one typed :class:`Tool` per declared operation."""
+
+    def __init__(self, spec: Any = None, *, env_prefix: str = "HTTP_API") -> None:
+        # Spec resolution is deferred so the module-level instance can be
+        # auto-discovered even before any configuration exists.
+        self._spec_arg = spec
+        self._env_prefix = env_prefix
+        self._specs: list[HttpApiSpec] | None = None
+        self._tools: list[Tool] | None = None
+
+    @property
+    def name(self) -> str:
+        return "http_api"
+
+    # -- public API ---------------------------------------------------------
+
+    def tools(self) -> list[Tool]:
+        """The generated tools; raises if no spec has been configured."""
+        if self._tools is None:
+            specs = self._resolve_specs()
+            built: list[Tool] = []
+            multiple = len(specs) > 1
+            for spec in specs:
+                prefix = f"{spec.name}_" if multiple else ""
+                client = HttpClient(
+                    spec.base_url,
+                    headers=spec.headers,
+                    auth=spec.auth if spec.auth.type != "none" else None,
+                    rate_limit=spec.rate_limit,
+                    timeout=spec.timeout,
+                )
+                for operation in spec.operations:
+                    built.append(build_operation_tool(spec, operation, client, prefix=prefix))
+            self._tools = built
+        return self._tools
+
+    def register(self, kernel: object) -> None:
+        try:
+            tools = self.tools()
+        except ValueError as exc:
+            logger = getattr(kernel, "logger", None)
+            if logger is not None and callable(getattr(logger, "warning", None)):
+                logger.warning("http_api plugin not configured: %s", exc)
+            return
+        registry = kernel.resolve("tools")
+        for tool in tools:
+            registry.register(tool)
+
+    def unregister(self, kernel: object) -> None:
+        if self._spec_arg is None and self._specs is None and not self._configured_via_env():
+            return
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            _pop_tool(registry, tool.name)
+
+    def _configured_via_env(self) -> bool:
+        prefix = self._env_prefix
+        return bool(os.getenv(f"{prefix}_SPEC") or os.getenv(f"{prefix}_SPEC_JSON"))
+
+    # -- internals ----------------------------------------------------------
+
+    def _resolve_specs(self) -> list[HttpApiSpec]:
+        if self._specs is None:
+            if self._spec_arg is not None:
+                self._specs = _normalize_specs(self._spec_arg)
+            else:
+                self._specs = _normalize_specs(self._spec_from_env())
+        return self._specs
+
+    def _spec_from_env(self) -> Any:
+        prefix = self._env_prefix
+        spec_json = os.getenv(f"{prefix}_SPEC_JSON")
+        if spec_json:
+            try:
+                return json.loads(spec_json)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"{prefix}_SPEC_JSON is not valid JSON: {exc}") from exc
+        spec_path = os.getenv(f"{prefix}_SPEC")
+        if spec_path:
+            path = Path(spec_path)
+            if not path.is_file():
+                raise ValueError(f"{prefix}_SPEC points to a missing file: {path}")
+            return path
+        raise ValueError(
+            "http_api plugin is not configured: pass spec=... or set "
+            f"{prefix}_SPEC (path to a JSON/YAML file) or {prefix}_SPEC_JSON"
+        )
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = HttpApiPlugin()

xyberos_http_api/spec.py

@@ -0,0 +1,241 @@
+"""Declarative REST API specification for the HTTP/API connector.
+
+A spec is authored as a Python ``dict``, a JSON file, or a YAML file (the YAML
+dependency is imported lazily). It describes a ``base_url``, optional headers,
+optional auth, optional rate limiting, and a list of *operations* — each of
+which becomes one typed :class:`~xyberos.contracts.Tool`.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from xyberos.exceptions.provider import ProviderError
+
+_TYPE_MAP: dict[str, type] = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+    "array": list,
+    "object": dict,
+}
+
+#: Where a parameter value is placed on the wire.
+_PARAM_LOCATIONS = ("query", "path", "header", "body")
+_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS")
+
+
+@dataclass(frozen=True)
+class Param:
+    """One declared operation parameter."""
+
+    name: str
+    in_: str = "query"  # query | path | header | body
+    type: str = "string"  # string | integer | number | boolean | array | object
+    required: bool = False
+    description: str = ""
+    default: Any = None
+
+    @property
+    def python_type(self) -> type:
+        return _TYPE_MAP.get(self.type, str)
+
+
+@dataclass(frozen=True)
+class Operation:
+    """One declared API operation (an HTTP method + path + typed params)."""
+
+    name: str
+    method: str = "GET"
+    path: str = "/"
+    description: str = ""
+    params: tuple[Param, ...] = ()
+    response_format: str = "json"  # json | text
+    response_path: str | None = None  # dotted path extracted from a JSON body
+
+
+@dataclass(frozen=True)
+class AuthSpec:
+    """Authentication strategy. Secrets come from ``*_env`` variables when set."""
+
+    type: str = "none"  # none | api_key | bearer | basic | oauth2
+    # api_key
+    key_name: str = "api_key"
+    key_in: str = "header"  # header | query
+    value: str | None = None
+    env: str | None = None
+    # bearer
+    token: str | None = None
+    token_env: str | None = None
+    # basic
+    username: str | None = None
+    username_env: str | None = None
+    password: str | None = None
+    password_env: str | None = None
+    # oauth2 (client_credentials)
+    token_url: str | None = None
+    client_id: str | None = None
+    client_id_env: str | None = None
+    client_secret: str | None = None
+    client_secret_env: str | None = None
+    scope: str | None = None
+
+
+@dataclass(frozen=True)
+class RateLimitSpec:
+    """Token-bucket rate limiting, backed by ``xyberos.utils.resilience.RateLimiter``."""
+
+    calls_per_second: float = 1.0
+    burst: int = 1
+
+
+@dataclass
+class HttpApiSpec:
+    """A complete declarative API connection."""
+
+    name: str
+    base_url: str
+    operations: list[Operation] = field(default_factory=list)
+    headers: dict[str, str] = field(default_factory=dict)
+    auth: AuthSpec = field(default_factory=AuthSpec)
+    rate_limit: RateLimitSpec | None = None
+    timeout: float = 30.0
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "HttpApiSpec":
+        """Build a spec from a plain mapping, validating required fields."""
+        name = data.get("name")
+        base_url = data.get("base_url")
+        if not name:
+            raise ValueError("spec 'name' is required")
+        if not base_url:
+            raise ValueError("spec 'base_url' is required")
+
+        operations: list[Operation] = []
+        for index, raw in enumerate(data.get("operations") or ()):
+            operations.append(_operation_from_dict(raw, index))
+
+        auth = _auth_from_dict(data.get("auth") or {})
+        rate_limit = _rate_limit_from_dict(data.get("rate_limit"))
+        return cls(
+            name=str(name),
+            base_url=str(base_url).rstrip("/"),
+            operations=operations,
+            headers=dict(data.get("headers") or {}),
+            auth=auth,
+            rate_limit=rate_limit,
+            timeout=float(data.get("timeout", 30.0)),
+        )
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "HttpApiSpec":
+        """Load a spec from a JSON or YAML file (YAML imported lazily)."""
+        path = Path(path)
+        text = path.read_text(encoding="utf-8")
+        if path.suffix.lower() in (".yaml", ".yml"):
+            try:
+                yaml = importlib.import_module("yaml")  # optional dependency
+            except ImportError as exc:  # pragma: no cover - environment specific
+                raise ProviderError(
+                    "the 'PyYAML' package is required to load YAML specs; "
+                    "install it with 'pip install PyYAML' or use a JSON spec"
+                ) from exc
+            data: Any = yaml.safe_load(text)
+        else:
+            data = json.loads(text)
+        return cls.from_dict(data)
+
+
+def _operation_from_dict(raw: Mapping[str, Any], index: int) -> Operation:
+    name = raw.get("name")
+    if not name:
+        raise ValueError(f"operations[{index}] is missing a 'name'")
+    method = str(raw.get("method", "GET")).upper()
+    if method not in _METHODS:
+        raise ValueError(f"operation '{name}' has unsupported method '{method}'")
+    params: list[Param] = []
+    for param_index, p in enumerate(raw.get("params") or ()):
+        param_name = p.get("name")
+        if not param_name:
+            raise ValueError(f"operation '{name}' params[{param_index}] is missing a 'name'")
+        location = str(p.get("in", "query")).lower()
+        if location not in _PARAM_LOCATIONS:
+            raise ValueError(f"operation '{name}' param '{param_name}' has bad 'in': {location}")
+        params.append(
+            Param(
+                name=str(param_name),
+                in_=location,
+                type=str(p.get("type", "string")).lower(),
+                required=bool(p.get("required", False)),
+                description=str(p.get("description", "")),
+                default=p.get("default"),
+            )
+        )
+    return Operation(
+        name=str(name),
+        method=method,
+        path=str(raw.get("path", "/")),
+        description=str(raw.get("description", "")),
+        params=tuple(params),
+        response_format=str(raw.get("response_format", "json")).lower(),
+        response_path=raw.get("response_path"),
+    )
+
+
+def _auth_from_dict(data: Mapping[str, Any]) -> AuthSpec:
+    auth_type = str(data.get("type", "none")).lower()
+    fields: dict[str, Any] = {"type": auth_type}
+    if auth_type == "api_key":
+        fields.update(
+            key_name=str(data.get("key_name", "api_key")),
+            key_in=str(data.get("in", "header")).lower(),
+            value=data.get("value"),
+            env=data.get("env"),
+        )
+    elif auth_type == "bearer":
+        fields.update(token=data.get("token"), token_env=data.get("env") or data.get("token_env"))
+    elif auth_type == "basic":
+        fields.update(
+            username=data.get("username"),
+            username_env=data.get("username_env"),
+            password=data.get("password"),
+            password_env=data.get("password_env"),
+        )
+    elif auth_type == "oauth2":
+        fields.update(
+            token_url=data.get("token_url"),
+            client_id=data.get("client_id"),
+            client_id_env=data.get("client_id_env"),
+            client_secret=data.get("client_secret"),
+            client_secret_env=data.get("client_secret_env"),
+            scope=data.get("scope"),
+        )
+    elif auth_type != "none":
+        raise ValueError(f"unsupported auth type: {auth_type}")
+    return AuthSpec(**fields)
+
+
+def _rate_limit_from_dict(data: Mapping[str, Any] | None) -> RateLimitSpec | None:
+    if not data:
+        return None
+    return RateLimitSpec(
+        calls_per_second=float(data.get("calls_per_second", 1.0)),
+        burst=int(data.get("burst", 1)),
+    )
+
+
+def load_spec(source: Any) -> HttpApiSpec | list[HttpApiSpec]:
+    """Load one or more specs from a dict, JSON/YAML file path, or file text."""
+    if isinstance(source, (str, Path)):
+        return HttpApiSpec.from_file(source)
+    if isinstance(source, list):
+        return [HttpApiSpec.from_dict(item) for item in source]
+    if isinstance(source, Mapping):
+        return HttpApiSpec.from_dict(source)
+    raise TypeError("spec must be a mapping, a list of mappings, or a path to a JSON/YAML file")

xyberos_http_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: xyberos-http-api
+Version: 0.1.0
+Summary: Generic HTTP/API connector plugin (M2): point at any REST API, get typed tools
+License: Apache-2.0
+Keywords: xyberos,plugin,http,api,rest,tool
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+
+# xyberos-http-api
+
+**Generic HTTP/API connector plugin — RFC-0019, M2.** *"Point at any REST API,
+get typed tools."*
+
+A declarative spec (JSON / YAML / Python `dict`) describes a `base_url`,
+optional auth, optional rate limiting, and one *operation* per endpoint. Each
+operation becomes a typed [`Tool`](https://docs.xyberos.com) whose parameters
+are validated and coerced through `FunctionTool` / `coerce_arguments`.
+
+This is the highest-leverage item after MCP: it is a dependency of the MCP
+client (M3) and web search (M5), and it unblocks the whole multiplier chain.
+
+## Install
+
+```bash
+pip install -e ./http-api
+```
+
+## Usage
+
+Load a plugin from a spec file:
+
+```python
+from xyberos import create_app
+from xyberos_http_api import HttpApiPlugin
+
+app = create_app()
+app.load_plugin(HttpApiPlugin("examples/weather.json"))
+
+app.tools.execute("get_forecast", None, latitude=40.71, longitude=-74.01)
+```
+
+Or from a `dict` / YAML, or configure it entirely through the environment:
+
+```bash
+export HTTP_API_SPEC=/path/to/spec.json     # or HTTP_API_SPEC_JSON='{...}'
+```
+
+The module-level `plugin` is auto-discovered via the `xyberos.plugins`
+entry-point group; an unconfigured instance registers nothing (it logs a
+warning instead of breaking `load_entry_points()`).
+
+## Spec format
+
+```jsonc
+{
+  "name": "github",
+  "base_url": "https://api.github.com",
+  "headers": { "Accept": "application/vnd.github+json" },
+  "auth": { "type": "bearer", "token_env": "GITHUB_TOKEN" },
+  "rate_limit": { "calls_per_second": 5, "burst": 10 },
+  "operations": [
+    {
+      "name": "get_user",
+      "method": "GET",
+      "path": "/users/{username}",
+      "description": "Get a GitHub user's public profile.",
+      "params": [
+        { "name": "username", "in": "path", "required": true },
+        { "name": "per_page", "in": "query", "type": "integer", "default": 30 }
+      ],
+      "response_path": "some.nested[0].value"   // optional JSON extraction
+    }
+  ]
+}
+```
+
+### Parameters
+
+Each param has `name`, `in` (`query` | `path` | `header` | `body`), `type`
+(`string` | `integer` | `number` | `boolean` | `array` | `object`),
+`required`, `description`, and an optional `default`. The generated tool's JSON
+schema mirrors these, so an LLM gets a typed signature.
+
+### Auth
+
+| type | fields | notes |
+| ---- | ------ | ----- |
+| `api_key` | `key_name`, `in` (`header`/`query`), `value`/`env` | sent per request |
+| `bearer` | `token`/`token_env` | `Authorization: Bearer <token>` |
+| `basic` | `username`/`username_env`, `password`/`password_env` | base64 basic |
+| `oauth2` | `token_url`, `client_id`/`client_id_env`, `client_secret`/`client_secret_env`, `scope` | client_credentials, token cached |
+
+Secrets are read from environment variables first, then literals. No secret is
+ever required in the spec file.
+
+### Rate limiting
+
+`rate_limit` uses the core `xyberos.utils.resilience.RateLimiter` (token
+bucket) and is applied per request.
+
+## Examples
+
+- `examples/http_api_weather.py` — Open-Meteo (no key).
+- `examples/http_api_github.py` — GitHub REST API.
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+The tests spin up a local `http.server` and exercise the full stdlib client —
+no external network required.
+
+## Contract & ship location
+
+- **Contract:** `Tool` (`FunctionTool` public API only).
+- **Ship:** Plugin (`xyberos.plugins` entry point).
+- **Dependencies:** `xyberos>=1.0`; everything else is standard library.

xyberos_http_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+xyberos_http_api/__init__.py,sha256=iylqaHOTtJmTn3if4Q-Sd6LMldZ9XTPfCtKe4uzrIjE,949
+xyberos_http_api/auth.py,sha256=vr2rMIAZojCGTnbva7FBPTKZciZ0J-mL8ALH0BIG_LA,4949
+xyberos_http_api/builder.py,sha256=s5haW3FzAbWYtEfK-Ky-kd-OYKkI7U3tnIBD4IQ7XnM,4834
+xyberos_http_api/client.py,sha256=uFqyI7_gHmywi94u9Dm9Xy4M71vTXbpueRdD0BhQrGs,4348
+xyberos_http_api/errors.py,sha256=gMU8PooWMZS7K0SNslnOgUXFqnJDVfse8VvWGVQySq4,648
+xyberos_http_api/plugin.py,sha256=HTaaEBbl_JpQws21IzekTgwT9NV7GVWon5EcumMZr1k,4982
+xyberos_http_api/spec.py,sha256=bAznNdyftuJHVjc0d2sdlgRR36mVOFIbywSNmshorvU,8386
+xyberos_http_api-0.1.0.dist-info/METADATA,sha256=bsoSr0JYkmJzHsGpPFzjT9tH_o-xlXCl0FEw9MBP2Mk,3747
+xyberos_http_api-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+xyberos_http_api-0.1.0.dist-info/entry_points.txt,sha256=-SVdmedK3189l6SputRUAseCwj7HQ9jldQ6B9W-t-tM,60
+xyberos_http_api-0.1.0.dist-info/top_level.txt,sha256=Qz4epkWtSjRFxOvYd20ZeUPJjPPmfMmllEaxzP0WesM,17
+xyberos_http_api-0.1.0.dist-info/RECORD,,

xyberos_http_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xyberos_http_api-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+http_api = xyberos_http_api.plugin:plugin

xyberos_http_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_http_api