feat(styxkit): add cross-backend convenience package

.github/workflows/docs.yaml

@@ -31,6 +31,7 @@ jobs:
         - styxdocker
         - styxpodman
         - styxsingularity
+        - styxkit
     steps:
     - uses: actions/checkout@v6
     - uses: astral-sh/setup-uv@v7

.github/workflows/publish.yaml

@@ -21,6 +21,7 @@ on:
     - 'styxdocker-v*'
     - 'styxpodman-v*'
     - 'styxsingularity-v*'
+    - 'styxkit-v*'
 
 jobs:
   publish:

packages/styxkit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Child Mind Institute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/styxkit/README.md

@@ -0,0 +1,64 @@
+# Styxkit - convenience helpers for the Styx runtime
+
+`styxkit` is a small convenience layer on top of the Styx runtime. It provides
+one-call runner selection across whichever backend packages you have installed,
+so you do not have to import each runner class and wire up the global runner by
+hand.
+
+It sits at the top of the runtime stack:
+
+- `styxdefs` is the base contract (the `Runner` protocol, `LocalRunner`,
+  `DryRunner`, and `set_global_runner` / `get_global_runner`).
+- Each backend (`styxdocker`, `styxpodman`, `styxsingularity`, `styxgraph`) is an
+  independent package depending only on `styxdefs`.
+- `styxkit` depends only on `styxdefs` and imports the backends **lazily**, so
+  installing it does not pull in any container backend you do not want.
+
+## Installation
+
+```bash
+pip install styxkit                 # base, plus styxdefs
+pip install "styxkit[docker]"       # + the Docker backend
+pip install "styxkit[all]"          # + every backend (docker, podman, singularity, graph)
+```
+
+Calling a `use_*()` for a backend you have not installed raises a friendly error
+telling you exactly what to install.
+
+## Usage
+
+```python
+import styxkit
+
+# Pick a specific runner:
+styxkit.use_docker()
+styxkit.use_singularity(singularity_executable="apptainer")
+styxkit.use_local()
+
+# ...or let styxkit detect the best available container runtime,
+# falling back to local when none is found:
+runner = styxkit.use_auto()
+
+# Each use_*() registers the runner as the global runner and returns it,
+# so you can configure it without a get_global_runner() round-trip:
+runner = styxkit.use_docker()
+runner.data_dir = "/tmp/styx"
+```
+
+`use_auto()` prefers, in order, the first container backend that is both
+installed and has its executable on `PATH`: Docker, then Podman, then
+Singularity/Apptainer, otherwise the local runner.
+
+## Available helpers
+
+- `use_local`, `use_dry` - always available (from `styxdefs`).
+- `use_docker`, `use_podman`, `use_singularity` - lazy, require the matching backend.
+- `use_graph(base=None)` - wraps a runner in a graph recorder; defaults to the
+  current global runner.
+- `use_auto()` / `resolve_runner()` - detect and select a runner.
+- The core `styxdefs` symbols (`Runner`, `Execution`, `Metadata`,
+  `set_global_runner`, ...) are re-exported for convenience.
+
+## License
+
+`styxkit` is released under the MIT License. See the LICENSE file for details.

packages/styxkit/docs/pdoc-theme/frame.html.jinja2

@@ -0,0 +1,7 @@
+{% extends "default/frame.html.jinja2" %}
+
+{% block head %}
+    <!-- Cloudflare Web Analytics -->
+    <script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "3cc81275d9484412b3569fdb3580758a"}'></script>
+    <!-- End Cloudflare Web Analytics -->
+{% endblock %}

packages/styxkit/docs/pdoc-theme/syntax-highlighting.css

@@ -0,0 +1,156 @@
+
+/* auto-generated, see templates/README.md */
+pre { line-height: 125%; }
+span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 20px; }
+.pdoc-code .hll { background-color: #ffffcc }
+.pdoc-code { background: #f8f8f8; }
+.pdoc-code .c { color: #3D7B7B; font-style: italic } /* Comment */
+.pdoc-code .err { border: 1px solid #FF0000 } /* Error */
+.pdoc-code .k { color: #008000; font-weight: bold } /* Keyword */
+.pdoc-code .o { color: #666666 } /* Operator */
+.pdoc-code .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */
+.pdoc-code .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */
+.pdoc-code .cp { color: #9C6500 } /* Comment.Preproc */
+.pdoc-code .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */
+.pdoc-code .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */
+.pdoc-code .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */
+.pdoc-code .gd { color: #A00000 } /* Generic.Deleted */
+.pdoc-code .ge { font-style: italic } /* Generic.Emph */
+.pdoc-code .gr { color: #E40000 } /* Generic.Error */
+.pdoc-code .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.pdoc-code .gi { color: #008400 } /* Generic.Inserted */
+.pdoc-code .go { color: #717171 } /* Generic.Output */
+.pdoc-code .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
+.pdoc-code .gs { font-weight: bold } /* Generic.Strong */
+.pdoc-code .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.pdoc-code .gt { color: #0044DD } /* Generic.Traceback */
+.pdoc-code .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
+.pdoc-code .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
+.pdoc-code .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
+.pdoc-code .kp { color: #008000 } /* Keyword.Pseudo */
+.pdoc-code .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
+.pdoc-code .kt { color: #B00040 } /* Keyword.Type */
+.pdoc-code .m { color: #666666 } /* Literal.Number */
+.pdoc-code .s { color: #BA2121 } /* Literal.String */
+.pdoc-code .na { color: #687822 } /* Name.Attribute */
+.pdoc-code .nb { color: #008000 } /* Name.Builtin */
+.pdoc-code .nc { color: #0000FF; font-weight: bold } /* Name.Class */
+.pdoc-code .no { color: #880000 } /* Name.Constant */
+.pdoc-code .nd { color: #AA22FF } /* Name.Decorator */
+.pdoc-code .ni { color: #717171; font-weight: bold } /* Name.Entity */
+.pdoc-code .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */
+.pdoc-code .nf { color: #0000FF } /* Name.Function */
+.pdoc-code .nl { color: #767600 } /* Name.Label */
+.pdoc-code .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
+.pdoc-code .nt { color: #008000; font-weight: bold } /* Name.Tag */
+.pdoc-code .nv { color: #19177C } /* Name.Variable */
+.pdoc-code .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
+.pdoc-code .w { color: #bbbbbb } /* Text.Whitespace */
+.pdoc-code .mb { color: #666666 } /* Literal.Number.Bin */
+.pdoc-code .mf { color: #666666 } /* Literal.Number.Float */
+.pdoc-code .mh { color: #666666 } /* Literal.Number.Hex */
+.pdoc-code .mi { color: #666666 } /* Literal.Number.Integer */
+.pdoc-code .mo { color: #666666 } /* Literal.Number.Oct */
+.pdoc-code .sa { color: #BA2121 } /* Literal.String.Affix */
+.pdoc-code .sb { color: #BA2121 } /* Literal.String.Backtick */
+.pdoc-code .sc { color: #BA2121 } /* Literal.String.Char */
+.pdoc-code .dl { color: #BA2121 } /* Literal.String.Delimiter */
+.pdoc-code .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
+.pdoc-code .s2 { color: #BA2121 } /* Literal.String.Double */
+.pdoc-code .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */
+.pdoc-code .sh { color: #BA2121 } /* Literal.String.Heredoc */
+.pdoc-code .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */
+.pdoc-code .sx { color: #008000 } /* Literal.String.Other */
+.pdoc-code .sr { color: #A45A77 } /* Literal.String.Regex */
+.pdoc-code .s1 { color: #BA2121 } /* Literal.String.Single */
+.pdoc-code .ss { color: #19177C } /* Literal.String.Symbol */
+.pdoc-code .bp { color: #008000 } /* Name.Builtin.Pseudo */
+.pdoc-code .fm { color: #0000FF } /* Name.Function.Magic */
+.pdoc-code .vc { color: #19177C } /* Name.Variable.Class */
+.pdoc-code .vg { color: #19177C } /* Name.Variable.Global */
+.pdoc-code .vi { color: #19177C } /* Name.Variable.Instance */
+.pdoc-code .vm { color: #19177C } /* Name.Variable.Magic */
+.pdoc-code .il { color: #666666 } /* Literal.Number.Integer.Long */
+
+@media (prefers-color-scheme: dark) {
+    /* monokai color scheme, see pdoc/template/README.md */
+    pre { line-height: 125%; }
+    span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 20px; }
+    .pdoc-code .hll { background-color: #49483e }
+    .pdoc-code { background: #272822; color: #f8f8f2 }
+    .pdoc-code .c { color: #75715e } /* Comment */
+    .pdoc-code .err { color: #960050; background-color: #1e0010 } /* Error */
+    .pdoc-code .esc { color: #f8f8f2 } /* Escape */
+    .pdoc-code .g { color: #f8f8f2 } /* Generic */
+    .pdoc-code .k { color: #66d9ef } /* Keyword */
+    .pdoc-code .l { color: #ae81ff } /* Literal */
+    .pdoc-code .n { color: #f8f8f2 } /* Name */
+    .pdoc-code .o { color: #f92672 } /* Operator */
+    .pdoc-code .x { color: #f8f8f2 } /* Other */
+    .pdoc-code .p { color: #f8f8f2 } /* Punctuation */
+    .pdoc-code .ch { color: #75715e } /* Comment.Hashbang */
+    .pdoc-code .cm { color: #75715e } /* Comment.Multiline */
+    .pdoc-code .cp { color: #75715e } /* Comment.Preproc */
+    .pdoc-code .cpf { color: #75715e } /* Comment.PreprocFile */
+    .pdoc-code .c1 { color: #75715e } /* Comment.Single */
+    .pdoc-code .cs { color: #75715e } /* Comment.Special */
+    .pdoc-code .gd { color: #f92672 } /* Generic.Deleted */
+    .pdoc-code .ge { color: #f8f8f2; font-style: italic } /* Generic.Emph */
+    .pdoc-code .gr { color: #f8f8f2 } /* Generic.Error */
+    .pdoc-code .gh { color: #f8f8f2 } /* Generic.Heading */
+    .pdoc-code .gi { color: #a6e22e } /* Generic.Inserted */
+    .pdoc-code .go { color: #66d9ef } /* Generic.Output */
+    .pdoc-code .gp { color: #f92672; font-weight: bold } /* Generic.Prompt */
+    .pdoc-code .gs { color: #f8f8f2; font-weight: bold } /* Generic.Strong */
+    .pdoc-code .gu { color: #75715e } /* Generic.Subheading */
+    .pdoc-code .gt { color: #f8f8f2 } /* Generic.Traceback */
+    .pdoc-code .kc { color: #66d9ef } /* Keyword.Constant */
+    .pdoc-code .kd { color: #66d9ef } /* Keyword.Declaration */
+    .pdoc-code .kn { color: #f92672 } /* Keyword.Namespace */
+    .pdoc-code .kp { color: #66d9ef } /* Keyword.Pseudo */
+    .pdoc-code .kr { color: #66d9ef } /* Keyword.Reserved */
+    .pdoc-code .kt { color: #66d9ef } /* Keyword.Type */
+    .pdoc-code .ld { color: #e6db74 } /* Literal.Date */
+    .pdoc-code .m { color: #ae81ff } /* Literal.Number */
+    .pdoc-code .s { color: #e6db74 } /* Literal.String */
+    .pdoc-code .na { color: #a6e22e } /* Name.Attribute */
+    .pdoc-code .nb { color: #f8f8f2 } /* Name.Builtin */
+    .pdoc-code .nc { color: #a6e22e } /* Name.Class */
+    .pdoc-code .no { color: #66d9ef } /* Name.Constant */
+    .pdoc-code .nd { color: #a6e22e } /* Name.Decorator */
+    .pdoc-code .ni { color: #f8f8f2 } /* Name.Entity */
+    .pdoc-code .ne { color: #a6e22e } /* Name.Exception */
+    .pdoc-code .nf { color: #a6e22e } /* Name.Function */
+    .pdoc-code .nl { color: #f8f8f2 } /* Name.Label */
+    .pdoc-code .nn { color: #f8f8f2 } /* Name.Namespace */
+    .pdoc-code .nx { color: #a6e22e } /* Name.Other */
+    .pdoc-code .py { color: #f8f8f2 } /* Name.Property */
+    .pdoc-code .nt { color: #f92672 } /* Name.Tag */
+    .pdoc-code .nv { color: #f8f8f2 } /* Name.Variable */
+    .pdoc-code .ow { color: #f92672 } /* Operator.Word */
+    .pdoc-code .w { color: #f8f8f2 } /* Text.Whitespace */
+    .pdoc-code .mb { color: #ae81ff } /* Literal.Number.Bin */
+    .pdoc-code .mf { color: #ae81ff } /* Literal.Number.Float */
+    .pdoc-code .mh { color: #ae81ff } /* Literal.Number.Hex */
+    .pdoc-code .mi { color: #ae81ff } /* Literal.Number.Integer */
+    .pdoc-code .mo { color: #ae81ff } /* Literal.Number.Oct */
+    .pdoc-code .sa { color: #e6db74 } /* Literal.String.Affix */
+    .pdoc-code .sb { color: #e6db74 } /* Literal.String.Backtick */
+    .pdoc-code .sc { color: #e6db74 } /* Literal.String.Char */
+    .pdoc-code .dl { color: #e6db74 } /* Literal.String.Delimiter */
+    .pdoc-code .sd { color: #e6db74 } /* Literal.String.Doc */
+    .pdoc-code .s2 { color: #e6db74 } /* Literal.String.Double */
+    .pdoc-code .se { color: #ae81ff } /* Literal.String.Escape */
+    .pdoc-code .sh { color: #e6db74 } /* Literal.String.Heredoc */
+    .pdoc-code .si { color: #e6db74 } /* Literal.String.Interpol */
+    .pdoc-code .sx { color: #e6db74 } /* Literal.String.Other */
+    .pdoc-code .sr { color: #e6db74 } /* Literal.String.Regex */
+    .pdoc-code .s1 { color: #e6db74 } /* Literal.String.Single */
+    .pdoc-code .ss { color: #e6db74 } /* Literal.String.Symbol */
+    .pdoc-code .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */
+    .pdoc-code .fm { color: #a6e22e } /* Name.Function.Magic */
+    .pdoc-code .vc { color: #f8f8f2 } /* Name.Variable.Class */
+    .pdoc-code .vg { color: #f8f8f2 } /* Name.Variable.Global */
+    .pdoc-code .vi { color: #f8f8f2 } /* Name.Variable.Instance */
+    .pdoc-code .vm { color: #f8f8f2 } /* Name.Variable.Magic */
+}

packages/styxkit/docs/pdoc-theme/theme.css

@@ -0,0 +1,44 @@
+/* pdoc color scheme (see also: examples/dark-mode) */
+:root {
+    --pdoc-background: #fff;
+}
+
+.pdoc {
+    --text: #212529;
+    --muted: #6c757d;
+    --link: #3660a5;
+    --link-hover: #1659c5;
+    --code: #f8f8f8;
+    --active: #fff598;
+
+    --accent: #eee;
+    --accent2: #c1c1c1;
+
+    --nav-hover: rgba(255, 255, 255, 0.5);
+    --name: #0066BB;
+    --def: #008800;
+    --annotation: #007020;
+}
+
+@media (prefers-color-scheme: dark) {
+    :root {
+        --pdoc-background: #212529;
+    }
+
+    .pdoc {
+        --text: #f7f7f7;
+        --muted: #9d9d9d;
+        --link: #58a6ff;
+        --link-hover: #3989ff;
+        --code: #333;
+        --active: #555;
+
+        --accent: #343434;
+        --accent2: #555;
+
+        --nav-hover: rgba(0, 0, 0, 0.1);
+        --name: #77C1FF;
+        --def: #0cdd0c;
+        --annotation: #00c037;
+    }
+}

packages/styxkit/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "styxkit"
+version = "0.1.0"
+description = "Convenience helpers spanning the Styx runtime backends."
+authors = [
+  {name = "Florian Rupprecht", email = "33600480+nx10@users.noreply.github.com"}
+]
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+dependencies = [
+  "styxdefs>=0.7.0,<0.8",
+]
+
+# Backends are imported lazily; install the ones you need (or `styxkit[all]`).
+[project.optional-dependencies]
+docker = ["styxdocker"]
+podman = ["styxpodman"]
+singularity = ["styxsingularity"]
+graph = ["styxgraph"]
+all = ["styxdocker", "styxpodman", "styxsingularity", "styxgraph"]
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.10.0"]
+build-backend = "uv_build"