velophex 0.2.0__py3-none-any.whl

velophex/cli/sync.py

@@ -0,0 +1,90 @@
+"""Keeps ``project.json`` in step with the decorated handlers.
+
+The entry point schemas in ``project.json`` are what the Orchestrator validates job inputs
+against and what the start form is generated from, so they must not be hand-maintained: a
+schema that has drifted from the handler fails on the robot, not in the editor. ``velophex
+pack`` therefore imports each handler and rewrites its entry point before it packs.
+
+Importing runs the author's own module, which is the same thing ``velophex run`` does; the
+synchronisation is skipped with ``--no-sync`` for a project whose handlers cannot be imported
+on the machine that packs (a Windows-only automation packed on a build agent, say).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from velophex.contracts.project import EntryPoint, ProjectFiles, ProjectManifest, RuntimeSpec
+from velophex.contracts.runtimes import RuntimeKind
+from velophex.worker.loader import PackageLoadError, load_entry_point
+
+__all__ = ["DEFAULT_PYTHON_VERSION", "SyncResult", "synchronize"]
+
+#: ADR-P008: the platform ships CPython 3.12 and nothing else.
+DEFAULT_PYTHON_VERSION = ">=3.12,<3.13"
+
+
+@dataclass(slots=True)
+class SyncResult:
+    """The manifest after synchronisation, and what could not be refreshed."""
+
+    manifest: ProjectManifest
+    warnings: list[str]
+    changed: bool
+
+
+def synchronize(
+    project_directory: str | Path,
+    manifest: ProjectManifest,
+    *,
+    import_handlers: bool = True,
+) -> SyncResult:
+    """Return *manifest* with the Python runtime settings and entry point schemas refreshed."""
+    warnings: list[str] = []
+    runtime = _runtime(manifest.runtime)
+    entry_points = list(manifest.entry_points)
+
+    if import_handlers:
+        for index, entry in enumerate(entry_points):
+            refreshed, warning = _refresh(project_directory, entry)
+            entry_points[index] = refreshed
+
+            if warning:
+                warnings.append(warning)
+
+    updated = manifest.model_copy(update={"runtime": runtime, "entry_points": entry_points}).normalized()
+
+    return SyncResult(manifest=updated, warnings=warnings, changed=updated != manifest.normalized())
+
+
+def _runtime(runtime: RuntimeSpec) -> RuntimeSpec:
+    return runtime.model_copy(
+        update={
+            "kind": RuntimeKind.PYTHON,
+            "python_version": runtime.python_version or DEFAULT_PYTHON_VERSION,
+            "lock_file": runtime.lock_file or ProjectFiles.PYTHON_LOCK_FILE_NAME,
+        }
+    )
+
+
+def _refresh(project_directory: str | Path, entry: EntryPoint) -> tuple[EntryPoint, str | None]:
+    try:
+        loaded = load_entry_point(project_directory, entry.id)
+    except PackageLoadError as error:
+        return entry, f"Entry point '{entry.id}' was left as it is: {error}"
+
+    definition = loaded.definition
+
+    return (
+        entry.model_copy(
+            update={
+                "handler": definition.handler,
+                "display_name": entry.display_name or definition.display_name,
+                "description": entry.description or definition.description,
+                "input": definition.input_schema,
+                "output": definition.output_schema,
+            }
+        ),
+        None,
+    )

velophex/cli/templates.py

@@ -0,0 +1,126 @@
+"""The project ``velophex init`` writes.
+
+A new automation is a uv project with a ``src/`` layout, one decorated handler and a
+``project.json`` that already says what the platform needs to place and run it. It is
+deliberately small: the schemas come from the handler's signature, so there is nothing in
+``project.json`` for the author to keep in step by hand.
+
+``uv.lock`` is *not* written here. It is produced by ``uv sync``, which is also what pins the
+``velophex`` SDK into the lock file - and a Python package without ``uv.lock`` is refused both
+by ``velophex pack`` and by the Orchestrator inspector (ADR-P008).
+"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from velophex.cli.sync import DEFAULT_PYTHON_VERSION
+from velophex.contracts.project import (
+    CURRENT_SCHEMA_VERSION,
+    EntryPoint,
+    ExecutionSettings,
+    ProjectManifest,
+    RuntimeSpec,
+)
+from velophex.contracts.runtimes import RuntimeKind
+
+__all__ = ["handler_module", "module_name", "new_project_manifest", "pyproject_toml", "python_version_marker"]
+
+
+def module_name(project_name: str) -> str:
+    """The importable module name for a project name such as ``Invoice.Ocr``."""
+    cleaned = "".join(character if character.isalnum() else "_" for character in project_name).strip("_").lower()
+    return cleaned or "automation"
+
+
+def python_version_marker() -> str:
+    """The ``requires-python`` marker the platform supports."""
+    return DEFAULT_PYTHON_VERSION
+
+
+def new_project_manifest(name: str, version: str = "1.0.0", project_id: UUID | None = None) -> ProjectManifest:
+    """The ``project.json`` of a new Python automation."""
+    module = module_name(name)
+
+    return ProjectManifest(
+        schemaVersion=CURRENT_SCHEMA_VERSION,
+        projectId=project_id or uuid4(),
+        name=name,
+        version=version,
+        description=f"{name} automation.",
+        outputType="process",
+        runtime=RuntimeSpec(kind=RuntimeKind.PYTHON, pythonVersion=DEFAULT_PYTHON_VERSION, lockFile="uv.lock"),
+        main=f"src/{module}/main.py",
+        entryPoints=[
+            EntryPoint(id="main", path=f"src/{module}/main.py", handler=f"{module}.main:run"),
+        ],
+        execution=ExecutionSettings(),
+    )
+
+
+def pyproject_toml(name: str, version: str, sdk_specifier: str, sdk_wheel: str | None = None) -> str:
+    """The ``pyproject.toml`` of a new automation.
+
+    With *sdk_wheel* (a path relative to the project) the SDK comes from that vendored wheel
+    instead of an index: ``uv.lock`` then records the relative path and the wheel's SHA-256,
+    and ``velophex pack`` carries the wheel inside the package, so a Robot's
+    ``uv sync --frozen`` restores it from the package itself and never asks an index for a
+    package named ``velophex`` (PY-01, PY-02).
+    """
+    module = module_name(name)
+    sources = (
+        f"""
+[tool.uv.sources]
+# Vendored: packed with the automation, so a Robot restores the SDK without any index.
+velophex = {{ path = "{sdk_wheel}" }}
+"""
+        if sdk_wheel
+        else ""
+    )
+
+    return f"""[project]
+name = "{module}"
+version = "{version}"
+description = "{name} automation."
+requires-python = "{DEFAULT_PYTHON_VERSION}"
+dependencies = [
+  "velophex{sdk_specifier}",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{module}"]
+{sources}"""
+
+
+def handler_module(name: str) -> str:
+    """The starting handler of a new automation."""
+    return f'''"""Entry points of the {name} automation."""
+
+import logging
+
+import velophex
+from velophex import runtime
+
+log = logging.getLogger(__name__)
+
+
+@velophex.entrypoint(id="main", display_name="Run")
+def run(message: str = "Hello from VeloPhex") -> dict[str, str]:
+    """Say hello.
+
+    Every parameter becomes an input in project.json, typed from its annotation, and the
+    return annotation becomes the output schema - there is nothing to keep in step by hand.
+    """
+    log.info("%s", message)
+
+    # Long-running work polls this so a Stop from the Orchestrator ends the run cleanly
+    # instead of waiting for the kill.
+    if runtime.stop_requested():
+        raise velophex.BusinessError("The run was stopped before it did anything.")
+
+    return {{"message": message}}
+'''

velophex/contracts/__init__.py

@@ -0,0 +1,103 @@
+"""Python models of the VeloPhex platform contracts.
+
+One definition per contract, mirroring ``VeloPhex.Platform.Contracts`` and the JSON Schemas
+in ``VeloPhex.Platform.Contracts/schemas``:
+
+* :mod:`velophex.contracts.project` - ``project.json`` (ADR-P002)
+* :mod:`velophex.contracts.package` - ``velophex/package-manifest.json`` v2 (ADR-P003)
+* :mod:`velophex.contracts.executor` - the executor protocol messages (ADR-P005)
+* :mod:`velophex.contracts.runtimes` - runtime kinds, phases, levels and fault kinds
+* :mod:`velophex.contracts.signin` - the states a sign-in passes through (D1)
+* :mod:`velophex.contracts.validation` - the lexical rules the schemas express
+
+Contracts change only through the ``velophex-contract-change`` skill, which updates every
+consumer together; nothing here may drift on its own.
+"""
+
+from velophex.contracts.diagnostics import (
+    ContractError,
+    Diagnostic,
+    PackageDiagnosticCodes,
+    ProjectDiagnosticCodes,
+    Severity,
+    has_errors,
+)
+from velophex.contracts.package import (
+    PackageFile,
+    PackageLayout,
+    PackageManifest,
+    create_package_manifest,
+    describe_file,
+    read_package_manifest,
+    sha512_hex,
+    validate_package_manifest,
+    write_package_manifest,
+)
+from velophex.contracts.project import (
+    AutomationDependency,
+    DesignerSettings,
+    EntryPoint,
+    ExecutionSettings,
+    ExpressionLanguages,
+    OutputTypes,
+    ProjectFiles,
+    ProjectManifest,
+    RuntimeSpec,
+    read_project_manifest,
+    validate_project_manifest,
+    write_project_manifest,
+)
+from velophex.contracts.runtimes import (
+    AttemptOutcomes,
+    ExecutionPhases,
+    FaultCodes,
+    FaultKinds,
+    LogLevels,
+    LogStages,
+    PhaseStatuses,
+    RuntimeKind,
+    RuntimeStatuses,
+    SignalReasons,
+)
+from velophex.contracts.signin import SignInStates
+
+__all__ = [
+    "AttemptOutcomes",
+    "AutomationDependency",
+    "ContractError",
+    "DesignerSettings",
+    "Diagnostic",
+    "EntryPoint",
+    "ExecutionPhases",
+    "ExecutionSettings",
+    "ExpressionLanguages",
+    "FaultCodes",
+    "FaultKinds",
+    "LogLevels",
+    "LogStages",
+    "OutputTypes",
+    "PackageDiagnosticCodes",
+    "PackageFile",
+    "PackageLayout",
+    "PackageManifest",
+    "PhaseStatuses",
+    "ProjectDiagnosticCodes",
+    "ProjectFiles",
+    "ProjectManifest",
+    "RuntimeKind",
+    "RuntimeSpec",
+    "RuntimeStatuses",
+    "Severity",
+    "SignInStates",
+    "SignalReasons",
+    "create_package_manifest",
+    "describe_file",
+    "has_errors",
+    "read_package_manifest",
+    "read_project_manifest",
+    "sha512_hex",
+    "validate_package_manifest",
+    "validate_project_manifest",
+    "write_package_manifest",
+    "write_project_manifest",
+]

velophex/contracts/_model.py

@@ -0,0 +1,26 @@
+"""Shared base for contract models.
+
+Contract documents travel between five codebases, so an unknown member is data from a newer
+writer rather than a mistake: models keep it (``extra="allow"``) and emit it again after the
+members they know, which is where ``[JsonExtensionData]`` puts it in .NET.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from velophex._json import omit_none
+
+__all__ = ["ContractModel", "omit_none"]
+
+
+class ContractModel(BaseModel):
+    """Base for contract models: camelCase on the wire, unknown members preserved."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow", arbitrary_types_allowed=True)
+
+    def extras(self) -> dict[str, Any]:
+        """Members this version of the SDK does not know, in the order they were read."""
+        return dict(self.__pydantic_extra__ or {})

velophex/contracts/agents.py

@@ -0,0 +1,110 @@
+"""The agent definition, version 1 (``schemas/agent-definition.v1.schema.json``, contracts 0.8.37).
+
+Mirrors ``VeloPhex.Platform.Contracts.Agents``. Version 1 changes additively only, so members a
+newer writer adds are kept (``extra="allow"``) rather than refused, and an absent member means the
+default below.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from pydantic import Field
+
+from velophex.contracts._model import ContractModel
+
+__all__ = [
+    "DEFAULT_BINDING",
+    "DEFAULT_MAX_STEPS",
+    "DEFAULT_MAX_TOKENS",
+    "DEFAULT_TEMPERATURE",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "SPEC_VERSION",
+    "AgentDefinition",
+    "AgentGuardrails",
+    "AgentModel",
+    "AgentModelParameters",
+    "AgentTool",
+    "AgentToolApprovals",
+    "AgentToolKinds",
+]
+
+SPEC_VERSION: Final = 1
+DEFAULT_MAX_STEPS: Final = 12
+DEFAULT_MAX_TOKENS: Final = 50_000
+DEFAULT_TIMEOUT_SECONDS: Final = 900
+DEFAULT_TEMPERATURE: Final = 0.2
+DEFAULT_BINDING: Final = "agent:default"
+
+
+class AgentToolKinds:
+    """The ``kind`` of an agent tool."""
+
+    PROCESS: Final = "process"
+    MCP: Final = "mcp"
+    HTTP: Final = "http"
+    VECTOR_SEARCH: Final = "vector_search"
+    ACTION_TASK: Final = "action_task"
+
+
+class AgentToolApprovals:
+    """The ``approval`` of an agent tool."""
+
+    NONE: Final = "none"
+    BEFORE_CALL: Final = "before_call"
+
+
+class AgentModelParameters(ContractModel):
+    """Sampling parameters of every model call."""
+
+    temperature: float | None = None
+    max_tokens: int | None = Field(default=None, alias="maxTokens")
+    top_p: float | None = Field(default=None, alias="topP")
+
+
+class AgentModel(ContractModel):
+    """The model binding (``<purpose>:<name>``) and its parameters."""
+
+    binding: str = DEFAULT_BINDING
+    parameters: AgentModelParameters | None = None
+
+
+class AgentTool(ContractModel):
+    """One tool the model may call."""
+
+    kind: str
+    ref: str
+    name: str
+    description: str
+    entry_point: str | None = Field(default=None, alias="entryPoint")
+    input_schema: dict[str, Any] | None = Field(default=None, alias="inputSchema")
+    approval: str = AgentToolApprovals.NONE
+    top_k: int | None = Field(default=None, alias="topK")
+
+
+class AgentGuardrails(ContractModel):
+    """Limits of one run."""
+
+    max_steps: int = Field(default=DEFAULT_MAX_STEPS, alias="maxSteps")
+    max_tokens: int = Field(default=DEFAULT_MAX_TOKENS, alias="maxTokens")
+    max_cost: float | None = Field(default=None, alias="maxCost")
+    timeout_seconds: int = Field(default=DEFAULT_TIMEOUT_SECONDS, alias="timeoutSeconds")
+    blocked_tools: list[str] = Field(default_factory=list, alias="blockedTools")
+    output_validation: str = Field(default="schema", alias="outputValidation")
+
+
+class AgentDefinition(ContractModel):
+    """What an agent is: instructions, model, schemas, tools and limits."""
+
+    spec_version: int = Field(default=SPEC_VERSION, alias="specVersion")
+    key: str
+    name: str
+    description: str | None = None
+    instructions: str
+    model: AgentModel = Field(default_factory=AgentModel)
+    input: dict[str, Any] | None = None
+    output: dict[str, Any] | None = None
+    tools: list[AgentTool] = Field(default_factory=list)
+    guardrails: AgentGuardrails = Field(default_factory=AgentGuardrails)
+    memory: dict[str, Any] | None = None
+    loop: str | None = None

velophex/contracts/diagnostics.py

@@ -0,0 +1,157 @@
+"""Contract diagnostics, with the same codes and JSON pointers the .NET validators emit.
+
+A developer who sees ``VPC1012`` from ``velophex pack`` and ``VPC1012`` from the Orchestrator
+upload is looking at the same rule, so the codes are copied from
+``VeloPhex.Platform.Contracts`` rather than invented here. Codes are stable; a retired code
+is never reused.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Final
+
+__all__ = [
+    "ContractError",
+    "Diagnostic",
+    "PackageDiagnosticCodes",
+    "ProjectDiagnosticCodes",
+    "Severity",
+    "has_errors",
+]
+
+
+# Not StrEnum: that changes str(Severity.ERROR) from "Severity.ERROR" to "Error", which is a
+# behaviour change for anything that formats the member rather than its value.
+class Severity(str, Enum):  # noqa: UP042
+    """How badly a diagnostic breaks the contract."""
+
+    ERROR = "Error"
+    WARNING = "Warning"
+    INFORMATION = "Information"
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """One rule violation, located by a JSON pointer-ish path such as ``$.entryPoints[0].id``."""
+
+    code: str
+    path: str
+    message: str
+    severity: Severity = Severity.ERROR
+
+    @classmethod
+    def error(cls, code: str, path: str, message: str) -> Diagnostic:
+        """Create an error diagnostic."""
+        return cls(code, path, message, Severity.ERROR)
+
+    @classmethod
+    def warning(cls, code: str, path: str, message: str) -> Diagnostic:
+        """Create a warning diagnostic."""
+        return cls(code, path, message, Severity.WARNING)
+
+    def __str__(self) -> str:
+        return f"{self.severity.value} {self.code} at {self.path}: {self.message}"
+
+
+def has_errors(diagnostics: list[Diagnostic]) -> bool:
+    """True when at least one diagnostic is an error."""
+    return any(diagnostic.severity is Severity.ERROR for diagnostic in diagnostics)
+
+
+class ContractError(Exception):
+    """Raised when a contract document cannot be read or does not validate."""
+
+    def __init__(self, diagnostics: list[Diagnostic]) -> None:
+        super().__init__("; ".join(str(diagnostic) for diagnostic in diagnostics) or "The document is invalid.")
+        self.diagnostics = diagnostics
+
+
+class ProjectDiagnosticCodes:
+    """Diagnostic codes for ``project.json`` (mirrors ``ProjectDiagnosticCodes`` in .NET)."""
+
+    INVALID_JSON: Final = "VPC1000"
+    UNSUPPORTED_SCHEMA_VERSION: Final = "VPC1001"
+    MISSING_PROJECT_ID: Final = "VPC1002"
+    INVALID_NAME: Final = "VPC1003"
+    INVALID_VERSION: Final = "VPC1004"
+    UNKNOWN_OUTPUT_TYPE: Final = "VPC1005"
+    UNKNOWN_RUNTIME: Final = "VPC1006"
+    UNSUPPORTED_EXPRESSION_LANGUAGE: Final = "VPC1007"
+    MISSING_PYTHON_VERSION: Final = "VPC1008"
+    MISSING_LOCK_FILE: Final = "VPC1009"
+    INVALID_WORKFLOW_ENTRY_PATH: Final = "VPC1010"
+    UNEXPECTED_HANDLER: Final = "VPC1011"
+    INVALID_PYTHON_HANDLER: Final = "VPC1012"
+    MISSING_ENTRY_POINTS: Final = "VPC1013"
+    INVALID_ENTRY_POINT_ID: Final = "VPC1014"
+    UNSAFE_PATH: Final = "VPC1015"
+    INVALID_ARGUMENT_SCHEMA: Final = "VPC1016"
+    MAIN_NOT_AN_ENTRY_POINT: Final = "VPC1017"
+    INVALID_DEPENDENCY: Final = "VPC1018"
+    INVALID_AUTOMATION_DEPENDENCY: Final = "VPC1019"
+    SELF_DEPENDENCY: Final = "VPC1020"
+    INVALID_TIMEOUT: Final = "VPC1021"
+    INVALID_CAPABILITY: Final = "VPC1022"
+    DOCUMENT_TOO_LARGE: Final = "VPC1023"
+    DUPLICATE_ENTRY_POINT: Final = "VPC1024"
+    NO_RUN_MODE_ALLOWED: Final = "VPC1025"
+
+    #: A dependency's value is present but is not a NuGet version range.
+    INVALID_DEPENDENCY_VERSION_RANGE: Final = "VPC1026"
+
+    #: An automation dependency's version is present but is not a NuGet version range.
+    INVALID_AUTOMATION_DEPENDENCY_VERSION_RANGE: Final = "VPC1027"
+
+    #: The version is SemVer 2.0 but carries build metadata (``1.0.0+build.7``), which NuGet drops
+    #: from a package's identity; the manifest and the feed would name different versions.
+    VERSION_HAS_BUILD_METADATA: Final = "VPC1028"
+
+    #: ``expressions`` names an unknown policy, or an extra type that is not a type name or is on
+    #: the expression floor (engine ADR 0036).
+    INVALID_EXPRESSION_POLICY: Final = "VPC1029"
+
+    #: A global or constant has a name that is not an identifier, repeats another global's or
+    #: constant's name (ignoring case, as Visual Basic does), has no type, or a constant has no
+    #: value (contracts 0.8.11).
+    INVALID_PROJECT_SYMBOL: Final = "VPC1030"
+
+    #: ``exceptionHandlerWorkflow`` is not a safe relative ``.xaml`` path, or the project is not a
+    #: VeloPhex workflow project (engine ADR 0037 section 5, contracts 0.8.16).
+    INVALID_EXCEPTION_HANDLER_WORKFLOW: Final = "VPC1031"
+
+    #: An entry point's ``testCase`` is in a ``library`` project, or its ``dataSource`` is not a
+    #: safe relative ``.csv``, ``.json`` or ``.xlsx[#Sheet]`` path (0.8.30), or names one in a
+    #: project that is not a VeloPhex workflow project (contracts 0.8.25).
+    INVALID_TEST_CASE: Final = "VPC1032"
+
+    #: ``icon`` is not a safe relative ``.png`` or ``.svg`` path (contracts 0.8.36). The file's
+    #: presence and size are checked when the package is built.
+    INVALID_ICON: Final = "VPC1033"
+
+
+class PackageDiagnosticCodes:
+    """Diagnostic codes for automation packages (mirrors ``PackageDiagnosticCodes`` in .NET)."""
+
+    INVALID_JSON: Final = "VPC2000"
+    UNSUPPORTED_FORMAT: Final = "VPC2001"
+    UNSUPPORTED_MANIFEST_VERSION: Final = "VPC2002"
+    PACKAGE_ID_MISMATCH: Final = "VPC2003"
+    PACKAGE_VERSION_MISMATCH: Final = "VPC2004"
+    RUNTIME_MISMATCH: Final = "VPC2005"
+    REQUIRED_RUNTIMES_MISMATCH: Final = "VPC2006"
+    INVALID_FILE_ENTRY: Final = "VPC2007"
+    DUPLICATE_FILE: Final = "VPC2008"
+    FILES_NOT_SORTED: Final = "VPC2009"
+    DOCUMENT_TOO_LARGE: Final = "VPC2010"
+    MISSING_PROJECT_MANIFEST: Final = "VPC2011"
+    MISSING_FILE: Final = "VPC2012"
+    UNLISTED_FILE: Final = "VPC2013"
+    HASH_MISMATCH: Final = "VPC2014"
+    SIZE_MISMATCH: Final = "VPC2015"
+    MISSING_ENTRY_POINT_FILE: Final = "VPC2016"
+    MISSING_PYTHON_LOCK_FILE: Final = "VPC2017"
+
+    #: ``expressionPolicy`` is invalid, has no tier version, or does not carry its own fingerprint.
+    INVALID_EXPRESSION_POLICY: Final = "VPC2018"