cadrumo.application.provisioning_host module

Local model runtime host lifecycle: detect, start and install the runtime itself.

The model-level verbs in provisioning_runtime assume a runtime is already listening. This module owns the step before that, per platform:

  • Detect. Locate the runtime executable on PATH and in each platform’s standard install location, and ask the configured endpoint whether it answers.

  • Start. Spawn <runtime> serve detached when the endpoint is local, the executable is present and nothing answers yet. Starting an already running runtime is a successful no-op, so the verb is idempotent.

  • Install. Run the platform package manager – winget on Windows, Homebrew on macOS – only with explicit operator consent. Linux has no unprivileged installer: the upstream script needs root, so the operator runs it and this module reports the typed refusal.

Nothing here stops, signals or replaces a process Cadrumo did not spawn, and a remote endpoint is never started or installed on the operator’s behalf.

class RuntimeHostPlatform(*values)[source]

Bases: StrEnum

The operating-system families whose install and start paths differ.

WINDOWS
MACOS
LINUX
OTHER
class RuntimeInstaller(*values)[source]

Bases: StrEnum

The package manager an install would run, or none this host offers.

WINGET
HOMEBREW
NONE
current_runtime_platform(platform=None)[source]

Classify sys.platform (or the given value) into a runtime host platform.

Return type:

RuntimeHostPlatform

Parameters:

platform (str | None)

locate_runtime_executable(*, platform=None, env=None, which=<function which>)[source]

Return the runtime executable on PATH or in a standard location, or None.

The standard locations matter as much as PATH: an installer that has just finished updates the user’s PATH for new shells only, so the process that ran it would otherwise not find what it installed.

Return type:

Path | None

Parameters:
available_runtime_installer(*, platform=None, which=<function which>)[source]

Return the package manager this host can install the runtime with.

Return type:

RuntimeInstaller

Parameters:
runtime_endpoint_is_local(chat_url)[source]

Return whether the configured endpoint names this machine’s loopback interface.

Return type:

bool

Parameters:

chat_url (str)

read_runtime_version(settings=None)[source]

Return the runtime’s reported version, or None when nothing answers.

Return type:

str | None

Parameters:

settings (Settings | None)

class RuntimeHostStatus(**data)[source]

Bases: ProvisioningOutcome

Whether the local model runtime is installed, and whether it answers.

available is the reachability claim; everything else explains it. An installed runtime that does not answer is a start away from ready, and an absent one is an install away – the verdict names which.

Parameters:
platform: RuntimeHostPlatform
endpoint_url: str
endpoint_local: bool
executable_located: bool
reachable: bool
version: str | None
installer: RuntimeInstaller
available: bool
probe_runtime_host(settings=None, *, platform=None, which=<function which>)[source]

Detect the runtime installation and whether its endpoint answers. Never raises.

Return type:

RuntimeHostStatus

Parameters:
class RuntimeStartOutcome(**data)[source]

Bases: ProvisioningOutcome

The result of asking for a running runtime, including one already running.

Parameters:
running: bool
already_running: bool
started_pid: int | None
start_runtime(settings=None, *, spawn, timeout_s=None, which=<function which>)[source]

Make the configured local runtime answer, starting it only when it does not.

Idempotent: a runtime that already answers is reported running and nothing is spawned. A remote endpoint is refused rather than started, because a process on this machine cannot make another machine’s server answer.

Parameters:

  • settings (Settings | None) – Settings carrying the endpoint; loaded when omitted.

  • timeout_s (float | None) – How long to wait for a spawned runtime to answer.

  • spawn (TypeAliasType) – Starts <executable> serve detached and returns its process id.

  • which (TypeAliasType) – Executable lookup used to locate the runtime.

Return type:

RuntimeStartOutcome

Returns:

A RuntimeStartOutcome. Never raises.

class RuntimeInstallOutcome(**data)[source]

Bases: ProvisioningOutcome

The result of an install request, including one that needed no install.

Parameters:
installed: bool
already_installed: bool
installer: RuntimeInstaller
consented: bool
installer_exit_code: int | None
install_runtime(*, consent, run, platform=None, which=<function which>)[source]

Install the local runtime through the platform package manager, with consent.

Idempotent: an executable that is already present is reported installed and nothing runs, with or without consent. Without consent nothing is downloaded; the refusal names the installer that would run so the operator can decide.

Parameters:

  • consent (bool) – The operator’s explicit agreement to run the installer.

  • platform (RuntimeHostPlatform | None) – Host platform; detected when omitted.

  • which (TypeAliasType) – Executable lookup for the runtime and the package manager.

  • run (TypeAliasType) – Runs the install invocation and returns its exit code.

Return type:

RuntimeInstallOutcome

Returns:

A RuntimeInstallOutcome. Never raises.