Manager

The Manager is the high-level entry point for most users. It wraps an authenticated ApiClient and offers helper methods that reduce boilerplate when running avatarizations.

Why use the Manager?

• Single place to authenticate.

• Shortcuts to create a Runner and load YAML configs.

• Convenience helpers to inspect recent jobs / results.

See also

For detailed information about configuring the Manager to connect to different servers (SaaS vs on-premise), authentication methods, and advanced configuration options, see Configuration.

Quick example

Using username/password authentication:

from avatars import Manager
manager = Manager()
manager.authenticate(username="user", password="pass")
runner = manager.create_runner(set_name="demo")
runner.add_table("wbcd", "fixtures/wbcd.csv")
runner.set_parameters("wbcd", k=15)
runner.run()

Detailed reference

class avatars.manager.Manager(base_url: str | None = None, *, api_client: ApiClient | None = None, api_key: str | None = None, config: ClientConfig | None = None, should_verify_compatibility: bool | None = None)

Bases: object

High-level convenience facade for interacting with the Avatar API.

The Manager wraps an authenticated avatars.client.ApiClient instance and exposes a small, task‑oriented surface area so end users can:

• authenticate once (authenticate) or use API key authentication

• spin up a avatars.runner.Runner (create_runner / create_runner_from_yaml)

• quickly inspect recent jobs & results (get_last_jobs / get_last_results)

• perform simple platform health checks (get_health)

• handle password reset flows (forgotten_password / reset_password)

It deliberately hides the lower-level resource clients (jobs, results, datasets …) unless you access the underlying auth_client directly. This keeps common workflows succinct while preserving an escape hatch for advanced usage. The Runner objects created through the manager inherit the authenticated context, so you rarely have to pass tokens or low-level clients around manually.

auth_client

The underlying avatars.client.ApiClient used to perform all HTTP requests.

authenticate(username: str, password: str, should_verify_compatibility: bool | None = None) → None

Authenticate the user with the given username and password.

Deprecated since version Username/password: authentication is deprecated. After logging in, create an API key and use it for future sessions. See the warning emitted on successful login for the exact migration steps, or visit https://python.docs.octopize.io/latest/user_guide.html

Note: This method should not be called if the Manager was initialized with an api_key. API key authentication is already active and doesn’t require calling authenticate().

forgotten_password(email: str) → None

Send a forgotten password email to the user.

reset_password(email: str, new_password: str, new_password_repeated: str, token: str | UUID) → None

Reset the password of the user.

create_runner(set_name: str, seed: int | None = None, max_distribution_plots: int | None = None, pia_data_recipient: DataRecipient = DataRecipient.UNKNOWN, pia_data_type: DataType = DataType.UNKNOWN, pia_data_subject: DataSubject = DataSubject.UNKNOWN, pia_sensitivity_level: SensitivityLevel = SensitivityLevel.UNDEFINED, report_language: ReportLanguage = ReportLanguage.EN) → Runner

Create a new runner.

create_runner_from_id(set_name: str | UUID) → Runner

Reconstruct a Runner from an existing set_name UUID with historical results.

This method fetches the configuration and job history from a previous avatarization, allowing you to access results without re-running jobs.

Note: If you call run() on the reconstructed runner, it will create a NEW set_name. A UserWarning is emitted with the old set_name so you can recover previous results if needed.

Parameters:

set_name (str | UUID) – The UUID of the resource set to load. This is the value of runner.set_name after a job has been run.

Returns:

A reconstructed Runner with access to historical results.

Return type:

Runner

Raises:

• TypeError – If set_name is not a str or UUID.

• ValueError – If the set_name string is not a valid UUID format.

• Exception – If resources cannot be fetched from the API.

See also

create_runner_from_name

Simpler method using a runner name

Examples

>>> set_name = runner.set_name  # Save this UUID after running
>>> runner2 = manager.create_runner_from_id(set_name)
>>> results = runner2.shuffled("customers") # Access old results without re-running jobs
>>>
>>> # Re-run
>>> runner2.run(ignore_warnings=True) # will create new results with a new id,
>>> # you can still access old results with the old id

get_last_results(count: int = 1) → list[dict[str, str]]

Get the last n results.

get_last_jobs(count: int = 1) → dict[str, JobResponse]

Get the last n results.

get_health() → dict[str, str]

Get the health of the server.

find_ids_by_name(set_name: str) → list[tuple[str, list[JobResponse]]]

Find all run UUIDs associated with a given set_name.

Multiple runs can share the same set_name, each representing a different version. Jobs sharing the same UUID are grouped together.

Parameters:

set_name (str) – The human-readable name to search for (e.g., "my_dataset"). This is the name passed to create_runner(set_name=...).

Returns:

List of (uuid, jobs) tuples sorted by the most recent job creation time within each group (newest first). Each tuple contains:

• uuid: UUID string of the run

• jobs: All jobs belonging to that run

Returns an empty list if no matching display name is found.

Return type:

list[tuple[str, list[JobResponse]]]

create_runner_from_name(display_name: str) → Runner

Create a Runner from the most recent run associated with a display name.

This is the primary method for reloading results from a previous run. It looks up all runs matching the given display name and returns a Runner loaded with the most recent one.

If multiple runs share the same display name, the one with the most recent job creation time will be used. To load a specific run by UUID, use create_runner_from_id instead.

Parameters:

display_name (str) – The human-readable name given to the run (the set_name argument passed to create_runner). Must match exactly (case-sensitive).

Returns:

A Runner instance loaded with results from the most recent matching run.

Return type:

Runner

Raises:

ValueError – If no runs are found for the given display name.

Examples

>>> runner = manager.create_runner_from_name("my_dataset")
>>> df = runner.shuffled("patients")
>>> metrics = runner.privacy_metrics("patients")

create_runner_from_yaml(yaml_path: str, set_name: str) → Runner

Create a new runner from a yaml file. :param yaml_path: :type yaml_path: The path to the yaml file. :param set_name: :type set_name: Name of the set of resources.

delete_job(name: str) → BulkDeleteResponse

Delete all jobs for a run identified by its name.

Looks up all runs whose name matches exactly. If exactly one run is found, all its jobs are deleted. If multiple runs share the same name, a ValueError is raised with the commands to use delete_job_by_id() for each run.

Parameters:

name – The human-readable name given to the run (the set_name argument passed to create_runner).

Returns:

Response containing deleted and failed jobs.

Return type:

BulkDeleteResponse

Raises:

ValueError – If no run is found for the given name, or if multiple runs match and the caller must disambiguate by id.

delete_job_by_id(id: UUID | str) → BulkDeleteResponse

Delete all jobs belonging to a specific run identified by its id.

Parameters:

id – The UUID (or its string representation) of the run whose jobs should be deleted.

Returns:

Response containing deleted and failed jobs.

Return type:

BulkDeleteResponse

delete_jobs(job_names: list[str]) → BulkDeleteResponse

Delete multiple jobs by name, batching in groups of up to 100.

Parameters:

job_names – The names of the jobs to delete.

Returns:

Aggregated response containing all deleted and failed jobs across batches.

Return type:

BulkDeleteResponse