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.cloud.ai4eosc.eu/ai4os/ai4-papi:prod
• registry.cloud.ai4eosc.eu/ai4os/ai4-papi:dev

The Dashboards pointing to those APIs are respectively:

• production Dashboard
• development Dashboard

Installation

External requirements

• Install Nomad to be able to interact with deployments. In addition, you will need to ask the administrator of the cluster for the proper access certificates and include the as environment variables.
• Install RCLONE to be able to connect with storages.
• Define the following environment variables. You can include them in a .env file in the root folder.

Once you are done with the preliminary steps, you can proceed to install the module:

pip install git+https://github.com/ai4eosc/ai4-papi.git

If you plan to use the module to develop, install instead in editable mode:

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:

   ai4papi-run --host 0.0.0.0 --port 8080

2. Using uvicorn directly (with the auto reload feature enabled if you are developing):

   uvicorn ai4papi.main:app --reload

3. Using our Makefile

   make run

4. From Dockerhub

   docker run  -v /local-path-to/nomad-certs:/home/nomad-certs -p 8080:80 registry.cloud.ai4eosc.eu/ai4os/ai4-papi:prod

5. Building from our Dockerfile.

   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:

   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> \
    --scope="openid profile email roles" \
    --redirect-uri "http://localhost:43985" \
    ai4os-keycloak

   To retrieve the <client-secret>, contact Ignacio Heredia. 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.

3. Add the following line to your .bashrc to start the agent automatically at startup (ref):

   eval `oidc-agent-service use` > /dev/null

4. Generate the OIDC token

   oidc-token ai4os-keycloak

5. Optional: You can check you have set everything up correctly by running:

   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:

  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

  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.

  Requirements

  For this you need to declare a ENV variable with the path of the Nomad cluster logs repo:

  export ACCOUNTING_PTH="/your/custom/path/ai4-accounting"

  It will serve the contents of the ai4-accounting/summaries folder.

The API methods can also be accessed by interacting directly with the Python package.

from types import SimpleNamespace

from ai4papi.routers.v1 import deployments

# Get all the user's deployments
deployments.modules.get_deployments(
    vos=['vo.ai4eosc.eu'],
    authorization=SimpleNamespace(
        credentials='your-OIDC-token'
    ),
)
#
# [{'job_ID': 'example',
#   'status': 'running',
#   'owner': '4545898984949741@someprovider',
#   'submit_time': '2023-01-13 11:36:16',
#   'alloc_ID': 'e6b24722-e332-185a-a9b6-817ce8d26f48',
#   'resources': {
#       'cpu_num': 2,
#       'gpu_num': 0,
#       'memoryMB': 8000,
#       'diskMB': 300
#   },
#   'endpoints': {
#       'deepaas': 'https://deepaas.xxx.xxx.xxx.xxx',
#       'monitor': 'https://monitor.xxx.xxx.xxx.xxx',
#       'ide': 'https://ide.xxx.xxx.xxx'
#   }
# }]

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. We use the following development stack:

• ruff for code formatting

• ty for type checking

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

  pre-commit install

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