Skip to content

Setup, system and jobs

Opening a data folder, checking and installing dependencies, the machine's specs and GPU, background jobs, cleanup and the panic stop, and the dashboard.

_core

Pieces every SDK area uses: the data folder, the base Handle class, background jobs, printing and the route map.

Conventions for SDK modules (one per area, mirroring llmdyno/services): * talk to LLMDyno only through call("area.function", **kwargs), never through the database or engine modules; * mark each public function or method with @covers("METHOD /api/path") for every web API route it gives access to, so tests/test_parity.py can prove the library can do everything the web app does; * never give a public name the name of a llmdyno submodule (jobs, profiles, benchmarks, judge, config, …): the package exports these names lazily and a submodule import would replace them.

Handle

Handle(data: dict[str, Any] | str)

Base of the SDK's objects (Profile, Plan, Job, …): an id plus the latest data LLMDyno returned for it.

h["field"] and h.get("field") read that data, to_dict() copies it, refresh() fetches it again. Two handles are equal when they are the same kind of thing with the same id.

refresh

refresh() -> Self

Fetch the latest data; returns self.

to_dict

to_dict() -> dict[str, Any]

Everything LLMDyno knows about this object, as a plain dict (a copy).

Job

Job(data: dict[str, Any] | str)

Bases: Handle

A background task: a download, image build, plan, review or import. Most SDK calls wait for their job; the ones with wait=False return it so you can follow it yourself.

status property

status: str

queued, running, done, failed, cancelled or paused (fetched fresh).

progress property

progress: float | None

0-1 when the job reports it (fetched fresh).

log property

log: str

The tail of the job's log (fetched fresh).

cancel

cancel() -> None

Stop the job (a download keeps what it has, a plan keeps finished runs).

wait

wait(quiet: bool = False, verbose: bool = False, every_s: float = 2.0) -> dict[str, Any]

Block until the job ends, printing its progress, and return its result. Ctrl+C cancels the job; a failed or cancelled job raises LLMDynoError.

drain

drain(timeout_s: float = 120) -> None

Wait (quietly) for a cancelled job to actually stop.

covers

covers(*routes: str) -> Callable[[F], F]

Declare that the decorated SDK function, method or property gives access to these web API routes, written as "GET /api/runs/{rid}" (the path exactly as the server declares it).

init

init(data_dir: str | Path | None = None) -> Path

Open (and create if needed) a data folder. Optional: without it LLMDyno uses LLMDYNO_DATA or the default folder (./data in a git checkout, otherwise %LOCALAPPDATA%\LLMDyno, ~/Library/Application Support/LLMDyno or ~/.local/share/llmdyno). Call it again with another folder to switch.

data_dir

data_dir() -> Path

The data folder in use (models, runs, database, keys).

job

job(job_id: str) -> Job

A background job by id.

system

System: dependency checks and setup, specs, GPU, jobs, cleanup and the panic stop.

Doctor

Bases: list[dict[str, Any]]

The Setup page's checks as a list of dicts; prints as a table. ok is True when nothing required is missing.

doctor

doctor() -> Doctor

System and dependency checks (Docker, images, llama.cpp, harnesses, SWE-bench harness, …).

setup

setup(harnesses: Union[str, Sequence[str]] = ('pi',), *, quality: bool = True, llama_cpp: Union[bool, str] = True, swebench: bool = False, polyglot: bool = False, quiet: bool = False, verbose: bool = False) -> Doctor

Install what benchmarks need, skipping what is already there: the sandbox image, the code-quality image, harness images, a llama.cpp build for this machine (True picks the best one; or pass a variant such as "cuda-13", "metal", "vulkan", "cpu"), and optionally the SWE-bench harness and the polyglot toolchain image. These download several GB the first time. Docker must be running.

specs

specs(refresh: bool = False) -> dict[str, Any]

This machine: CPU and instruction sets, RAM, GPUs with VRAM and driver, disk, OS and Docker (what the Overview page shows). refresh=True detects again instead of using the cached result.

gpu_usage

gpu_usage() -> list[Any]

Live GPU readings: utilisation, VRAM used and free, temperature and power for each GPU.

active_work

active_work() -> dict[str, Any]

What panic() would stop right now: running jobs, plans, containers and the llama-server.

panic

panic() -> dict[str, Any]

Stop everything at once (the red button): cancels every job and plan, kills LLMDyno's containers and the llama-server. Finished runs are kept. Returns what was stopped.

cleanup

cleanup() -> int

Remove sandbox containers left behind by crashed or interrupted runs; returns how many were removed.

list_jobs

list_jobs(active: bool = False, kind: str | None = None, limit: int = 100) -> list[Any]

Background jobs, newest first (downloads, builds, plans, reviews, imports). active=True keeps the queued and running ones; kind filters by type ("download", "build", "plan", "judge", "import", "install", …).

clear_jobs

clear_jobs() -> int

Forget finished jobs (done, failed, cancelled, interrupted); returns how many were removed.

start_docker

start_docker() -> str

Start Docker Desktop (Windows and macOS); it takes about a minute to come up.

repair_docker

repair_docker() -> str

Restart Docker Desktop after moving aside stale sockets that keep it from starting (a known Windows issue).

install_docker

install_docker(quiet: bool = False) -> dict[str, Any]

Download and run the Docker Desktop installer (Windows and macOS; Linux uses the distribution's packages).

use_llama_cpp

use_llama_cpp(path: str) -> dict[str, Any]

Use a llama.cpp build you already have (the folder holding llama-server) instead of installing one.

ui

The web dashboard: start it on this data folder, or open a page of it.

serve

serve(port: int | None = None, *, open_browser: bool = True, block: bool = True) -> str

Start the dashboard on this data folder. block=False runs it in a background thread (handy in notebooks).