xyberos-http-api 0.1.0__tar.gz

xyberos_http_api-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xyberos-http-api"
+version = "0.1.0"
+description = "Generic HTTP/API connector plugin (M2): point at any REST API, get typed tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = ["xyberos>=1.0"]
+keywords = ["xyberos", "plugin", "http", "api", "rest", "tool"]
+
+[project.entry-points."xyberos.plugins"]
+http_api = "xyberos_http_api.plugin:plugin"
+
+[tool.setuptools]
+packages = ["xyberos_http_api"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xyberos_http_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xyberos_http_api-0.1.0/tests/test_auth.py

@@ -0,0 +1,66 @@
+"""Tests for auth resolution against the local HTTP server."""
+
+from __future__ import annotations
+
+from xyberos_http_api import AuthSpec
+from xyberos_http_api.auth import AuthResolver
+
+
+def test_no_auth():
+    assert AuthResolver(AuthSpec()).resolve().headers == {}
+
+
+def test_api_key_header(monkeypatch):
+    resolver = AuthResolver(AuthSpec(type="api_key", key_name="X-API-Key", value="secret123"))
+    resolved = resolver.resolve()
+    assert resolved.headers == {"X-API-Key": "secret123"}
+    assert resolved.query == {}
+
+
+def test_api_key_query():
+    resolved = AuthResolver(
+        AuthSpec(type="api_key", key_name="apikey", key_in="query", value="abc")
+    ).resolve()
+    assert resolved.query == {"apikey": "abc"}
+
+
+def test_api_key_from_env(monkeypatch):
+    monkeypatch.setenv("MY_KEY", "env-value")
+    resolved = AuthResolver(
+        AuthSpec(type="api_key", key_name="X-Key", env="MY_KEY", value="literal")
+    ).resolve()
+    assert resolved.headers == {"X-Key": "env-value"}
+
+
+def test_bearer():
+    resolved = AuthResolver(AuthSpec(type="bearer", token="tok123")).resolve()
+    assert resolved.headers == {"Authorization": "Bearer tok123"}
+
+
+def test_basic():
+    resolved = AuthResolver(
+        AuthSpec(type="basic", username="user", password="pass")
+    ).resolve()
+    import base64
+
+    expected = "Basic " + base64.b64encode(b"user:pass").decode("ascii")
+    assert resolved.headers == {"Authorization": expected}
+
+
+def test_oauth2_client_credentials(server):
+    base_url, requests = server
+    auth = AuthSpec(
+        type="oauth2",
+        token_url=f"{base_url}/token",
+        client_id="cid",
+        client_secret="csecret",
+        scope="read",
+    )
+    resolver = AuthResolver(auth)
+    first = resolver.resolve()
+    second = resolver.resolve()
+    assert first.headers == {"Authorization": "Bearer tok123"}
+    # Token is cached — only one token request is made.
+    token_calls = [r for r in requests if r["path"] == "/token"]
+    assert len(token_calls) == 1
+    assert second.headers == first.headers

xyberos_http_api-0.1.0/tests/test_builder.py

@@ -0,0 +1,127 @@
+"""Tests for typed tool generation from declared operations."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from xyberos_http_api import HttpClient, HttpApiSpec, Operation, Param, build_operation_tool
+
+
+def _spec(base_url: str, operation: Operation, **kwargs) -> HttpApiSpec:
+    return HttpApiSpec(name="t", base_url=base_url, operations=[operation], **kwargs)
+
+
+def test_tool_schema_is_typed(server):
+    base_url, _ = server
+    op = Operation(
+        name="get_forecast",
+        method="GET",
+        path="/forecast",
+        params=(
+            Param("latitude", type="number", required=True),
+            Param("longitude", type="number", required=True),
+            Param("units", type="string", default="metric"),
+            Param("active", type="boolean", required=False, default=True),
+        ),
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    schema = tool.schema
+    assert schema["name"] == "get_forecast"
+    props = schema["parameters"]["properties"]
+    assert props["latitude"] == {"type": "number"}
+    assert props["longitude"] == {"type": "number"}
+    assert props["units"] == {"type": "string"}
+    assert props["active"] == {"type": "boolean"}
+    assert schema["parameters"]["required"] == ["latitude", "longitude"]
+
+
+def test_tool_executes_and_coerces(server):
+    base_url, _ = server
+    op = Operation(
+        name="get_forecast",
+        path="/forecast",
+        params=(
+            Param("latitude", type="number", required=True),
+            Param("longitude", type="number", required=True),
+            Param("units", type="string", default="metric"),
+        ),
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    result = tool.execute(None, latitude="10.5", longitude="-66")
+    assert result["latitude"] == 10.5  # coerced from string
+    assert result["units"] == "metric"
+
+
+def test_tool_missing_required_raises(server):
+    base_url, _ = server
+    op = Operation(
+        name="get_forecast",
+        path="/forecast",
+        params=(Param("latitude", type="number", required=True),),
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    with pytest.raises(Exception, match="latitude"):
+        tool.execute(None)
+
+
+def test_path_param_substitution(server):
+    base_url, _ = server
+    op = Operation(
+        name="get_user",
+        path="/users/{name}",
+        params=(Param("name", in_="path", required=True),),
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    result = tool.execute(None, name="baltz")
+    assert result["login"] == "baltz"
+    assert result["public_repos"] == 42
+
+
+def test_header_param_sent(server):
+    base_url, requests = server
+    op = Operation(
+        name="with_header",
+        path="/users/baltz",
+        params=(Param("X-Trace", in_="header", default="abc"),),
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    # Non-identifier names are exposed under a sanitized signature name.
+    assert "X_Trace" in tool.schema["parameters"]["properties"]
+    tool.execute(None, X_Trace="abc")
+    assert requests[0]["headers"].get("x-trace") == "abc"
+
+
+def test_body_param(server):
+    base_url, _ = server
+    op = Operation(
+        name="send",
+        method="POST",
+        path="/body",
+        params=(Param("payload", in_="body", type="object", required=True),),
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    result = tool.execute(None, payload={"hello": "world"})
+    assert result == {"received": {"hello": "world"}}
+
+
+def test_response_path_extraction(server):
+    base_url, _ = server
+    op = Operation(
+        name="temp",
+        path="/forecast",
+        params=(Param("latitude", type="number", required=True),),
+        response_path="current_weather.temperature",
+    )
+    tool = build_operation_tool(_spec(base_url, op), op, HttpClient(base_url))
+    assert tool.execute(None, latitude=1) == 21.5
+
+
+def test_extract_path_with_indices():
+    from xyberos_http_api.builder import extract_path
+
+    data = {"a": [{"b": 7}, {"b": 8}]}
+    assert extract_path(data, "a[1].b") == 8
+    assert extract_path(data, "missing") is None
+    assert extract_path(data, None) == data

xyberos_http_api-0.1.0/tests/test_client.py

@@ -0,0 +1,66 @@
+"""Tests for the stdlib HTTP client."""
+
+from __future__ import annotations
+
+import pytest
+
+from xyberos_http_api import AuthSpec, HttpApiError, HttpClient, RateLimitSpec
+
+
+def test_get_json(server):
+    base_url, requests = server
+    client = HttpClient(base_url)
+    result = client.get("/forecast", query={"latitude": 10.5, "longitude": -66})
+    assert result["latitude"] == 10.5
+    assert requests[0]["method"] == "GET"
+    assert "latitude=10.5" in requests[0]["path"]
+
+
+def test_post_json_body(server):
+    base_url, _ = server
+    client = HttpClient(base_url)
+    result = client.post("/body", body={"name": "x", "n": 3})
+    assert result == {"received": {"name": "x", "n": 3}}
+
+
+def test_http_error(server):
+    base_url, _ = server
+    client = HttpClient(base_url)
+    with pytest.raises(HttpApiError) as exc_info:
+        client.get("/missing")
+    assert exc_info.value.status == 404
+
+
+def test_bearer_header_sent(server):
+    base_url, _ = server
+    client = HttpClient(base_url, auth=AuthSpec(type="bearer", token="tok123"))
+    assert client.get("/needs-bearer") == {"ok": True}
+
+
+def test_api_key_header_sent(server):
+    base_url, _ = server
+    client = HttpClient(
+        base_url, auth=AuthSpec(type="api_key", key_name="X-API-Key", value="secret123")
+    )
+    assert client.get("/needs-key") == {"ok": True}
+
+
+def test_declared_headers_merged(server):
+    base_url, requests = server
+    client = HttpClient(base_url, headers={"X-Custom": "yes"})
+    client.get("/users/baltz")
+    assert requests[0]["headers"]["x-custom"] == "yes"
+
+
+def test_rate_limiter_throttles(server):
+    import time
+
+    base_url, requests = server
+    client = HttpClient(base_url, rate_limit=RateLimitSpec(calls_per_second=20, burst=1))
+    start = time.monotonic()
+    for _ in range(3):
+        client.get("/rate")
+    elapsed = time.monotonic() - start
+    # 3 calls at 20/s with burst 1 => at least ~0.1s total.
+    assert elapsed >= 0.09
+    assert len(requests) == 3

xyberos_http_api-0.1.0/tests/test_plugin.py

@@ -0,0 +1,92 @@
+"""Tests for loading the http_api plugin into a Xyberos app."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from xyberos import create_app
+
+from xyberos_http_api.plugin import HttpApiPlugin
+
+
+def _spec_for(base_url: str) -> dict:
+    return {
+        "name": "demo",
+        "base_url": base_url,
+        "operations": [
+            {
+                "name": "get_user",
+                "method": "GET",
+                "path": "/users/{username}",
+                "params": [{"name": "username", "in": "path", "required": True}],
+            },
+            {
+                "name": "get_forecast",
+                "method": "GET",
+                "path": "/forecast",
+                "params": [
+                    {"name": "latitude", "in": "query", "type": "number", "required": True},
+                    {"name": "longitude", "in": "query", "type": "number", "required": True},
+                ],
+            },
+        ],
+    }
+
+
+def test_plugin_conforms_to_contract():
+    plugin = HttpApiPlugin(_spec_for("https://example.com"))
+    assert plugin.name == "http_api"
+    assert callable(plugin.register) and callable(plugin.unregister)
+
+
+def test_plugin_registers_and_executes(server):
+    base_url, _ = server
+    app = create_app()
+    plugin = HttpApiPlugin(_spec_for(base_url))
+    app.load_plugin(plugin)
+
+    assert "get_user" in app.tools.names
+    assert "get_forecast" in app.tools.names
+
+    result = app.tools.execute("get_user", None, username="baltz")
+    assert result["login"] == "baltz"
+    forecast = app.tools.execute("get_forecast", None, latitude="10.5", longitude="-66")
+    assert forecast["latitude"] == 10.5
+
+    app.unload_plugin(plugin.name)
+    assert "get_user" not in app.tools.names
+
+
+def test_plugin_from_json_file(server, tmp_path):
+    base_url, _ = server
+    path = tmp_path / "spec.json"
+    path.write_text(json.dumps(_spec_for(base_url)), encoding="utf-8")
+    app = create_app()
+    app.load_plugin(HttpApiPlugin(path))
+    assert "get_user" in app.tools.names
+
+
+def test_plugin_from_env(server, monkeypatch):
+    base_url, _ = server
+    monkeypatch.setenv("HTTP_API_SPEC_JSON", json.dumps(_spec_for(base_url)))
+    plugin = HttpApiPlugin()
+    assert {t.name for t in plugin.tools()} == {"get_user", "get_forecast"}
+
+
+def test_unconfigured_register_is_safe(server):
+    base_url, _ = server
+    app = create_app()
+    plugin = HttpApiPlugin()  # no spec, no env
+    app.load_plugin(plugin)  # must not raise
+    assert app.plugins.names == ("http_api",)
+    app.unload_plugin("http_api")
+
+
+def test_multi_spec_tools_are_prefixed(server):
+    base_url, _ = server
+    specs = [_spec_for(base_url), {**_spec_for(base_url), "name": "second"}]
+    plugin = HttpApiPlugin(specs)
+    names = {t.name for t in plugin.tools()}
+    assert "demo_get_user" in names
+    assert "second_get_user" in names