@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