velophex 0.2.0__py3-none-any.whl

velophex/entrypoints.py

@@ -0,0 +1,329 @@
+"""The ``@velophex.entrypoint`` decorator and the JSON Schemas it derives from type hints.
+
+An entry point's input and output schema is what the Orchestrator validates job inputs
+against and what the start form in the web UI is generated from (ADR-P002), so the schema has
+to come from something a developer cannot forget to update. It is derived from the handler's
+signature with pydantic's ``TypeAdapter``: parameters become properties, parameters without a
+default become ``required``, and the return annotation becomes the output schema.
+
+    >>> from velophex import entrypoint
+    >>>
+    >>> @entrypoint(id="main", description="Extract the totals of one invoice.")
+    ... def run(pdf_path: str, pages: int = 1) -> dict[str, float]:
+    ...     ...
+
+``velophex pack`` reads the schemas out of the decorated functions; the worker validates the
+``start`` inputs against the same adapter before it calls the handler, so a bad input is a
+``Business``-free ``Application`` fault with a pointer rather than a ``TypeError`` halfway
+through the automation.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import Any, Final, get_type_hints
+
+from pydantic import TypeAdapter, ValidationError
+
+from velophex import _json
+
+__all__ = [
+    "ENTRYPOINT_ATTRIBUTE",
+    "EntryPointDefinition",
+    "EntryPointInputError",
+    "entrypoint",
+    "entrypoint_definition",
+    "is_entrypoint",
+    "normalize_outputs",
+]
+
+#: Attribute the decorator puts on the function; ``velophex pack`` and the worker read it.
+ENTRYPOINT_ATTRIBUTE: Final = "__velophex_entrypoint__"
+
+_EMPTY_OBJECT_SCHEMA: Final[dict[str, Any]] = {"type": "object", "properties": {}, "additionalProperties": False}
+
+
+class EntryPointInputError(ValueError):
+    """The ``start`` inputs do not fit the handler's signature.
+
+    :attr:`pointers` lists a JSON pointer per offending member, which is what the Orchestrator
+    puts into its ``422`` problem details.
+    """
+
+    def __init__(self, message: str, pointers: list[str]) -> None:
+        super().__init__(message)
+        self.pointers = pointers
+
+
+@dataclass(frozen=True, slots=True)
+class EntryPointDefinition:
+    """Everything the SDK knows about one decorated handler."""
+
+    id: str
+    function: Callable[..., Any]
+    display_name: str | None
+    description: str | None
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] | None
+    is_async: bool
+    #: Adapters for the individual parameters, used to coerce and validate start inputs.
+    parameters: dict[str, TypeAdapter[Any]]
+    required: tuple[str, ...]
+
+    @property
+    def handler(self) -> str:
+        """The ``module:function`` reference that goes into ``project.json``."""
+        return f"{self.function.__module__}:{self.function.__name__}"
+
+    def bind(self, inputs: Any) -> dict[str, Any]:
+        """Validate and coerce *inputs* into keyword arguments for the handler.
+
+        Raises :class:`EntryPointInputError` when a required input is missing, an input is
+        unknown or a value does not fit its annotation.
+        """
+        values = inputs if inputs is not None else {}
+
+        if not isinstance(values, dict):
+            raise EntryPointInputError("The inputs must be a JSON object.", ["$"])
+
+        pointers = [f"$.{name}" for name in self.required if name not in values]
+        unknown = [f"$.{name}" for name in values if name not in self.parameters]
+
+        if pointers or unknown:
+            missing = ", ".join(pointer.removeprefix("$.") for pointer in pointers)
+            extra = ", ".join(pointer.removeprefix("$.") for pointer in unknown)
+            parts = [text for text in (f"missing: {missing}" if missing else "", f"unknown: {extra}" if extra else "")]
+            raise EntryPointInputError(
+                f"The inputs do not fit '{self.id}' ({'; '.join(part for part in parts if part)}).",
+                pointers + unknown,
+            )
+
+        bound: dict[str, Any] = {}
+
+        for name, value in values.items():
+            try:
+                bound[name] = self.parameters[name].validate_python(value)
+            except ValidationError as error:
+                # str(error) echoes the rejected value (input_value=...), and this message becomes
+                # the stored fault. Inputs carry secrets, so only the path and the reason are kept
+                # (PY-04); `from None` keeps the value out of a chained traceback too.
+                reasons = "; ".join(
+                    f"{'.'.join(str(part) for part in (name, *detail['loc']))}: {detail['msg']}"
+                    for detail in error.errors(include_input=False, include_url=False, include_context=False)
+                )
+                raise EntryPointInputError(f"Input '{name}' is not valid: {reasons}.", [f"$.{name}"]) from None
+
+        return bound
+
+
+def entrypoint[Handler: Callable[..., Any]](
+    function: Handler | None = None,
+    *,
+    id: str | None = None,
+    display_name: str | None = None,
+    description: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+    output_schema: dict[str, Any] | None = None,
+) -> Handler | Callable[[Handler], Handler]:
+    """Mark *function* as an entry point of the automation.
+
+    The decorator returns the function unchanged, so a handler stays an ordinary callable
+    that tests can call directly. It only attaches the definition the CLI and the worker read.
+
+    Args:
+        function: The handler, when the decorator is used without parentheses.
+        id: The entry point id; defaults to the function name. It must match
+            ``^[A-Za-z][A-Za-z0-9_.-]{0,63}$``.
+        display_name: A label for Studio and the web UI.
+        description: Free text; defaults to the function's docstring summary.
+        input_schema: The input schema, declared rather than derived from the signature.
+            ``velophex pack`` writes it to ``project.json`` as given, so a schema another
+            document owns (an agent definition) is never rewritten from type hints.
+        output_schema: The output schema, declared the same way.
+    """
+
+    def decorate(target: Handler) -> Handler:
+        definition = _describe(target, id, display_name, description)
+
+        if input_schema is not None or output_schema is not None:
+            definition = replace(
+                definition,
+                input_schema=_plain(input_schema) if input_schema is not None else definition.input_schema,
+                output_schema=_plain(output_schema) if output_schema is not None else definition.output_schema,
+            )
+
+        setattr(target, ENTRYPOINT_ATTRIBUTE, definition)
+        return target
+
+    return decorate if function is None else decorate(function)
+
+
+def normalize_outputs(value: Any) -> Any:
+    """Shape a handler's return value into the JSON object a run's result carries.
+
+    One rule for every place a handler runs, so ``velophex run`` prints what the worker sends:
+    ``None`` is ``{}``, a pydantic model is its JSON dump, an object is itself, and a scalar or a
+    list is wrapped as ``{"value": ...}``, matching the output schema the decorator derives. A
+    value with no JSON form (a ``datetime``, NaN) is left for the writer to refuse, which both
+    callers report as ``RESULT_NOT_SERIALIZABLE``.
+    """
+    if value is None:
+        return {}
+
+    if isinstance(value, dict):
+        return value
+
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json", by_alias=True)
+
+    return {"value": value}
+
+
+def is_entrypoint(value: object) -> bool:
+    """True when *value* is a function decorated with :func:`entrypoint`."""
+    return getattr(value, ENTRYPOINT_ATTRIBUTE, None) is not None
+
+
+def entrypoint_definition(value: object) -> EntryPointDefinition:
+    """The definition attached to a decorated handler."""
+    definition = getattr(value, ENTRYPOINT_ATTRIBUTE, None)
+
+    if not isinstance(definition, EntryPointDefinition):
+        raise TypeError(f"{value!r} is not decorated with @velophex.entrypoint.")
+
+    return definition
+
+
+def _describe(
+    target: Callable[..., Any],
+    entry_id: str | None,
+    display_name: str | None,
+    description: str | None,
+) -> EntryPointDefinition:
+    signature = inspect.signature(target)
+    hints = get_type_hints(target)
+
+    parameters: dict[str, TypeAdapter[Any]] = {}
+    required: list[str] = []
+
+    for name, parameter in signature.parameters.items():
+        if parameter.kind in (parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD):
+            raise TypeError(f"'{target.__name__}' cannot be an entry point: *args and **kwargs have no schema.")
+
+        parameters[name] = TypeAdapter(hints.get(name, Any))
+
+        if parameter.default is inspect.Parameter.empty:
+            required.append(name)
+
+    properties, definitions = _parameter_schemas(parameters)
+
+    for name, parameter in signature.parameters.items():
+        if parameter.default is not inspect.Parameter.empty:
+            properties[name]["default"] = parameter.default
+
+    input_schema: dict[str, Any] = {"type": "object", "properties": properties, "additionalProperties": False}
+
+    if required:
+        input_schema["required"] = required
+
+    if definitions:
+        # One shared $defs at the document root, where every "#/$defs/..." reference in the
+        # properties points. Per-parameter schemas used to keep their own $defs nested under
+        # "properties", which left every reference to a nested model unresolvable.
+        input_schema["$defs"] = definitions
+
+    return EntryPointDefinition(
+        id=entry_id or target.__name__,
+        function=target,
+        display_name=display_name,
+        description=description or _summary(target),
+        input_schema=input_schema,
+        output_schema=_output_schema(hints.get("return", inspect.Signature.empty)),
+        is_async=inspect.iscoroutinefunction(target),
+        parameters=parameters,
+        required=tuple(required),
+    )
+
+
+def _output_schema(annotation: Any) -> dict[str, Any] | None:
+    if annotation is inspect.Signature.empty or annotation is None or annotation is type(None):
+        # A handler that returns nothing still has an output contract: the empty object.
+        return dict(_EMPTY_OBJECT_SCHEMA)
+
+    schema = _json_schema(TypeAdapter(annotation))
+
+    # Outputs travel as the JSON object of a `result` message, so a handler that returns a
+    # scalar is described as an object with a single `value` member.
+    if schema.get("type") != "object" and not _refers_to_an_object(schema):
+        # The wrapped schema's $defs move up to the new root: its references are
+        # root-relative ("#/$defs/..."), so left under "properties.value" they resolve to
+        # nothing (a list of models, or a recursive model whose root is a $ref).
+        definitions = schema.pop("$defs", None)
+        wrapped: dict[str, Any] = {"type": "object", "properties": {"value": schema}, "required": ["value"]}
+
+        if definitions:
+            wrapped["$defs"] = definitions
+
+        return wrapped
+
+    return schema
+
+
+def _refers_to_an_object(schema: dict[str, Any]) -> bool:
+    """True for ``{"$ref": "#/$defs/X", "$defs": {...}}`` where ``X`` is an object.
+
+    pydantic describes a recursive model that way. The handler still returns the model, which
+    the worker sends as its own JSON object, so it must not be wrapped in ``{"value": ...}``.
+    """
+    reference = schema.get("$ref")
+
+    if not isinstance(reference, str) or not reference.startswith("#/$defs/"):
+        return False
+
+    target = (schema.get("$defs") or {}).get(reference.removeprefix("#/$defs/"))
+    return isinstance(target, dict) and target.get("type") == "object"
+
+
+_REF_TEMPLATE: Final = "#/$defs/{model}"
+
+
+def _json_schema(adapter: TypeAdapter[Any]) -> dict[str, Any]:
+    # `serialization` mode keeps the schema aligned with what the handler actually returns;
+    # for inputs the two modes agree for every type the protocol can carry.
+    schema = adapter.json_schema(ref_template=_REF_TEMPLATE)
+
+    # Round-trip through the platform reader so the schema carries only plain JSON values and
+    # can be embedded in project.json without surprises.
+    return _plain(schema)
+
+
+def _parameter_schemas(parameters: dict[str, TypeAdapter[Any]]) -> tuple[dict[str, Any], dict[str, Any]]:
+    """The schema of every parameter, and the definitions they share.
+
+    All parameters are generated in one pass so pydantic names the definitions once for the
+    whole document: two parameters of the same model share one entry, and two different
+    models that happen to have the same name get distinct ones instead of overwriting each
+    other. The references it writes are ``#/$defs/<name>``, so the definitions belong at the
+    root of the input schema.
+    """
+    if not parameters:
+        return {}, {}
+
+    schemas, definitions = TypeAdapter.json_schemas(
+        [(name, "validation", adapter) for name, adapter in parameters.items()],
+        ref_template=_REF_TEMPLATE,
+    )
+
+    properties = {name: _plain(schemas[(name, "validation")]) for name in parameters}
+    return properties, _plain(definitions.get("$defs") or {})
+
+
+def _plain(schema: Any) -> Any:
+    return _json.loads(_json.encode_wire(schema))
+
+
+def _summary(target: Callable[..., Any]) -> str | None:
+    doc = inspect.getdoc(target)
+    return doc.split("\n", 1)[0].strip() if doc else None

velophex/errors.py

@@ -0,0 +1,44 @@
+"""The exceptions a VeloPhex Python automation raises and the SDK's own failure type."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from velophex.contracts.executor import FaultInfo
+
+__all__ = ["BusinessError", "VelophexError"]
+
+
+class VelophexError(Exception):
+    """Base class for every error the SDK raises itself.
+
+    Automation code normally sees subclasses only; the worker turns anything else into an
+    ``Application`` fault.
+    """
+
+    def to_fault(self) -> FaultInfo | None:
+        """The fault the worker reports for this error, or ``None`` for ``UNHANDLED_EXCEPTION``.
+
+        A subclass that knows its code (a Runtime API refusal, an agent guardrail) overrides
+        this, so the code reaches the job instead of collapsing into ``UNHANDLED_EXCEPTION``.
+        """
+        return None
+
+
+class BusinessError(VelophexError):
+    """A business rule the automation cannot satisfy — an expected, final outcome.
+
+    The worker reports it as ``Fault(kind="Business")``, which the Orchestrator never
+    retries (ADR-P004): a rejected invoice does not become acceptable on a second run. Use
+    an ordinary exception for anything that a retry could fix.
+
+    Example:
+        >>> raise BusinessError("Total is negative.", code="INVOICE_REJECTED")
+    """
+
+    def __init__(self, message: str, *, code: str = "BUSINESS_RULE_VIOLATED", detail: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.detail = detail