biolm.protocols

When to use which

• biolm protocol validate — quick YAML checks against the JSON schema

• biolm protocol run — submit and wait from the terminal

• Protocol — load, validate, and inspect YAML locally

• ProtocolClient / run_protocol() — submit runs from Python with progress and results

Schema reference

Field-level protocol schema (inputs, tasks, execution, outputs, full JSON Schema): Protocol Schema Reference.

Examples

Validate a protocol file:

biolm protocol validate my-protocol.yaml

Validate from Python:

from biolm.protocols import Protocol

result = Protocol.validate("my-protocol.yaml")
if not result.is_valid:
    for err in result.errors:
        print(err.path, err.message)

Run from Python:

from biolm import run_protocol

results = run_protocol("my-protocol-slug", inputs={"sequences": ["MKTAYIAKQRQ"]})

Programmatic runs

For progress tracking, cancellation, and result download, use ProtocolClient directly:

from biolm.protocol_runs import ProtocolClient

client = ProtocolClient()
run = client.submit("my-protocol-slug", inputs={"sequences": ["MKTAYIAKQRQ"]})
run.wait()
print(run.results())

API

class biolm.protocols.Protocol(yaml_path: str)

Load and validate BioLM protocol YAML files.

Args:

yaml_path: Path to a protocol YAML file. The file is loaded and

validated on construction; invalid YAML raises ValueError.

Use validate() as a classmethod to validate without instantiating.

classmethod validate(yaml_path: str) → ProtocolValidationResult

Validate a protocol YAML file.

Args:

yaml_path: Path to protocol YAML file.

Returns:

ProtocolValidationResult with validation results.

biolm.run_protocol(slug: str, inputs: dict, *, run_name: str | None = None, api_key: str | None = None, base_url: str | None = None, timeout: float = 3600.0, show_progress: bool = True) → dict

Submit a BioLM protocol run and block until results are ready.

class biolm.protocol_runs.ProtocolClient(api_key: str | None = None, base_url: str | None = None)

Submit and monitor BioLM protocol runs from Python.

Wraps the /api/protocols/ REST endpoints. Use submit() to start a run, run_and_wait() for a blocking workflow, or get_run() to poll an existing run ID.

get_run(run_id: str) → ProtocolRun

Reconnect to an existing run by ID.

list(search: str | None = None, page: int = 1, page_size: int = 20) → Dict[str, Any]

run_and_wait(slug: str, inputs: Dict[str, Any], run_name: str | None = None, timeout: float = 3600.0, show_progress: bool = True) → Dict[str, Any]

submit(slug: str, inputs: Dict[str, Any], version: int | None = None, run_name: str | None = None, environment_id: int | None = None, files: Dict[str, Any] | None = None) → ProtocolRun

class biolm.protocol_runs.ProtocolRun(data: Dict[str, Any], client: ProtocolClient)

A submitted protocol run returned by ProtocolClient.submit().

cancel() → Dict[str, Any]

Cancel this run (idempotent; may error if already terminal).

download(output_dir: str | Path = '.', file_type: str = 'csv', overwrite: bool = False) → Path

results() → Dict[str, Any]

wait(timeout: float = 3600.0, show_progress: bool = True) → ProtocolRun

See also

• biolm protocol — CLI validate and run

• Protocol Schema Reference — protocol YAML schema

• biolm package — biolm.protocol_runs module reference