velophex 0.2.0__py3-none-any.whl

velophex/__init__.py

@@ -0,0 +1,38 @@
+"""VeloPhex Python SDK: author, run, pack and publish Python automations.
+
+A Python automation is an ordinary package with a ``project.json`` (ADR-P002) and one or more
+functions marked with :func:`entrypoint`. ``velophex pack`` turns it into the same signed
+``.nupkg`` a Studio workflow produces, and the Runner executes it with ``python -m
+velophex.worker`` over the executor protocol (ADR-P005, ADR-P008).
+
+    >>> import velophex
+    >>>
+    >>> @velophex.entrypoint(id="main")
+    ... def run(pdf_path: str) -> dict[str, float]:
+    ...     if not pdf_path.endswith(".pdf"):
+    ...         raise velophex.BusinessError("Only PDF invoices are accepted.")
+    ...     return {"total": 42.5}
+
+Submodules:
+
+* :mod:`velophex.runtime` - assets, secrets, queues, child jobs and cooperative stop
+* :mod:`velophex.contracts` - the platform contracts as Python models
+* :mod:`velophex.worker` - the executor protocol worker; the Runner's entry point
+* :mod:`velophex.cli` - ``velophex init | run | pack | publish``
+"""
+
+from velophex.entrypoints import EntryPointDefinition, EntryPointInputError, entrypoint
+from velophex.errors import BusinessError, VelophexError
+from velophex.runtime import should_stop
+
+__all__ = [
+    "BusinessError",
+    "EntryPointDefinition",
+    "EntryPointInputError",
+    "VelophexError",
+    "__version__",
+    "entrypoint",
+    "should_stop",
+]
+
+__version__ = "0.2.0"

velophex/_json.py

@@ -0,0 +1,297 @@
+r"""Byte-exact JSON compatible with ``VeloPhex.Platform.Contracts.Json.PlatformJson``.
+
+Every VeloPhex tool must produce the *same bytes* for the same contract document:
+``velophex/package-manifest.json`` carries the SHA-512 of ``content/project.json``, so a
+package written by the Python CLI and one written by Studio only verify against each other
+when both writers agree down to the last escape. Python's :mod:`json` does not agree with
+``System.Text.Json``, which is why this module exists rather than a call to ``json.dumps``.
+
+The four differences that matter, all taken from .NET 10 rather than from the documentation:
+
+* ``System.Text.Json`` uses ``JavaScriptEncoder.Default``, which escapes the HTML-sensitive
+  ASCII characters ``"`` ``&`` ``'`` ``+`` ``<`` ``>`` and the backtick, plus ``\``, the
+  controls and everything outside printable ASCII, as ``\uXXXX`` with **upper-case** hex
+  digits (non-BMP characters as their surrogate pair; a lone surrogate as ``�``).
+  Python escapes almost nothing by default.
+* Indented output is two spaces with LF endings and no space before the ``:``.
+* A ``JsonElement`` (an opaque subtree such as an entry point's JSON Schema) is re-emitted
+  with its **original number literals**: ``1.0`` stays ``1.0`` and ``1e2`` stays ``1e2``.
+  :class:`RawInt` and :class:`RawFloat` carry the literal through a load/dump round trip.
+* ``DateTimeOffset``, ``Guid`` and friends are written by typed fast paths that never reach
+  the encoder, so their ``+`` is not escaped. :class:`VerbatimString` says so.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator, Mapping, Sequence
+from decimal import Decimal
+from typing import Any, Final
+
+__all__ = [
+    "MAXIMUM_DEPTH",
+    "JsonValue",
+    "RawFloat",
+    "RawInt",
+    "VerbatimString",
+    "dumps_document",
+    "dumps_wire",
+    "encode_wire",
+    "escape_string",
+    "loads",
+    "omit_none",
+]
+
+#: Mirrors ``PlatformJson.MaximumDepth``; documents nested deeper are rejected on read.
+MAXIMUM_DEPTH: Final = 64
+
+JsonValue = Any
+"""Any value the platform JSON writer accepts: ``None``, bool, int, float, str, list or dict."""
+
+_INDENT: Final = "  "
+
+# U+FEFF, spelled as a code point so no editor can lose it to its own BOM handling.
+_BOM: Final = chr(0xFEFF)
+
+# Short escapes System.Text.Json emits instead of \uXXXX.
+_SHORT_ESCAPES: Final[dict[int, str]] = {
+    0x08: "\\b",
+    0x09: "\\t",
+    0x0A: "\\n",
+    0x0C: "\\f",
+    0x0D: "\\r",
+    0x5C: "\\\\",
+}
+
+# Printable ASCII that JavaScriptEncoder.Default still escapes, because the encoder is safe
+# for HTML and script contexts by default.
+_HTML_SENSITIVE: Final[frozenset[int]] = frozenset({0x22, 0x26, 0x27, 0x2B, 0x3C, 0x3E, 0x60})
+
+
+class RawInt(int):
+    """An integer JSON literal that remembers the text it was parsed from.
+
+    ``System.Text.Json`` writes a ``JsonElement`` number verbatim, so a schema authored as
+    ``1e2`` must not come back as ``100``. Instances behave as the number they stand for;
+    only the writer looks at :attr:`literal`.
+    """
+
+    # No __slots__: CPython forbids a non-empty one on an int or float subclass.
+    literal: str
+
+    def __new__(cls, literal: str) -> RawInt:
+        value = super().__new__(cls, int(literal))
+        value.literal = literal
+        return value
+
+    def __repr__(self) -> str:
+        return f"RawInt({self.literal!r})"
+
+
+class VerbatimString(str):
+    r"""A string .NET writes without running it through the escaping encoder.
+
+    ``Utf8JsonWriter`` has typed fast paths for ``DateTimeOffset``, ``DateTime``, ``Guid`` and
+    ``TimeSpan`` that format straight into the buffer. The encoder never sees them, so a
+    ``DateTimeOffset`` of ``1970-01-01T00:00:00+00:00`` keeps its ``+`` where the same text in
+    a plain ``string`` property would come out as ``+``. The executor frame vectors pin
+    that difference, so the writer needs a way to say "this one is already formatted".
+
+    Only ever wrap machine-generated text: the contents are emitted between quotes as they
+    are, with no escaping at all.
+    """
+
+
+class RawFloat(float):
+    """A fractional JSON literal that remembers the text it was parsed from."""
+
+    literal: str
+
+    def __new__(cls, literal: str) -> RawFloat:
+        value = super().__new__(cls, float(literal))
+        value.literal = literal
+        return value
+
+    def __repr__(self) -> str:
+        return f"RawFloat({self.literal!r})"
+
+
+def omit_none(members: dict[str, JsonValue]) -> dict[str, JsonValue]:
+    """Drop null members, matching .NET's ``JsonIgnoreCondition.WhenWritingNull``.
+
+    Every contract body is built this way rather than by filtering afterwards, so the member
+    order of the .NET record stays visible in the source.
+    """
+    return {name: value for name, value in members.items() if value is not None}
+
+
+def escape_string(value: str) -> str:
+    """Escape *value* exactly as ``JavaScriptEncoder.Default`` does, without the quotes."""
+    pieces: list[str] = []
+
+    for character in value:
+        code = ord(character)
+
+        if code < 0x20 or code == 0x7F or code in _HTML_SENSITIVE or code == 0x5C:
+            short = _SHORT_ESCAPES.get(code)
+            pieces.append(short if short is not None else f"\\u{code:04X}")
+        elif code < 0x7F:
+            pieces.append(character)
+        elif code > 0xFFFF:
+            # Non-BMP scalars are escaped as the UTF-16 surrogate pair, as .NET does.
+            offset = code - 0x10000
+            pieces.append(f"\\u{0xD800 + (offset >> 10):04X}\\u{0xDC00 + (offset & 0x3FF):04X}")
+        elif 0xD800 <= code <= 0xDFFF:
+            # A lone surrogate (Python keeps them, e.g. from surrogateescape) is not valid
+            # UTF-16; .NET writes U+FFFD in its place rather than failing.
+            pieces.append("\\uFFFD")
+        else:
+            pieces.append(f"\\u{code:04X}")
+
+    return "".join(pieces)
+
+
+def _format_number(value: object) -> str:
+    literal = getattr(value, "literal", None)
+
+    if isinstance(literal, str):
+        return literal
+
+    if isinstance(value, bool):  # bool is an int; callers should never reach here
+        raise TypeError("Booleans are not numbers in JSON.")
+
+    if isinstance(value, int):
+        return str(value)
+
+    if isinstance(value, Decimal):
+        return format(value, "f")
+
+    number = float(value)
+
+    if number != number or number in (float("inf"), float("-inf")):
+        raise ValueError(f"{value!r} has no JSON representation.")
+
+    # repr() gives Python's shortest round-trip form, which matches .NET for every value the
+    # contracts carry (sizes, timeouts, schema bounds). Exponential literals differ in case
+    # and padding, so a document that needs one must keep its RawNumber.
+    return repr(number)
+
+
+def _write(value: JsonValue, out: list[str], indent: int | None, depth: int) -> None:
+    if depth > MAXIMUM_DEPTH:
+        raise ValueError(f"The document is nested deeper than {MAXIMUM_DEPTH} levels.")
+
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, VerbatimString):
+        out.append(f'"{value}"')
+    elif isinstance(value, str):
+        out.append(f'"{escape_string(value)}"')
+    elif isinstance(value, (int, float, Decimal)):
+        out.append(_format_number(value))
+    elif isinstance(value, Mapping):
+        _write_object(value, out, indent, depth)
+    elif isinstance(value, Sequence):
+        _write_array(value, out, indent, depth)
+    else:
+        raise TypeError(f"{type(value).__name__} is not a JSON value.")
+
+
+def _write_object(value: Mapping[str, JsonValue], out: list[str], indent: int | None, depth: int) -> None:
+    items = list(value.items())
+
+    if not items:
+        out.append("{}")
+        return
+
+    inner = None if indent is None else indent + 1
+    out.append("{")
+
+    for index, (name, member) in enumerate(items):
+        if index:
+            out.append(",")
+        if inner is not None:
+            out.append("\n" + _INDENT * inner)
+        out.append(f'"{escape_string(str(name))}":')
+        if inner is not None:
+            out.append(" ")
+        _write(member, out, inner, depth + 1)
+
+    if indent is not None:
+        out.append("\n" + _INDENT * indent)
+
+    out.append("}")
+
+
+def _write_array(value: Sequence[JsonValue], out: list[str], indent: int | None, depth: int) -> None:
+    items = list(value)
+
+    if not items:
+        out.append("[]")
+        return
+
+    inner = None if indent is None else indent + 1
+    out.append("[")
+
+    for index, member in enumerate(items):
+        if index:
+            out.append(",")
+        if inner is not None:
+            out.append("\n" + _INDENT * inner)
+        _write(member, out, inner, depth + 1)
+
+    if indent is not None:
+        out.append("\n" + _INDENT * indent)
+
+    out.append("]")
+
+
+def dumps_document(value: JsonValue) -> str:
+    """Serialize *value* the way the platform writes files: 2-space indent, LF, no trailing newline."""
+    out: list[str] = []
+    _write(value, out, 0, 0)
+    return "".join(out)
+
+
+def dumps_wire(value: JsonValue) -> str:
+    """Serialize *value* the way the platform writes protocol and HTTP payloads: compact."""
+    out: list[str] = []
+    _write(value, out, None, 0)
+    return "".join(out)
+
+
+def encode_wire(value: JsonValue) -> bytes:
+    """UTF-8 bytes of :func:`dumps_wire`."""
+    return dumps_wire(value).encode("utf-8")
+
+
+def loads(payload: str | bytes | bytearray) -> JsonValue:
+    """Parse JSON, keeping number literals intact and rejecting documents that are too deep.
+
+    A UTF-8 byte order mark is tolerated because editors on Windows add one, which is what
+    ``ContractDocumentReader`` does too.
+    """
+    text = bytes(payload).decode("utf-8-sig") if isinstance(payload, (bytes, bytearray)) else payload.lstrip(_BOM)
+
+    value = json.loads(text, parse_int=RawInt, parse_float=RawFloat)
+    _check_depth(value, 0)
+    return value
+
+
+def _check_depth(value: JsonValue, depth: int) -> None:
+    if depth > MAXIMUM_DEPTH:
+        raise ValueError(f"The document is nested deeper than {MAXIMUM_DEPTH} levels.")
+
+    for child in _children(value):
+        _check_depth(child, depth + 1)
+
+
+def _children(value: JsonValue) -> Iterator[JsonValue]:
+    if isinstance(value, Mapping):
+        yield from value.values()
+    elif isinstance(value, list):
+        yield from value

velophex/agents/__init__.py

@@ -0,0 +1,130 @@
+"""Run an agent definition: a model that calls tools until it has an answer.
+
+Needs the ``agents`` extra (``velophex[agents]``). The loop is LangGraph, but nothing here
+exposes it: a definition goes in (``agent-definition`` v1), a validated output comes out, and
+every limit, tool call, approval and trace span goes through the platform's own layer.
+
+    >>> import velophex
+    >>> from velophex import agents
+    >>>
+    >>> @velophex.entrypoint(id="agent")
+    ... def run(question: str) -> dict:
+    ...     return agents.run(DEFINITION, {"question": question})
+
+Inside a job the model is called through the Orchestrator's LLM gateway with the job token,
+tools reach the platform under the same token (process tools run in this job, through the
+Robot), and each step is traced. Outside one (``velophex run``) ``VELOPHEX_AI_BASE_URL``,
+``VELOPHEX_AI_API_KEY`` and optionally ``VELOPHEX_AI_MODEL`` name an OpenAI-compatible
+endpoint, and nothing is traced.
+
+Defaults: 12 model calls, 50 000 tokens and 15 minutes per run, temperature 0.2. A run that
+reaches a limit fails with ``agent_limit_exceeded``; an answer that does not satisfy the output
+schema gets one repair turn, then fails with ``agent_output_invalid``. A run that fails after a
+tool call succeeded is never retried automatically.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from typing import Any
+
+from velophex.agents._errors import (
+    AgentDefinitionError,
+    AgentError,
+    AgentInputError,
+    AgentLimitExceededError,
+    AgentOutputInvalidError,
+    ToolOutcomeUnknownError,
+)
+from velophex.agents._loop import SUPPORTED_LANGGRAPH_MINOR, ChatEndpoint, run_definition
+from velophex.agents._tools import APPROVAL_TIMEOUT_SECONDS, RuntimeTools, ToolClient, ToolOutcome, fence
+from velophex.agents._tracing import NullTracer, RuntimeTracer, Tracer
+from velophex.contracts.agents import AgentDefinition, AgentTool
+from velophex.runtime import current_session, runtime_base_url
+
+__all__ = [
+    "APPROVAL_TIMEOUT_SECONDS",
+    "SUPPORTED_LANGGRAPH_MINOR",
+    "AgentDefinition",
+    "AgentDefinitionError",
+    "AgentError",
+    "AgentInputError",
+    "AgentLimitExceededError",
+    "AgentOutputInvalidError",
+    "AgentTool",
+    "ChatEndpoint",
+    "NullTracer",
+    "RuntimeTools",
+    "RuntimeTracer",
+    "ToolClient",
+    "ToolOutcome",
+    "ToolOutcomeUnknownError",
+    "Tracer",
+    "fence",
+    "run",
+]
+
+#: Seconds kept back from the job's deadline, so the run ends on its own terms rather than killed.
+_DEADLINE_MARGIN_SECONDS = 15
+
+
+def run(
+    definition: AgentDefinition | Mapping[str, Any],
+    inputs: Mapping[str, Any] | None = None,
+    *,
+    chat: ChatEndpoint | None = None,
+    tools: ToolClient | None = None,
+    tracer: Tracer | None = None,
+) -> dict[str, Any]:
+    """Run ``definition`` on ``inputs`` and return its validated output.
+
+    ``chat``, ``tools`` and ``tracer`` default to the job's (the gateway, the Runtime API and
+    the Robot, the job's trace); a test passes the fakes in :mod:`velophex.agents.testing`.
+    """
+    spec = definition if isinstance(definition, AgentDefinition) else AgentDefinition.model_validate(dict(definition))
+    session = current_session()
+    context = session.context if session is not None else None
+    in_job = context is not None and bool(context.orchestrator_url) and bool(context.runtime_token)
+
+    deadline = time.monotonic() + spec.guardrails.timeout_seconds
+
+    if context is not None and context.deadline is not None:
+        left = (context.deadline - datetime.now(UTC)).total_seconds() - _DEADLINE_MARGIN_SECONDS
+        deadline = min(deadline, time.monotonic() + left)
+
+    if tracer is None:
+        tracer = RuntimeTracer(session.client()) if in_job and session is not None else NullTracer()
+
+    return run_definition(
+        spec,
+        dict(inputs or {}),
+        chat=chat or _chat_endpoint(),
+        tools=tools or RuntimeTools(),
+        tracer=tracer,
+        run_id=str(context.job_id) if context is not None and context.job_id else uuid.uuid4().hex,
+        deadline=deadline,
+    )
+
+
+def _chat_endpoint() -> ChatEndpoint:
+    """The job's LLM gateway, or the local endpoint the environment names."""
+    session = current_session()
+    context = session.context if session is not None else None
+
+    if context is not None and context.orchestrator_url and context.runtime_token:
+        headers = {"traceparent": context.trace_parent} if context.trace_parent else {}
+        return ChatEndpoint(runtime_base_url(context.orchestrator_url) + "/ai", context.runtime_token, headers=headers)
+
+    base_url = os.environ.get("VELOPHEX_AI_BASE_URL")
+
+    if not base_url:
+        raise AgentError(
+            "There is no model to call: run the agent in a job, or set VELOPHEX_AI_BASE_URL "
+            "(and VELOPHEX_AI_API_KEY) to an OpenAI-compatible endpoint for a local run."
+        )
+
+    return ChatEndpoint(base_url, os.environ.get("VELOPHEX_AI_API_KEY") or "none", os.environ.get("VELOPHEX_AI_MODEL"))

velophex/agents/_errors.py

@@ -0,0 +1,75 @@
+"""The errors an agent run ends with, each reported under its own fault code."""
+
+from __future__ import annotations
+
+from velophex.contracts.executor import FAULT_ENVELOPE_VERSION, FaultInfo, FaultRetryScopes
+from velophex.contracts.runtimes import FaultCodes, FaultKinds
+from velophex.errors import VelophexError
+
+__all__ = [
+    "AgentDefinitionError",
+    "AgentError",
+    "AgentInputError",
+    "AgentLimitExceededError",
+    "AgentOutputInvalidError",
+    "ToolOutcomeUnknownError",
+]
+
+
+class AgentError(VelophexError):
+    """Base of the errors an agent run raises itself. Never retried automatically."""
+
+    code: str = FaultCodes.UNHANDLED_EXCEPTION
+    fix: str | None = None
+    retry_scope: str = FaultRetryScopes.RUN
+
+    def to_fault(self) -> FaultInfo:
+        """Reported under :attr:`code`, as an ``Application`` fault that is not retried."""
+        return FaultInfo(
+            kind=FaultKinds.APPLICATION,
+            code=self.code,
+            message=str(self),
+            retryable=False,
+            version=FAULT_ENVELOPE_VERSION,
+            fix=self.fix,
+            retry_scope=self.retry_scope,
+        )
+
+
+class AgentDefinitionError(AgentError):
+    """The definition cannot run on this SDK (a member version 1 does not have, a duplicate tool)."""
+
+    code = FaultCodes.INVALID_PACKAGE
+    fix = "Correct the agent definition and create a new candidate."
+    retry_scope = FaultRetryScopes.NONE
+
+
+class AgentInputError(AgentError):
+    """The run's inputs do not satisfy the definition's input schema."""
+
+    code = FaultCodes.INVALID_INPUT
+    fix = "Start the run with inputs that match the agent's input schema."
+    retry_scope = FaultRetryScopes.NONE
+
+
+class AgentOutputInvalidError(AgentError):
+    """The answer did not satisfy the output schema, after one repair turn."""
+
+    code = FaultCodes.AGENT_OUTPUT_INVALID
+    fix = "Make the instructions or the output schema clearer, then run again."
+
+
+class AgentLimitExceededError(AgentError):
+    """The run reached a guardrail: its steps, its tokens or its timeout."""
+
+    code = FaultCodes.AGENT_LIMIT_EXCEEDED
+    fix = "Raise the agent's limits, or narrow its task, then run again."
+
+
+class ToolOutcomeUnknownError(AgentError):
+    """A tool call ended without a known outcome. It is reconciled by a person, never replayed."""
+
+    code = FaultCodes.TOOL_OUTCOME_UNKNOWN
+    fix = "Check the system the tool writes to before running the agent again."
+    retry_scope = FaultRetryScopes.NONE
+    effects_committed = True