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), API key authentication, and advanced configuration options, see Configuration.

Quick example

from avatars import Manager
manager = Manager(api_key="octopize_apikey...")
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, serverless: bool = False, license_key: str | None = None, workdir: str | Path | None = None, serverless_config: ServerlessConfig | 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 using an API key

• 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)

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.

Variables:

auth_client – The client all requests go through. Against a server this is a avatars.client.ApiClient; in serverless mode it is a avatars.serverless.client.ServerlessClient. It is typed as the avatars.sdk_client.SdkClient protocol both satisfy.

license_info() → LicenseSummary

What the serverless licence in force grants.

Who it is for, the organization, the tier, the features, the maximum rows and columns per dataset, the expiry date, and the licence id to quote to support. print() it for a readable summary.

Raises:

ValueError – When this Manager talks to a server: there, the limits come from the platform account, not from a licence.

list_input_files() → InputFiles

List the files already in your storage, newest first.

Give one to runner.add_table in place of the data to reuse it without uploading it again.

create_runner(set_name: str, *, seed: int | None = None, max_distribution_plots: int | None = None, output_format: Literal['csv', 'parquet'] | 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, name: str | None = None) → dict[str, JobResponse]

Get the last n jobs, optionally filtered by name.

Parameters:

• count – Number of most recent jobs to return.

• name – If provided, only return jobs whose name matches exactly.

get_health() → dict[str, str]

Get the health of the server.

get_jobs_by_name(name: str) → list[JobResponse]

Return all jobs whose name matches exactly.

Parameters:

name – The human-readable run name (e.g. "my_dataset").

get_jobs_by_id(id: UUID | str) → list[JobResponse]

Return all jobs belonging to the given run ID.

Parameters:

id – The UUID of the run (as a UUID or its string representation).

get_last_set() → list[JobResponse]

Return all jobs belonging to the most recently created run (set_name).

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 set_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.

Parameters:

• yaml_path (The path to the yaml file.)

• 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

cancel_job(name: str) → list[JobResponse]

Stop every job of a run identified by its name that is still going.

Looks the run up the way delete_job() does, and refuses an ambiguous name the same way. A job that has not started stops at once; a running one stops at its next safe point and turns "cancelled" shortly after. See Runner.cancel() for what a cancelled database copy leaves in its target.

Parameters:

name – The human-readable name given to the run.

Returns:

The jobs a cancel was sent for, as the server answered.

Return type:

list[JobResponse]

Raises:

ValueError – If no run is found for the given name, or if several runs match and the caller must disambiguate with cancel_job_by_id().

cancel_job_by_id(id: UUID | str) → list[JobResponse]

Stop every job of the run id that is still going.

Parameters:

id – The UUID (or its string representation) of the run.

Returns:

The jobs a cancel was sent for, as the server answered.

Return type:

list[JobResponse]

cancel_jobs(job_names: list[str]) → list[JobResponse]

Stop the named jobs, leaving alone the ones that are already over.

Each job’s state is read just before its cancel is sent: cancelling one job cancels the jobs waiting on it, so a job listed after its parent is often over by the time its turn comes, and asking again would be refused.

Parameters:

job_names – The names of the jobs to cancel.

Returns:

The jobs a cancel was sent for, as the server answered.

Return type:

list[JobResponse]

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