reactor-runtime 2.2.0__tar.gz → 2.3.0__tar.gz

{reactor_runtime-2.2.0 → reactor_runtime-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.2.0
+Version: 2.3.0
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9
@@ -14,6 +14,7 @@ Requires-Dist: fastapi>=0.100.0
 Requires-Dist: uvicorn[standard]>=0.23.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: redis
+Requires-Dist: jsonschema>=4.20.0
 Requires-Dist: opentelemetry-api~=1.39
 Requires-Dist: opentelemetry-sdk~=1.39
 Requires-Dist: opentelemetry-exporter-otlp-proto-http~=1.39

{reactor_runtime-2.2.0 → reactor_runtime-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.2.0"
+version = "2.3.0"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }
@@ -22,6 +22,7 @@ dependencies = [
     "uvicorn[standard]>=0.23.0",
 	"aiohttp>=3.9.0",
 	"redis",
+	"jsonschema>=4.20.0",
 	"opentelemetry-api~=1.39",
 	"opentelemetry-sdk~=1.39",
 	"opentelemetry-exporter-otlp-proto-http~=1.39",

{reactor_runtime-2.2.0 → reactor_runtime-2.3.0}/src/reactor_cli/commands/__init__.py

@@ -7,10 +7,10 @@ Each command is implemented as a class following the HuggingFace pattern.
 
 from .run import RunCommand
 from .init import InitCommand
-from .capabilities import CapabilitiesCommand
+from .schema import SchemaCommand
 
 __all__ = [
     "RunCommand",
     "InitCommand",
-    "CapabilitiesCommand",
+    "SchemaCommand",
 ]

reactor_runtime-2.3.0/src/reactor_cli/commands/schema.py

@@ -0,0 +1,146 @@
+# Copyright (c) 2026 Reactor Technologies, Inc. All rights reserved.
+"""Schema command — prints or writes the model's OpenAPI 3.1 schema."""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from omegaconf import OmegaConf
+
+from reactor_runtime.schema import ModelSchema
+from reactor_runtime.config import ReactorConfig
+from reactor_runtime.utils.loader import resolve_class
+from reactor_runtime.utils.launch import add_import_paths
+
+_REACTOR_YAML = "reactor.yaml"
+
+_VERSION_PATTERN = re.compile(r"^v?\d+\.\d+\.\d+(-g[0-9a-f]+)?$")
+# Describes valid --version input. Reused by both the --version argparse
+# help text and the error message on pattern mismatch. Starts with a
+# capitalised "Format:" so it reads naturally both standalone and after
+# "Error: invalid --version 'bad': ".
+_VERSION_FORMAT_HINT = (
+    "Format: 'X.Y.Z' or 'X.Y.Z-g<hex>', optionally with a 'v' prefix "
+    "(e.g. '2.2.1', 'v2.2.1', '2.2.1-gac767ec', 'v2.2.1-gac767ec'). "
+    "The 'v' prefix is optional on input — the emitted schema always "
+    "carries it."
+)
+
+
+class SchemaCommand:
+    @staticmethod
+    def register_subcommand(subparsers):
+        """Register schema command."""
+        run_parser = subparsers.add_parser(
+            "schema", help="Print or write the model's OpenAPI schema."
+        )
+        run_parser.add_argument(
+            "--path",
+            "-p",
+            type=str,
+            default=None,
+            help="Path to model directory (default: current directory)",
+        )
+        run_parser.add_argument(
+            "--version",
+            "-v",
+            type=str,
+            default=None,
+            help=(
+                "Override the schema version emitted in info.version. "
+                f"{_VERSION_FORMAT_HINT} Default: v0.0.0."
+            ),
+        )
+        run_parser.add_argument(
+            "--out",
+            "-o",
+            type=str,
+            default=None,
+            help=(
+                "Write the schema JSON to this path instead of printing to "
+                "stdout. Parent directories are created if missing."
+            ),
+        )
+        run_parser.set_defaults(func=SchemaCommand)
+
+    def __init__(self, args):
+        """Initialize with parsed arguments."""
+        self.args = args
+
+    def run(self):
+        """Emit the OpenAPI schema of a Reactor model.
+
+        Loads the model class (triggering auto-registration of tracks,
+        events, and messages in the global registries), builds the
+        schema from those registries, optionally overrides the version,
+        and either prints the JSON to stdout or writes it to ``--out``.
+        """
+        if self.args.version is not None and not _VERSION_PATTERN.match(
+            self.args.version
+        ):
+            print(
+                f"Error: invalid --version {self.args.version!r}: "
+                f"{_VERSION_FORMAT_HINT}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        model_path = Path(self.args.path).resolve() if self.args.path else Path.cwd()
+
+        reactor_yaml_path = model_path / _REACTOR_YAML
+        if not reactor_yaml_path.exists():
+            print(f"Error: {_REACTOR_YAML} not found in {model_path}", file=sys.stderr)
+            sys.exit(1)
+
+        raw_yaml = OmegaConf.to_container(
+            OmegaConf.load(str(reactor_yaml_path)), resolve=True
+        )
+        if not isinstance(raw_yaml, dict) or "model" not in raw_yaml:
+            print(
+                f"Error: {_REACTOR_YAML} must contain a 'model' field",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        reactor_config = ReactorConfig.from_dict(raw_yaml)
+
+        add_import_paths([str(model_path)])
+
+        try:
+            model_cls = resolve_class(reactor_config.model)
+        except Exception as e:
+            print(f"Error loading model class: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            schema = ModelSchema.from_config(reactor_config, model_cls=model_cls)
+        except Exception as e:
+            print(f"Error extracting schema: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        if self.args.version is not None:
+            # Honour the ModelSchema.version invariant: the internal value
+            # always carries a 'v' prefix, matching the release-tag format
+            # stored in the Coordinator's schema registry. to_openapi()
+            # emits it as-is; to_legacy_tracks_only() is the only place
+            # that strips it for the legacy wire protocol_version field.
+            # See ModelSchema's class docstring.
+            v = self.args.version
+            schema.version = v if v.startswith("v") else f"v{v}"
+
+        openapi_doc = schema.to_openapi()
+        model_name = reactor_config.name or reactor_config.model
+
+        if self.args.out is not None:
+            out_path = Path(self.args.out).expanduser().resolve()
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            out_path.write_text(json.dumps(openapi_doc, indent=4))
+            emitted_version = openapi_doc["info"]["version"]
+            print(
+                f"Model: {model_name} — schema ({emitted_version}) written to "
+                f"{out_path}"
+            )
+        else:
+            print(f"Model: {model_name}")
+            print(json.dumps(openapi_doc, indent=4))

{reactor_runtime-2.2.0 → reactor_runtime-2.3.0}/src/reactor_cli/main.py

@@ -10,12 +10,12 @@ def main():
     from .commands import (
         RunCommand,
         InitCommand,
-        CapabilitiesCommand,
+        SchemaCommand,
     )
 
     RunCommand.register_subcommand(subparsers)
     InitCommand.register_subcommand(subparsers)
-    CapabilitiesCommand.register_subcommand(subparsers)
+    SchemaCommand.register_subcommand(subparsers)
 
     args, remaining = parser.parse_known_args()
     if hasattr(args, "func"):

{reactor_runtime-2.2.0 → reactor_runtime-2.3.0}/src/reactor_runtime/interface/__init__.py

@@ -21,7 +21,11 @@ from reactor_runtime.interface.events.event import EVENT_REGISTRY, Event
 from reactor_runtime.interface.events.connected import Connected, Disconnected
 from reactor_runtime.interface.events.upload import FileUploaded
 from reactor_runtime.interface.upload import UploadedFile
-from reactor_runtime.interface.events.messages import MESSAGE_REGISTRY, ModelMessage
+from reactor_runtime.interface.events.messages import (
+    MESSAGE_REGISTRY,
+    MessageField,
+    ModelMessage,
+)
 
 # Model layer (canonical) — includes decorators and field metadata
 from reactor_runtime.interface.model.reactor_model import ReactorModel
@@ -31,7 +35,7 @@ from reactor_runtime.interface.model.decorators import (
     event,
     file_uploaded,
 )
-from reactor_runtime.interface.model.input_fields import FieldInfo, InputField
+from reactor_runtime.interface.defaults import FieldInfo, InputField
 
 # Pipeline — generator + typed state layer
 from reactor_runtime.interface.pipeline.reactor_pipeline import ReactorPipeline
@@ -67,6 +71,7 @@ __all__ = [
     "FileUploaded",
     "UploadedFile",
     "EVENT_REGISTRY",
+    "MessageField",
     "ModelMessage",
     "MESSAGE_REGISTRY",
     # Model — decorators & fields

reactor_runtime-2.3.0/src/reactor_runtime/interface/defaults.py

@@ -0,0 +1,229 @@
+# Copyright (c) 2026 Reactor Technologies, Inc. All rights reserved.
+"""
+Field metadata and default-value validation primitives.
+
+Single home for the types and helpers that both :class:`Event` /
+:class:`ModelMessage` base classes and their user-facing surfaces
+(:func:`~reactor_runtime.interface.model.decorators.event`,
+:class:`~reactor_runtime.interface.pipeline.input_state.InputState`,
+:class:`~reactor_runtime.interface.events.messages.MessageField`)
+share to validate user-supplied defaults.
+
+Exports :class:`FieldInfo`, :func:`InputField`, :func:`validate_field`,
+:func:`raise_if_default_invalid`, :func:`raise_if_default_not_static`,
+and :func:`field_info_to_json_schema`. Re-exported from
+``reactor_runtime.interface`` and ``reactor_runtime`` as part of the
+public API.
+
+Lives one level above ``interface.model`` so the base classes in
+``interface.events`` can consume it without cycling back through
+``interface.model.__init__``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+_NO_DEFAULT = object()
+
+_MUTABLE_DEFAULT_TYPES = (list, dict, set)
+
+
+# ---------------------------------------------------------------------
+# FieldInfo + InputField — the user-facing declaration of a field's
+# default value and validation constraints.
+# ---------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class FieldInfo:
+    """Validation constraints for a single input field.
+
+    Create instances via :func:`InputField` rather than directly.
+    When no default is provided, ``default`` is :data:`_NO_DEFAULT`.
+    """
+
+    default: Any = _NO_DEFAULT
+    description: Optional[str] = None
+    ge: Optional[Union[int, float]] = None
+    le: Optional[Union[int, float]] = None
+    min_length: Optional[int] = None
+    max_length: Optional[int] = None
+    choices: Optional[List[Any]] = None
+
+
+def InputField(
+    default: Any = _NO_DEFAULT,
+    *,
+    default_factory: Any = None,
+    description: Optional[str] = None,
+    ge: Optional[Union[int, float]] = None,
+    le: Optional[Union[int, float]] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    choices: Optional[List[Any]] = None,
+) -> Any:
+    """Declare a default value and validation constraints for a field.
+
+    Use as the default value for ``@event`` handler parameters or
+    :class:`~reactor_runtime.interface.pipeline.input_state.InputState`
+    fields.  Values that violate constraints are rejected before
+    reaching the handler (logged at debug level, the event is dropped).
+
+    Args:
+        default: Default value for the field.
+        default_factory: Not supported; raises ``TypeError``. Defaults
+            must be statically representable — use a literal ``default=...``.
+        description: Human-readable description (exposed in capabilities).
+        ge: Minimum allowed value (inclusive).
+        le: Maximum allowed value (inclusive).
+        min_length: Minimum length for string/sequence values.
+        max_length: Maximum length for string/sequence values.
+        choices: Exhaustive list of allowed values.
+    """
+    if default_factory is not None:
+        raise TypeError(
+            "InputField(default_factory=...) is not supported. "
+            "Defaults must be statically representable — use a literal `default=...`."
+        )
+    return FieldInfo(
+        default=default,
+        description=description,
+        ge=ge,
+        le=le,
+        min_length=min_length,
+        max_length=max_length,
+        choices=choices,
+    )
+
+
+# ---------------------------------------------------------------------
+# Static-default check — rejects mutable containers, the one guardrail
+# every entry point funnels through.
+# ---------------------------------------------------------------------
+
+
+def raise_if_default_not_static(owner: str, field_name: str, default: Any) -> None:
+    """Raise ``TypeError`` when *default* is a mutable container.
+
+    Defaults must be statically representable. Mutable containers
+    (``list`` / ``dict`` / ``set``) would be shared across every
+    instance and produce surprising cross-session state leaks — the
+    same reason Python's ``dataclasses`` forbids ``field(default=[])``.
+    Users who need a per-instance container should use ``default=None``
+    and initialise inside the handler, or an immutable alternative like
+    ``tuple`` / ``frozenset``.
+
+    ``None`` is the canonical "unset" sentinel for Optional fields and
+    is always allowed.
+    """
+    if default is None:
+        return
+    if isinstance(default, _MUTABLE_DEFAULT_TYPES):
+        raise TypeError(
+            f"{owner}: default for '{field_name}' is a mutable "
+            f"{type(default).__name__} which can't be used as a static default. "
+            "Defaults must be statically representable — use `default=None` and "
+            "initialise inside the handler, or an immutable alternative "
+            "(tuple, frozenset)."
+        )
+
+
+# ---------------------------------------------------------------------
+# FieldInfo-aware validation — constraints + static-default check.
+# ---------------------------------------------------------------------
+
+
+def validate_field(name: str, value: Any, info: FieldInfo) -> Tuple[bool, str]:
+    """Validate *value* against its :class:`FieldInfo` constraints.
+
+    Returns ``(True, "")`` if valid, ``(False, reason)`` if not.
+    """
+    if info.choices is not None and value not in info.choices:
+        return False, f"{name}: {value!r} not in choices {info.choices}"
+
+    if info.ge is not None:
+        try:
+            if value < info.ge:
+                return False, f"{name}: {value} < ge({info.ge})"
+        except TypeError:
+            return False, f"{name}: {value!r} is not comparable to ge({info.ge})"
+
+    if info.le is not None:
+        try:
+            if value > info.le:
+                return False, f"{name}: {value} > le({info.le})"
+        except TypeError:
+            return False, f"{name}: {value!r} is not comparable to le({info.le})"
+
+    if info.min_length is not None:
+        try:
+            if len(value) < info.min_length:
+                return (
+                    False,
+                    f"{name}: length {len(value)} < min_length({info.min_length})",
+                )
+        except TypeError:
+            return (
+                False,
+                f"{name}: {value!r} has no length for min_length({info.min_length})",
+            )
+
+    if info.max_length is not None:
+        try:
+            if len(value) > info.max_length:
+                return (
+                    False,
+                    f"{name}: length {len(value)} > max_length({info.max_length})",
+                )
+        except TypeError:
+            return (
+                False,
+                f"{name}: {value!r} has no length for max_length({info.max_length})",
+            )
+
+    return True, ""
+
+
+def raise_if_default_invalid(
+    owner: str, field_name: str, default: Any, info: FieldInfo
+) -> None:
+    """Raise ``TypeError`` when *default* is unusable for *field_name*.
+
+    Single source of truth for decoration-time / class-creation-time
+    checks on ``InputField`` defaults. Runs two checks in order:
+
+    1. The default must be statically representable (no mutable
+       containers) — delegated to :func:`raise_if_default_not_static`.
+    2. The default must satisfy its own ``info`` constraints
+       (``choices`` / ``ge`` / ``le`` / ``min_length`` / ``max_length``).
+
+    Bypasses both checks for the ``_NO_DEFAULT`` sentinel and for
+    explicit ``None`` (the "unset" value for Optional fields).
+    """
+    if default is _NO_DEFAULT or default is None:
+        return
+    raise_if_default_not_static(owner, field_name, default)
+    ok, reason = validate_field(field_name, default, info)
+    if not ok:
+        raise TypeError(
+            f"{owner}: default value for '{field_name}' violates "
+            f"its own InputField constraints ({reason})."
+        )
+
+
+def field_info_to_json_schema(schema: Dict[str, Any], info: FieldInfo) -> None:
+    """Merge :class:`FieldInfo` constraints into a JSON Schema dict."""
+    if info.description:
+        schema["description"] = info.description
+    if info.ge is not None:
+        schema["minimum"] = info.ge
+    if info.le is not None:
+        schema["maximum"] = info.le
+    if info.min_length is not None:
+        schema["minLength"] = info.min_length
+    if info.max_length is not None:
+        schema["maxLength"] = info.max_length
+    if info.choices is not None:
+        schema["enum"] = info.choices

{reactor_runtime-2.2.0 → reactor_runtime-2.3.0}/src/reactor_runtime/interface/driver/pipeline_executor.py

@@ -10,7 +10,7 @@ from typing import Any, Dict, Iterator, List, Optional, Type
 from reactor_runtime.interface.driver.step_result import StepResult
 from reactor_runtime.interface.events.messages import ModelMessage
 from reactor_runtime.interface.model.handlers import Handlers, build_dispatch_table
-from reactor_runtime.interface.model.input_fields import validate_field
+from reactor_runtime.interface.defaults import validate_field
 from reactor_runtime.interface.pipeline.idle import Idle
 from reactor_runtime.interface.pipeline.reactor_pipeline import (
     GeneratorEnded,