Python API

All CLI commands are also available programmatically via album.api.Album. The Python API exposes the same controller that the CLI, the GUI, and the MCP server use, so anything you can do interactively you can also script — including from inside another Album solution. Solution-side composition (one solution calling other solutions) is the pattern used in case-studies, scenario B.

Quick start

from album.api import Album

album = Album.Builder().base_cache_path("/my/album/dir").build()
album.load_or_create_collection()

if not album.is_installed("album:template-python:0.1.0"):
    album.install("album:template-python:0.1.0")

album.run("album:template-python:0.1.0", ["--name", "World"])
album.close()

This makes it possible to script album workflows — also directly from within an album solution. See the Album template solution for a worked example.

Builder options

Use Album.Builder() to configure the instance before calling .build():

Method	Description
`base_cache_path(path)`	Root directory for Album’s local cache (catalogs, environments, …)
`log_level(LogLevel)`	Logging verbosity (`LogLevel.INFO`, `DEBUG`, `WARNING`, …)
`log_format(fmt)`	Custom log format string
`log_format_time(fmt)`	Custom log time format string

from album.api import Album
from album.runner.album_logging import LogLevel

album = (
    Album.Builder()
    .base_cache_path("/tmp/album")
    .log_level(LogLevel.DEBUG)
    .build()
)

Core methods

Collection & catalog management

album.load_or_create_collection()         # must be called first
album.add_catalog("https://gitlab.com/album-app/catalogs/default")
album.remove_catalog_by_name("my-catalog")
album.remove_catalog_by_src("https://...")
album.update()                            # fetch latest catalog indices
album.update("my-catalog")                # single catalog
album.upgrade()                           # sync collection with catalogs
album.upgrade("my-catalog", dry_run=True) # preview changes

Resolve, install, run, test, uninstall

album.install("group:name:version")
album.run("group:name:version", ["--arg", "value"])
album.test("group:name:version")
album.uninstall("group:name:version")

Solutions can be identified by any format accepted by the CLI: name, group:name, group:name:version, catalog:group:name:version, a file path, URL, or DOI.

Deploy & undeploy

album.deploy(
    deploy_path="./my-solution",
    catalog_name="my-catalog",
    dry_run=False,
    changelog="Initial release",
)
album.undeploy("group:name:version", catalog_name="my-catalog", dry_run=False)

Search & inspect

results = album.search("segmentation deep learning")
index = album.get_index_as_dict()
catalogs = album.get_catalogs_as_dict()
catalog = album.get_catalog_by_name("default")

Clone

# Clone a solution as starting point
album.clone("album:template-python:0.1.0", "/target/dir", "my-solution")
# Clone a catalog template
album.clone("template:catalog", "/target/dir", "my-catalog")

Load a solution from disk

solution = album.load("/path/to/solution.py")

Cleanup

Always close the instance when done — this releases loggers and resources:

album.close()

Album also implements __del__, so cleanup happens on garbage collection, but explicit close() is recommended.