@pi-stef/azure-foundry

Azure Foundry and Azure OpenAI deployments as native Pi providers — config-driven, JSONC support, validation.

Overview

This package registers Azure Foundry and Azure OpenAI deployments as native Pi providers from a JSONC configuration file. Each deployment becomes a provider whose model IDs are selected as <deployment-id>/<model-id>.

Key features:

• Config-driven setup with JSONC support
• Two API modes: openai-completions and azure-openai-responses
• Custom headers support
• Multiple deployments per configuration
• Built-in validation and verification

Install

pi install npm:@pi-stef/azure-foundry

Start Pi once after installing. On first load, the extension creates:

~/.pi/azure-foundry/config.json
~/.pi/azure-foundry/config.schema.json

Configuration

Edit config.json, uncomment or add a deployment, and export the bearer-token env var named by apiKeyEnv.

export AZURE_API_KEY=...

Azure Foundry (openai-completions)

For Azure Foundry, use the modern OpenAI-compatible v1 endpoint:

{
  "id": "azure-foundry",
  "name": "Azure Foundry East US",
  "baseUrl": "https://<resource>.services.ai.azure.com/openai/v1/",
  "apiKeyEnv": "AZURE_API_KEY",
  "api": "openai-completions",
  "models": [
    {
      "id": "Kimi-K2.6",
      "name": "Kimi K2.6",
      "reasoning": false,
      "input": ["text"],
      "contextWindow": 128000,
      "maxTokens": 2048,
      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
    }
  ]
}

Azure OpenAI (azure-openai-responses)

Classic Azure OpenAI via azure-openai-responses:

{
  "id": "aoai-eastus",
  "name": "Azure OpenAI East US",
  "baseUrl": "https://my-aoai.openai.azure.com",
  "apiKeyEnv": "AZURE_OPENAI_API_KEY",
  "api": "azure-openai-responses",
  "models": [
    {
      "id": "o4-mini",
      "name": "o4-mini",
      "reasoning": true,
      "input": ["text"],
      "contextWindow": 200000,
      "maxTokens": 16000,
      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
    }
  ]
}

For azure-openai-responses, Pi normalizes the URL to <host>/openai/v1 and reads the API version from AZURE_OPENAI_API_VERSION, defaulting to v1. The host must end with .openai.azure.com or .cognitiveservices.azure.com.

Config Reference

Top-level shape:

{
  "$schema": "./config.schema.json",
  "deployments": []
}

Deployment fields:

| Field | Required | Notes | | --- | --- | --- | | id | Yes | Provider id. Lowercase letters, numbers, and hyphens. | | name | Yes | Display name. | | baseUrl | Yes | https:// endpoint. Rules depend on api. | | apiKeyEnv | Yes | Env-var name containing the bearer token. The secret is not stored in config. | | api | Yes | openai-completions or azure-openai-responses. | | authHeader | No | Defaults to true. Set false only if custom headers carry auth. | | headers | No | Map of header name to env-var name. Values must look like env-var names. | | models | Yes | One or more model entries. |

Multiple Deployments

{
  "deployments": [
    { "id": "foundry-east", "name": "Foundry East", "baseUrl": "https://east.services.ai.azure.com/openai/v1/", "apiKeyEnv": "AZURE_EAST_KEY", "api": "openai-completions", "models": [] },
    { "id": "foundry-west", "name": "Foundry West", "baseUrl": "https://west.services.ai.azure.com/openai/v1/", "apiKeyEnv": "AZURE_WEST_KEY", "api": "openai-completions", "models": [] },
    { "id": "aoai-eastus", "name": "AOAI East US", "baseUrl": "https://my-aoai.openai.azure.com", "apiKeyEnv": "AZURE_OPENAI_API_KEY", "api": "azure-openai-responses", "models": [] }
  ]
}

Custom Headers

"headers": {
  "api-key": "AZURE_HEADER_KEY",
  "x-ms-useragent": "AZURE_USER_AGENT"
}

Header values are env-var names. Pi resolves them at request time. If an env var is missing, Pi sends the literal configured string as a fallback, so keep config values as env-var names rather than secrets.

Verification

Run the package verifier after exporting the configured API key:

pnpm -F @pi-stef/azure-foundry verify

Use PI_AZURE_FOUNDRY_CONFIG=/path/to/config.json to verify a test config without touching the default file.

Common outputs:

| Output | Fix | | --- | --- | | 200 | The deployment is reachable. | | 401 | Check the env var named by apiKeyEnv. | | 404 | Check the model deployment id and base URL. | | timeout after 10s | Check network access, proxy, and endpoint host. |

Environment Variables

| Variable | Purpose | | --- | --- | | AZURE_API_KEY | Example bearer token env var for Azure Foundry deployments when apiKeyEnv is set to AZURE_API_KEY. | | PI_AZURE_FOUNDRY_CONFIG | Override config path for tests or alternate profiles. | | PI_AZURE_FOUNDRY_DEBUG | Set to 1 for debug logging. | | AZURE_OPENAI_API_VERSION | Optional Pi-side version for azure-openai-responses; defaults to v1. |

Troubleshooting

Authentication Fails

Check the env var named by apiKeyEnv is exported and contains the correct bearer token.

Model Not Found

Check the model deployment id and base URL. For azure-openai-responses, ensure the host ends with .openai.azure.com or .cognitiveservices.azure.com.

Timeout

Check network access, proxy, and endpoint host. Use PI_AZURE_FOUNDRY_DEBUG=1 for detailed logging.

Remove

pi remove @pi-stef/azure-foundry

Update

pi update @pi-stef/azure-foundry