szpont 0.2.0__tar.gz

szpont-0.2.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: szpont
+Version: 0.2.0
+Summary: Install-and-run for Diplomat, and typed Python bindings for SzpontNet, the leaderless LAN peer-to-peer resource-sharing protocol
+Author: Ignacy Łątka
+License: MIT
+Project-URL: Homepage, https://github.com/latekvo/Diplomat
+Project-URL: Source, https://github.com/latekvo/Diplomat/tree/main/packages/szpont
+Project-URL: Specification, https://github.com/latekvo/Diplomat/tree/main/packages/szpontnet-spec
+Keywords: diplomat,szpontnet,mesh,peer-to-peer,lan,distributed,bindings,launcher
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: szpontnet<0.6,>=0.5
+Provides-Extra: trust
+Requires-Dist: szpontnet[trust]<0.6,>=0.5; extra == "trust"
+
+# szpont
+
+Typed Python bindings for **[SzpontNet](../szpontnet-core/README.md)**, the
+leaderless LAN protocol for self-discovery, resource advertisement and work
+hand-off.
+
+SzpontNet's reference node is the [`szpontnet`](../szpontnet-core/README.md)
+package, and its public surface is the **wire format**: JSON snapshots,
+string-keyed dictionaries, `lastSeenSecsAgo`, and one exception class for every
+way a control session can fail. That is the right shape for a protocol and an
+awkward one to program against.
+
+`szpont` is that surface bound to Python types. It adds nothing to the protocol
+and reimplements none of it - every call here is the corresponding `szpontnet`
+call with its answer parsed and its failure classified.
+
+```python
+import szpont
+
+mesh = szpont.Mesh()
+
+for peer in mesh.status().peers:
+    print(peer.name, peer.link, peer.quota.surplus, peer.trust)
+
+result = mesh.dispatch("review", prompt, work_key="review:owner/repo#41")
+if result.suppressed:
+    print("another machine already has this one")
+```
+
+## What it gives you over the dictionaries
+
+**Types.** `Snapshot`, `Node`, `Peer`, `Assignment`, `Dispatch`, `Slot`, `Claim`,
+`Quota`, `Device`, `Tor` - with the questions you actually ask as properties:
+`peer.up`, `peer.personal`, `assignment.satisfied`, `result.ok`, `slot.suppressed`.
+
+Parsing never raises. A snapshot can be truncated mid-write, written by a newer
+protocol version, or hand-edited by someone hostile; the library's own contract is
+that such a file degrades to "no node" rather than crashing whoever renders it,
+and these types inherit that. Every object also keeps the dict it was read from as
+`.raw`, because the protocol grows by adding fields - `onion`, `stats` and `sig`
+all arrived that way - and bindings that exposed only what they knew about would
+hide the next one.
+
+**Failures you can branch on.** The library raises one `CtlError` for every
+control-session failure and puts the difference in the message. This package
+splits it along the line that decides what a caller should do:
+
+| | meaning | what to do |
+|---|---|---|
+| `NodeUnavailable` | there was no node to talk to, so nothing was attempted | start one, or retry |
+| `CommandRejected` | a node was there and the command did not take effect | retrying sends the same thing |
+
+The split is structural, not textual - it turns on whether a live node with a
+usable control port was there, and on whether the library chained a socket error -
+so it does not quietly go wrong the day a message is reworded. Both remain
+`szpontnet.ctl.CtlError`, so code already written against the library keeps working.
+
+**Hosting without a subclass.** A node asks its *host* the five things it cannot
+answer alone. The library's way to answer is to subclass `szpontnet.host.Host`;
+most hosts answer one or two of them, and a class for that is ceremony:
+
+```python
+szpont.register_host(
+    duties=["render"],
+    run_job=lambda prompt, done_path: my_queue.submit(prompt, done_path),
+)
+```
+
+Anything you leave out keeps the library's default, which is a real answer rather
+than a placeholder: no runner means this machine declines work and the dispatcher
+fails over to the next candidate.
+
+This registers **in-process**. A node your application *spawns* is a separate
+process and cannot see it - point that one at a module with `SZPONTNET_HOST`.
+
+## Reading is two calls, on purpose
+
+```python
+mesh.snapshot()   # state.json: a file read, no socket, no node needed
+mesh.status()     # the node itself: fresher, needs a live node
+```
+
+They cost different things. `snapshot()` is what a UI polls every couple of
+seconds; it can lag the node slightly and it survives the node's death, so check
+`mesh.running` before treating what it says as current. `status()` is what you
+call before acting on what you read.
+
+## Install
+
+```bash
+pip install szpont          # the bindings and the node
+pip install 'szpont[trust]' # ... with Ed25519 device identity
+```
+
+Without the `trust` extra a node still runs, keyless: it advertises no public key,
+can never be verified, and so is foreign to any peer with a trust allowlist.
+
+## The command of the same name
+
+The distribution also installs `szpont`, which fetches, builds and starts
+**[Diplomat](../../README.md#install)** - the applet this protocol was written for.
+`szpont --plan` prints what it would do without doing any of it.
+
+```bash
+pip install szpont && szpont      # the same thing `npx szpont` does
+```
+
+It is `szpont_launcher.py`, a top-level module rather than part of this package,
+and it imports nothing outside the standard library: starting an applet has no use
+for the protocol library, and `import szpont` has no use for a launcher. Its twin
+is [`packages/szpont-npm`](../szpont-npm/README.md), which publishes the same
+command to npm; the two are held to the same plan by a parity test.
+
+## What it does not do
+
+Wrap what already has a good shape. The node itself, its CLI (`python -m
+szpontnet`), the placement function and the protocol codec are all reached
+through `szpontnet` directly and are not duplicated here.
+
+## Its own tests
+
+```bash
+pip install -e ./packages/szpontnet-core -e ./packages/szpont pytest
+pytest packages/szpont/tests -q
+```
+
+The suite refuses to open a socket. That is not tidiness: a test's state directory
+is isolated but the port inside a snapshot is not, and a fixture naming the
+protocol's default 40878 is naming exactly the port a developer's own node is
+listening on. A test that reached the transport would drive that live node - and
+pass while doing it - so the transport is removed and reaching it is the failure.
+
+## Note on the name
+
+`szpont` names three things, and they share the namespace rather than compete for
+it: this import package (`import szpont`), the launcher installed as the `szpont`
+command, and the [conformance tester](../szpontnet-spec/conformance/README.md), run
+as `python -m szpont` from its own directory.
+
+Only the last is precarious. The tester is never installed, and the working
+directory precedes site-packages on `sys.path`, so it wins from where it is run -
+but publishing *it* under this name is what the three could not share. The console
+script cannot collide with either: an entry point is a file in `bin/`, not a name
+on the import path.

szpont-0.2.0/README.md

@@ -0,0 +1,144 @@
+# szpont
+
+Typed Python bindings for **[SzpontNet](../szpontnet-core/README.md)**, the
+leaderless LAN protocol for self-discovery, resource advertisement and work
+hand-off.
+
+SzpontNet's reference node is the [`szpontnet`](../szpontnet-core/README.md)
+package, and its public surface is the **wire format**: JSON snapshots,
+string-keyed dictionaries, `lastSeenSecsAgo`, and one exception class for every
+way a control session can fail. That is the right shape for a protocol and an
+awkward one to program against.
+
+`szpont` is that surface bound to Python types. It adds nothing to the protocol
+and reimplements none of it - every call here is the corresponding `szpontnet`
+call with its answer parsed and its failure classified.
+
+```python
+import szpont
+
+mesh = szpont.Mesh()
+
+for peer in mesh.status().peers:
+    print(peer.name, peer.link, peer.quota.surplus, peer.trust)
+
+result = mesh.dispatch("review", prompt, work_key="review:owner/repo#41")
+if result.suppressed:
+    print("another machine already has this one")
+```
+
+## What it gives you over the dictionaries
+
+**Types.** `Snapshot`, `Node`, `Peer`, `Assignment`, `Dispatch`, `Slot`, `Claim`,
+`Quota`, `Device`, `Tor` - with the questions you actually ask as properties:
+`peer.up`, `peer.personal`, `assignment.satisfied`, `result.ok`, `slot.suppressed`.
+
+Parsing never raises. A snapshot can be truncated mid-write, written by a newer
+protocol version, or hand-edited by someone hostile; the library's own contract is
+that such a file degrades to "no node" rather than crashing whoever renders it,
+and these types inherit that. Every object also keeps the dict it was read from as
+`.raw`, because the protocol grows by adding fields - `onion`, `stats` and `sig`
+all arrived that way - and bindings that exposed only what they knew about would
+hide the next one.
+
+**Failures you can branch on.** The library raises one `CtlError` for every
+control-session failure and puts the difference in the message. This package
+splits it along the line that decides what a caller should do:
+
+| | meaning | what to do |
+|---|---|---|
+| `NodeUnavailable` | there was no node to talk to, so nothing was attempted | start one, or retry |
+| `CommandRejected` | a node was there and the command did not take effect | retrying sends the same thing |
+
+The split is structural, not textual - it turns on whether a live node with a
+usable control port was there, and on whether the library chained a socket error -
+so it does not quietly go wrong the day a message is reworded. Both remain
+`szpontnet.ctl.CtlError`, so code already written against the library keeps working.
+
+**Hosting without a subclass.** A node asks its *host* the five things it cannot
+answer alone. The library's way to answer is to subclass `szpontnet.host.Host`;
+most hosts answer one or two of them, and a class for that is ceremony:
+
+```python
+szpont.register_host(
+    duties=["render"],
+    run_job=lambda prompt, done_path: my_queue.submit(prompt, done_path),
+)
+```
+
+Anything you leave out keeps the library's default, which is a real answer rather
+than a placeholder: no runner means this machine declines work and the dispatcher
+fails over to the next candidate.
+
+This registers **in-process**. A node your application *spawns* is a separate
+process and cannot see it - point that one at a module with `SZPONTNET_HOST`.
+
+## Reading is two calls, on purpose
+
+```python
+mesh.snapshot()   # state.json: a file read, no socket, no node needed
+mesh.status()     # the node itself: fresher, needs a live node
+```
+
+They cost different things. `snapshot()` is what a UI polls every couple of
+seconds; it can lag the node slightly and it survives the node's death, so check
+`mesh.running` before treating what it says as current. `status()` is what you
+call before acting on what you read.
+
+## Install
+
+```bash
+pip install szpont          # the bindings and the node
+pip install 'szpont[trust]' # ... with Ed25519 device identity
+```
+
+Without the `trust` extra a node still runs, keyless: it advertises no public key,
+can never be verified, and so is foreign to any peer with a trust allowlist.
+
+## The command of the same name
+
+The distribution also installs `szpont`, which fetches, builds and starts
+**[Diplomat](../../README.md#install)** - the applet this protocol was written for.
+`szpont --plan` prints what it would do without doing any of it.
+
+```bash
+pip install szpont && szpont      # the same thing `npx szpont` does
+```
+
+It is `szpont_launcher.py`, a top-level module rather than part of this package,
+and it imports nothing outside the standard library: starting an applet has no use
+for the protocol library, and `import szpont` has no use for a launcher. Its twin
+is [`packages/szpont-npm`](../szpont-npm/README.md), which publishes the same
+command to npm; the two are held to the same plan by a parity test.
+
+## What it does not do
+
+Wrap what already has a good shape. The node itself, its CLI (`python -m
+szpontnet`), the placement function and the protocol codec are all reached
+through `szpontnet` directly and are not duplicated here.
+
+## Its own tests
+
+```bash
+pip install -e ./packages/szpontnet-core -e ./packages/szpont pytest
+pytest packages/szpont/tests -q
+```
+
+The suite refuses to open a socket. That is not tidiness: a test's state directory
+is isolated but the port inside a snapshot is not, and a fixture naming the
+protocol's default 40878 is naming exactly the port a developer's own node is
+listening on. A test that reached the transport would drive that live node - and
+pass while doing it - so the transport is removed and reaching it is the failure.
+
+## Note on the name
+
+`szpont` names three things, and they share the namespace rather than compete for
+it: this import package (`import szpont`), the launcher installed as the `szpont`
+command, and the [conformance tester](../szpontnet-spec/conformance/README.md), run
+as `python -m szpont` from its own directory.
+
+Only the last is precarious. The tester is never installed, and the working
+directory precedes site-packages on `sys.path`, so it wins from where it is run -
+but publishing *it* under this name is what the three could not share. The console
+script cannot collide with either: an entry point is a file in `bin/`, not a name
+on the import path.

szpont-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "szpont"
+version = "0.2.0"
+description = "Install-and-run for Diplomat, and typed Python bindings for SzpontNet, the leaderless LAN peer-to-peer resource-sharing protocol"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Ignacy Łątka" }]
+keywords = ["diplomat", "szpontnet", "mesh", "peer-to-peer", "lan", "distributed", "bindings", "launcher"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Distributed Computing",
+  "Topic :: System :: Networking",
+  "Typing :: Typed",
+]
+# The node itself. This package is bindings for it and has no independent
+# behaviour, so the dependency is required rather than an extra.
+dependencies = ["szpontnet>=0.5,<0.6"]
+
+[project.optional-dependencies]
+# Passed through to the library: Ed25519 device identity. Without it a node runs
+# keyless, advertises no public key, and is foreign to any peer with an allowlist.
+trust = ["szpontnet[trust]>=0.5,<0.6"]
+
+[project.scripts]
+# `pip install szpont` then `szpont`. The launcher is a top-level module rather
+# than part of the package on purpose - see its docstring; nothing about starting
+# an applet needs the protocol library that importing `szpont` would pull in.
+szpont = "szpont_launcher:main"
+
+[project.urls]
+Homepage = "https://github.com/latekvo/Diplomat"
+Source = "https://github.com/latekvo/Diplomat/tree/main/packages/szpont"
+Specification = "https://github.com/latekvo/Diplomat/tree/main/packages/szpontnet-spec"
+
+[tool.setuptools]
+packages = ["szpont"]
+py-modules = ["szpont_launcher"]
+
+[tool.setuptools.package-data]
+szpont = ["py.typed"]

szpont-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

szpont-0.2.0/szpont/__init__.py

@@ -0,0 +1,66 @@
+"""szpont - a typed Python API for SzpontNet.
+
+SzpontNet is a leaderless LAN protocol: machines find each other over UDP, gossip
+what they can do, and agree with no coordinator on which machine owns each class
+of work. Its reference node is the ``szpontnet`` package, and that package's
+public surface is the wire format - JSON snapshots, string-keyed dictionaries, and
+one exception class for every way a control session can fail.
+
+This package is that surface bound to Python types. It adds nothing to the
+protocol and re-implements none of it; every call here is the corresponding
+``szpontnet`` call with its answer parsed and its failure classified.
+
+    import szpont
+
+    mesh = szpont.Mesh()
+    if mesh.running:
+        for peer in mesh.status().peers:
+            print(peer.name, peer.link, peer.quota.surplus)
+
+    result = mesh.dispatch("review", prompt, work_key="review:owner/repo#41")
+    if result.suppressed:
+        ...  # another machine already has this one
+
+Three things it gives you over the dictionaries:
+
+* **Types.** :class:`~szpont.models.Snapshot`, :class:`~szpont.models.Peer`,
+  :class:`~szpont.models.Dispatch` and friends, with the questions you actually
+  ask as properties - ``peer.up``, ``assignment.satisfied``, ``result.ok``.
+  Parsing never raises, and every object keeps the dict it came from as ``raw``,
+  so a field this package has not heard of is still reachable.
+* **Failures you can branch on.** :class:`~szpont.errors.NodeUnavailable` (there
+  was no node, so nothing happened) against
+  :class:`~szpont.errors.CommandRejected` (there was, and it did not do it).
+  Both remain :class:`szpontnet.ctl.CtlError`.
+* **Hosting without a subclass.** :func:`register_host` takes the answers a node
+  needs from its host as plain functions.
+
+The library itself stays right there: ``import szpontnet`` for the node, its CLI
+(``python -m szpontnet``) and everything this package deliberately does not
+duplicate.
+"""
+
+from __future__ import annotations
+
+from .errors import CommandRejected, NodeUnavailable, SzpontError
+from .hosting import (Host, NoRunner, build_host, duty_model, register_host,
+                      unregister_host)
+from .mesh import DEFAULT_DISPATCH_TIMEOUT, DEFAULT_TIMEOUT, Mesh
+from .models import (NEUTRAL_SURPLUS, Assignment, Claim, Device, Dispatch, Node,
+                     Peer, Quota, Shortfall, Slot, Snapshot, Tor)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    # client
+    "Mesh", "DEFAULT_TIMEOUT", "DEFAULT_DISPATCH_TIMEOUT",
+    # errors
+    "SzpontError", "NodeUnavailable", "CommandRejected",
+    # models
+    "Snapshot", "Node", "Peer", "Quota", "Assignment", "Shortfall", "Dispatch",
+    "Slot", "Claim", "Device", "Tor", "NEUTRAL_SURPLUS",
+    # hosting
+    "Host", "NoRunner", "build_host", "register_host", "unregister_host",
+    "duty_model",
+]

szpont-0.2.0/szpont/errors.py

@@ -0,0 +1,42 @@
+"""What went wrong, told apart by whether retrying could ever help.
+
+The library raises one :class:`szpontnet.ctl.CtlError` for every control-session
+failure, so a caller that wants to react has to read the message to learn which
+kind it got. This package splits that class along the only line that changes what
+a caller should do:
+
+* :class:`NodeUnavailable` - there was no node to talk to. Nothing was attempted,
+  so nothing happened; start a node, or wait and retry.
+* :class:`CommandRejected` - a node was there and the command did not take
+  effect. Retrying the same command gets the same answer.
+
+Both are also :class:`szpontnet.ctl.CtlError`, so code that already catches the
+library's own exception keeps catching these unchanged - the split is additive.
+"""
+
+from __future__ import annotations
+
+from szpontnet.ctl import CtlError
+
+
+class SzpontError(Exception):
+    """Base class for everything this package raises."""
+
+
+class NodeUnavailable(SzpontError, CtlError):
+    """No local node was reachable, so the command was never put to one.
+
+    Raised when no node has ever run against this state directory, when the one
+    that did is dead, when its snapshot names no usable control port, or when the
+    socket to it fails. In every case the mesh saw nothing.
+    """
+
+
+class CommandRejected(SzpontError, CtlError):
+    """A node was reached and the command did not take effect.
+
+    Either it answered with an error - an unknown duty, a bad attribute, a
+    missing API key - or it ended the control session without answering at all.
+    The two are one class because they leave the caller in the same position: the
+    node is up, and this command is not going to work as sent.
+    """

szpont-0.2.0/szpont/hosting.py

@@ -0,0 +1,168 @@
+"""Putting your application behind a node, without writing a class.
+
+A node asks its **host** the five things it cannot answer alone: which duties this
+deployment routes, where its state lives, where its events go, what running a job
+means here, and whether that work is already under way on this machine
+(:mod:`szpontnet.host`). The library's own way to answer is to subclass
+:class:`~szpontnet.host.Host` and override what you answer differently.
+
+Most hosts answer one or two of those - usually just :func:`run_job` - and a class
+for that is ceremony. :func:`register` takes the answers as functions:
+
+    import szpont
+
+    szpont.register_host(
+        duties=["render"],
+        run_job=lambda prompt, done_path: my_queue.submit(prompt, done_path),
+    )
+
+Whatever you leave out keeps the library's default, which is a real answer and not
+a placeholder: no runner means this machine declines work and the dispatcher fails
+over to the next candidate, which is exactly what a machine with nothing to run it
+should say.
+
+This registers **in-process**. A node your application *spawns* is a separate
+process and cannot see it - point that one at a module with ``SZPONTNET_HOST``,
+as :mod:`szpontnet.host` describes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from pathlib import Path
+
+from szpontnet import host as _host
+from szpontnet.host import Host, NoRunner
+
+__all__ = ["Host", "NoRunner", "build_host", "register_host", "unregister_host",
+           "duty_model"]
+
+
+def duty_model(duties: Iterable[str], *, token_aware: bool = True,
+               spread: Iterable[tuple[str, int]] = ()) -> dict:
+    """A network model that routes exactly ``duties``, for the common case.
+
+    The duty catalog is replaced wholesale rather than merged, so a deployment
+    that names its duties gets *those* duties and not those plus the canonical
+    ``review``/``conflicts``/``audit``. Every duty here shares one placement;
+    a deployment that needs them to differ writes the model out by hand and
+    passes it as ``model`` instead.
+
+    ``token_aware`` excludes machines that are out of tokens, and ``spread`` is
+    the ``(platform, count)`` staffing a duty requires - an empty spread means one
+    slot on whichever machine ranks best.
+
+    Each spread pair is written out as the ``{"platform", "count"}`` object the
+    schema defines. That shape is load-bearing rather than cosmetic: placements
+    arrive over gossip too, so the library skips any spread entry that is not an
+    object - a pair emitted as a two-element list would not be rejected, it would
+    silently resolve to no spread at all, and the duty would staff one machine
+    instead of the platforms asked for.
+    """
+    slots = [{"platform": platform, "count": int(count)} for platform, count in spread]
+    # A fresh placement per duty, so a caller that edits one duty's spread in the
+    # returned model does not silently edit every other duty's too.
+    return {"duties": [{"id": duty,
+                        "placement": {"tokenAware": bool(token_aware),
+                                      "spread": [dict(s) for s in slots]}}
+                       for duty in duties]}
+
+
+def build_host(
+    *,
+    model: Callable[[], dict] | dict | None = None,
+    duties: Iterable[str] | None = None,
+    state_dir: Callable[[], Path | str] | Path | str | None = None,
+    log: Callable[[str, str], None] | None = None,
+    run_job: Callable[[str, str | None], str] | None = None,
+    work_already_running: Callable[[str], bool] | None = None,
+) -> Host:
+    """A :class:`~szpontnet.host.Host` answering only what you gave it.
+
+    Each argument takes either a callable, which the node calls when it needs the
+    answer, or a plain value, which is treated as a callable returning it. Anything
+    omitted falls through to the library's default.
+
+    ``duties`` is shorthand for ``model=duty_model(duties)`` and cannot be combined
+    with an explicit ``model``.
+    """
+    if duties is not None:
+        if model is not None:
+            raise ValueError("pass either `duties` or `model`, not both - "
+                             "`duties` is shorthand for a model that routes them")
+        model = duty_model(duties)
+
+    return _CallableHost(
+        model=_as_callable(model),
+        state_dir=_as_path_callable(state_dir),
+        log=log,
+        run_job=run_job,
+        work_already_running=work_already_running,
+    )
+
+
+def register_host(**answers) -> Host:
+    """Build a host from :func:`build_host`'s arguments and put it behind the
+    node in this process. Returns it, so a caller can hold on to it.
+
+    The host is process-global and there is one: registering replaces whoever was
+    there. It also overrides ``SZPONTNET_HOST``, since an application driving the
+    node's modules directly is more specific than the environment it inherited.
+    """
+    host = build_host(**answers)
+    _host.set_host(host)
+    return host
+
+
+def unregister_host() -> None:
+    """Take the registered host away - back to the library's own defaults."""
+    _host.reset_host()
+
+
+def _as_callable(value):
+    if value is None or callable(value):
+        return value
+    return lambda: value
+
+
+def _as_path_callable(value):
+    if value is None:
+        return None
+    if callable(value):
+        return lambda: Path(value())
+    resolved = Path(value)
+    return lambda: resolved
+
+
+class _CallableHost(Host):
+    """A host whose answers are the functions it was given.
+
+    Each method delegates when it has a function for that question and falls
+    through to :class:`~szpontnet.host.Host`'s own answer when it does not - so
+    an omitted ``run_job`` still raises :class:`~szpontnet.host.NoRunner`, which
+    the dispatcher handles as the ordinary decline it is.
+    """
+
+    def __init__(self, **answers) -> None:
+        self._answers = {name: fn for name, fn in answers.items() if fn is not None}
+
+    def model(self) -> dict:
+        fn = self._answers.get("model")
+        return fn() if fn else super().model()
+
+    def state_dir(self) -> Path:
+        fn = self._answers.get("state_dir")
+        return fn() if fn else super().state_dir()
+
+    def log(self, action: str, detail: str) -> None:
+        fn = self._answers.get("log")
+        if fn:
+            fn(action, detail)
+
+    def run_job(self, prompt: str, done_path: str | None) -> str:
+        fn = self._answers.get("run_job")
+        return fn(prompt, done_path) if fn else super().run_job(prompt, done_path)
+
+    def work_already_running(self, work_key: str) -> bool:
+        fn = self._answers.get("work_already_running")
+        return bool(fn(work_key)) if fn else super().work_already_running(work_key)