tuneinsight 1.5.0
Official Python SDK for the Tune Insight API. The current version is compatible with the same version of the API.
License: Apache-2.0
Requires Python: <4.0,>3.10.0

# Tune Insight Python SDK

This is the official Python SDK for the Tune Insight API. It can be used to interface with a Tune Insight instance. The SDK enables programmatic use of Tune Insight from Jupyter notebooks and integration with other softwares, and gives access to advanced features such as custom preprocessing algorithms and machine learning pipelines.

## Documentation

The [official documentation](https://dev.tuneinsight.com/docs/Usage/python-sdk/) gives a detailed explanation on how to use the SDK. The recommended starting point to learn how to use the SDK is with the [Quickstart notebook](https://github.com/tuneinsight/python-sdk/tree/main/examples/Quickstart.ipynb).

## Installation

The SDK is available on `pip`:

```bash
pip install tuneinsight
```

If instructed by your administrator, you might need to install a specific version (e.g., `xx.y`):

```bash
pip install tuneinsight==xx.y
```

Note that versions `0.13.1` and older are not available on `pip`: [contact us](tech-support@tuneinsight.com) to get packages for these versions.

It is recommended to set up a custom environment for the SDK, e.g. using [`conda`](https://anaconda.org/anaconda/conda).

### Installing optional dependencies

Starting with version 1.1.1, some dependencies are no longer packaged with the SDK to make the installation lighter. These include all dependencies related to Jupyter notebooks. If size is not a constraint, you can install all dependencies by adding `[full]` to the package name:

```bash
pip install tuneinsight[full]
```

### Testing your implementation

After installing the package, run the following command in your terminal.

```bash
test-ti-install
```

If your installation succeeded, you should see the following message:

```
# Package is available          ✅
# Cryptolib is available        ✅
The Tune Insight SDK is correctly installed.
```

Refer to the [troubleshooting](#troubleshooting) section if you see any ❌.

Note: if you did not install the full package, you might see the following error message that can be safely ignored:

```
Checking optional packages:
# Jupyter is available  ❌
        Jupyter is not installed, use `pip install tuneinsight[full]` to install it if needed.
```

### Connecting to a server

To further test your implementation, you can open a Python interpreter (e.g. a Jupyter notebook), and run the following commands, replacing `api_url` and `frontend_client_id` with the appropriate values. This will open a browser window asking you to log in to your Tune Insight account.

```python
from tuneinsight import Diapason

client = Diapason.from_config(
    api_url="<api_url>/api", # The url of the Tune Insight API to which the client will connect.
    oidc_client_id="<frontend_client_id>", # This is the front client id given by Tune Insight in the Portal.
)

client.login()

client.healthcheck(error=True)
```

If all goes well, this should complete in a few seconds (after you have entered your login details). You now have everything you need to start using the SDK! The recommended next step is to run the [Quickstart notebook](https://github.com/tuneinsight/python-sdk/tree/main/examples/Quickstart.ipynb) to learn more about existing features.

If the instance you are trying to reach is in a secure environment, you might need to access it through a proxy. Enter the URL of your proxy as `http_proxy` and `https_proxy` parameters of `Diapason.from_config`. Most of the time, these will be the same value.

```python
client = Diapason.from_config(
    api_url="<api_url>/api", # The url of the Tune Insight API to which the client will connect.
    oidc_client_id="<frontend_client_id>", # This is the front client id given by Tune Insight in the Portal.
    http_proxy="http://url/of/proxy:port", # URL of the proxy to use for HTTP requests (often http://localhost:port).
    https_proxy="http://url/of/proxy:port", # URL of the proxy to use for HTTPS requests (usually the same as http_proxy).
)
```

## Troubleshooting

#### command not found: test-ti-install

The installation of the package did not work, or a version before `0.14.0` was installed. To check the installed version, run the following line in the terminal:

```bash
pip freeze | grep tuneinsight
```

The result should look like this:

```
tuneinsight==1.0.0
```

If you see a line that looks like this,

```
tuneinsight @ file:///path/to/file/tuneinsight-0.13.1-py3-none-any.whl#sha256=...
```

the SDK was installed directly from a `.whl` file, suggesting you are using an older version. You might need to install a more recent version, using `pip`:

`pip install tuneinsight==1.0.0`

#### Error: Could not load the cryptolib: contact your administrator.

This means that the installation succeeded, but the `cryptolib` module of the SDK could not be installed on your system. You can still use your installation, but some features will not be available.

This issue should also trigger a warning to help identify the cause.

- `Could not find the cryptolib library. Your platform might not be supported.`: this means that the precompiled binary of the cryptolib is not available, most likely because it was not compiled for your operating system and architecture. The SDK is available for all common OSes and architectures, but we can compile for additional architectures if necessary.
- `cannot open shared object file: ...`: the precompiled binary was found, but it could not be loaded by your system. This issue could be caused by a number of issues, so we suggest [reaching out to us](contact@tuneinsight.com).
- `/lib/.../libc.so: version 'GLIBC_2.32' not found`: you need to install [`libc`](https://www.gnu.org/software/libc/) at the appropriate version (`2.32` in this case) on the machine that runs the SDK (potentially, a Docker container).

#### Client is not allowed to initiate OAuth 2.0 Device Authorization Grant.

This error (which occurs when running `client.login`) suggests that the client or instance is not properly configured. Usually, this is caused by one of the following:

- The `frontend_client_id` you entered is not correct.
- Your Python environment can't connect to the authentication provider (https://auth.tuneinsight.com)
- The authentication configuration does not allow the use of the SDK. Contact your administrator.
- Your instance uses a different authentication provider. You will need to change the `oidc_url` argument in `Diapason.from_config`. Ask your administrator for the url that you should use (don't forget the `/auth/` at the end of the URL).

#### `client.login` hangs for some time after entering credentials.

This means that the login was successful, but the client is not able to connect to the Tune Insight instance. An error message will typically appear after a minute or so. If you get the following error, it might just be that the `api_url` you entered was not correct:

```
httpx.ConnectError: [Errno -3] Temporary failure in name resolution
```

For other errors, contact your administrator: this might suggest that the instance is down or otherwise unavailable, or that there was an issue with the configuration (wrong URL, client ID, or proxy configuration).

#### API version mismatch: the server and client use different versions of the API.

This warning will not occur during the test script, but commonly occurs when using the SDK (specifically, creating or connecting to a project). It means that the version you installed is not consistent with the version of the Tune Insight instance you are connecting to.
Depending on the versions, this might not be too big of an issue, but it is strongly recommended to install the same version.
Ask your administrator for the version installed on the Tune Insight instance, and install the corresponding SDK version with

```bash
pip install tuneinsight==0.xx.y
```

## License

Apache License 2.0