Python API reference

The public API is the four functions in the top-level mayaku package, plus the classes and helpers listed below. Anything else under mayaku.* is internal and may change.

Python

import mayaku

mayaku.train            # train a model
mayaku.evaluate         # score a model
mayaku.from_pretrained  # load a model for prediction
mayaku.health_check     # inspect a COCO split
mayaku.__version__      # e.g. "3.0.0"

mayaku.train

Python

mayaku.train(
    config=None, *, weights=None,
    train_annotations=None, train_images=None,
    val_annotations=None, val_images=None,
    output_dir=None, size_budget=None, num_epochs=None, overrides=None,
    device="auto", num_gpus=1, resume=None, log=print,
) -> dict

Trains a detector (detection, segmentation, keypoints, oriented boxes) from COCO JSON, or a classifier (model.task: classify) from class folders.

Parameter	Type	Meaning
`config`	`str`, `Path`, `MayakuConfig` or `None`	YAML path or config object.
`weights`	`str`, `Path` or `None`	Hosted model name or checkpoint to start from. Without `config`, it also defines the architecture.
`train_annotations`	path or `None`	Training COCO JSON. Required for detectors, not allowed for classifiers.
`train_images`	path	Required. Training images, or the class-folder root.
`val_annotations`, `val_images`	path or `None`	Validation split. Pass both for detectors, `val_images` only for classifiers.
`output_dir`	path or `None`	Run directory. Default `runs/<name>`.
`size_budget`	`int` or `None`	Sets `input.size_budget`.
`num_epochs`	`int` or `None`	Sets `train.epochs`.
`overrides`	nested mapping or `None`	Config fields, e.g. `{"train": {"lr": 0.005}}`.
`device`	`str`	`"auto"`, `"cuda"`, `"cuda:N"`, `"mps"`, `"cpu"`.
`num_gpus`	`int`	GPUs on this machine. Leave at 1 under `torchrun`.
`resume`	path or `None`	`state.pt` or `train/` directory of a run to continue.
`log`	callable	Receives each log line as a string.

Returns a dict with final_weights (Path), output_dir (Path), metrics (dict or None), best (dict or None), train_seconds, eval_seconds and metadata. See Training.

mayaku.evaluate

Python

mayaku.evaluate(weights, *, annotations=None, images, output_dir=None,
                device="auto", log=print) -> dict

Scores a checkpoint, hosted model or exported file. Returns a flat dict of metrics: COCO metrics for detectors (AP, AP50, ..., plus segm_* / kpt_*), or top1 and top5 for classifiers, whose annotations must be None. With output_dir, it also writes metrics.json there. See Evaluation.

mayaku.from_pretrained

Python

mayaku.from_pretrained(source, device="auto") -> Predictor | ArtifactPredictor

Loads a model for prediction:

A checkpoint path or hosted model name gives a Predictor, which runs in PyTorch.
A path ending in .onnx, .mlpackage, .xml or .engine gives an ArtifactPredictor, which runs in that runtime.

Both have the same interface. See Prediction.

Predictor and ArtifactPredictor

from mayaku.inference import Predictor, ArtifactPredictor

Member	Meaning
`__call__(image, conf=None)`	One image (path, or `(H, W, 3)` RGB `uint8` array) → `Detections`, or `Classification` for a classifier. `conf` overrides the recorded score threshold.
`batch(images, conf=None)`	A list of images → a list of results.
`class_names`	`list[str]`
`canvas`	`(height, width)` input size
`sidecar`	`dict`: the model's embedded description (config, classes, canvas, outputs, decode values, preprocessing, task settings, quantization, export info).

Predictor only:

Member	Meaning
`Predictor.from_checkpoint(path, device="auto")`	Load from a checkpoint file. A name is not downloaded here; use `from_pretrained` for that.
`export(target="onnx", output=None, precision=None) -> Path`	Write an exported file. See Export.
`model`	The underlying `torch.nn.Module`, in its deployment form.
`device`	The `torch.device` it runs on.

Detections

from mayaku.inference import Detections

A dataclass, with one per image, on the CPU, in original-image pixels, sorted by score:

Field	Type
`boxes`	`Tensor (n, 4)` float32, `[x1, y1, x2, y2]`
`scores`	`Tensor (n,)` float32
`labels`	`Tensor (n,)` int64
`masks`	`Tensor (n, H, W)` bool, or `None`
`keypoints`	`Tensor (n, K, 3)` float32 `(x, y, visibility probability)`, or `None`
`rboxes`	`Tensor (n, 5)` float32 `(cx, cy, w, h, theta)`, theta in radians, or `None`

len(detections) is n.

Classification

from mayaku.inference.decode import Classification

Member	Type
`scores`	`Tensor (num_classes,)` probabilities
`label`	`int`, the most likely class index
`top(k=5)`	`list[tuple[int, float]]`, best first

mayaku.health_check

Python

mayaku.health_check(annotations, images, cfg=None) -> dict

Scans one COCO split: counts, the canvas training would use (from cfg, default MayakuConfig()), object-size fractions, box aspect percentiles, class balance and warnings. See Datasets.

mayaku.config

Python

from mayaku.config import (
    MayakuConfig, ModelConfig, InputConfig, KeypointConfig, DataLoaderConfig, AutoConfig,
    load_yaml, read_yaml, dump_yaml, to_yaml_string, merge_overrides, parse_assignments,
)

Name	Meaning
`MayakuConfig(model=..., input=..., train=..., dataloader=..., auto_config=...)`	The whole configuration. Sections accept dicts. Immutable (pydantic, frozen, unknown fields rejected). See Configuration.
`load_yaml(path) -> MayakuConfig`	Read and validate a YAML file.
`read_yaml(path) -> (dict, MayakuConfig)`	The same, also returning the raw mapping as written.
`dump_yaml(cfg, path)` / `to_yaml_string(cfg)`	Write a config as YAML.
`merge_overrides(cfg, overrides) -> MayakuConfig`	Deep-merge a nested mapping into a new config.
`parse_assignments(["train.lr=0.005", ...]) -> dict`	Turn `--set`-style strings into a nested mapping.

mayaku.utils.download

Python

from mayaku.utils.download import download_model, list_models, list_revisions, resolve_weights, DownloadError

Name	Meaning
`download_model(name, *, revision=None, cache_dir=None, manifest_url=..., verify_sha256=True) -> Path`	Return `<dir>/<name>.pth`, downloading it if missing. `cache_dir` is a `pathlib.Path`.
`list_models(*, manifest_url=...) -> dict[str, list[str]]`	Hosted model names by task.
`list_revisions(name, *, manifest_url=...) -> list[str]`	Dated revisions of a model, oldest first.
`resolve_weights(weights) -> Path`	What `train`, `from_pretrained` and the CLI do with a weights argument: an existing file, else a download.
`DownloadError`	Raised when a download or integrity check fails.

See Models.

Helpers for task outputs

Name	Meaning
`mayaku.model.obb.corners(rboxes)`	`(..., 5)` oriented boxes → `(..., 4, 2)` corner points. See Oriented boxes.
`mayaku.inference.export.metadata.read_sidecar(path, target)`	Read the embedded description of an exported file (`target`: `"onnx"`, `"coreml"`, `"openvino"`, `"tensorrt"`).
`mayaku.inference.export.metadata.strip_tensorrt_header(path) -> bytes`	The plain engine bytes of a Mayaku `.engine` file.