jayrun 0.1.0__py3-none-any.whl

jayrun/__init__.py

@@ -0,0 +1,32 @@
+"""Public graph construction, execution, and data-context API."""
+
+from .core.artifact.base import Artifact
+from .core.artifact.context import ArtifactContext
+from .core.artifact.field import ArtifactField
+from .core.config.context import ConfigContext
+from .core.config.field import ConfigField
+from .core.context.runtime_data import Data
+from .core.graph.artifact_flow import ArtifactFlow
+from .core.graph.graph_definition import GraphDefinition
+from .core.operator.base import BaseOperator
+from .core.resource.base import BaseResource
+from .core.resource.field import ResourceField
+from .engine.api import Engine
+
+__version__ = "0.1.0"
+
+__all__ = (
+    "__version__",
+    "Artifact",
+    "ArtifactContext",
+    "ArtifactField",
+    "ArtifactFlow",
+    "BaseOperator",
+    "BaseResource",
+    "ConfigContext",
+    "ConfigField",
+    "Data",
+    "Engine",
+    "GraphDefinition",
+    "ResourceField",
+)

jayrun/context.py

@@ -0,0 +1,11 @@
+"""Public execution-context states, snapshots, and retained artifact results."""
+
+from .engine.artifact.result import ArtifactResult
+from .engine.registry.context_snapshot import ContextSnapshot
+from .engine.registry.context_state import ContextState
+
+__all__ = (
+    "ArtifactResult",
+    "ContextSnapshot",
+    "ContextState",
+)

jayrun/core/artifact/base.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, eq=False)
+class Artifact:
+    """Declare a named value that moves through a graph.
+
+    An artifact describes identity and intent; its runtime value is supplied through
+    an :class:`~jayrun.ArtifactContext` or produced by an operator. Declarations use
+    identity semantics, so two artifacts with the same name remain distinct.
+
+    Args:
+        name: Optional human-readable name used in reports and graph plots.
+        description: Optional explanation of the value represented by the artifact.
+    """
+
+    name: str | None = None
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.name is not None and not isinstance(self.name, str):
+            raise TypeError(
+                f"{type(self).__name__} 'name' must be str or None, got {type(self.name).__name__!r}"
+            )
+
+        if self.description is not None and not isinstance(self.description, str):
+            raise TypeError(
+                f"{type(self).__name__} 'description' must be str or None, got {type(self.description).__name__!r}"
+            )
+
+    def __repr__(self) -> str:
+        name = self.name if self.name is not None else "<unnamed>"
+        return f"{type(self).__name__}(name={name!r})"

jayrun/core/artifact/context.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ..context.base import DataContext
+from ..context.runtime_data import Data
+from ..graph.definition.artifact import ArtifactDefinition, ArtifactRole
+from ..graph.graph_definition import GraphDefinition
+from .base import Artifact
+
+
+class ArtifactContext(DataContext[Artifact, Data]):
+    """Hold the entry-artifact values for one graph submission.
+
+    The graph must be confirmed before the context is created. Values are wrapped in
+    :class:`~jayrun.Data`; callers may address artifacts by object, inspected
+    definition, or graph-local integer ID.
+
+    Args:
+        graph: Confirmed graph whose artifacts the context accepts.
+        name: Optional name for diagnostics.
+        description: Optional description for diagnostics.
+
+    Raises:
+        TypeError: If ``graph`` is not a :class:`~jayrun.GraphDefinition`.
+        RuntimeError: If the graph has not been confirmed.
+    """
+
+    def __init__(
+        self,
+        *,
+        graph: GraphDefinition,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        super().__init__(name=name, description=description)
+
+        if not isinstance(graph, GraphDefinition):
+            raise TypeError("graph must be a GraphDefinition instance")
+        if not graph.confirmed:
+            raise RuntimeError("The graph must be confirmed.")
+
+        self._graph = graph
+        self._registry = graph._specification.artifacts
+        self._definitions_by_id = {
+            definition.artifact_id: definition
+            for definition in self._registry.definitions
+        }
+        self._release_target: ArtifactContext | None = None
+
+    def set(
+        self,
+        artifacts: Mapping[int | Artifact | ArtifactDefinition, object],
+    ) -> None:
+        """Set or replace artifact values.
+
+        Args:
+            artifacts: Mapping from artifact IDs, artifacts, or inspected artifact
+                definitions to raw values.
+
+        Raises:
+            KeyError: If a key does not belong to this graph.
+            TypeError: If ``artifacts`` is not a mapping or a key is unsupported.
+            ValueError: If multiple keys resolve to the same artifact.
+        """
+        if not isinstance(artifacts, Mapping):
+            raise TypeError(
+                "Expected a mapping of artifact IDs, Artifact, or "
+                "ArtifactDefinition to values."
+            )
+
+        instances: dict[Artifact, Data] = {}
+
+        for key, value in artifacts.items():
+            artifact = self._resolve_artifact(key)
+
+            if artifact in instances:
+                raise ValueError("Multiple artifact keys resolve to the same Artifact.")
+
+            instances[artifact] = Data(value=value)
+
+        self._update_instances(instances)
+
+    def get(
+        self,
+        artifact: int | Artifact | ArtifactDefinition,
+    ) -> Data | None:
+        """Return an artifact's wrapped value, or ``None`` if it is unset."""
+        return self._instances.get(self._resolve_artifact(artifact))
+
+    def clear(self) -> None:
+        """Remove every value from this context."""
+        self._instances.clear()
+
+    def clear_entries(self) -> None:
+        """Remove graph-entry values from this context and its release target."""
+        self._clear_entries()
+        if self._release_target is not None:
+            self._release_target._clear_entries()
+
+    def _clear_entries(self) -> None:
+        for definition in self._registry.definitions:
+            if definition.role is ArtifactRole.ENTRY:
+                self._instances.pop(
+                    self._registry.source_for(definition),
+                    None,
+                )
+
+    def _fork(self) -> ArtifactContext:
+        context = ArtifactContext(
+            graph=self.graph,
+            name=self.name,
+            description=self.description,
+        )
+        context._instances = dict(self._instances)
+        context._release_target = self
+        return context
+
+    def validate(self) -> bool:
+        """Return whether every graph entry artifact has a value."""
+        return all(
+            self._registry.source_for(definition) in self._instances
+            for definition in self._registry.definitions
+            if definition.role is ArtifactRole.ENTRY
+        )
+
+    def _resolve_artifact(
+        self,
+        artifact: int | Artifact | ArtifactDefinition,
+    ) -> Artifact:
+        if type(artifact) is int:
+            try:
+                definition = self._definitions_by_id[artifact]
+            except KeyError:
+                raise KeyError(f"Unknown artifact ID: {artifact!r}.") from None
+
+            return self._registry.source_for(definition)
+
+        if isinstance(artifact, ArtifactDefinition):
+            if artifact not in self._registry.definitions:
+                raise KeyError("The ArtifactDefinition does not belong to this graph.")
+
+            return self._registry.source_for(artifact)
+
+        if isinstance(artifact, Artifact):
+            if artifact not in self._registry.sources:
+                raise KeyError("The Artifact does not belong to this graph.")
+
+            return artifact
+
+        raise TypeError(
+            "Expected int, Artifact, or ArtifactDefinition, "
+            f"got {type(artifact).__name__!r}."
+        )
+
+    @property
+    def graph(self) -> GraphDefinition:
+        """The confirmed graph associated with this context."""
+        return self._graph

jayrun/core/artifact/field.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..declaration.field import DeclarativeField
+from .base import Artifact
+from .properties import ArtifactProperty
+
+
+@dataclass(slots=True, frozen=True, kw_only=True, eq=False)
+class ArtifactField(DeclarativeField):
+    """Declare an operator input or output artifact contract.
+
+    Args:
+        name: Optional display name.
+        description: Optional explanation of the artifact contract.
+        required: Whether the field must be connected. Input fields enforce this
+            during operator construction; output fields may still be bound to
+            ``None`` to disable a route.
+        properties: Optional tuple of artifact properties used by graph validation.
+    """
+
+    properties: tuple[ArtifactProperty, ...] | None = None
+    artifact: Artifact | None = field(init=False, default=None, repr=False)
+    is_bound: bool = field(init=False, default=False, repr=False)
+
+    def __post_init__(self) -> None:
+        DeclarativeField.__post_init__(self)
+
+        if self.properties is None:
+            object.__setattr__(self, "properties", ())
+            return
+
+        if not isinstance(self.properties, tuple):
+            raise TypeError(
+                f"'properties' must be a tuple of ArtifactProperty instances or None, "
+                f"got {type(self.properties).__name__!r}"
+            )
+
+        properties_by_type = list()
+
+        for artifact_property in self.properties:
+            if not isinstance(artifact_property, ArtifactProperty):
+                raise TypeError(
+                    f"'properties' must contain only ArtifactProperty instances, "
+                    f"got {type(artifact_property).__name__!r}"
+                )
+            property_type = type(artifact_property)
+
+            if property_type in properties_by_type:
+                raise ValueError(
+                    f"Duplicate artifact property: {property_type.__name__}."
+                )
+            properties_by_type.append(property_type)
+
+    def bind(self, artifact: Artifact | None) -> None:
+        """Bind this input field to an artifact exactly once.
+
+        Args:
+            artifact: Artifact to consume, or ``None`` for an optional field.
+
+        Raises:
+            RuntimeError: If the field is already bound.
+            TypeError: If ``artifact`` has an unsupported type.
+            ValueError: If a required field is bound to ``None``.
+        """
+        self._bind(artifact, enforce_required=True)
+
+    def _bind(
+        self,
+        artifact: Artifact | None,
+        *,
+        enforce_required: bool,
+    ) -> None:
+        if self.is_bound:
+            raise RuntimeError(f"{type(self).__name__} is already bound")
+
+        if artifact is not None and not isinstance(artifact, Artifact):
+            raise TypeError(
+                f"'artifact' must be an Artifact or None, "
+                f"got {type(artifact).__name__!r}"
+            )
+
+        if enforce_required and artifact is None and self.required:
+            raise ValueError(
+                f"Required artifact field {self.display_name!r} cannot be bound to None"
+            )
+
+        object.__setattr__(self, "artifact", artifact)
+        object.__setattr__(self, "is_bound", True)

jayrun/core/artifact/properties.py

@@ -0,0 +1,111 @@
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from typing import Generic, Self, TypeVar
+
+T = TypeVar("T")
+
+
+class ArtifactProperty(ABC, Generic[T]):
+    """Base class for one statically validated artifact characteristic.
+
+    Args:
+        value: Declared property value.
+    """
+
+    def __init__(self, value: T) -> None:
+        self._validate_value(value)
+        self._value = value
+
+    @property
+    def value(self) -> T:
+        """Normalized declared value."""
+        return self._value
+
+    def _validate_value(self, value: T) -> None:
+        pass
+
+    @abstractmethod
+    def accepts(self, output: Self) -> bool:
+        """Return whether a producer property satisfies this consumer property.
+
+        Args:
+            output: Property declared by the producing output field.
+        """
+        pass
+
+
+class TypeProperty(ArtifactProperty[type]):
+    """Require an exact Python value type."""
+
+    def _validate_value(self, value: type) -> None:
+        if not isinstance(value, type):
+            raise TypeError("Expected a Python type.")
+
+    def accepts(self, output: Self) -> bool:
+        return self.value is output.value
+
+
+class DTypeProperty(ArtifactProperty[tuple[object, ...]]):
+    """Require at least one shared dtype from a set of accepted values.
+
+    Args:
+        value: One dtype or an iterable of acceptable dtypes.
+    """
+
+    def __init__(self, value: object | Iterable[object]) -> None:
+        if isinstance(value, Iterable) and not isinstance(value, (str, bytes)):
+            values = tuple(value)
+        else:
+            values = (value,)
+
+        super().__init__(values)
+
+    def _validate_value(self, value: tuple[object, ...]) -> None:
+        if len(value) == 0:
+            raise ValueError("Expected at least one dtype.")
+
+    def accepts(self, output: Self) -> bool:
+        return not set(self.value).isdisjoint(output.value)
+
+
+class ShapeProperty(ArtifactProperty[tuple[int | None, ...]]):
+    """Require a tensor-like shape, using ``None`` as a consumer wildcard."""
+
+    def _validate_value(self, value: tuple[int | None, ...]) -> None:
+        for dimension in value:
+            if dimension is not None and not isinstance(dimension, int):
+                raise TypeError("Shape dimensions must be integers or None.")
+
+    def accepts(self, output: Self) -> bool:
+        if len(self.value) != len(output.value):
+            return False
+
+        for input_artifact, output_artifact in zip(self.value, output.value):
+            if input_artifact is None and output_artifact is not None:
+                continue
+            if input_artifact != output_artifact:
+                return False
+
+        return True
+
+
+class DeviceProperty(ArtifactProperty[str]):
+    """Require an exact device name such as ``\"cpu\"`` or ``\"cuda\"``."""
+
+    def _validate_value(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("Expected a device name.")
+
+    def accepts(self, output: Self) -> bool:
+        return self.value == output.value
+
+
+class BackendProperty(ArtifactProperty[str]):
+    """Require an exact data backend name such as ``\"torch\"``."""
+
+    def _validate_value(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("Expected a backend name.")
+
+    def accepts(self, output: Self) -> bool:
+        return self.value == output.value

jayrun/core/base/error.py

@@ -0,0 +1,2 @@
+class ConfigError(Exception):
+    pass

jayrun/core/config/context.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ..context.base import DataContext
+from ..context.runtime_data import Data
+from ..graph.definition.field import ConfigDefinition
+from ..graph.graph_definition import GraphDefinition
+from .field import ConfigField
+
+
+class ConfigContext(DataContext[ConfigField, Data]):
+    """Hold configuration values for one graph submission.
+
+    Args:
+        graph: Confirmed graph whose configuration fields the context accepts.
+        name: Optional name for diagnostics.
+        description: Optional description for diagnostics.
+
+    Raises:
+        TypeError: If ``graph`` is not a :class:`~jayrun.GraphDefinition`.
+        RuntimeError: If the graph has not been confirmed.
+    """
+
+    def __init__(
+        self,
+        *,
+        graph: GraphDefinition,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        super().__init__(name=name, description=description)
+
+        if not isinstance(graph, GraphDefinition):
+            raise TypeError("graph must be a GraphDefinition instance")
+        if not graph.confirmed:
+            raise RuntimeError("The graph must be confirmed.")
+        self._graph = graph
+        self._registry = graph._specification.configs
+        self._definitions_by_id = {
+            definition.config_id: definition
+            for definition in self._registry.definitions
+        }
+
+    def set(
+        self,
+        configs: Mapping[int | ConfigField | ConfigDefinition, object],
+    ) -> None:
+        """Set or replace configuration values.
+
+        Args:
+            configs: Mapping from config IDs, fields, or inspected definitions to
+                values.
+
+        Raises:
+            KeyError: If a key does not belong to this graph.
+            TypeError: If a value does not match its field type.
+            ValueError: If a required value is ``None`` or keys are ambiguous.
+        """
+        if not isinstance(configs, Mapping):
+            raise TypeError(
+                "Expected a mapping of config IDs, ConfigField, or "
+                "ConfigDefinition to values."
+            )
+
+        instances: dict[ConfigField, Data] = {}
+
+        for key, value in configs.items():
+            field = self._resolve_field(key)
+
+            if field in instances:
+                raise ValueError(
+                    "Multiple config keys resolve to the same ConfigField."
+                )
+
+            self._validate_value(field, value)
+            instances[field] = Data(value=value)
+
+        self._update_instances(instances)
+
+    def get(
+        self,
+        config: int | ConfigField | ConfigDefinition,
+    ) -> Data | None:
+        """Return a configured or default value wrapped in :class:`~jayrun.Data`."""
+        field = self._resolve_field(config)
+
+        if field in self._instances:
+            return self._instances[field]
+
+        if field.default is None:
+            return None
+
+        return Data(value=field.default)
+
+    def validate(self) -> bool:
+        """Return whether every required configuration field has a value."""
+        return all(
+            self.get(definition) is not None
+            for definition in self._registry.definitions
+            if definition.required
+        )
+
+    def _fork(self) -> ConfigContext:
+        context = ConfigContext(
+            graph=self.graph,
+            name=self.name,
+            description=self.description,
+        )
+        context._instances = dict(self._instances)
+        return context
+
+    def to_yaml(self) -> str:
+        """Serialize graph configuration metadata and current values as YAML."""
+        import yaml
+
+        configs = {
+            definition.config_id: self._yaml_entry(definition)
+            for definition in sorted(
+                self._registry.definitions,
+                key=lambda definition: definition.config_id,
+            )
+        }
+
+        return yaml.safe_dump(
+            {"configs": configs},
+            sort_keys=False,
+            allow_unicode=True,
+        )
+
+    def load_yaml(self, content: str) -> None:
+        """Load values from YAML produced by :meth:`to_yaml`.
+
+        Existing values not present in ``content`` are preserved.
+
+        Args:
+            content: YAML document containing a top-level ``configs`` mapping.
+        """
+        import yaml
+
+        if not isinstance(content, str):
+            raise TypeError("content must be str")
+
+        document = yaml.safe_load(content)
+
+        if document is None:
+            return
+
+        if not isinstance(document, Mapping):
+            raise TypeError("YAML root must be a mapping")
+
+        configs = document.get("configs")
+
+        if not isinstance(configs, Mapping):
+            raise TypeError("'configs' must be a mapping")
+
+        values: dict[int, object] = {}
+
+        for config_id, config in configs.items():
+            if type(config_id) is not int:
+                raise TypeError("Config IDs in YAML must be integers")
+
+            if not isinstance(config, Mapping):
+                raise TypeError(f"Config {config_id!r} must be a mapping")
+
+            if "value" not in config:
+                raise ValueError(f"Config {config_id!r} is missing 'value'")
+
+            values[config_id] = config["value"]
+
+        self.set(values)
+
+    def _yaml_entry(
+        self,
+        definition: ConfigDefinition,
+    ) -> dict[str, object]:
+        field = self._registry.source_for(definition)
+        instance = self._instances.get(field)
+
+        return {
+            "name": definition.name,
+            "description": definition.description,
+            "owner": definition.owner,
+            "required": definition.required,
+            "layout_position": list(definition.layout_position),
+            "attribute_name": definition.attribute_name,
+            "value_type": self._type_name(definition.value_type),
+            "default": definition.default,
+            "value": instance.value if instance is not None else definition.default,
+        }
+
+    def _resolve_field(
+        self,
+        config: int | ConfigField | ConfigDefinition,
+    ) -> ConfigField:
+        if type(config) is int:
+            try:
+                definition = self._definitions_by_id[config]
+            except KeyError:
+                raise KeyError(f"Unknown config ID: {config!r}.") from None
+
+            return self._registry.source_for(definition)
+
+        if isinstance(config, ConfigDefinition):
+            if config not in self._registry.definitions:
+                raise KeyError("The ConfigDefinition does not belong to this graph.")
+
+            return self._registry.source_for(config)
+
+        if isinstance(config, ConfigField):
+            if config not in self._registry.sources:
+                raise KeyError("The ConfigField does not belong to this graph.")
+
+            return config
+
+        raise TypeError(
+            "Expected int, ConfigField, or ConfigDefinition, "
+            f"got {type(config).__name__!r}."
+        )
+
+    @staticmethod
+    def _validate_value(
+        field: ConfigField,
+        value: object,
+    ) -> None:
+        if value is None:
+            if field.required:
+                raise ValueError("A required config cannot be None.")
+            return
+
+        if not isinstance(value, field.value_type):
+            raise TypeError(
+                f"Expected {field.value_type.__name__!r}, got {type(value).__name__!r}."
+            )
+
+        hash(value)
+
+    @staticmethod
+    def _type_name(value_type: type) -> str:
+        if value_type.__module__ == "builtins":
+            return value_type.__qualname__
+
+        return f"{value_type.__module__}.{value_type.__qualname__}"
+
+    @property
+    def graph(self) -> GraphDefinition:
+        """The confirmed graph associated with this context."""
+        return self._graph