14  Environment Setup and Configuration

Authors

Stephen Obundah Nwobike

R.Andres Castaneda

15 Environment Setup and Configuration

Once your ITSAI on-boarding request has been approved and uv is installed, it’s time to configure credentials and verify your first API call.

Reminder — two different credentials:

  1. Artifactory identity token — used only to download the itsai-platform SDK from the internal package repository.
  2. mAI Factory access token — used to call the AI models. For Desktop Access there is no static key; the SDK obtains it via an interactive browser login (covered below).

15.1 Step 1: Generate Your Artifactory Token

This token lets uv install packages from the World Bank’s internal JFrog repository.

15.1.1 Access the Artifactory Login Page

Troubleshooting: HTTP 400 Bad Request

If the OpenID OAuth login returns an HTTP 400 Bad Request error:

  1. Confirm that GlobalProtect is connected to the correct VPN gateway. Unless you are in the DC office and connected to the bluemarlin WiFi network, use the US East gateway.
  2. Confirm that your ITSAI platform onboarding request has been approved. Access may not work while the request is still pending.
  3. Clear your browser’s temporary files and cookies, close the browser, and try signing in again.
  4. If the error persists after completing these checks, contact ITS for assistance and include the error message and your onboarding request or ticket number.

15.1.2 Generate Your Access Token

  • Navigate to the itsai-platform repository.
  • Click “Set Me Up”, locate the Client drop-down, and change the selection from Poetry to Pip.
  • You may see the message “You do not have deploy permissions to this repository.” You can safely ignore it because deploy permissions are not required to generate a token or install the package.
  • Generate a new token using “Get token & Generate Instructions”.

15.2 Step 2: Configure the Artifactory Index URL

Copy your-username and your-access-token from your JFrog setup. In your-username, replace spaces with %20 (e.g., John Doe → john%20doe).

The UV_INDEX environment variable tells uv where to find the internal package repository. You can set it temporarily (per terminal session) or permanently (in your shell profile).

$env:UV_INDEX = "https://your-username:your-access-token@artifactory.worldbank.org/artifactory/api/pypi/itsdt-pypi-virtual/simple"

Verify:

echo $env:UV_INDEX

To persist across terminal sessions, add the $env:UV_INDEX = ... line to your PowerShell profile:

notepad $PROFILE

Paste the $env:UV_INDEX line, save, and restart your terminal.

export UV_INDEX="https://your-username:your-access-token@artifactory.worldbank.org/artifactory/api/pypi/itsdt-pypi-virtual/simple"

Verify (the export command produces no visible output on success):

echo $UV_INDEX

To persist across terminal sessions:

  1. Open your shell profile: nano ~/.zshrc
  2. Paste the export line at the bottom of the file.
  3. Save and exit: Ctrl+O, then Enter, then Ctrl+X.
  4. Reload in the current terminal: source ~/.zshrc

From now on, every new terminal window will automatically have UV_INDEX set.

Security note: Your shell profile (or .env file) will contain the token in plain text. Do not share your user account, and never commit the token into any code repository. Regenerate the token in Artifactory if you ever suspect it has been exposed.

15.3 Step 3: Install the itsai-platform Package

With UV_INDEX set, create a project environment and install the SDK:

uv init          # if there is no pyproject.toml in the current directory
uv add itsai-platform pyjwt
uv init          # if there is no pyproject.toml in the current directory
uv add itsai-platform pyjwt

15.4 Step 4: Verify Desktop Authentication

This is the natural next step after installing itsai-platform. Once this runs successfully, you are onboarded and authenticated, and ready to use mAI Factory APIs.

Before running the authentication script, make sure your Python virtual environment is activated:

venv\Scripts\activate
source .venv/bin/activate

Then run:

# desktop_auth.py
from itsai.platform.authentication import DesktopToken

token_provider = DesktopToken()
access_token = token_provider.get_token(env="DEV_DESKTOP")  # "DEV_DESKTOP", "QA_DESKTOP", "PROD_DESKTOP"
print("Authentication successful!")

The first call opens a browser window prompting you to log in with your WBG credentials. Once authenticated, the token is cached and auto-refreshes on later calls.

Environment strings: Use "DEV_DESKTOP" for testing and proof-of-concept work. The QA and PROD equivalents ("QA_DESKTOP", "PROD_DESKTOP") require additional app registration under an ACN.

15.5 Step 5: Health Check

Before making a real model call, confirm the gateway is reachable:

GET https://azapimdev.worldbank.org/conversationalai/platform/health/

Expected response: {"status": "healthy"}

15.6 Step 6: Test an mAI Factory API Call

After the authentication test prints Authentication successful!, run this small end-to-end request to confirm that your account can call a model through mAI Factory:

# test_maifactory.py
from itsai.platform.authentication import DesktopToken
from openai import AzureOpenAI

token_provider = DesktopToken()

client = AzureOpenAI(
    azure_endpoint="https://azapimdev.worldbank.org/conversationalai/v2/",
    api_version="2025-04-01-preview",
    azure_ad_token_provider=lambda: token_provider.get_token(env="DEV_DESKTOP"),
)

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly: mAI Factory API call successful",
        }
    ],
    max_tokens=20,
)

print(response.choices[0].message.content)

If the request succeeds, the response should be:

mAI Factory API call successful

This confirms both desktop authentication and model access. If authentication succeeds in Step 4 but this request fails, record the HTTP status code and error message when contacting the ITSAI platform team; never include the access token.

15.7 Keeping API Access Persistent

The setup above works per-project. If you want mAI Factory access available automatically in every new project without repeating the configuration, you can make the environment persistent.

15.7.2 Option B: Shared virtual environment

Create a single virtual environment outside any project folder and activate it whenever you need mAI Factory access:

python -m venv C:\Users\<username>\venvs\mai-factory
C:\Users\<username>\venvs\mai-factory\Scripts\activate
uv pip install --extra-index-url $env:UV_INDEX itsai-platform pyjwt openai
python3 -m venv ~/venvs/mai-factory
source ~/venvs/mai-factory/bin/activate
uv pip install --extra-index-url "$UV_INDEX" itsai-platform pyjwt openai

You can add the activate line to your shell profile to have it load automatically, or create a short alias:

function mai-activate { & "C:\Users\<username>\venvs\mai-factory\Scripts\activate" }
alias mai-activate="source ~/venvs/mai-factory/bin/activate"

15.8 Making API Calls Outside the SDK

Once authenticated, you can also call the mAI Factory API directly with httr (R), requests (Python), or any HTTP client. The key elements are:

Component Value
Base URL (DEV) https://azapimdev.worldbank.org/conversationalai/v2/openai/deployments
URL structure {base_url}/{model}/chat/completions?api-version={version}
Auth header Authorization: Bearer {your-access-token}
Required audit headers x-source-type: interactive, x-team-name: pip
API version 2025-01-01-preview (or 2025-04-01-preview)

For a first test, gpt-4.1-mini is a lightweight, low-cost model to verify your pipeline works end to end.

Example endpoints beyond Azure OpenAI:

  • Gemini chat: /platform/gemini/chat/
  • Claude via Bedrock: /bedrock/model/{model_id}/converse

15.9 Troubleshooting Checklist

If a call fails, check:

If everything checks out and it’s still failing, this likely points to an onboarding/permissions issue rather than a code issue.

15.10 Getting Further Help