jayrun 0.2.0__tar.gz → 0.3.0__tar.gz

jayrun-0.3.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to Jayrun are documented in this file.
+
+Release notes describe new capabilities, compatibility changes and fixes.
+
+## [0.3.0] - 2026-09-28
+
+### Added
+
+- SQLite-backed execution/session history, bounded retention, explicit flush and
+  scoped historical readers through `jayrun.persistence`.
+- Portable configuration and ContextRecord codecs through `jayrun.serialization`.
+- Public inspection, report and lifecycle types organized into documented facades.
+- Interactive definition, registry and completed-run viewers, plus a dashboard
+  with consistent themes and an offline documentation preview.
+- A rebuilt manual, runnable examples and seven application tutorials with
+  matching Python sources and notebooks.
+
+### Changed
+
+- Graphs require explicit `graph.confirm()` after binding resources and serializers.
+  Confirmation validates and freezes preparation; invalid graphs remain inspectable.
+- Submit with `engine.submit(graph, artifacts, configs, settings=...)`. ArtifactContext
+  and ConfigContext are value builders rather than graph-bound submission wrappers.
+- One `EngineSettings.failure_mode` governs execution and owned persistence.
+  Standalone Database operations remain strict; use explicit flush to check settlement.
+- Configuration accepts bounded immutable built-in values; use a string such as
+  `"float32"` instead of a Python/library object such as `torch.float32`.
+- Settings are keyword-only. RecordingMode, engine_id, unfinished_contexts and
+  database methods with an `_async` suffix use consistent terminology.
+- `ArtifactPolicy(retained_artifacts=None)` retains eligible exits, `()` retains
+  none, and a tuple selects declared exits. Retention does not cap total process RSS.
+- Strengthened operator-output handling, failure-reference cleanup and lifecycle
+  qualification. Simplified public imports and updated all published examples.
+
+### Compatibility
+
+0.3.0 includes breaking changes from 0.2.0. For example:
+
+```python
+# 0.2: graph-bound builders, inferred graph at submission
+artifacts = ArtifactContext(graph=graph)
+configs = ConfigContext(graph=graph)
+run = engine.submit(artifacts, configs)
+
+# 0.3: prepare explicitly, then submit the graph and value builders
+# Bind required resources/serializers before confirming.
+graph.confirm()
+artifacts = ArtifactContext({source: value})
+configs = ConfigContext({operator.factor: 3})
+run = engine.submit(graph, artifacts, configs)
+```
+
+Replace `ArtifactContext.clear_entries()` with `clear()`. Builder validation occurs
+at submission; retired no-argument builder `validate()` methods and public compiled
+plan/layout access are removed. BaseOperator construction is unchanged. Component
+identity versions remain independent of the package version.
+
+History is bounded diagnostic evidence, not automatic application checkpointing or
+an exactly-once event archive. Concurrency, placement and cooperative shutdown retain
+their documented limits. See the [current manual](https://jayrun.readthedocs.io/en/latest/)
+for supported imports, complete examples and operational limits.
+
+## [0.2.0] - 2026-09-01
+
+### Added
+
+- Added `ContextRun`, a stable object for observing and controlling one submitted context throughout its lifecycle.
+- Added synchronous and asynchronous waiting through `ContextRun.wait()`, `ContextRun.wait_async()`, `Engine.wait()`, and `Engine.wait_async()`; a run can also be awaited directly.
+- Added terminal artifact access through `ContextRun.artifact()` and terminal reporting through `ContextRun.report`.
+- Added context-scoped stored-value access through `ContextRun.get_value()`, `get_values()`, `get_value_record()`, and `get_value_records()`.
+- Added graph-scoped supervision with `Engine.submit(..., supervises=...)`. Supervisors see only runs belonging to the exact graph objects they are authorized to supervise.
+- Added authorized runtime identities and a serialized messaging path for lifecycle control and context storage across thread boundaries.
+- Added continuous-integration checks and stricter automated documentation builds.
+
+### Changed
+
+- `Engine.submit()` now returns a `ContextRun` and accepts graph-bound `ArtifactContext` and `ConfigContext` objects as the submission boundary.
+- Unified external and in-graph supervision around the same `ContextRun` observation, waiting, and control API.
+- Unified pause, resume, stop-iteration, abort, and store requests through the runtime messaging system.
+- Completed runs are released from the engine registry while existing `ContextRun` objects remain usable for reports, retained artifacts, and stored values.
+- Clarified lifecycle terminology: `stop()` prevents another graph iteration, while `abort()` prevents further dispatch and drains accepted work.
+- Strengthened context finalization, executor cleanup, placement reconciliation, and graceful and forced shutdown behavior.
+- Expanded public docstrings and generated the API Reference from the documented public API.
+- Revised the explanatory documentation and tutorials to use the stabilized context lifecycle and supervision APIs.
+
+### Removed
+
+- Removed the public `ContextSnapshot` workflow in favor of the single live-to-terminal `ContextRun` abstraction.
+- Removed legacy split context result and status pathways superseded by `ContextRun`.
+
+## [0.1.0] - 2026-08-28
+
+### Added
+
+- Initial public release.
+- Artifact-centric computational graphs with explicit configuration and artifact contexts.
+- Iterative graph execution and repeated operator execution.
+- Synchronous and asynchronous operators.
+- Shared resource lifecycle management.
+- CPU, GPU, and multi-device placement reservations.
+- Graph validation, inspection, and interactive plotting.
+- Context supervision, failure handling, and coordinated shutdown.
+
+[0.2.0]: https://github.com/jayrun-project/jayrun/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/jayrun-project/jayrun/releases/tag/v0.1.0
+
+[0.3.0]: https://github.com/jayrun-project/jayrun/compare/v0.2.0...v0.3.0

jayrun-0.3.0/MANIFEST.in

@@ -0,0 +1,24 @@
+include LICENSE
+include NOTICE
+include CHANGELOG.md
+include README.md
+prune docs
+prune examples
+prune tests
+global-exclude __pycache__ *.py[cod] .DS_Store
+
+prune _tests
+prune _examples
+prune _previews
+prune _audits
+prune _evidence
+prune _benchmarks
+prune _project_history
+prune legacy_remote_automation
+
+prune tutorials
+prune _legacy_remote_automation
+prune _screenshot
+prune graphify-out
+prune .github
+exclude AGENTS.md reply.txt

jayrun-0.3.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: jayrun
+Version: 0.3.0
+Summary: Artifact-centric execution for iterative graphs, shared resources, and placement-aware workloads
+Author: Masoud Yavari
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/jayrun-project/jayrun
+Project-URL: Documentation, https://jayrun.readthedocs.io/
+Project-URL: Repository, https://github.com/jayrun-project/jayrun
+Project-URL: Issues, https://github.com/jayrun-project/jayrun/issues
+Keywords: artifacts,dag,execution,orchestration,resources,scheduling,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: packaging>=25
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0; extra == "yaml"
+Provides-Extra: plotting
+Dynamic: license-file
+
+# Jayrun
+
+[![PyPI version](https://img.shields.io/pypi/v/jayrun.svg)](https://pypi.org/project/jayrun/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Documentation](https://github.com/jayrun-project/jayrun/actions/workflows/docs.yml/badge.svg)](https://github.com/jayrun-project/jayrun/actions/workflows/docs.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/jayrun-project/jayrun/blob/main/LICENSE)
+
+Jayrun is an artifact-centric Python execution framework for pipelines, iterative computation and application services. Operators consume and produce artifact values; an Engine manages execution, resource lifetimes and control of running work. Components use ordinary synchronous or asynchronous Python methods.
+
+[Documentation](https://jayrun.readthedocs.io/en/latest/) · [First program](https://jayrun.readthedocs.io/en/latest/start/first-graph.html) · [Tutorials](https://jayrun.readthedocs.io/en/latest/tutorials/index.html) · [API reference](https://jayrun.readthedocs.io/en/latest/reference/imports.html)
+
+[![Jayrun dashboard listing running and paused contexts with graph versions, progress and iteration counts](https://raw.githubusercontent.com/jayrun-project/jayrun/main/docs/_static/screenshots/dashboard.png)](https://jayrun.readthedocs.io/en/latest/guides/visualization/dashboard.html)
+
+*Running and paused work in the dashboard. The dashboard is itself a graph, built from an observing operator and a managed service resource. Click the screenshot for an interactive offline preview and setup guide.*
+
+## What Jayrun does
+
+- **Release intermediate data automatically.** Artifact flow lets Jayrun release consumed values when execution no longer needs them. Entry/exit retention policies and application references still determine what stays alive.
+- **Reuse expensive resources.** Models, calibration data and clients can remain available across compatible runs. The Engine manages acquisition, reuse and eventual teardown.
+- **Build your own observers and controllers.** Use graphs for monitoring, experiment scheduling or distributed-work coordination. They use the existing execution and lifecycle machinery, with separate supervision capacity. Your application supplies transport and authentication.
+- **Separate declaration from execution.** Validate and visualize a graph before running it, then submit it repeatedly with different inputs and configuration. Each submission returns its own `ContextRun`.
+- **Manage iteration and capacity explicitly.** Combine graph iteration, operator repetition, conditional routes, sync/async execution and placement requests with lifecycle controls and scoped authority.
+- **Keep dependencies small.** The required third-party runtime dependency is `packaging`; PyYAML is optional. HTML visualization needs no additional plotting package.
+
+See [what Jayrun does](https://jayrun.readthedocs.io/en/latest/start/overview.html) for practical benefits and boundaries, and [data and lifetimes](https://jayrun.readthedocs.io/en/latest/start/data-and-lifetimes.html) for how artifacts, configuration and resources work together.
+
+## Install
+
+Requires Python 3.11 or later:
+
+```bash
+python -m pip install jayrun
+```
+
+For YAML configuration support, install `jayrun[yaml]`. Workload libraries such as PyTorch are application dependencies, not core requirements.
+
+## A complete first graph
+
+This program declares a multiplication, confirms the graph, supplies input and configuration, and prints `21`:
+
+```python
+from jayrun import (
+    Artifact, ArtifactContext, ArtifactField, ArtifactFlow, BaseOperator,
+    ConfigContext, ConfigField, Engine, GraphDefinition,
+)
+from jayrun.context import ContextState
+
+
+class Scale(BaseOperator):
+    def __init__(self, *, source, outputs):
+        super().__init__()
+        self.source = ArtifactField()
+        self.factor = ConfigField(value_type=int)
+        self.outputs = (ArtifactField(),)
+
+    def execute(self):
+        result = self.source.value * self.factor.value
+        self.context.record("scaled", result)
+        return result
+
+
+source = Artifact(name="source")
+result = Artifact(name="result")
+scale = Scale(source=source, outputs=(result,))
+flow = ArtifactFlow(scale, artifact=source)
+graph = GraphDefinition(flow, entry_flows=flow)
+graph.confirm()
+
+with Engine() as engine:
+    run = engine.submit(
+        graph,
+        ArtifactContext({source: 7}),
+        ConfigContext({scale.factor: 3}),
+    )
+    run.wait(timeout=10)
+    if run.state is not ContextState.FINISHED:
+        raise RuntimeError(str(run.report.data.failure))
+    print(run.artifact(result).value)  # 21
+```
+
+`ArtifactContext` supplies data; `ConfigContext` supplies the operator's parameters. Execution settings separately control policies such as retries and iteration limits. `run.wait()` waits for finalization, which can include failure; the example checks the outcome before reading the result.
+
+The same confirmed graph can serve another submission. The [complete walkthrough](https://jayrun.readthedocs.io/en/latest/start/first-graph.html) explains each declaration, inspects recorded values and visualizes the finished run.
+
+## Inspect declarations and execution
+
+Save a declaration with `graph.plot.save("graph.html")`, a registry with `registry.plot.save("registry.html")`, or a completed run with `run.plot.save("run.html")`. These HTML viewers are interactive and open in a browser. Declaration views show structure; run views add captured outcomes, timings, records and reports.
+
+[![Split-and-join graph with an explicit Splitter, two processing branches and a Join operator](https://raw.githubusercontent.com/jayrun-project/jayrun/main/docs/_static/screenshots/split-and-join.png)](https://jayrun.readthedocs.io/en/latest/guides/visualization/graphs.html)
+
+*An explicit split-and-join declaration. Click to explore the interactive graph and its explanation.*
+
+The [visualization and reporting chapter](https://jayrun.readthedocs.io/en/latest/guides/evidence/plots.html) covers graph definitions, registries, completed runs and the dashboard. A controller graph can use `self.runtime` to observe or coordinate work; see [the Controller example](https://jayrun.readthedocs.io/en/latest/guides/runtime/controller.html) and [Engine/runtime correspondence](https://jayrun.readthedocs.io/en/latest/guides/runtime/correspondence.html).
+
+## Persist execution history
+
+Pass `Database("execution.sqlite")` from `jayrun.persistence` to `Engine(database=...)` to retain bounded execution/session history and timing profiles. The Engine owns the database lifecycle. After a run finishes, explicit `engine.database.flush()` checks storage settlement; computation completion alone does not establish successful persistence.
+
+The [Persistence and Database guide](https://jayrun.readthedocs.io/en/latest/guides/evidence/persistence.html) includes a complete write–close–read example. Stored diagnostic history is separate from application checkpoints and arbitrary artifact storage.
+
+## Tutorials
+
+Explore complete applications with a walkthrough, runnable Python source and notebook:
+
+| Tutorial | Python source | Notebook | What it demonstrates |
+| --- | --- | --- | --- |
+| [Build and validate](https://jayrun.readthedocs.io/en/latest/tutorials/build-and-validate-graph.html) | [build_graph.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/build_graph.py) | [01_build_graph](https://github.com/jayrun-project/jayrun/blob/main/tutorials/01_build_graph.ipynb) | Properties, diagnostics and corrected execution |
+| [Image service](https://jayrun.readthedocs.io/en/latest/tutorials/denoise-images-with-fastapi.html) | [denoise_images.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/denoise_images.py) | [02_denoise_images](https://github.com/jayrun-project/jayrun/blob/main/tutorials/02_denoise_images.ipynb) | Async service, shared client and routing |
+| [Shared model inference](https://jayrun.readthedocs.io/en/latest/tutorials/mnist-inference-and-training.html#share-a-read-only-model-for-inference) | [mnist_inference.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/mnist_inference.py) | [03_mnist_inference](https://github.com/jayrun-project/jayrun/blob/main/tutorials/03_mnist_inference.ipynb) | Read-only model reuse and placement |
+| [Supervised training](https://jayrun.readthedocs.io/en/latest/tutorials/mnist-inference-and-training.html#supervise-replace-and-promote) | [mnist_training.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/mnist_training.py) | [04_mnist_training](https://github.com/jayrun-project/jayrun/blob/main/tutorials/04_mnist_training.ipynb) | Iteration, mutable state and scoped supervision |
+| [Document service](https://jayrun.readthedocs.io/en/latest/tutorials/document-ingestion.html) | [document_ingestion.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/document_ingestion.py) | [05_document_ingestion](https://github.com/jayrun-project/jayrun/blob/main/tutorials/05_document_ingestion.ipynb) | Long-running jobs and transactional publication |
+| [Adapter checkpointing](https://jayrun.readthedocs.io/en/latest/tutorials/checkpointed-adapter-finetuning.html) | [adapter_finetuning.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/adapter_finetuning.py) | [06_adapter_finetuning](https://github.com/jayrun-project/jayrun/blob/main/tutorials/06_adapter_finetuning.ipynb) | Model/optimizer/RNG checkpoints |
+| [Scientific campaign](https://jayrun.readthedocs.io/en/latest/tutorials/adaptive-scientific-calibration.html) | [heat_calibration.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/heat_calibration.py) | [07_heat_calibration](https://github.com/jayrun-project/jayrun/blob/main/tutorials/07_heat_calibration.ipynb) | Adaptive control and reproducibility |
+
+Each tutorial includes a small offline CPU path. See the [tutorial setup guide](https://jayrun.readthedocs.io/en/latest/tutorials/index.html) for dependencies and optional GPU/model workloads.
+
+## Find your next step
+
+| Task | Guide |
+| --- | --- |
+| Build, validate, submit and inspect a graph | [From declaration to execution](https://jayrun.readthedocs.io/en/latest/guides/workflow/index.html) |
+| Resolve fan-out, fan-in and conditional routes | [Graph-definition resolutions](https://jayrun.readthedocs.io/en/latest/guides/graphs/resolutions.html) |
+| Use context, execution, placement and runtime handles | [Component interfaces](https://jayrun.readthedocs.io/en/latest/guides/components/index.html) |
+| Add reusable models or clients | [Resources](https://jayrun.readthedocs.io/en/latest/guides/graphs/resources.html) |
+| Integrate services, remote work and checkpoints | [Application integration](https://jayrun.readthedocs.io/en/latest/guides/integration/index.html) |
+| Check exact imports and contracts | [Public API](https://jayrun.readthedocs.io/en/latest/reference/imports.html) |
+
+The [documentation sources](https://github.com/jayrun-project/jayrun/blob/main/docs/index.md) are included in this repository. Supported public imports come from `jayrun` and its documented public modules; `jayrun.core` and `jayrun.engine` are implementation details.
+
+## Scope and project status
+
+Jayrun manages graph execution and ownership; applications own network transport, authentication, external side effects and checkpoint contents. Placement accounts for declared capacity rather than performing device allocation. Cleanup releases framework references rather than guaranteeing an immediate drop in process memory. See [supported behavior and limitations](https://jayrun.readthedocs.io/en/latest/reference/limits.html).
+
+Jayrun provides a tested foundation for graph execution, with ongoing improvements to reliability, usability and documentation. Report bugs and request features through [GitHub Issues](https://github.com/jayrun-project/jayrun/issues).
+
+## License
+
+[Apache License 2.0](https://github.com/jayrun-project/jayrun/blob/main/LICENSE). Copyright 2026 Masoud Yavari.

jayrun-0.3.0/README.md

@@ -0,0 +1,138 @@
+# Jayrun
+
+[![PyPI version](https://img.shields.io/pypi/v/jayrun.svg)](https://pypi.org/project/jayrun/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Documentation](https://github.com/jayrun-project/jayrun/actions/workflows/docs.yml/badge.svg)](https://github.com/jayrun-project/jayrun/actions/workflows/docs.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/jayrun-project/jayrun/blob/main/LICENSE)
+
+Jayrun is an artifact-centric Python execution framework for pipelines, iterative computation and application services. Operators consume and produce artifact values; an Engine manages execution, resource lifetimes and control of running work. Components use ordinary synchronous or asynchronous Python methods.
+
+[Documentation](https://jayrun.readthedocs.io/en/latest/) · [First program](https://jayrun.readthedocs.io/en/latest/start/first-graph.html) · [Tutorials](https://jayrun.readthedocs.io/en/latest/tutorials/index.html) · [API reference](https://jayrun.readthedocs.io/en/latest/reference/imports.html)
+
+[![Jayrun dashboard listing running and paused contexts with graph versions, progress and iteration counts](https://raw.githubusercontent.com/jayrun-project/jayrun/main/docs/_static/screenshots/dashboard.png)](https://jayrun.readthedocs.io/en/latest/guides/visualization/dashboard.html)
+
+*Running and paused work in the dashboard. The dashboard is itself a graph, built from an observing operator and a managed service resource. Click the screenshot for an interactive offline preview and setup guide.*
+
+## What Jayrun does
+
+- **Release intermediate data automatically.** Artifact flow lets Jayrun release consumed values when execution no longer needs them. Entry/exit retention policies and application references still determine what stays alive.
+- **Reuse expensive resources.** Models, calibration data and clients can remain available across compatible runs. The Engine manages acquisition, reuse and eventual teardown.
+- **Build your own observers and controllers.** Use graphs for monitoring, experiment scheduling or distributed-work coordination. They use the existing execution and lifecycle machinery, with separate supervision capacity. Your application supplies transport and authentication.
+- **Separate declaration from execution.** Validate and visualize a graph before running it, then submit it repeatedly with different inputs and configuration. Each submission returns its own `ContextRun`.
+- **Manage iteration and capacity explicitly.** Combine graph iteration, operator repetition, conditional routes, sync/async execution and placement requests with lifecycle controls and scoped authority.
+- **Keep dependencies small.** The required third-party runtime dependency is `packaging`; PyYAML is optional. HTML visualization needs no additional plotting package.
+
+See [what Jayrun does](https://jayrun.readthedocs.io/en/latest/start/overview.html) for practical benefits and boundaries, and [data and lifetimes](https://jayrun.readthedocs.io/en/latest/start/data-and-lifetimes.html) for how artifacts, configuration and resources work together.
+
+## Install
+
+Requires Python 3.11 or later:
+
+```bash
+python -m pip install jayrun
+```
+
+For YAML configuration support, install `jayrun[yaml]`. Workload libraries such as PyTorch are application dependencies, not core requirements.
+
+## A complete first graph
+
+This program declares a multiplication, confirms the graph, supplies input and configuration, and prints `21`:
+
+```python
+from jayrun import (
+    Artifact, ArtifactContext, ArtifactField, ArtifactFlow, BaseOperator,
+    ConfigContext, ConfigField, Engine, GraphDefinition,
+)
+from jayrun.context import ContextState
+
+
+class Scale(BaseOperator):
+    def __init__(self, *, source, outputs):
+        super().__init__()
+        self.source = ArtifactField()
+        self.factor = ConfigField(value_type=int)
+        self.outputs = (ArtifactField(),)
+
+    def execute(self):
+        result = self.source.value * self.factor.value
+        self.context.record("scaled", result)
+        return result
+
+
+source = Artifact(name="source")
+result = Artifact(name="result")
+scale = Scale(source=source, outputs=(result,))
+flow = ArtifactFlow(scale, artifact=source)
+graph = GraphDefinition(flow, entry_flows=flow)
+graph.confirm()
+
+with Engine() as engine:
+    run = engine.submit(
+        graph,
+        ArtifactContext({source: 7}),
+        ConfigContext({scale.factor: 3}),
+    )
+    run.wait(timeout=10)
+    if run.state is not ContextState.FINISHED:
+        raise RuntimeError(str(run.report.data.failure))
+    print(run.artifact(result).value)  # 21
+```
+
+`ArtifactContext` supplies data; `ConfigContext` supplies the operator's parameters. Execution settings separately control policies such as retries and iteration limits. `run.wait()` waits for finalization, which can include failure; the example checks the outcome before reading the result.
+
+The same confirmed graph can serve another submission. The [complete walkthrough](https://jayrun.readthedocs.io/en/latest/start/first-graph.html) explains each declaration, inspects recorded values and visualizes the finished run.
+
+## Inspect declarations and execution
+
+Save a declaration with `graph.plot.save("graph.html")`, a registry with `registry.plot.save("registry.html")`, or a completed run with `run.plot.save("run.html")`. These HTML viewers are interactive and open in a browser. Declaration views show structure; run views add captured outcomes, timings, records and reports.
+
+[![Split-and-join graph with an explicit Splitter, two processing branches and a Join operator](https://raw.githubusercontent.com/jayrun-project/jayrun/main/docs/_static/screenshots/split-and-join.png)](https://jayrun.readthedocs.io/en/latest/guides/visualization/graphs.html)
+
+*An explicit split-and-join declaration. Click to explore the interactive graph and its explanation.*
+
+The [visualization and reporting chapter](https://jayrun.readthedocs.io/en/latest/guides/evidence/plots.html) covers graph definitions, registries, completed runs and the dashboard. A controller graph can use `self.runtime` to observe or coordinate work; see [the Controller example](https://jayrun.readthedocs.io/en/latest/guides/runtime/controller.html) and [Engine/runtime correspondence](https://jayrun.readthedocs.io/en/latest/guides/runtime/correspondence.html).
+
+## Persist execution history
+
+Pass `Database("execution.sqlite")` from `jayrun.persistence` to `Engine(database=...)` to retain bounded execution/session history and timing profiles. The Engine owns the database lifecycle. After a run finishes, explicit `engine.database.flush()` checks storage settlement; computation completion alone does not establish successful persistence.
+
+The [Persistence and Database guide](https://jayrun.readthedocs.io/en/latest/guides/evidence/persistence.html) includes a complete write–close–read example. Stored diagnostic history is separate from application checkpoints and arbitrary artifact storage.
+
+## Tutorials
+
+Explore complete applications with a walkthrough, runnable Python source and notebook:
+
+| Tutorial | Python source | Notebook | What it demonstrates |
+| --- | --- | --- | --- |
+| [Build and validate](https://jayrun.readthedocs.io/en/latest/tutorials/build-and-validate-graph.html) | [build_graph.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/build_graph.py) | [01_build_graph](https://github.com/jayrun-project/jayrun/blob/main/tutorials/01_build_graph.ipynb) | Properties, diagnostics and corrected execution |
+| [Image service](https://jayrun.readthedocs.io/en/latest/tutorials/denoise-images-with-fastapi.html) | [denoise_images.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/denoise_images.py) | [02_denoise_images](https://github.com/jayrun-project/jayrun/blob/main/tutorials/02_denoise_images.ipynb) | Async service, shared client and routing |
+| [Shared model inference](https://jayrun.readthedocs.io/en/latest/tutorials/mnist-inference-and-training.html#share-a-read-only-model-for-inference) | [mnist_inference.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/mnist_inference.py) | [03_mnist_inference](https://github.com/jayrun-project/jayrun/blob/main/tutorials/03_mnist_inference.ipynb) | Read-only model reuse and placement |
+| [Supervised training](https://jayrun.readthedocs.io/en/latest/tutorials/mnist-inference-and-training.html#supervise-replace-and-promote) | [mnist_training.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/mnist_training.py) | [04_mnist_training](https://github.com/jayrun-project/jayrun/blob/main/tutorials/04_mnist_training.ipynb) | Iteration, mutable state and scoped supervision |
+| [Document service](https://jayrun.readthedocs.io/en/latest/tutorials/document-ingestion.html) | [document_ingestion.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/document_ingestion.py) | [05_document_ingestion](https://github.com/jayrun-project/jayrun/blob/main/tutorials/05_document_ingestion.ipynb) | Long-running jobs and transactional publication |
+| [Adapter checkpointing](https://jayrun.readthedocs.io/en/latest/tutorials/checkpointed-adapter-finetuning.html) | [adapter_finetuning.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/adapter_finetuning.py) | [06_adapter_finetuning](https://github.com/jayrun-project/jayrun/blob/main/tutorials/06_adapter_finetuning.ipynb) | Model/optimizer/RNG checkpoints |
+| [Scientific campaign](https://jayrun.readthedocs.io/en/latest/tutorials/adaptive-scientific-calibration.html) | [heat_calibration.py](https://github.com/jayrun-project/jayrun/blob/main/tutorials/heat_calibration.py) | [07_heat_calibration](https://github.com/jayrun-project/jayrun/blob/main/tutorials/07_heat_calibration.ipynb) | Adaptive control and reproducibility |
+
+Each tutorial includes a small offline CPU path. See the [tutorial setup guide](https://jayrun.readthedocs.io/en/latest/tutorials/index.html) for dependencies and optional GPU/model workloads.
+
+## Find your next step
+
+| Task | Guide |
+| --- | --- |
+| Build, validate, submit and inspect a graph | [From declaration to execution](https://jayrun.readthedocs.io/en/latest/guides/workflow/index.html) |
+| Resolve fan-out, fan-in and conditional routes | [Graph-definition resolutions](https://jayrun.readthedocs.io/en/latest/guides/graphs/resolutions.html) |
+| Use context, execution, placement and runtime handles | [Component interfaces](https://jayrun.readthedocs.io/en/latest/guides/components/index.html) |
+| Add reusable models or clients | [Resources](https://jayrun.readthedocs.io/en/latest/guides/graphs/resources.html) |
+| Integrate services, remote work and checkpoints | [Application integration](https://jayrun.readthedocs.io/en/latest/guides/integration/index.html) |
+| Check exact imports and contracts | [Public API](https://jayrun.readthedocs.io/en/latest/reference/imports.html) |
+
+The [documentation sources](https://github.com/jayrun-project/jayrun/blob/main/docs/index.md) are included in this repository. Supported public imports come from `jayrun` and its documented public modules; `jayrun.core` and `jayrun.engine` are implementation details.
+
+## Scope and project status
+
+Jayrun manages graph execution and ownership; applications own network transport, authentication, external side effects and checkpoint contents. Placement accounts for declared capacity rather than performing device allocation. Cleanup releases framework references rather than guaranteeing an immediate drop in process memory. See [supported behavior and limitations](https://jayrun.readthedocs.io/en/latest/reference/limits.html).
+
+Jayrun provides a tested foundation for graph execution, with ongoing improvements to reliability, usability and documentation. Report bugs and request features through [GitHub Issues](https://github.com/jayrun-project/jayrun/issues).
+
+## License
+
+[Apache License 2.0](https://github.com/jayrun-project/jayrun/blob/main/LICENSE). Copyright 2026 Masoud Yavari.

jayrun-0.3.0/jayrun/__init__.py

@@ -0,0 +1,59 @@
+"""Public graph construction, execution, and data-context API.
+
+Exports are resolved on demand so the portable visualization package can be
+imported without loading execution, declaration, or validation modules.
+"""
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .authority import Controller, Supervisor
+    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 .core.serializer.base import BaseSerializer
+    from .engine.api import Engine
+    from .engine.engine_state import EngineState, RuntimeActivity
+    from .registry import GraphRegistry
+
+__version__ = "0.3.0"
+
+__all__ = (
+    "__version__", "Artifact", "ArtifactContext", "ArtifactField", "ArtifactFlow",
+    "BaseOperator", "BaseResource", "BaseSerializer", "ConfigContext", "ConfigField",
+    "Controller", "Data", "Engine", "EngineState", "RuntimeActivity", "GraphDefinition", "GraphRegistry",
+    "ResourceField", "Supervisor",
+)
+
+_EXPORTS = {
+    "Artifact": ".core.artifact.base", "ArtifactContext": ".core.artifact.context",
+    "ArtifactField": ".core.artifact.field", "ArtifactFlow": ".core.graph.artifact_flow",
+    "BaseOperator": ".core.operator.base", "BaseResource": ".core.resource.base",
+    "BaseSerializer": ".core.serializer.base", "ConfigContext": ".core.config.context",
+    "ConfigField": ".core.config.field", "Controller": ".authority",
+    "Data": ".core.context.runtime_data", "Engine": ".engine.api",
+    "EngineState": ".engine.engine_state", "RuntimeActivity": ".engine.engine_state",
+    "GraphDefinition": ".core.graph.graph_definition", "GraphRegistry": ".registry",
+    "ResourceField": ".core.resource.field", "Supervisor": ".authority",
+}
+
+
+def __getattr__(name: str) -> object:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

jayrun-0.3.0/jayrun/authority.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core.graph.graph_definition import GraphDefinition
+    from .persistence import DatabaseReader
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class Supervisor:
+    """Grant a submitted context authority over other context runs.
+
+    Args:
+        *graphs: Exact graph objects whose contexts may be observed and controlled.
+            When omitted, the authority covers every graph in the engine.
+    """
+
+    graphs: tuple[GraphDefinition, ...]
+
+    def __init__(self, *graphs: GraphDefinition) -> None:
+        object.__setattr__(self, "graphs", graphs)
+
+
+@dataclass(frozen=True, slots=True)
+class Controller:
+    """Grant engine-wide observation and control to a submitted context.
+
+    A controller may also submit registered graph identities through
+    ``self.runtime.submit(...)`` and asynchronously request engine shutdown.
+    Controller contexts execute locally through supervision capacity and cannot
+    be transferred. An optional ``history`` reader explicitly grants its existing
+    session scope. The runtime lends an attenuated view for this controller
+    lifetime; it cannot close/flush the store or acquire additional live rights.
+    """
+
+    history: DatabaseReader | None = None
+
+    def __post_init__(self) -> None:
+        # A history grant is local, explicit and independent of live authority.
+        # Default Controller() does not import persistence or reveal its store.
+        if self.history is not None:
+            from .persistence import DatabaseReader
+            if type(self.history) is not DatabaseReader:
+                raise TypeError("history must be a DatabaseReader or None")