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

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

```python
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](https://www.octopize.app), 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:

```bash
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.

```python
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:

```python
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:

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

```python
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 {doc}`jobs`).

## Recommended workflow

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

```python
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 {doc}`parameters` for all the parameters, and {doc}`jobs` 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:

```python
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 {doc}`reporting`.

**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.
:::