Skip to content

SDK reference ​

hmz.sdk: the supported import path for programs that drive Humanize. It defines Hmz, Run, Client, Daemons and fakes; every other name is the object the runtime or the daemon layer holds, handed through unchanged. Its epics are run by a daemon, never in the calling process. Notation: Conventions.

python
from hmz.sdk import Hmz, Daemons, Refused, fakes

Module ​

python
__all__ = ["Accounts", "Client", "Daemon", "Daemons", "Epics", "Flows", "Flowverses", "Hmz", "Link",
           "NousBook", "Refused", "Run", "Runtimes", "fakes"]
def __getattr__(name: str) -> object: ...
NameKindDefined inSection
Hmzclasshmz.sdk.runningHmz
Runclasshmz.sdk.runningRun
Refusedexceptionhmz.runtimeRefused
Flowsclasshmz.runtimeFlows
Flowversesclasshmz.runtimeFlowverses
Accountsclasshmz.runtimeAccounts
Runtimesclasshmz.runtimeRuntimes
NousBookclasshmz.runtimeNousBook
Epicsclasshmz.runtimeEpics
Clientclasshmz.sdk.clientClient
Daemonsclasshmz.sdk.daemonsDaemons
Daemonfrozen dataclasshmz.daemonDaemon
Linkclasshmz.daemonLink
fakesmodulehmz.sdk.fakingfakes
Rule
LazyEach name is imported from its layer on first access (module __getattr__). import hmz.sdk imports nothing else.
Identityhmz.sdk.X is <layer>.X: the same class, not a wrapper. hmz.sdk.Hmz subclasses hmz.runtime.Hmz.
Unknown namesAttributeError: module 'hmz.sdk' has no attribute '<name>'.
fakesA module attribute: from hmz.sdk import fakes works; import hmz.sdk.fakes raises ModuleNotFoundError.
StabilityNames in __all__ are stable. Types they return that are not in __all__ (Line, Opened, Offer, Declaration, Provider, …, listed under Returned types) are internal: their fields are documented as they are.

Hmz ​

python
class Hmz:
    def __init__(self, workspace: str | os.PathLike[str] | None = None) -> None

One workspace and everything Humanize can be asked to do in it. The constructor loads nothing.

ParameterTypeDefaultMeaning
workspacestr | PathLike | NoneNoneThe project directory. None: the current directory, re-read at each use. Kept as given; ~ is not expanded.

Properties ​

PropertyTypeValue
workspacePathThe project directory.
homePath$HUMANIZE_HOME, else ~/.hmz (a ~/.humanize is moved there). Not created.
settingshmz.runtime.settings.SettingsWhat is remembered for this workspace and machine (Settings). Internal type.
flowsFlows
versesFlowversesThe same object as flows.verses.
accountsAccounts
runtimesRuntimes
nousNousBook
epicsEpicsOf this workspace.

workspace and home are computed on each access; the others are created on first access and cached on the instance.

Methods ​

MethodReturnsRaises
run(flow, task, *, …)RunRefused, OSError
runner(flow, *, …)RunnerRefused, OSError
read(argv)LineSystemExit
exec(argv)AnySystemExit, Refused, OSError, what the flow raised
backends()tuple[Profile, ...]—
reports()bool—
  • backends(): every coding-agent CLI Humanize drives, installed or not, as internal hmz.coganchor.backends.Profile objects (.name, .aliases, .efforts, .installs, …). [p.name for p in Hmz().backends()] is ['claude', 'agy', 'codex', 'dsh', 'grok', 'kimi', 'pi', 'omp', 'qwen', 'opencode', 'mimo', 'cursor-agent', 'mcode', 'litellm'].
  • reports(): starts error reporting where it has been answered yes (or HUMANIZE_SENTRY=on). Returns whether anything is being reported. Never asks.

Hmz.run ​

python
def run(
    self,
    flow: str | os.PathLike[str],
    task: str,
    *,
    agents: Mapping[str, str | AgentDriver] | Iterable[AgentSpec] = (),
    envs: Mapping[str, str | EnvDriver] | Iterable[EnvSpec] = (),
    params: Mapping[str, Any] | FlowParams | None = None,
    budget: Budget | Mapping[str, Any] | None = None,
    profile_flow: bool = False,
    profile_environment: bool = False,
    resume: bool | str | os.PathLike[str] = False,
    outworlder: OutworlderDriver | None = None,
) -> Run

Equivalent to Run(self.runner(flow, agents=…, envs=…, params=…, budget=…, profile_flow=…, profile_environment=…, resume=…), task, outworlder=outworlder). Nothing starts. Where each agent's harness runs is not a parameter: it is the harness setting of the runtime its work is on.

The epic is held by this machine's daemon, started where none runs, and outlives the program that asked for it. Where any role is given a driver object (a fakes.FakeAgentDriver, …), it is held instead by a private daemon of the calling program's own, as run_fake holds it.

ParameterAcceptsDefault
flowA -f ref or a path.—
taskThe task text.—
agents{role: spec} where spec is an -a spec without <role>= ("claude@work/claude-opus-5:high") or an AgentDriver (e.g. fakes.FakeAgentDriver); or an iterable of AgentSpec (Line.agents).()
envs{role: spec} with an -e spec without <role>=, or an EnvDriver; or an iterable of EnvSpec.()
paramsA mapping (strings read as -p reads them) or an instance of the flow's FlowParams. None: defaults.None
budgetA Budget, or a mapping validated by Budget.model_validate ({"cost": 5}, {"duration": 3600}, {"duration": "PT1H"}; "1h" is not accepted). None: refused.None
profile_flowWhether to profile the flow's own Python, as well as tracing the run; as --profile-flow.False
profile_environmentWhether to profile the programs the run's agents start, as well as tracing them; as --profile-environment.False
resumeFalse: from the top. True: the newest resumable epic of this flow here. A path: that epic.False
outworlderThe driver answering Outworlder roles (e.g. fakes.FakeOutworlder), from this process: the run claims each such role, sets away those its away_for says, and answers each question with what its run(text, None, role) returns. None: every role away, as under hmz exec.None

Raises OSError where the daemon cannot be reached, and Refused for everything hmz exec refuses at stage 3, in the same words, plus:

ConditionMessage
a role given twice across a mapping and specs<flow>: duplicate agent role '<role>' / … environment role …
an invalid budget mappingthe budget is invalid: <pydantic error>
a resume path with no journal entry<epic name> has no saved progress to resume from
python
from hmz.sdk import Hmz, Refused

try:
    Hmz().run("goal", "fix the build", agents={"worker": "pi/gpt-5.5:high"}, budget={"cost": 5})
except Refused as why:
    print(why)   # goal: 'worker' needs GoalCommandAgentMixin, which pi does not support

Hmz.runner ​

python
def runner(self, flow, *, agents=(), envs=(), params=None, budget=None, profile_flow=False,
           profile_environment=False, resume=False) -> Runner

Parameters and refusals as run, without task and outworlder. Asks the daemon that is to hold the epic to check it (flows.check), and returns the internal hmz.sdk.running.Runner: what epic.start will be called with, and what the check answered. Nothing is started, and no CLI or machine is reached.

Hmz.read ​

python
def read(self, argv: list[str]) -> Line

Parses an hmz exec argument list (without exec) to a Line. Loads no flow. A line argparse rejects, or an -a/-e/-p that does not parse, prints usage and the error to stderr and raises SystemExit(2); --help prints help and raises SystemExit(0).

python
hmz = Hmz()
line = hmz.read(["-f", "ralph_loop", "-a", "agent=claude/claude-opus-5:high",
                 "-p", "budget.duration=6h,budget.cost=50", "fix the build"])
run = hmz.run(line.flow, line.task, agents=line.agents, envs=line.envs,
              params=line.params, budget=line.budget, profile_flow=line.profile_flow,
              profile_environment=line.profile_environment, resume=line.resume)

Hmz.exec ​

python
def exec(self, argv: list[str]) -> Any

read(argv), then run(…), then Run.run(). Returns what the flow returned, as the ended record says it. Raises OSError where the daemon cannot be reached. Unlike the hmz exec command it draws nothing, installs no signal handlers and does not convert Refused or BudgetExceeded into an exit status.

Run ​

python
class Run:
    def __init__(self, runner: Runner, task: str, *,
                 outworlder: OutworlderDriver | None = None) -> None

One epic, held by a daemon on a new exec slot (exec:<hex>) of the workspace and followed by a subscription of a Client of its own. Made by Hmz.run. Constructing one starts nothing. If its session ends before the ended record, the run attaches again where it left off; where it cannot, it ends with RuntimeError("the daemon went away"). Once the epic has ended it stays attached, on a thread of its own, while backed of runs.get says a backup is not done, so that its host waits for the backups too, for at most 60 seconds or until close().

Properties ​

PropertyTypeValue
flowstrThe flow as named.
refstrIts canonical ref (rlar:rlar, humanize1:rlcr).
taskstr
declarationdictWhat the flow declares: the declared mapping the daemon's check answered.
budgetBudgetWhat the run may spend.
profile_flow, profile_environmentboolWhether the run's flow, and the programs its agents start, are profiled as well as traced.
usagehmz.flows.UsageSpent so far, as the latest usage record says: duration: timedelta, cost: float, output_tokens: int.
agentstuple[Opened, ...]Each open session, oldest first, as its opened record said it.
epicPath | NoneThe epic directory, once the daemon names it.
runningboolWhether it is going: from start() until its ended record.
raisedBaseException | NoneOnce over: asyncio.CancelledError (stopped), BudgetExceeded (budget), Refused (refused), RuntimeError(why) (failed or crashed), else None. On a private daemon, the very exception the flow raised.
resultAnyOnce over: the result of the ended record (JSON). On a private daemon, the very object the flow returned.

Methods ​

MethodReturnsBehaviour
run()Anystart(), then waits for the ended record; returns result or raises raised.
start()NoneAttaches to a new exec slot of the workspace, sets every role away (or, with an outworlder, claims its roles), and starts the epic (epic.start); returns at once. Refused if epic.start is refused; OSError if the daemon cannot be reached; RuntimeError if already started.
wait(timeout: float | None = None)boolBlocks until the ended record comes or timeout seconds pass; returns whether it came.
stop()NoneStops the epic (epic.stop); every flow call raises CancelledError where it stands. Thread-safe. Does not wait.
close()Nonestop(), then forces the epic (epic.force) where it has not ended, and lets go of the daemon.
unreadable()strThe budget cap nothing driven can enforce, in words (the hmz exec note), or "", as the daemon's check answered it.
watch(listener)NoneRegisters listener(agent: str, session: str | None, event: dict), called with the agent's name, its session's key, and the event record, for every event of every session, from the client's thread.
noticed(callback)NoneRegisters callback(text: str), called with every notice record: Humanize's own word about the run, such as an environment moved down its runtime's fallback list (docker:a cannot hold 'box': <why>; using docker:b).
printed(callback)NoneRegisters callback(text: str), called with every line the host printed while it held the epic (printed records).
opened(callback)NoneRegisters callback(role: str, opened: Opened), called as each opened record comes, before any event of that session.

Opened (hmz.sdk.running, frozen dataclass): key (<agent>/<n>), role, agent, cli, model, person: bool, env: dict \| None, harness. Records: Daemon.

Refused ​

python
class Refused(ValueError):
    def __init__(self, message: str, *, code: int = 0, data: dict | None = None) -> None
    code: int
    data: dict[str, Any]

A run, or a request to a daemon or host, refused before anything of it ran. str(error) is the message hmz exec prints after hmz exec: error: , and the reason a host gives every frontend. code is the daemon's error code (409 for a host's refusal, 503 once a Client's session has ended, 0 for a refusal made in the calling process); data is the error's further fields, or {}. __cause__ is the underlying exception where there was one (FlowException, SpecError, pydantic.ValidationError).

Flows ​

Hmz().flows. Constructor: Flows().

MemberReturnsBehaviour
versesFlowversesProperty.
all()list[Offer]Every runnable flow, in offer order.
find(named: str)strThe resolved file of a flow, or "" where nothing resolves. A path starts with ., / or ~; anything else is a name, never a file of that name in the working directory.
about(named: str)strThe flow's one-line description, or "".
declared(named: str | PathLike)DeclarationA str as -f reads it; a PathLike always a path, ./'d where it is relative. Imports the flow. Raises the flow API's FlowException for a flow that cannot load.
resumes(named: str | PathLike)boolWhether it is resumable. Imports the flow.
fork(named: str, into: str | PathLike | None = None)strCopies the flow, what it imports and its skills into ./.hmz/flows/ (or into), as Copy here does in /flow; not an installed flow's .installed.json. Returns the directory. ValueError: not a flow, or already a copy here. OSError: cannot copy.
running()tuple[LiveCall, ...]Every flow call in progress in this process, oldest first.
python
for offer in Hmz().flows.all():
    print(offer.name, "·", offer.about)

Flowverses ​

Hmz().verses: the store /flow's Flowverses page edits. flow arguments are the name a flow is offered under: <flow> or <user>/<flow> for official's, @<flowverse>/<flow> or @<flowverse>/<user>/<flow> for another's. index() takes a flowverse's bare name, and its methods a flow by index name (<flow>, <user>/<flow>). Semantics: Flows › Flowverses.

MethodReturnsBehaviour
all()list[Flowverse]Offer order: official, added ones alphabetically, local, user.
nearest()list[Flowverse]Lookup order for a bare name: local, user, official, added ones.
find(name: str)Flowverse | None
add(url: str, name: str = "")FlowverseClones the index at url (a URL, a path, or owner/repo on GitHub) under name (default: the repository's name). Installs nothing. ValueError: name taken, reserved (official, local, user) or not a valid directory name. OSError: clone failed.
fetch(name: str)FlowverseFetches the index again, or for the first time; resets the clone to the remote. Installed flows are untouched. ValueError: no such name, or local/user. OSError: git failed.
remove(name: str)boolDeletes the index and every flow installed from it; whether there was one. ValueError: official, local, user.
index(name: str)IndexWhat its index lists, as last fetched. Reads YAML only; empty for local, user, an unfetched one or an unknown name.
install(flow: str, version: str = "")list[Installed]Installs that release ("": the newest that is not a prerelease, else the newest prerelease) and what it needs. Returns what is now installed of every flow the install came to, the asked-for one last. Another version of an installed flow switches it. ValueError: no such flowverse, flow or release; unfetched; a cycle; a range nothing satisfies; breaking another installed flow's range. OSError: fetch or copy failed.
uninstall(flow: str)boolRemoves an installed flow; whether there was one. ValueError: another installed flow needs it. OSError: it will not go.
installed()list[Installed]Every installed flow, by flowverse and then name.
updates()list[Update]Every installed flow whose index, as last fetched, lists a newer release.
holds(one: Flowverse)list[Offer]What it offers to run: built-in and installed flows for official, installed ones for another, the directory's for local and user. Imports every flow in it. Never a flow its index only lists.
edited(one: Flowverse)boolWhether the clone holds changes a fetch would discard. False for a non-clone.
standing(one: Flowverse)strThe clone's commit, or "".
where(name: str)PathIts index's directory, fetched or not.
plain(url: str)strurl with credentials removed.
whence(one: Flowverse, nowhere: str = "-")strDisplayable origin: the credential-free URL; your own flows in .hmz/flows for local, your own flows in ~/.hmz/flows for user; nowhere for a directory with no readable origin.
python
from hmz.sdk import Hmz

verses = Hmz().verses
verses.fetch("official")
for release in verses.index("official").versions("flame_chasoid"):
    print(release.version, release.commit[:12])
verses.install("flame_chasoid")
for update in verses.updates():
    print(update.installed.called, update.installed.version, "->", update.version)

Accounts ​

Hmz().accounts: provider accounts. cli accepts any name or alias of a backend. An account name of "" is the machine's own login (as local).

MethodReturnsBehaviour
all(cli: str = "")list[Provider]Every account, or one backend's; by backend, then name.
find(cli: str, name: str)Provider | None
ways(cli: str)tuple[Way, ...]How the backend can be signed into, in offer order (for claude: login, console, token, key, wif, anthropic-gateway, bedrock-gateway, vertex-gateway, bedrock, bedrock-key, mantle, vertex, foundry, aws, google-cloud, env).
way(cli: str, name: str)Way | None
asks(way: Way, given: Mapping[str, str])list[str]Variables still unanswered.
make(cli, name, way: Way, answers=None)ProviderWrites an account from a way's answers; makes its directory. ValueError: bad backend or name. OSError.
sign_in(provider, way, answers=None)intRuns the backend's sign-in command under the account's paths; its exit status.
write(cli, name, way="", env=None, args=())ProviderWrites an account as given, replacing env/args, keeping credentials. With args empty, a named way that adds arguments (codex's openai-gateway) has them filled from env. ValueError, OSError.
where(cli, name)PathIts credentials directory. ValueError: unknown backend or invalid name.
serves(one: Provider)tuple[str, ...]Other backends its credentials could run.
copies(one, cli, name="")ProviderWrites the same account for another backend. ValueError: that backend cannot use it.
remove(cli, name)boolDeletes an account and its credentials. ValueError for "".
env(said: str)dict[str, str]Parses NAME=VALUE lines.
environ(provider: Provider | None)dict[str, str]The environment a turn under it gets; {} for None.
models(cli, provider="")tuple[Model, ...]What the backend last reported it runs as this account; () if never asked.
asked(cli, provider="")strWhen that was, or "".
stale(cli, provider="")boolNever asked, or asked longer ago than hmz.coganchor.models.STALE (one week).
ask(cli, provider="", seconds=None)tuple[Model, ...]Starts the backend to list its models, and keeps the answer. () if it does not answer.

Runtimes ​

Hmz().runtimes: saved runtimes, named by -e <role>=ssh@<name> and -e <role>=docker@<name>. backend is "ssh" or "docker".

MethodReturnsBehaviour
all(backend: str = "")list[Runtime]By backend, then name.
find(backend, name)Runtime | None
where(backend, name)PathWhere it is kept. ValueError: bad backend or name.
new(backend, name, **fields)RuntimeBuilds and validates one; saves nothing. ValueError: unknown field or bad value. new(**p.held()) equals p. harness="docker:gpubox" (default "env"; also "local") sets where the harness of work on it runs (Remote execution › The harness setting).
add(runtime)RuntimeSaves a new one. ValueError: name taken. OSError.
write(runtime)RuntimeSaves, replacing any of that name. OSError.
remove(backend, name)boolValueError: bad backend or name.
hosts(config: str | PathLike | None = None)list[SSHHost]Every Host in an ssh config (default ~/.ssh/config), as ssh -G resolves it. OSError: no ssh, unreadable config.
import_ssh(config=None, names=None, *, update=False)list[SSHRuntime]Saves one ssh runtime per Host (or per name in names), named after it; existing ones kept unless update. ValueError: a name not in the config.
resolve(runtime: SSHRuntime)SSHHostWhat ssh -G makes of it; reaches nothing.
check(runtime, seconds: float = 30.0)CheckedReaches it: an ssh host for home, CPUs, memory, GPUs; a docker daemon via docker info. Never raises.

NousBook ​

Hmz().nous: every nous, concrete (<cli>[@<account>]/<model>[:<effort>]) or virtual (a name standing for a graph). Each has tries, policy, timeout and a then graph; a virtual one also has its graph. Values are Nous(name, tries, policy, timeout, graph, then), Graph(start, nodes) and Node(id, use, balance, among, spread, on) from hmz.coganchor.nous.

MemberReturnsBehaviour
defaultstrProperty: "exponential-jitter".
policies()tuple[Policy, ...]none, constant, linear, exponential, exponential-jitter, fibonacci.
named(policy: str)Policy | None
strategies()tuple[Strategy, ...]shuffle, round-robin, least-busy, latency, usage, cost, then those added.
strategy(name, about, picks)StrategyAdds one for this process: picks(members: Sequence[Member]) -> str, each Member holding name, weight, busy, latency, tokens, price, cooling. ValueError for a built-in name.
faults()tuple[str, ...]What an edge may be named after: every fault class, then *.
spec(backend, model, provider="", effort="")strspec("codex", "gpt-5.6-sol", "work", "high") → "codex@work/gpt-5.6-sol:high".
reads(said: str)strThe canonical spelling of a concrete nous, a virtual one's name, or "".
all()list[Nous]Every nous, in the order written.
rule(said)NousWhat is written under said, else under said without its effort, else an empty Nous.
graph(said)Graph | NoneReads a nous, a list of nous, or {start, nodes} (nodes a mapping by id or a list of nodes with id). TypeError for anything else.
shown(graph)dict | NoneThe graph as nous.list carries it.
write(name, *, tries=0, policy="", timeout=0.0, graph=None, then=None)NousWrites a nous whole; graph and then in any shape graph() reads. ValueError, TypeError.
put(nous: Nous)NousThe same, from a Nous.
check(nous, among=None)NousWhat put would write beside among (default: every nous written), writing nothing. ValueError as put.
checked(name, graph)GraphThe same for one graph of the nous name.
then(said, to)NousSets then: a Graph, a list of nous (a single string is one), or None. ValueError.
retrying(said, tries, policy, timeout)NousSets extra tries (0 none), the wait policy, and the limit in seconds (0 none). ValueError.
renamed(said, name)NousRenames a virtual nous, in every graph naming it too. ValueError.
entry(said)strThe concrete nous a walk of said starts at: where an agent at a virtual nous is built.
clear(said)boolRemoves the nous. ValueError for a virtual one another nous names.

Epics ​

Hmz().epics, or Epics(workspace=None). A run is named by its epic directory.

MethodReturnsBehaviour
under()PathThis workspace's epics directory.
all()list[Path]Every epic, oldest first.
read(epic: Path)Ran | NoneNone for a directory holding no run.
sessions(epic)list[Session]Every session, across every record of the epic.
opened(epic)dict[str, list[str]]Session ids per agent, by its name.
resumed(flow: str)Path | NoneThe epic --resume would pick up. flow: canonical ref or name as run.
picks_up(epic)boolWhether its journal has an entry, it is not going, and it is not foreign.
foreign(epic)strWhy an imported run cannot be picked up here (its workspace is not at that path, or lacks the commit its bundle recorded), or "".
state(epic, flow: str = "")dict[str, Any]A resumable flow's kept ctx.state: the run's own flow, or another by canonical ref.
traced(epic, *, output=None, start=None, end=None)tuple[Path, dict]Gathers the run's own sessions into a Chrome trace. Default output: the epic's traces/, named for the moment. start/end: any wording dateparser reads. Tracing.
trace(*, sessions=None, agents=None, output=None, start=None, end=None, profile=None, flow_profile=None, kept=None)dictThe same collector for any sessions. sessions=None: every session of the workspace; empty iterable: none. kept: directories of kept sessions to read (default: everywhere Humanize keeps them).
transcripts(epic)list[dict]What each session of the run said and did, read back out of its logs: per session that did anything, key (<cli>:<id>), agent and actions -- each category, name, at, start, seconds and args -- in order. Writes nothing.
timeline(epic)TimelineThe run as an Exomyth timeline: .document, and .span(id) for one span whole. Writes nothing.
bundled(epic, *, output, transcript=None)tuple[Path, dict]One .hmzepic of the whole run, credentials struck out. output (required): a file, or a directory to put it in. Returns the path and its manifest. Exporting a run.
imported(archive)PathReads a .hmzepic back in as an epic of the workspace it ran in, wherever that is. ValueError for anything else, an unsafe member, or an epic already here. Importing a run.

Client ​

python
class Client:
    @classmethod
    def local(cls, *, name: str = "", kind: str = "sdk") -> Client
    def call(self, method: str, params: Mapping[str, Any] | None = None, *,
             idem: str | None = None, seconds: float | None = None) -> Any
    def heard(self, listener: Callable[[str, dict[str, Any]], None]) -> None
    def close(self) -> None
    def __enter__(self) -> Self
    def __exit__(self, *exc) -> None      # close()
    daemon_id: str
    version: str
    protocol: str
    capabilities: tuple[str, ...]
    device: str

One session of the wire protocol with one daemon, for a program that wants the methods themselves. What Run follows its epic with.

MemberBehaviour
local(name="", kind="sdk")A session with this machine's daemon over its unix socket, the daemon started where none runs. OSError: it cannot be reached or started, or speaks another protocol.
call(method, params=None, *, idem=None, seconds=None)Makes one call (a method protocol/openrpc.json lists) and waits for its result. idem, where given, is added to params as the write's idempotency key. Raises Refused with the error's message, code and data, or with code 503 (the daemon went away) once the session has ended; TimeoutError("no answer to '<method>' in <s>s"), the call then cancelled.
heard(listener)Hands every notification, those already waiting first, to listener(method, params) on a thread of the client's own, in order; what it raises is let go. RuntimeError if a listener is already set.
close()Ends the session and every subscription of it; every epic goes on. Idempotent.
closedProperty: whether the session has ended.
daemon_id, version, protocol, capabilities, deviceWhat session.hello answered.
python
from hmz.sdk import Client

with Client.local(name="ci") as client:
    print(client.call("hosts.list"))

Daemons ​

python
class Daemons:
    def here(self, workspace: str | os.PathLike[str] | None = None) -> Daemon | None
    def all(self) -> list[Daemon]
    def host(self, workspace: str | os.PathLike[str] | None = None) -> Daemon
MethodSame asBehaviour
here(workspace=None)hmz.daemon.runningThe host holding that workspace's runs, or None (no daemon answers on this machine's socket, or it holds no host of that workspace).
all()hmz.daemon.daemonsEvery live workspace's host on this machine, oldest first.
host(workspace=None)hmz.daemon.hostThe host of the workspace, started where none is -- and this machine's daemon with it (10 s each to come up). OSError: an older Humanize's daemon is running, or none came up.

workspace=None is the current directory.

Daemon ​

python
@dataclass(frozen=True, slots=True)
class Daemon:
    at: Path            # this machine's daemon's directory (socket, daemon.json)
    workspace: str      # the project directory its host holds runs for
    pid: int            # the host process
    started: str        # UTC, ISO 8601
    protocol: int = 0   # the frontend protocol the daemon speaks; 0 = an older Humanize's
MemberReturnsBehaviour
aliveboolProperty: the process exists.
link(name="", kind="sdk", *, replay=True)LinkAttaches a frontend. OSError: nothing accepts the connection, or hello is refused or not answered within 10 s. protocol is not checked here (host() and hmz check it).
status()dictStatus keys; from these fields for a host that does not answer.
detach()intLets every frontend go; runs continue. Returns how many.
stop(*, seconds=20.0)boolAsks the host to close its runs and exit; waits up to seconds. Whether it has gone.
kill(*, seconds=20.0)boolSIGTERM to the host process, then SIGKILL; the daemon and other workspaces' hosts go on. Whether it has gone.
asked(said: dict)dictSends one control request; {} where no answer came.
python
class Link:
    client: str
    def told(self, message: dict[str, Any]) -> None
    def heard(self, listener: Callable[[dict[str, Any]], None]) -> None
    def __iter__(self) -> Iterator[dict[str, Any]]
    def asked(self, said: Mapping[str, Any], *, seconds: float | None = None) -> dict[str, Any]
    def start(self, flow: str | os.PathLike[str], task: str, *,
              agents: Mapping[str, Any] | None = None, envs: Mapping[str, Any] | None = None,
              params: Any = None, budget: Any = None, profile_flow: bool = False,
              profile_environment: bool = False, resume: bool | str | os.PathLike[str] = False) -> dict[str, Any]
    def say(self, text: str, *, to: str = "") -> dict[str, Any]
    def answer(self, question: str, text: str) -> dict[str, Any]
    def stop(self) -> dict[str, Any]
    def force(self) -> dict[str, Any]
    def afk(self, *, on: bool, role: str = "") -> dict[str, Any]
    def claim(self, role: str, *, take: bool = False) -> dict[str, Any]
    def release(self, role: str) -> dict[str, Any]
    def board(self, key: str, value: str) -> dict[str, Any]
    def aside(self, **said: Any) -> dict[str, Any]
    def close(self) -> None
    def __enter__(self) -> Self
    def __exit__(self, *exc) -> None      # close()

One frontend of a workspace's host, over this machine's daemon. Obtained from Daemon.link.

MemberBehaviour
clientThis frontend's client id; owner and client fields in messages use it.
told(message)Called by the transport to deliver a message. Not for callers.
heard(listener)Delivers every message, already-queued ones first, to listener on a thread of the link's own, in order. RuntimeError if a listener is already set.
__iter__Yields every message in order until gone or close(). RuntimeError if a listener is set.
asked(said, *, seconds=None)Sends one request and waits (seconds=None: indefinitely). Returns the reply (ok: true). Raises Refused with the reply's why, or TimeoutError("no answer to '<do>' in <s>s").
start(…)start request. agents/envs: specs as -a/-e after <role>=. params, budget: mappings or models (serialised). profile_flow, profile_environment: whether the run's flow, and the programs its agents start, are profiled. Reply carries run.
say, answer, stop, force, afk, claim, release, board, asideThe request of the same name.
close()Lets go of the host; runs continue.

Every method that sends a request goes through asked and raises Refused when refused, including after the host has gone (the reason is then the gone reason). Link has no helpers for the unaside, status, detach and quit requests: send them with asked({"do": …}). Transport behaviour is in Daemon › Link.

python
from hmz.sdk import Daemons

with (Daemons().here() or Daemons().host()).link(name="ci", replay=False) as link:
    link.claim("reviewer")
    for said in link:
        if said["type"] == "pending":
            for asked in said["pending"]:
                if asked["owner"] == link.client:
                    link.answer(asked["question"], "looks good")

fakes ​

hmz.sdk.faking: the drivers of hmz.runtime.flowing.fakes, handed through, and run_fake. __all__:

NameIs
run_fake(flow, task="", *, agents=None, envs=None, params=None, budget=None, outworlder=None, local=None, journal=None, resume=False)Runs a flow on fakes through a private daemon; returns or raises the very object the flow returned or raised.
FakeAgentDriver(harness=HarnessKind.CLAUDE, *, reply=None, model="fake", effort="", provider="", capabilities=None, cost=0.0, output_tokens=1, seconds=0.0, forks=None, names_late=False)A scripted agent driver. Also accepted by Hmz.run(agents=…), which then runs the epic on a private daemon.
FakeSessionA session of a FakeAgentDriver.
FakeEnvDriver(files=None, *, workdir="/work", backend=EnvBackendKind.LOCAL, provider="", capabilities=None, cpu_count=8, memory=64 GiB, gpu_count=0, gpu_memory=0, run=None, refs=("HEAD", "main"), repo=True)An in-memory environment.
FakeOutworlder(reply=None, *, away=False)An outworlder answering from a script.
Answer, Command, Handler, ReplyType aliases for the scripts above.

Driver objects cannot be handed to another process, so an epic given any (run_fake, or Hmz.run with a driver for a role) is held by a private daemon the calling program starts in its own process, reached over a socket pair. Its hosts run in that process too, so a fake's prompts and the rest are filled in; each driver is named to it as fake:<key>. It has a temporary home and machine directory of its own (with a copy of the settings file; private daemons going at once in one process share them, as the environment that names them is the process's), never touches this machine's daemon, and is torn down when run_fake returns or raises, or the Run has ended -- the epic written in its home with it, so Hmz().epics never lists a run on fakes. The home and machine directory are named by the process's environment, so private daemons running at once in one process (say, asyncio.gather over two run_fake) share them, and they are removed when the last of those is torn down.

Semantics: Flows › Testing a flow.

Returned types ​

Internal types returned by the classes above. Named tuples and frozen dataclasses; fields in declaration order.

Line ​

hmz.runtime.runner.Line (named tuple), from Hmz.read.

FieldTypeDefaultFrom
flowstr—-f
taskstr—task
agentstuple[AgentSpec, ...]()every -a, in order
envstuple[EnvSpec, ...]()every -e, in order
paramsdict[str, str]{}every -p but budget.*, values unparsed
budgetBudget | NoneNoneevery -p budget.<limit>=, parsed
profile_flowboolFalse--profile-flow
profile_environmentboolFalse--profile-environment
resumeboolFalse--resume
as_jsonboolFalse--json

AgentSpec, EnvSpec ​

hmz.runtime.flowing.specs, frozen dataclasses. str() writes each back as its flag takes it.

TypeFields
AgentSpecrole: str, harness: HarnessKind (ACP for an ACP CLI), provider: str ("" = as local), model: str, effort: str ("" = auto), cli: str
EnvSpecrole: str, backend: EnvBackendKind, provider: str (a saved runtime's name, an ssh host nobody saved in its brackets, "[me@box:22]", or "" for this machine), workdir: PurePosixPath (~/… relative to home)

Flow types ​

TypeFields
Offerwhose: str (a flowverse, local or user), name: str (what -f takes: aot, alice/kernel, @theirs/review, @local/x), about: str
Declarationname, ref, description: str | None, hidden: bool, resumable: bool, agents: tuple[AgentRole, ...], envs: tuple[EnvRole, ...], params: type[FlowParams]; methods agent(name), env(name) → role or None
AgentRolename, declared: type, required: bool, auto: bool (runtime-filled), harness: HarnessKind | None, capabilities: frozenset[type], permission, skills: tuple[str, ...], grant
EnvRolename, declared: type, required, auto, capabilities, cpu_count: int, memory: int, gpu_count: int, gpu_memory: int, image: str, grant, resources: bool
LiveCallref, name, depth: int (1 = the run's flow), since: float (monotonic), id: int (journal id, 0 = none), parent: LiveCall | None, task: str, resumable: bool
Flowversename, url ("" for local, user), at: Path, fetched: bool, fixed: bool (official, local, user)

Flowverse types ​

hmz.runtime.flowing.index; all but Skipped are also exported from hmz.runtime.flowing.

TypeFields
Index (named tuple)verse: str, releases: tuple[Release, ...] (by index name, newest first), skipped: tuple[Skipped, ...]; methods flows() (index names, aot and alice/kernel, sorted), versions(flow) (newest first), release(flow, version) → Release | None, newest(flow, spec="") → the newest in range that is not a prerelease, else the newest prerelease, else None
Release (pydantic, frozen)name, version, description, repo, ref, commit, subdir, license, dependencies: dict[str, str], owner (the <user> it is listed under, "" bare); properties listed (its index name), owned (its repository's GitHub owner, or ""), semver (a semver.Version), url (what git fetches)
Skipped (named tuple)at: Path (the manifest, or a <user> directory), why: str
Installed (pydantic, frozen)verse, name, version, commit, repo, ref, subdir, dependencies, owner; properties listed (its index name), called (the name it is offered under), at: Path (its directory)
Update (named tuple)installed: Installed, version: str (the newest after it)

Account types ​

TypeFields
Providercli, name, way: str = "env", env: Mapping[str, str], args: tuple[str, ...], made: str; property at: Path; methods held(), command(argv), swaps()
Wayname, about, argv: tuple[str, ...] (sign-in command), asks: tuple[Asked, ...], sets: tuple[tuple[str, str], ...], args: tuple[str, ...], stdin: str
Modelname, efforts: tuple[str, ...] (hardest first), swarms: bool = False
Fallsspec, to: tuple[str, ...] (() = nowhere), tries: int = 0, policy: str = "exponential-jitter", timeout: float = 0.0; method says()
Policyname, about

Environment types ​

TypeFields
SSHRuntimename, host, user, port: int = 0, identity_file, proxy_jump, options: Mapping[str, str], alias, config, workdir, made: str = "typed" (typed/imported); property at; methods destination(), login(), settings(), target() (coganchor target), held(); backend == "ssh"
DockerRuntimename, endpoint: str = "local", tls_dir, container, exec_user, exec_env: tuple[str, ...], exec_wrapper: tuple[str, ...], image, runtime, run_args: tuple[str, ...], name_prefix, cpus: float, memory: int (bytes), gpus: tuple[str, ...], gpu_memory: int, max_containers: int (0 = no limit), workdir, made; property at; methods daemon() → Endpoint (Machines), exec_options(), held(); backend == "docker"
SSHHostalias, host, user, port: int, identity_files: tuple[str, ...], proxy_jump
Checkedreached: bool, said: str, home: str, cpus: float, memory: int, gpus: tuple[str, ...], gpu_memory: int, runtimes: tuple[str, ...], version: str, short: tuple[str, ...] (what it is saved to hand out and has not got)

Epic types ​

hmz.runtime.epic, named tuples. Values as the epic record wrote them.

TypeFields
Ranat: Path, flow, task, workspace, began, ended ("" while running or abandoned), how (done, failed, stopped, or ""), agents: tuple[Drove, ...], sessions: tuple[Session, ...], called: tuple[Called, ...], resumable: bool, ref, envs: tuple[str, ...] (as -e spells them, a run's kept in an older spelling included), params: dict, budget: dict | None, picked_up: str (epic name or ""), profile_flow: bool, profile_environment: bool (whether its flow, and the programs its agents started, were profiled); property name
Droveagent (the role), backend, model, effort ("" = auto), provider ("" = as local), name (what the agent filling it is called; "" in an epic written before agents had names); property spec (-a spelling after <role>=)
Calledflow, task, record (file in the epic), began, ended, how, calls: tuple[Called, ...]
Sessionagent, backend, provider (local = as local), ident (backend's id), name, at, flow, parent (forked-from id or ""), record, where (kept-session path), harness (local, env, the <backend>:<name> of a runtime a harness setting named, or "" for work on this machine)

Released under the Apache-2.0 licence.