AI4EOSC - Platform API

This is the Platform API for interacting with the AI4EOSC services, built using FastAPI. It aims at providing a stable UI, effectively decoupling the services offered by the project from the underlying tools we use to provide them (ie. Nomad, OSCAR).

The API is currently deployed here:

• production API (master branch)
• development API (dev branch)

Images of both API are accessible in the project's Harbor registry:

• registry.services.ai4os.eu/ai4os/ai4-papi:prod
• registry.services.ai4os.eu/ai4os/ai4-papi:dev

The Dashboards pointing to those APIs are respectively:

• production Dashboard
• development Dashboard

Installation

Requirements To use this library you need to have Nomad installed to be able to interact with deployments. Once you have Nomad installed you have to export the following variables with the proper local paths and http address: bash export NOMAD_ADDR=https://some-public-ip:4646 export NOMAD_CACERT=/path/to/tls/nomad-ca.pem export NOMAD_CLIENT_CERT=/path/to/tls/nomad-cli.pem export NOMAD_CLIENT_KEY=/path/to/tls/nomad-cli-key.pem For this you will need to ask the administrator of the cluster for the proper certificates.

Once you are done you can proceed to install the module: bash pip install git+https://github.com/ai4eosc/ai4-papi.git

If you plan to use the module to develop, install instead in editable mode: bash git clone https://github.com/ai4eosc/ai4-papi cd ai4-papi pip install -e .

Running the API

To deploy the API, the are several options:

1. Using entrypoints: bash ai4papi-run --host 0.0.0.0 --port 8080

2. Using uvicorn directly (with the auto reload feature enabled if you are developing): bash uvicorn ai4papi.main:app --reload

3. Using our Makefile bash make run

4. From Dockerhub bash docker run -v /local-path-to/nomad-certs:/home/nomad-certs -p 8080:80 registry.services.ai4os.eu/ai4os/ai4-papi:prod

5. Building from our Dockerfile. bash docker build -t ai4-papi:prod --build-arg papi_branch=master . docker run -v /local-path-to/nomad-certs:/home/nomad-certs -p 8080:80 ai4-papi:prod

Once the API is running, go to http://127.0.0.1:8080/docs to check the API methods in the Swagger UI.

Authentication

Some of the API methods are authenticated (🔒) via OIDC tokens, so you will need to perform the following steps to access those methods.

Generate an OIDC token

First, you will need to create an AI4OS Keycloak account.

Then, you will a token via the terminal. For this you need:

1. Install the OIDC agent in your system.

2. Configure the OIDC agent: bash eval `oidc-agent-service start` oidc-gen \ --configuration-endpoint https://login.cloud.ai4eosc.eu/realms/ai4eosc/.well-known/openid-configuration \ --client-id "ai4-papi" \ --client-secret <client-secret> \ ai4os-keycloak

To retrieve the <client-secret>, contact Ignacio Heredia.

You will then be ask some question. Use default values, except for: - Redirect_uris (space separated): http://localhost:43985

The browser will open so you can authenticate with your AI4OS account. Then go back to the terminal and finish by setting and encryption password.

1. Add the following line to your .bashrc to start the agent automatically at startup (ref): bash eval `oidc-agent-service use` > /dev/null

2. Generate the OIDC token bash oidc-token ai4os-keycloak

3. Optional: You can check you have set everything up correctly by running: bash flaat-userinfo --oidc-agent-account ai4os-keycloak This should print you AI4OS user information.

Making authenticated calls

To make authenticated calls, you have several options:

• Using CURL calls: bash curl --location 'http://localhost:8080' --header 'Authorization: Bearer <your-OIDC-token>'

• From in the Swagger UI (http://localhost:8080/docs), click in the upper right corner button Authorize 🔓 and input your token. From now on you will be authenticated when making API calls from the Swagger UI.

• From inside a Python script

```python from types import SimpleNamespace from ai4papi.routers.v1 import deployments

deployments.get_deployments( vos=['vo.ai4eosc.eu'], authorization=SimpleNamespace( credentials='your-OIDC-token' ), ) ```

Description

API methods

Here follows an overall summary of the available routes. The 🔒 symbol indicates the method needs authentication to be accessed. More details can be found in the API docs.

• /v1/catalog/: interact with the metadata of the modules/tools in the marketplace.

Notes: The catalog caches results for up to 6 hours to improve UX (see doctring).

• /v1/try_me/: endpoint where anyone can deploy a short-lived container to try a module

• /v1/deployments/: (🔒) deploy modules/tools in the platform to perform trainings

• /v1/stats/deployments/: (🔒) retrieve usage stats for users and overall platform.

Configuration files

These are the configuration files the API uses:

• etc/main_conf.yaml: main configuration file of the API
• etc/modules: configuration files for standard modules
• etc/tools: configuration files for tools
  • ai4os-federated-server: federated server

The pattern for the subfolders follows: - user.yaml: user customizable configuration to make a deployment in Nomad. Also contains the generic quotas for hardware (see range parameter). - nomad.hcl: additional non-customizable values (eg. ports)

Contributing

We provide some default VScode configuration to make the development workflow smoother.

The repository is formatted with Ruff. We use Pre-commit to enforce correct formatting in new contributions. To automatically run locally the pre-commit checks before committing, install the custom pre-commit workflow:

bash pre-commit install

For contributors that do not run it locally, we use Pre-commit.CI to enforce formatting at the Github level.