curupira-sdk 0.1.0.dev0__py3-none-any.whl

curupira_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""Declarative SDK for Curupira process extensions."""
+
+from __future__ import annotations
+
+from .app import Curupira
+from .errors import RegistrationError, RpcError, SerializationError, ValidationError
+from .framing import read_frame, write_frame
+from .server import ExtensionServer, serve_stdio
+
+__all__ = [
+    "Curupira",
+    "ExtensionServer",
+    "RegistrationError",
+    "RpcError",
+    "SerializationError",
+    "ValidationError",
+    "read_frame",
+    "serve_stdio",
+    "write_frame",
+]
+
+from importlib.metadata import version
+
+# Read from the installed distribution, whose version comes from the release tag.
+__version__ = version("curupira-sdk")

curupira_sdk/app.py

@@ -0,0 +1,180 @@
+"""Declarative Curupira extension application."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+from .errors import RegistrationError, RpcError, SerializationError, ValidationError
+from .runtime import invoke, shutdown_runtime
+from .serialize import serialize_trigger_result
+from .server import ExtensionServer, serve_stdio
+from .signature import TriggerSpec, bind_arguments, build_trigger_spec, normalize_configuration
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Curupira:
+    """Extension application that registers typed trigger functions."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        version: str,
+        agents: list[dict[str, Any]] | None = None,
+    ) -> None:
+        self.name = name
+        self.version = version
+        self.agents = agents or []
+        self._triggers: dict[str, TriggerSpec] = {}
+        self._agent_handlers: dict[str, Callable[[Any], Any]] = {}
+        self._lifecycle: dict[str, Callable[[Any], Any]] = {}
+        self._param_checks: dict[str, Callable[[dict[str, Any]], None]] = {}
+
+    @overload
+    def trigger(self, func: F) -> F: ...
+
+    @overload
+    def trigger(self, *, alias: str) -> Callable[[F], F]: ...
+
+    def trigger(
+        self, func: F | None = None, *, alias: str | None = None
+    ) -> F | Callable[[F], F]:
+        """Register ``func`` as a trigger.
+
+        Use ``@app.trigger`` with no parentheses to derive the local name from
+        ``func.__name__`` in kebab-case (``github_issues`` → ``github-issues``).
+        Use ``@app.trigger(alias="issues")`` to override the local name.
+
+        The host addresses triggers as ``<plugins-alias>/<local-name>`` after the
+        extension is registered under ``[plugins.<alias>]`` in settings TOML.
+        """
+
+        def decorator(fn: F) -> F:
+            spec = build_trigger_spec(fn, name=alias)
+            if spec.name in self._triggers:
+                raise RegistrationError(f"duplicate trigger name {spec.name!r}")
+            self._triggers[spec.name] = spec
+            return fn
+
+        if func is not None:
+            if alias is not None:
+                raise RegistrationError("use @app.trigger(alias=...) as a decorator factory")
+            return decorator(func)
+        return decorator
+
+    def param_check(
+        self, trigger_name: str, fn: Callable[[dict[str, Any]], None]
+    ) -> Callable[[dict[str, Any]], None]:
+        """Register an extra argument check run during validate and poll."""
+        self._param_checks[trigger_name] = fn
+        return fn
+
+    def on(self, method: str, handler: Callable[[Any], Any]) -> None:
+        """Register a low-level JSON-RPC handler (agent/lifecycle methods)."""
+        if method.startswith("agent/"):
+            self._agent_handlers[method] = handler
+        else:
+            self._lifecycle[method] = handler
+
+    def triggers(self) -> list[TriggerSpec]:
+        """Return registered trigger specs in registration order."""
+        return list(self._triggers.values())
+
+    def run(self) -> None:
+        """Serve the extension protocol on stdin/stdout until shutdown or EOF."""
+        server = ExtensionServer(
+            name=self.name,
+            version=self.version,
+            triggers=[
+                {"trigger_type": spec.name, "prompt_fields": list(spec.prompt_fields)}
+                for spec in self._triggers.values()
+            ],
+            agents=self.agents,
+        )
+        server.on("trigger/schema", self._handle_schema)
+        server.on("trigger/validate", self._handle_validate)
+        server.on("trigger/poll", self._handle_poll)
+        server.on("trigger/onStarted", self._handle_lifecycle("trigger/onStarted"))
+        server.on("trigger/onFinished", self._handle_lifecycle("trigger/onFinished"))
+        for method, handler in self._agent_handlers.items():
+            server.on(method, handler)
+        for method, handler in self._lifecycle.items():
+            if method not in {"trigger/onStarted", "trigger/onFinished"}:
+                server.on(method, handler)
+        try:
+            serve_stdio(server)
+        finally:
+            shutdown_runtime()
+
+    def print_manifest(self, manifest_template: str) -> None:
+        """Print a filled manifest template to stdout (for plugins install)."""
+        print(manifest_template.format(version=self.version, python=sys.executable))
+
+    def _get_spec(self, trigger_type: str) -> TriggerSpec:
+        # Host may send the namespaced form ``alias/local``; accept either.
+        local = trigger_type.rsplit("/", 1)[-1]
+        spec = self._triggers.get(local) or self._triggers.get(trigger_type)
+        if spec is None:
+            raise RpcError(-32003, f"unsupported trigger_type {trigger_type!r}")
+        return spec
+
+    def _handle_schema(self, params: Any) -> dict[str, Any]:
+        trigger_type = (params or {}).get("trigger_type")
+        if not isinstance(trigger_type, str):
+            raise RpcError(-32602, "trigger_type is required")
+        spec = self._get_spec(trigger_type)
+        return {"schema": spec.schema, "prompt_fields": list(spec.prompt_fields)}
+
+    def _handle_validate(self, params: Any) -> dict[str, Any]:
+        trigger_type = (params or {}).get("trigger_type")
+        configuration = dict((params or {}).get("configuration") or {})
+        if not isinstance(trigger_type, str):
+            raise RpcError(-32602, "trigger_type is required")
+        try:
+            spec = self._get_spec(trigger_type)
+            kwargs = bind_arguments(spec, configuration)
+            self._run_param_check(spec.name, kwargs)
+            normalized = normalize_configuration(spec, configuration)
+        except RpcError as exc:
+            return {"ok": False, "error": str(exc)}
+        except (ValidationError, RegistrationError) as exc:
+            return {"ok": False, "error": str(exc)}
+        return {"ok": True, "configuration": normalized}
+
+    def _run_param_check(self, trigger_name: str, kwargs: dict[str, Any]) -> None:
+        check = self._param_checks.get(trigger_name)
+        if check is not None:
+            check(kwargs)
+
+    def _handle_poll(self, params: Any) -> dict[str, Any]:
+        trigger_type = (params or {}).get("trigger_type")
+        automation = dict((params or {}).get("automation") or {})
+        if not isinstance(trigger_type, str):
+            raise RpcError(-32602, "trigger_type is required")
+        spec = self._get_spec(trigger_type)
+        try:
+            kwargs = bind_arguments(spec, automation)
+            self._run_param_check(spec.name, kwargs)
+            result = invoke(spec.func, kwargs, is_async=spec.is_async)
+            task = serialize_trigger_result(result, spec.return_annotation, trigger_name=spec.name)
+        except RpcError:
+            raise
+        except (ValidationError, SerializationError, RegistrationError) as exc:
+            raise RpcError(-32002, str(exc)) from exc
+        except Exception as exc:
+            raise RpcError(-32002, f"execution error: {exc}") from exc
+        return {"task": task}
+
+    def _handle_lifecycle(self, method: str) -> Callable[[Any], Any]:
+        custom = self._lifecycle.get(method)
+
+        def handler(params: Any) -> dict[str, Any]:
+            if custom is not None:
+                result = custom(params)
+                return result if isinstance(result, dict) else {}
+            return {}
+
+        return handler

curupira_sdk/errors.py

@@ -0,0 +1,26 @@
+"""SDK and JSON-RPC errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RegistrationError(Exception):
+    """Raised when a trigger cannot be registered."""
+
+
+class ValidationError(Exception):
+    """Raised when configuration or arguments fail validation."""
+
+
+class SerializationError(Exception):
+    """Raised when a trigger return value cannot be serialized."""
+
+
+class RpcError(Exception):
+    """JSON-RPC error with numeric code."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.data = data

curupira_sdk/framing.py

@@ -0,0 +1,39 @@
+"""Length-prefixed JSON frames (8 hex digits + body)."""
+
+from __future__ import annotations
+
+import sys
+from typing import BinaryIO
+
+DEFAULT_MAX_FRAME_BYTES = 16 * 1024 * 1024
+
+
+def write_frame(writer: BinaryIO, payload: bytes) -> None:
+    """Write one frame to a binary writer (typically stdout.buffer)."""
+    if len(payload) > 0xFFFFFFFF:
+        raise ValueError("frame too large")
+    writer.write(f"{len(payload):08x}".encode("ascii"))
+    writer.write(payload)
+    writer.flush()
+
+
+def read_frame(reader: BinaryIO, max_bytes: int = DEFAULT_MAX_FRAME_BYTES) -> bytes:
+    """Read one frame from a binary reader (typically stdin.buffer)."""
+    header = reader.read(8)
+    if len(header) < 8:
+        raise EOFError("unexpected EOF while reading frame header")
+    try:
+        length = int(header.decode("ascii"), 16)
+    except ValueError as exc:
+        raise ValueError("invalid frame header") from exc
+    if length > max_bytes:
+        raise ValueError(f"frame length {length} exceeds limit {max_bytes}")
+    body = reader.read(length)
+    if len(body) < length:
+        raise EOFError("unexpected EOF while reading frame body")
+    return body
+
+
+def log(message: str) -> None:
+    """Write a diagnostic line to stderr (never stdout)."""
+    print(message, file=sys.stderr, flush=True)

curupira_sdk/runtime.py

@@ -0,0 +1,39 @@
+"""Invoke synchronous and asynchronous trigger functions."""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+from typing import Any
+
+_LOOP: asyncio.AbstractEventLoop | None = None
+
+
+def get_event_loop() -> asyncio.AbstractEventLoop:
+    """Return a process-wide event loop for async triggers."""
+    global _LOOP
+    if _LOOP is None or _LOOP.is_closed():
+        _LOOP = asyncio.new_event_loop()
+        asyncio.set_event_loop(_LOOP)
+    return _LOOP
+
+
+def invoke(func: Any, kwargs: dict[str, Any], *, is_async: bool) -> Any:
+    """Call a sync or async function and return its result."""
+    if not is_async:
+        return func(**kwargs)
+
+    loop = get_event_loop()
+    if loop.is_running():
+        # Nested call from within a running loop: use a worker thread with its own loop.
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, func(**kwargs)).result()
+    return loop.run_until_complete(func(**kwargs))
+
+
+def shutdown_runtime() -> None:
+    """Close the shared event loop if present."""
+    global _LOOP
+    if _LOOP is not None and not _LOOP.is_closed():
+        _LOOP.close()
+    _LOOP = None

curupira_sdk/serialize.py

@@ -0,0 +1,128 @@
+"""Validate and serialize a single trigger result or None."""
+
+from __future__ import annotations
+
+import collections.abc
+import dataclasses
+import types
+import typing
+from typing import Any, get_origin
+
+from .errors import SerializationError, ValidationError
+from .types import dump_value, is_collection_type, unwrap_optional
+
+
+def serialize_trigger_result(
+    value: Any, return_annotation: Any, *, trigger_name: str
+) -> dict[str, Any] | None:
+    """Return a host task envelope, or None when the trigger has no item."""
+    if _is_multi_value(value):
+        raise SerializationError(
+            f"trigger {trigger_name!r}: must return a single item or None, not a collection"
+        )
+
+    if value is None:
+        return None
+
+    if is_collection_type(return_annotation):
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return annotation must not be a collection"
+        )
+
+    if return_annotation is not typing.Any and return_annotation is not None:
+        _validate_against_annotation(value, return_annotation, trigger_name=trigger_name)
+
+    try:
+        payload = dump_value(value)
+    except SerializationError as exc:
+        raise SerializationError(f"trigger {trigger_name!r}: {exc}") from exc
+
+    return envelope_from_payload(payload, trigger_name=trigger_name)
+
+
+def envelope_from_payload(payload: Any, *, trigger_name: str) -> dict[str, Any]:
+    """Build `{id, title, url, item}` for the Rust host."""
+    if isinstance(payload, (str, int, float, bool)):
+        text = str(payload)
+        return {"id": text, "title": text, "url": "", "item": {"value": payload}}
+
+    if not isinstance(payload, dict):
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return value must serialize to an object or scalar"
+        )
+
+    item = dict(payload)
+    task_id = item.get("id")
+    if task_id is None and "number" in item:
+        task_id = item["number"]
+    if task_id is None:
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return object must include an 'id' field "
+            "(or 'number' for issue-like items)"
+        )
+    title = item.get("title") or item.get("name") or str(task_id)
+    url = item.get("url") or ""
+    return {
+        "id": str(task_id),
+        "title": str(title),
+        "url": str(url),
+        "item": item,
+    }
+
+
+def _is_multi_value(value: Any) -> bool:
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return True
+    if isinstance(value, types.GeneratorType):
+        return True
+    return isinstance(value, collections.abc.Iterator) and not isinstance(
+        value, (str, bytes, dict, collections.abc.Mapping)
+    )
+
+
+def _validate_against_annotation(value: Any, annotation: Any, *, trigger_name: str) -> None:
+    from .types import coerce_value
+
+    inner, _allows_none = unwrap_optional(annotation)
+    origin = get_origin(inner)
+
+    if origin is list or origin is tuple or origin is set:
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return annotation must not be a collection"
+        )
+
+    # Scalars: isinstance check.
+    if inner in {str, int, float, bool}:
+        if not isinstance(value, inner) or (inner is int and isinstance(value, bool)):
+            raise SerializationError(
+                f"trigger {trigger_name!r}: return value does not match annotation {annotation!r}"
+            )
+        return
+
+        # Exact instance of the annotated class is already valid.
+        if isinstance(inner, type) and isinstance(value, inner):
+            return
+
+        # Structured types: coerce via schema (dict / dataclass / pydantic / TypedDict).
+        try:
+            if dataclasses.is_dataclass(value) and not isinstance(value, type):
+                candidate: Any = dump_value(value)
+            elif _is_pydantic_instance(value):
+                candidate = dump_value(value)
+            elif isinstance(value, dict):
+                candidate = value
+            else:
+                candidate = value
+            coerce_value(annotation, candidate, context=f"trigger {trigger_name!r} return")
+        except (ValidationError, SerializationError) as exc:
+            raise SerializationError(
+                f"trigger {trigger_name!r}: return value incompatible with annotation: {exc}"
+            ) from exc
+
+
+def _is_pydantic_instance(value: Any) -> bool:
+    try:
+        from pydantic import BaseModel
+    except ImportError:
+        return False
+    return isinstance(value, BaseModel)

curupira_sdk/server.py

@@ -0,0 +1,107 @@
+"""JSON-RPC 2.0 extension server loop."""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+from .errors import RpcError
+from .framing import log, read_frame, write_frame
+
+PROTOCOL_VERSION = 1
+
+
+class ExtensionServer:
+    """Dispatch initialize/describe/trigger/agent methods to callables."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        version: str,
+        triggers: list[dict[str, Any]] | None = None,
+        agents: list[dict[str, Any]] | None = None,
+    ) -> None:
+        self.name = name
+        self.version = version
+        self.triggers = triggers or []
+        self.agents = agents or []
+        self._handlers: dict[str, Callable[[Any], Any]] = {
+            "initialize": self._initialize,
+            "describe": self._describe,
+            "shutdown": self._shutdown,
+        }
+
+    def on(self, method: str, handler: Callable[[Any], Any]) -> None:
+        """Register a JSON-RPC method handler."""
+        self._handlers[method] = handler
+
+    def _initialize(self, params: Any) -> dict[str, Any]:
+        peer = int((params or {}).get("protocol_version", 0))
+        if peer != PROTOCOL_VERSION:
+            raise RpcError(-32001, f"incompatible protocol version {peer}")
+        return {
+            "protocol_version": PROTOCOL_VERSION,
+            "server_info": {"name": self.name, "version": self.version},
+        }
+
+    def _describe(self, _params: Any) -> dict[str, Any]:
+        return {"triggers": self.triggers, "agents": self.agents}
+
+    def _shutdown(self, _params: Any) -> dict[str, Any]:
+        return {}
+
+
+def serve_stdio(server: ExtensionServer) -> None:
+    """Serve until EOF or shutdown."""
+    stdin = sys.stdin.buffer
+    stdout = sys.stdout.buffer
+    while True:
+        try:
+            raw = read_frame(stdin)
+        except EOFError:
+            return
+        except Exception as exc:  # noqa: BLE001 — surface parse failures on the wire
+            _write_error(stdout, None, -32700, f"parse error: {exc}")
+            continue
+        try:
+            request = json.loads(raw.decode("utf-8"))
+        except json.JSONDecodeError as exc:
+            _write_error(stdout, None, -32700, f"invalid JSON: {exc}")
+            continue
+        req_id = request.get("id")
+        method = request.get("method")
+        params = request.get("params")
+        if request.get("jsonrpc") != "2.0" or not isinstance(method, str):
+            _write_error(stdout, req_id, -32600, "invalid request")
+            continue
+        handler = server._handlers.get(method)
+        if handler is None:
+            _write_error(stdout, req_id, -32601, f"method not found: {method}")
+            continue
+        try:
+            result = handler(params)
+            write_frame(
+                stdout,
+                json.dumps({"jsonrpc": "2.0", "id": req_id, "result": result}).encode("utf-8"),
+            )
+            if method == "shutdown":
+                return
+        except RpcError as exc:
+            _write_error(stdout, req_id, exc.code, str(exc), exc.data)
+        except Exception as exc:  # noqa: BLE001
+            log(traceback.format_exc())
+            _write_error(stdout, req_id, -32002, f"execution error: {exc}")
+
+
+def _write_error(stdout: Any, req_id: Any, code: int, message: str, data: Any = None) -> None:
+    error: dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        error["data"] = data
+    write_frame(
+        stdout,
+        json.dumps({"jsonrpc": "2.0", "id": req_id, "error": error}).encode("utf-8"),
+    )

curupira_sdk/signature.py

@@ -0,0 +1,215 @@
+"""Function signature introspection for trigger parameters."""
+
+from __future__ import annotations
+
+import inspect
+import typing
+from dataclasses import dataclass
+from typing import Any, get_type_hints
+
+from .errors import RegistrationError, ValidationError
+from .types import coerce_value, is_collection_type, prompt_fields_for_return, type_to_json_schema
+
+# Core automation fields owned by the Rust host — not function parameters.
+CORE_CONFIG_KEYS = frozenset(
+    {
+        "trigger_type",
+        "repository",
+        "prompt",
+        "profile",
+        "checkout",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ParameterSpec:
+    name: str
+    annotation: Any
+    required: bool
+    default: Any
+    has_default: bool
+
+
+@dataclass(frozen=True, slots=True)
+class TriggerSpec:
+    name: str
+    func: Any
+    is_async: bool
+    parameters: tuple[ParameterSpec, ...]
+    return_annotation: Any
+    prompt_fields: tuple[str, ...]
+    schema: dict[str, Any]
+
+
+def to_kebab_case(name: str) -> str:
+    """Convert a Python identifier to kebab-case (``github_issues`` → ``github-issues``)."""
+    if not name:
+        raise RegistrationError("trigger name must not be empty")
+    parts = [part for part in name.replace("-", "_").split("_") if part]
+    if not parts:
+        raise RegistrationError(f"trigger name {name!r} is not a valid identifier")
+    return "-".join(part.lower() for part in parts)
+
+
+def validate_trigger_local_name(name: str) -> str:
+    """Accept a kebab-case local trigger name (no slash; used inside an extension)."""
+    if not name:
+        raise RegistrationError("trigger name must not be empty")
+    if "/" in name:
+        raise RegistrationError(
+            f"trigger name {name!r} must not contain '/'; "
+            "the host prefixes the [plugins.<alias>] registration name"
+        )
+    if name.startswith("-") or name.endswith("-") or "--" in name:
+        raise RegistrationError(f"trigger name {name!r} is not valid kebab-case")
+    if not all(c.isalnum() or c == "-" for c in name):
+        raise RegistrationError(f"trigger name {name!r} is not valid kebab-case")
+    if not any(c.isalpha() for c in name):
+        raise RegistrationError(f"trigger name {name!r} is not valid kebab-case")
+    return name
+
+
+def build_trigger_spec(func: Any, *, name: str | None = None) -> TriggerSpec:
+    """Introspect a trigger function without calling it.
+
+    When ``name`` is omitted, the local trigger name is the kebab-case form of
+    ``func.__name__``. Pass ``name`` (or ``@app.trigger(alias=...)``) to override.
+    """
+    if not callable(func):
+        raise RegistrationError("trigger must be a callable")
+    func_name = func.__name__
+    if not func_name.isidentifier():
+        raise RegistrationError(f"trigger function {func_name!r} is not a valid identifier")
+    local_name = validate_trigger_local_name(name if name is not None else to_kebab_case(func_name))
+
+    signature = inspect.signature(func)
+    try:
+        hints = get_type_hints(func, include_extras=True)
+    except Exception as exc:
+        raise RegistrationError(f"trigger {local_name!r}: cannot resolve type hints: {exc}") from exc
+
+    parameters: list[ParameterSpec] = []
+    for param_name, param in signature.parameters.items():
+        if param.kind is inspect.Parameter.VAR_POSITIONAL:
+            raise RegistrationError(f"trigger {local_name!r}: *args is not supported")
+        if param.kind is inspect.Parameter.VAR_KEYWORD:
+            raise RegistrationError(f"trigger {local_name!r}: **kwargs is not supported")
+        if param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            raise RegistrationError(
+                f"trigger {local_name!r}: positional-only parameter {param_name!r} "
+                "is not supported"
+            )
+        if param.kind not in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            raise RegistrationError(
+                f"trigger {local_name!r}: unsupported parameter kind for {param_name!r}"
+            )
+        if param_name in CORE_CONFIG_KEYS:
+            raise RegistrationError(
+                f"trigger {local_name!r}: parameter {param_name!r} conflicts with a core "
+                "automation field; use a different name (for example `repo`)"
+            )
+        if param.annotation is inspect.Parameter.empty:
+            raise RegistrationError(
+                f"trigger {local_name!r}: parameter {param_name!r} requires a type annotation"
+            )
+        annotation = hints.get(param_name, param.annotation)
+        context = f"trigger {local_name!r} parameter {param_name!r}"
+        # Ensure the type is representable (raises RegistrationError if not).
+        type_to_json_schema(annotation, context=context)
+        has_default = param.default is not inspect.Parameter.empty
+        parameters.append(
+            ParameterSpec(
+                name=param_name,
+                annotation=annotation,
+                required=not has_default,
+                default=param.default if has_default else None,
+                has_default=has_default,
+            )
+        )
+
+    return_annotation = hints.get("return", signature.return_annotation)
+    if return_annotation is inspect.Signature.empty:
+        return_annotation = typing.Any
+    if is_collection_type(return_annotation):
+        raise RegistrationError(
+            f"trigger {local_name!r}: return type must be a single item or None, "
+            "not a collection"
+        )
+
+    schema = _parameters_schema(local_name, parameters)
+    prompt_fields = tuple(prompt_fields_for_return(return_annotation))
+    return TriggerSpec(
+        name=local_name,
+        func=func,
+        is_async=inspect.iscoroutinefunction(func),
+        parameters=tuple(parameters),
+        return_annotation=return_annotation,
+        prompt_fields=prompt_fields,
+        schema=schema,
+    )
+
+
+def _parameters_schema(trigger_name: str, parameters: list[ParameterSpec]) -> dict[str, Any]:
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for param in parameters:
+        context = f"trigger {trigger_name!r} parameter {param.name!r}"
+        prop = type_to_json_schema(param.annotation, context=context)
+        if param.has_default:
+            from .errors import SerializationError
+            from .types import dump_value
+
+            try:
+                prop = {**prop, "default": dump_value(param.default)}
+            except SerializationError:
+                pass
+        properties[param.name] = prop
+        if param.required:
+            required.append(param.name)
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def bind_arguments(spec: TriggerSpec, configuration: dict[str, Any]) -> dict[str, Any]:
+    """Extract and coerce function kwargs from an automation configuration."""
+    param_names = {p.name for p in spec.parameters}
+    extras = sorted(
+        key for key in configuration if key not in CORE_CONFIG_KEYS and key not in param_names
+    )
+    if extras:
+        raise ValidationError(f"trigger {spec.name!r}: unknown parameters {extras}")
+
+    kwargs: dict[str, Any] = {}
+    for param in spec.parameters:
+        if param.name in configuration:
+            kwargs[param.name] = coerce_value(
+                param.annotation,
+                configuration[param.name],
+                context=f"trigger {spec.name!r} parameter {param.name!r}",
+            )
+        elif param.has_default:
+            kwargs[param.name] = param.default
+        else:
+            raise ValidationError(
+                f"trigger {spec.name!r}: missing required parameter {param.name!r}"
+            )
+    return kwargs
+
+
+def normalize_configuration(spec: TriggerSpec, configuration: dict[str, Any]) -> dict[str, Any]:
+    """Validate trigger params and return a full configuration with defaults applied."""
+    kwargs = bind_arguments(spec, configuration)
+    normalized = dict(configuration)
+    for param in spec.parameters:
+        normalized[param.name] = kwargs[param.name]
+    return normalized

curupira_sdk/types.py

@@ -0,0 +1,325 @@
+"""Type introspection helpers for JSON Schema and value conversion."""
+
+from __future__ import annotations
+
+import dataclasses
+import types
+import typing
+from typing import Any, get_args, get_origin
+
+from .errors import RegistrationError, SerializationError, ValidationError
+
+_SCALAR_SCHEMA: dict[type, dict[str, Any]] = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+}
+
+
+def _is_typed_dict(annotation: Any) -> bool:
+    return isinstance(annotation, type) and typing.is_typeddict(annotation)
+
+
+def _is_pydantic_model(annotation: Any) -> bool:
+    try:
+        from pydantic import BaseModel
+    except ImportError:
+        return False
+    return isinstance(annotation, type) and issubclass(annotation, BaseModel)
+
+
+def _require_pydantic(context: str) -> Any:
+    try:
+        from pydantic import BaseModel
+    except ImportError as exc:
+        raise RegistrationError(
+            f"{context}: Pydantic models require the optional dependency "
+            "`curupira-sdk[pydantic]` (pydantic>=2,<3)"
+        ) from exc
+    return BaseModel
+
+
+def unwrap_optional(annotation: Any) -> tuple[Any, bool]:
+    """Return (inner_type, allows_none)."""
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if origin is typing.Union or origin is types.UnionType:
+        non_none = [a for a in args if a is not type(None)]
+        allows_none = len(non_none) != len(args)
+        if len(non_none) == 1:
+            return non_none[0], allows_none
+        if allows_none:
+            combined = non_none[0]
+            for option in non_none[1:]:
+                combined |= option
+            return combined, True
+        return annotation, False
+    return annotation, False
+
+
+def type_to_json_schema(annotation: Any, *, context: str) -> dict[str, Any]:
+    """Convert a type annotation to a JSON Schema fragment."""
+    if annotation is typing.Any or annotation is None:
+        raise RegistrationError(f"{context}: untyped parameters are not supported")
+
+    inner, allows_none = unwrap_optional(annotation)
+    schema = _concrete_schema(inner, context=context)
+    if allows_none:
+        return {"anyOf": [schema, {"type": "null"}]}
+    return schema
+
+
+def _concrete_schema(annotation: Any, *, context: str) -> dict[str, Any]:
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if annotation is type(None):
+        return {"type": "null"}
+
+    if isinstance(annotation, type) and annotation in _SCALAR_SCHEMA:
+        return dict(_SCALAR_SCHEMA[annotation])
+
+    if origin is list or annotation is list:
+        if not args:
+            raise RegistrationError(f"{context}: list requires an item type annotation")
+        return {"type": "array", "items": type_to_json_schema(args[0], context=f"{context}[]")}
+
+    if origin is dict or annotation is dict:
+        if len(args) != 2 or args[0] is not str:
+            raise RegistrationError(f"{context}: only dict[str, T] is supported")
+        return {
+            "type": "object",
+            "additionalProperties": type_to_json_schema(args[1], context=f"{context}.value"),
+        }
+
+    if origin is typing.Union or origin is types.UnionType:
+        return {"anyOf": [type_to_json_schema(a, context=context) for a in args]}
+
+    if dataclasses.is_dataclass(annotation) and isinstance(annotation, type):
+        return _dataclass_schema(annotation, context=context)
+
+    if _is_typed_dict(annotation):
+        return _typed_dict_schema(annotation, context=context)
+
+    if _is_pydantic_model(annotation):
+        _require_pydantic(context)
+        return annotation.model_json_schema()  # type: ignore[no-any-return]
+
+    # Detect pydantic-looking BaseModel subclasses when pydantic is missing.
+    if isinstance(annotation, type) and any(
+        base.__name__ == "BaseModel" for base in getattr(annotation, "__mro__", ())
+    ):
+        _require_pydantic(context)
+
+    raise RegistrationError(
+        f"{context}: unsupported type {annotation!r}; use scalars, list[T], "
+        "dict[str, T], dataclass, TypedDict, or optional Pydantic models"
+    )
+
+
+def _dataclass_field_types(cls: type) -> dict[str, Any]:
+    try:
+        return typing.get_type_hints(cls)
+    except Exception:  # noqa: BLE001
+        return {f.name: f.type for f in dataclasses.fields(cls)}
+
+
+def _dataclass_schema(cls: type, *, context: str) -> dict[str, Any]:
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    hints = _dataclass_field_types(cls)
+    for field in dataclasses.fields(cls):
+        annotation = hints.get(field.name, field.type)
+        properties[field.name] = type_to_json_schema(annotation, context=f"{context}.{field.name}")
+        if (
+            field.default is dataclasses.MISSING and field.default_factory is dataclasses.MISSING  # type: ignore[comparison-overlap]
+        ):
+            required.append(field.name)
+        elif field.default is not dataclasses.MISSING:
+            try:
+                properties[field.name] = {
+                    **properties[field.name],
+                    "default": _json_safe(field.default),
+                }
+            except SerializationError:
+                pass
+    schema: dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    schema["additionalProperties"] = False
+    return schema
+
+
+def _typed_dict_schema(cls: type, *, context: str) -> dict[str, Any]:
+    hints = typing.get_type_hints(cls)
+    required_keys = set(getattr(cls, "__required_keys__", hints.keys()))
+    properties = {
+        name: type_to_json_schema(hint, context=f"{context}.{name}") for name, hint in hints.items()
+    }
+    schema: dict[str, Any] = {"type": "object", "properties": properties}
+    required = [name for name in hints if name in required_keys]
+    if required:
+        schema["required"] = required
+    schema["additionalProperties"] = False
+    return schema
+
+
+def coerce_value(annotation: Any, value: Any, *, context: str) -> Any:
+    """Validate and coerce a JSON value against an annotation."""
+    inner, allows_none = unwrap_optional(annotation)
+    if value is None:
+        if allows_none:
+            return None
+        raise ValidationError(f"{context}: expected a value, got null")
+    return _coerce_concrete(inner, value, context=context)
+
+
+def _coerce_concrete(annotation: Any, value: Any, *, context: str) -> Any:
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if annotation is str:
+        if not isinstance(value, str):
+            raise ValidationError(f"{context}: expected string")
+        return value
+    if annotation is int:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValidationError(f"{context}: expected integer")
+        return value
+    if annotation is float:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValidationError(f"{context}: expected number")
+        return float(value)
+    if annotation is bool:
+        if not isinstance(value, bool):
+            raise ValidationError(f"{context}: expected boolean")
+        return value
+
+    if origin is list:
+        if not isinstance(value, list):
+            raise ValidationError(f"{context}: expected array")
+        return [
+            coerce_value(args[0], item, context=f"{context}[{i}]") for i, item in enumerate(value)
+        ]
+
+    if origin is dict:
+        if not isinstance(value, dict):
+            raise ValidationError(f"{context}: expected object")
+        return {
+            str(key): coerce_value(args[1], item, context=f"{context}.{key}")
+            for key, item in value.items()
+        }
+
+    if origin is typing.Union or origin is types.UnionType:
+        errors: list[str] = []
+        for option in args:
+            if option is type(None):
+                continue
+            try:
+                return coerce_value(option, value, context=context)
+            except (ValidationError, RegistrationError) as exc:
+                errors.append(str(exc))
+        raise ValidationError(
+            f"{context}: value matched none of the union variants ({'; '.join(errors)})"
+        )
+
+    if dataclasses.is_dataclass(annotation) and isinstance(annotation, type):
+        if not isinstance(value, dict):
+            raise ValidationError(f"{context}: expected object for dataclass")
+        kwargs: dict[str, Any] = {}
+        fields = {f.name: f for f in dataclasses.fields(annotation)}
+        hints = _dataclass_field_types(annotation)
+        unknown = set(value) - set(fields)
+        if unknown:
+            raise ValidationError(f"{context}: unknown fields {sorted(unknown)}")
+        for name, field in fields.items():
+            field_type = hints.get(name, field.type)
+            if name in value:
+                kwargs[name] = coerce_value(field_type, value[name], context=f"{context}.{name}")
+            elif field.default is not dataclasses.MISSING:
+                kwargs[name] = field.default
+            elif field.default_factory is not dataclasses.MISSING:  # type: ignore[comparison-overlap]
+                kwargs[name] = field.default_factory()  # type: ignore[misc]
+            else:
+                raise ValidationError(f"{context}: missing required field {name!r}")
+        return annotation(**kwargs)
+
+    if _is_typed_dict(annotation):
+        if not isinstance(value, dict):
+            raise ValidationError(f"{context}: expected object for TypedDict")
+        hints = typing.get_type_hints(annotation)
+        required_keys = set(getattr(annotation, "__required_keys__", hints.keys()))
+        unknown = set(value) - set(hints)
+        if unknown:
+            raise ValidationError(f"{context}: unknown fields {sorted(unknown)}")
+        out: dict[str, Any] = {}
+        for name, hint in hints.items():
+            if name in value:
+                out[name] = coerce_value(hint, value[name], context=f"{context}.{name}")
+            elif name in required_keys:
+                raise ValidationError(f"{context}: missing required field {name!r}")
+        return out
+
+    if _is_pydantic_model(annotation):
+        _require_pydantic(context)
+        try:
+            return annotation.model_validate(value)  # type: ignore[no-any-return]
+        except Exception as exc:
+            raise ValidationError(f"{context}: {exc}") from exc
+
+    raise ValidationError(f"{context}: unsupported type {annotation!r}")
+
+
+def dump_value(value: Any) -> Any:
+    """Convert a Python value to a JSON-serializable structure."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, list):
+        return [dump_value(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): dump_value(item) for key, item in value.items()}
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {f.name: dump_value(getattr(value, f.name)) for f in dataclasses.fields(value)}
+    if _is_pydantic_model(type(value)):
+        return value.model_dump(mode="json")  # type: ignore[no-any-return]
+    raise SerializationError(f"value of type {type(value)!r} is not JSON-serializable")
+
+
+def _json_safe(value: Any) -> Any:
+    return dump_value(value)
+
+
+def prompt_fields_for_return(annotation: Any) -> list[str]:
+    """Derive prompt placeholder field names from a return annotation."""
+    if annotation is typing.Any or annotation is None or annotation is type(None):
+        return []
+    inner, _ = unwrap_optional(annotation)
+    if dataclasses.is_dataclass(inner) and isinstance(inner, type):
+        return [f.name for f in dataclasses.fields(inner)]
+    if _is_typed_dict(inner):
+        return list(typing.get_type_hints(inner))
+    if _is_pydantic_model(inner):
+        return list(inner.model_fields)  # type: ignore[attr-defined]
+    if isinstance(inner, type) and inner in _SCALAR_SCHEMA:
+        return ["value"]
+    origin = get_origin(inner)
+    if origin is dict:
+        return []
+    return []
+
+
+def is_collection_type(annotation: Any) -> bool:
+    """Return True when the annotation denotes a multi-value collection."""
+    if annotation is typing.Any or annotation is None:
+        return False
+    inner, _ = unwrap_optional(annotation)
+    origin = get_origin(inner) or inner
+    if origin in {list, tuple, set, frozenset}:
+        return True
+    return origin in {
+        typing.Iterable,
+        typing.Iterator,
+        typing.Generator,
+        typing.AsyncGenerator,
+    }

curupira_sdk-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: curupira-sdk
+Version: 0.1.0.dev0
+Summary: Declarative SDK for Curupira JSON-RPC process extensions
+Requires-Python: >=3.11
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2; extra == 'pydantic'

curupira_sdk-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,12 @@
+curupira_sdk/__init__.py,sha256=hxqiflm11Iq7H4CO68nik2ons3DOrhV2lOQecmtgErc,658
+curupira_sdk/app.py,sha256=lQzZH7g3qCi58JCFEgyjUc9WiXjebAKVtfzvFOmzsvI,7460
+curupira_sdk/errors.py,sha256=t300CJpMPk5H8F6_VuKDwuT9HO5C2AGikoa_MiiD27c,624
+curupira_sdk/framing.py,sha256=GknokQAAzS08T1aCTpZEKkLbdN-B_PLbMLp09rzZ2rI,1299
+curupira_sdk/runtime.py,sha256=pMIKIH5oSujntmMNJAfw7gxoUXUe9niSvrOtJQebal8,1202
+curupira_sdk/serialize.py,sha256=9jP5ZZErwWDA6ASQnyuj2HzsM4pTHEfCBi-UkWendtA,4503
+curupira_sdk/server.py,sha256=Tnms_nSADeEilO5rvRUVIe0osp7djwg5CJri6sgwBT4,3628
+curupira_sdk/signature.py,sha256=BTDLMdIWxPncLWEia4plGgsulh0MDUnSyVifG9KNuYk,8222
+curupira_sdk/types.py,sha256=lXxf0TthcQLoV6RqLSfaBn4vj3G44Qc6n4s3_KHcRLQ,12545
+curupira_sdk-0.1.0.dev0.dist-info/METADATA,sha256=31HAhdSJzetpcxISpLXCE5H1MaHwKy-FKgYNpl5nS9w,227
+curupira_sdk-0.1.0.dev0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+curupira_sdk-0.1.0.dev0.dist-info/RECORD,,

curupira_sdk-0.1.0.dev0.dist-info/WHEEL

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