Getting started¶

How to install the client and check its version¶

The package is published on PyPI as octopize.avatar, but you import it as avatars. Python 3.12 or later is required.

pip install -U octopize.avatar
# or, with uv:
uv add octopize.avatar

import avatars

print(avatars.__version__)

If a very old client (earlier than 0.7.3) is installed, remove it first with pip uninstall -y avatars.

How to create an API key¶

The Python client authenticates with an API key. An API key is a long-lived credential: you do not store a password in your scripts or notebooks.

Step 1 — Create your first API key in the web application. Log in to the web application, then go to Account → API Keys → Generate API key. Save the secret in a safe place: it is shown only once. If you lose it, create a new key.

Step 2 — Store the key outside your code, for example in a .env file or an environment variable:

AVATAR_API_KEY=<your-api-key>

How to log in to the server¶

Pass the API key to the Manager. The client is ready to use at once.

import os

from avatars.manager import Manager

# SaaS (https://www.octopize.app is the default server)
manager = Manager(api_key=os.environ["AVATAR_API_KEY"])

# Dedicated or on-premise instance: give the URL of your server
# manager = Manager(base_url="https://avatar.my-company.com", api_key=os.environ["AVATAR_API_KEY"])

manager.get_health()  # {'message': 'ok'}

If you do not pass api_key, the Manager reads the AVATAR_API_KEY environment variable. An empty key is refused when the Manager is created.

For an on-premise server without a valid SSL certificate, you can turn off the certificate check:

from avatars.client_config import ClientConfig

manager = Manager(
    config=ClientConfig(
        base_url="https://avatar.my-company.com",
        api_key=os.environ["AVATAR_API_KEY"],
        should_verify_ssl=False,
    )
)

The same ClientConfig accepts timeout= (in seconds) if the calls time out.

When you are logged in, you can create more API keys from Python:

from avatars.models import CreateApiKeyRequest, ExpirationDays

api_key_response = manager.auth_client.api_keys.create_api_key(
    CreateApiKeyRequest(name="my-key", expiration_days=ExpirationDays.integer_365)
)
# Save this value: it is shown only once.
print(api_key_response.get("api_key").get("plaintext"))

How to launch my first avatarization¶

You work with a runner. A runner holds one run: you add your tables, set the parameters, launch the jobs and get the results.

import os

from avatars.manager import Manager

manager = Manager(api_key=os.environ["AVATAR_API_KEY"])

runner = manager.create_runner(set_name="my_first_avatarization")
runner.add_table("wbcd", "fixtures/wbcd.csv")  # upload the data
runner.advise_parameters("wbcd")  # let the server recommend the parameters
runner.run()  # avatars, metrics and report

avatars_df = runner.shuffled("wbcd")  # waits for the job, then returns the avatars
runner.privacy_metrics("wbcd")
runner.signal_metrics("wbcd")
runner.download_report("wbcd_report.pdf")

run() returns at once. The result methods (shuffled, privacy_metrics, …) wait until the job is finished, and raise a ValueError if it failed (see Running jobs and getting results).

Recommended workflow¶

The fastest way to good results is to start from the server recommendation, then change only what you need:

runner = manager.create_runner("wbcd_tuning")
runner.add_table("wbcd", "fixtures/wbcd.csv")

runner.advise_parameters("wbcd")  # 1. recommended parameters
runner.print_parameters("wbcd")  # 2. check what will be sent
runner.update_parameters("wbcd", k=10)  # 3. change only what you need
runner.run()  # 4. run
runner.privacy_metrics("wbcd")  # 5. check the metrics, then iterate

See Avatarization parameters for all the parameters, and Running jobs and getting results to run only some of the jobs while you iterate.

How to set the options of a run¶

create_runner accepts options for the whole run:

from avatar_yaml.models.avatar_metadata import (
    DataRecipient,
    DataSubject,
    DataType,
    SensitivityLevel,
)
from avatar_yaml.models.parameters import ReportLanguage

runner = manager.create_runner(
    set_name="wbcd_full_options",  # name shown in the web application
    seed=42,  # same seed + same data + same parameters = same avatars
    output_format="csv",  # "csv" or "parquet" (default: format of the input)
    max_distribution_plots=30,  # number of distribution plots to generate
    pia_data_recipient=DataRecipient.TRUSTED_THIRDPARTY,
    pia_data_type=DataType.HEALTH,
    pia_data_subject=DataSubject.PATIENTS,
    pia_sensitivity_level=SensitivityLevel.HIGH,
    report_language=ReportLanguage.FR,
)

The pia_* values describe the context of the processing. They set the targets of the metrics and fill the PIA report. Without them, the strictest targets apply. See Plots and reports.

In the web app: step Name & input → Job Context.

Tip

Give each run a unique name. Several features find a run by its name, and when names are shared they take the most recent run.