@adhd/apigen-python-env 0.2.0 → 0.2.1

package/python/apigen_python/plugin_echo.py

@@ -0,0 +1,100 @@
+"""
+apigen_python.plugin_echo — trivial echo plugin for round-trip testing (SPEC §14).
+
+This is the "one echo plugin" required by the host contract: a simple Python
+function that the gateway can call to prove the full IPC round-trip works.
+
+The echo operation accepts any input dict and returns it unchanged together with
+a 'host' marker, proving that the Python runtime received the call and responded.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def echo(message: str = "") -> dict[str, Any]:
+    """Echo the message back with a host marker.
+
+    Args:
+        message: Any string message.
+
+    Returns:
+        A dict containing the echoed message and the host identifier.
+    """
+    return {
+        "message": message,
+        "host": "python",
+        "echo": True,
+    }
+
+
+def ping() -> dict[str, Any]:
+    """Health-check ping — returns a minimal ok payload.
+
+    Used by the gateway adapter's readiness probe.
+    """
+    return {"status": "ok", "host": "python"}
+
+
+# ---------------------------------------------------------------------------
+# Plugin operation descriptors — used by the gateway adapter to register these
+# fns without running a full extraction pass.
+# ---------------------------------------------------------------------------
+
+ECHO_OPERATION: dict[str, Any] = {
+    "id": "echo/echo",
+    "host": "python",
+    "namespace": {"raw": "echo", "words": ["echo"]},
+    "path": [{"raw": "echo", "words": ["echo"]}],
+    "kind": "action",
+    "async": False,
+    "streaming": False,
+    "safe": False,
+    "input": {
+        "type": "object",
+        "properties": {
+            "message": {"type": "string"},
+        },
+        "required": [],
+    },
+    "output": {
+        "type": "object",
+        "properties": {
+            "message": {"type": "string"},
+            "host": {"type": "string"},
+            "echo": {"type": "boolean"},
+        },
+    },
+    "envelope": {},
+    "typeText": None,
+}
+
+PING_OPERATION: dict[str, Any] = {
+    "id": "echo/ping",
+    "host": "python",
+    "namespace": {"raw": "echo", "words": ["echo"]},
+    "path": [{"raw": "ping", "words": ["ping"]}],
+    "kind": "query",
+    "async": False,
+    "streaming": False,
+    "safe": True,
+    "input": {"type": "object", "properties": {}},
+    "output": {
+        "type": "object",
+        "properties": {
+            "status": {"type": "string"},
+            "host": {"type": "string"},
+        },
+    },
+    "envelope": {},
+    "typeText": None,
+}
+
+# Registry entries used by the gateway adapter.
+ECHO_REGISTRY: dict[str, Any] = {
+    "echo/echo": echo,
+    "echo/ping": ping,
+}
+
+ECHO_OPERATIONS: list[dict[str, Any]] = [ECHO_OPERATION, PING_OPERATION]

package/python/apigen_python/runtime.py

@@ -0,0 +1,228 @@
+"""
+apigen_python.runtime — Python host harness: invoke / validate / dispatch (SPEC §8 / §14).
+
+The runtime receives a HostRequest (from the gateway or directly from a plugin),
+validates input against the Operation's JSON-Schema, dispatches to the Python fn,
+and maps exceptions to §9 ApiError codes.
+
+Lifecycle:
+    runtime = Runtime(fn_registry)
+    result  = await runtime.invoke(request, signal)   # async path
+    result  = runtime.invoke_sync(request)            # sync path (for tests / WSGI)
+
+The fn_registry maps operation id → callable.
+
+SPEC §6: validation is a fast-fail pre-filter, NOT the authoritative type gate.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any
+
+from .errors import ApiError, ApiErrorCode
+from .validator import validate, ValidationError
+
+
+# ---------------------------------------------------------------------------
+# HostRequest — matches gateway.ts HostRequest (the cross-language IPC contract)
+# ---------------------------------------------------------------------------
+
+class HostRequest:
+    """The single request the gateway forwards to the Python host runtime.
+
+    Fields mirror gateway.ts::HostRequest exactly so the IPC adapter can
+    deserialise directly into this class.
+    """
+
+    def __init__(
+        self,
+        operation: dict[str, Any],
+        data: dict[str, Any],
+        envelope: dict[str, Any],
+        transport: str,
+        pre_validated: bool = False,
+    ) -> None:
+        self.operation = operation          # full §4 Operation dict
+        self.data = data                    # bare domain params (ctx excluded)
+        self.envelope = envelope            # request side-channel (session, auth, …)
+        self.transport = transport          # 'http' | 'grpc' | 'mcp' | 'cli'
+        self.pre_validated = pre_validated  # True when the transport layer already
+                                           # validated wire data before logical decode;
+
+
+# ---------------------------------------------------------------------------
+# Runtime
+# ---------------------------------------------------------------------------
+
+class Runtime:
+    """Python host harness — validate → dispatch (SPEC §8 / §14).
+
+    Args:
+        fn_registry: Mapping of operation id → Python callable.
+            The callable receives keyword arguments matching the operation's
+            input schema properties. The 'ctx' parameter (if present) receives
+            the envelope dict.
+    """
+
+    def __init__(self, fn_registry: dict[str, Any]) -> None:
+        self._registry = fn_registry
+
+    # ------------------------------------------------------------------
+    # Core dispatch
+    # ------------------------------------------------------------------
+
+    def _resolve(self, op_id: str) -> Any:
+        """Look up the function for an operation id.
+
+        Raises:
+            ApiError(not_found): if no function is registered for op_id.
+        """
+        fn = self._registry.get(op_id)
+        if fn is None:
+            raise ApiError("not_found", f"no handler registered for operation '{op_id}'")
+        return fn
+
+    def _validate_input(self, op: dict[str, Any], data: dict[str, Any]) -> None:
+        """Validate *data* against the operation's input schema (SPEC §6).
+
+        Raises:
+            ApiError(invalid_argument): if validation fails.
+        """
+        input_schema = op.get("input", {})
+        if not input_schema:
+            return
+        try:
+            validate(input_schema, data)
+        except ValidationError as exc:
+            raise ApiError("invalid_argument", f"input validation failed: {exc}") from exc
+
+    def _validate_input_if_needed(self, req: "HostRequest") -> None:
+        """Validate request input unless the transport already pre-validated it.
+
+        When a transport layer (e.g. flask_server) validates wire data BEFORE
+        logical-type decoding and marks the request as pre_validated=True, the
+        runtime skips its own re-validation.  This prevents decoded native
+        values (e.g. decimal.Decimal, datetime) from being re-validated against
+        the wire schema ({"type":"string","format":"decimal"}) and incorrectly
+        failing.
+        """
+        if req.pre_validated:
+            return
+        self._validate_input(req.operation, req.data)
+
+    def _build_kwargs(self, fn: Any, data: dict[str, Any], envelope: dict[str, Any]) -> dict[str, Any]:
+        """Build keyword-argument dict for the function from data + envelope.
+
+        If the function has a first parameter named 'ctx', it receives the
+        envelope dict. All other parameters are pulled from data.
+        """
+        try:
+            sig = inspect.signature(fn)
+        except (ValueError, TypeError):
+            return dict(data)
+
+        params = list(sig.parameters.values())
+        kwargs: dict[str, Any] = {}
+
+        # Strip 'self' for bound methods.
+        if params and params[0].name == "self":
+            params = params[1:]
+
+        # 'ctx' first-param receives the envelope (§4 inv:ctx-name-only).
+        if params and params[0].name == "ctx":
+            kwargs["ctx"] = envelope
+            params = params[1:]
+
+        # Remaining params from data.
+        for p in params:
+            if p.kind in (
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ):
+                continue
+            if p.name in data:
+                kwargs[p.name] = data[p.name]
+
+        return kwargs
+
+    def _call_fn(self, fn: Any, kwargs: dict[str, Any]) -> Any:
+        """Call a synchronous function, mapping exceptions to ApiError."""
+        try:
+            return fn(**kwargs)
+        except ApiError:
+            raise
+        except TypeError as exc:
+            raise ApiError("invalid_argument", f"dispatch type error: {exc}") from exc
+        except Exception as exc:
+            raise ApiError("internal", f"dispatch error: {exc}") from exc
+
+    async def _call_fn_async(self, fn: Any, kwargs: dict[str, Any]) -> Any:
+        """Call an async function (coroutine), mapping exceptions to ApiError."""
+        try:
+            result = fn(**kwargs)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+        except ApiError:
+            raise
+        except TypeError as exc:
+            raise ApiError("invalid_argument", f"dispatch type error: {exc}") from exc
+        except Exception as exc:
+            raise ApiError("internal", f"dispatch error: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Public invoke API
+    # ------------------------------------------------------------------
+
+    async def invoke(self, req: HostRequest, signal: Any = None) -> Any:
+        """Invoke an operation asynchronously.
+
+        Validates input, resolves the function, dispatches, and returns the result.
+        Cancellation via *signal* is not yet propagated to the fn (future work).
+
+        Args:
+            req: The HostRequest from the gateway or plugin.
+            signal: Optional cancellation signal (reserved; not yet consumed).
+
+        Returns:
+            The function's return value (awaited if async).
+
+        Raises:
+            ApiError: on validation failure, not-found, or dispatch error.
+        """
+        op = req.operation
+        fn = self._resolve(op["id"])
+        self._validate_input_if_needed(req)
+        kwargs = self._build_kwargs(fn, req.data, req.envelope)
+
+        if inspect.iscoroutinefunction(fn) or inspect.isasyncgenfunction(fn):
+            return await self._call_fn_async(fn, kwargs)
+        # Sync fn — run in thread pool to avoid blocking the event loop.
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, lambda: self._call_fn(fn, kwargs))
+
+    def invoke_sync(self, req: HostRequest) -> Any:
+        """Invoke an operation synchronously (for tests and WSGI contexts).
+
+        For async functions this runs them in a new event loop; for sync
+        functions it calls them directly.
+
+        Args:
+            req: The HostRequest.
+
+        Returns:
+            The function's return value.
+
+        Raises:
+            ApiError: on validation failure, not-found, or dispatch error.
+        """
+        op = req.operation
+        fn = self._resolve(op["id"])
+        self._validate_input_if_needed(req)
+        kwargs = self._build_kwargs(fn, req.data, req.envelope)
+
+        if inspect.iscoroutinefunction(fn) or inspect.isasyncgenfunction(fn):
+            return asyncio.run(self._call_fn_async(fn, kwargs))
+        return self._call_fn(fn, kwargs)

package/python/apigen_python/validator.py

@@ -0,0 +1,135 @@
+"""
+apigen_python.validator — JSON-Schema 2020-12 validation for the Python host (SPEC §6).
+
+Implements validation as a fast-fail pre-filter. Tries to use the ``jsonschema``
+library if installed; falls back to a minimal stdlib-only validator that covers
+the common cases used by the conformance vectors.
+
+SPEC §6 note: validation is necessary-not-sufficient. The Python host validates
+as a pre-filter; typed dispatch is the authoritative boundary.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Try to import jsonschema (optional dependency)
+# ---------------------------------------------------------------------------
+
+try:
+    import jsonschema  # type: ignore[import]
+    _HAS_JSONSCHEMA = True
+except ImportError:
+    _HAS_JSONSCHEMA = False
+
+
+# ---------------------------------------------------------------------------
+# Minimal stdlib validator (fallback when jsonschema is not installed)
+#
+# Covers: type, required, properties, oneOf, items, additionalProperties.
+# Sufficient for all conformance vector schemas.
+# ---------------------------------------------------------------------------
+
+def _check_type(schema_type: str, value: Any) -> bool:
+    type_map = {
+        "object": lambda v: isinstance(v, dict),
+        "array": lambda v: isinstance(v, list),
+        "string": lambda v: isinstance(v, str),
+        "integer": lambda v: isinstance(v, int) and not isinstance(v, bool),
+        "number": lambda v: isinstance(v, (int, float)) and not isinstance(v, bool),
+        "boolean": lambda v: isinstance(v, bool),
+        "null": lambda v: v is None,
+    }
+    checker = type_map.get(schema_type)
+    return checker(value) if checker else True
+
+
+def _minimal_validate(schema: dict[str, Any], value: Any) -> bool:
+    """Validate *value* against *schema* using a minimal subset of JSON Schema.
+
+    Returns True if valid, False if invalid.
+    Does NOT raise; the caller decides how to surface failure.
+    """
+    if not isinstance(schema, dict):
+        return True  # empty / non-schema → accept
+
+    # type keyword
+    schema_type = schema.get("type")
+    if schema_type is not None:
+        if not _check_type(schema_type, value):
+            return False
+
+    # oneOf
+    one_of = schema.get("oneOf")
+    if one_of is not None:
+        matches = sum(1 for s in one_of if _minimal_validate(s, value))
+        if matches != 1:
+            # Relax to "at least one" (some schemas use oneOf where anyOf is meant).
+            if matches == 0:
+                return False
+
+    # required + properties (object only)
+    if schema_type == "object" and isinstance(value, dict):
+        required = schema.get("required", [])
+        for key in required:
+            if key not in value:
+                return False
+        properties = schema.get("properties", {})
+        for prop_name, prop_schema in properties.items():
+            if prop_name in value:
+                if not _minimal_validate(prop_schema, value[prop_name]):
+                    return False
+
+    # items (array only)
+    if schema_type == "array" and isinstance(value, list):
+        items_schema = schema.get("items")
+        if items_schema:
+            for item in value:
+                if not _minimal_validate(items_schema, item):
+                    return False
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+class ValidationError(Exception):
+    """Raised when input data fails JSON-Schema validation."""
+
+    def __init__(self, message: str, path: str = "") -> None:
+        super().__init__(message)
+        self.path = path
+
+
+def validate(schema: dict[str, Any], value: Any) -> None:
+    """Validate *value* against *schema*.
+
+    Uses ``jsonschema`` if installed (full JSON-Schema 2020-12), otherwise falls
+    back to the minimal stdlib validator.
+
+    Raises:
+        ValidationError: if the value does not satisfy the schema.
+    """
+    if _HAS_JSONSCHEMA:
+        try:
+            jsonschema.validate(value, schema)
+        except jsonschema.ValidationError as exc:
+            raise ValidationError(str(exc.message)) from exc
+    else:
+        if not _minimal_validate(schema, value):
+            raise ValidationError(
+                f"Value does not satisfy schema (minimal validator): {value!r}"
+            )
+
+
+def is_valid(schema: dict[str, Any], value: Any) -> bool:
+    """Return True if *value* satisfies *schema*, False otherwise. Never raises."""
+    try:
+        validate(schema, value)
+        return True
+    except ValidationError:
+        return False