feat(ai): make the AI platform reference architecture orderable

.agents/references/diagrams.md

@@ -93,6 +93,10 @@ in one diagram to a box in another without reading the label.
 | 🔌 | network, subnet |
 | ☸️ | Kubernetes cluster |
 | 🗄️ | container registry |
+| 👤 | end user, application team acting as a user |
+| 💬 | user-facing chat interface |
+| 🚪 | gateway, abstraction layer |
+| 📈 | observability, tracing, evaluation |
 | ⚙️ | CI/CD wiring |
 | 🔀 | git repository |
 | 🧠 | model serving / AI API |
@@ -105,7 +109,7 @@ a concept already listed.
 
 Copy the emoji straight from this table — several of them carry a **U+FE0F variation selector** that
 is invisible in the source but decides whether the glyph renders in colour. `☸ ⚙ 🗄 🗂 🛰` default to
-*text* presentation and come out as small monochrome symbols without it; `🏢 📁 🔑 🌐 🔌 🔀 🧠 🛬 📦`
+*text* presentation and come out as small monochrome symbols without it; `🏢 📁 🔑 🌐 🔌 🔀 🧠 🛬 📦 👤 💬 🚪 📈`
 are colour by default. If an icon renders monochrome in the SVG, it is missing the selector.
 
 The **same emoji with a different fill** is deliberate and useful: a green `🔀` repo inside the

AGENTS.md

@@ -338,7 +338,9 @@ getting-started steps, and shared responsibility matrix.
 ### Conventions
 
 - Folder name: `<cloud>-<capability>` (e.g. `azure-kubernetes`, `stackit-kubernetes`), with the
-  architecture itself in `README.md`.
+  architecture itself in `README.md`. Use `<capability>` alone (e.g. `ai-platform`) when the
+  architecture is genuinely multi-cloud — it lists several `cloudProviders` and its components are
+  cloud-agnostic, with each provider contributing only a small provider-specific module.
 - Logo: colocate as `logo.png` (or `logo.svg`) in the architecture folder, the same convention
   `buildingblock/logo.png` uses. The website generator copies it to
   `website/public/assets/reference-architecture-logos/<id>.png` — never add files there by hand,

modules/ai/README.md

@@ -0,0 +1,10 @@
+---
+name: AI
+description: meshStack integration with AI platforms puts a gateway in front of your model providers, so application teams call one OpenAI-compatible endpoint with a virtual key while the platform team keeps the provider credentials, the budgets and the spend records.
+category: ai
+benefits:
+  - Model Gateway
+  - Virtual Key Issuing
+  - Budget and Spend Tracking
+official: true
+---

modules/ai/azure-openai/buildingblock/README.md

@@ -0,0 +1,78 @@
+---
+name: Azure OpenAI Model Backend
+supportedPlatforms:
+  - ai
+description: Registers an Azure OpenAI deployment as a model backend on the LiteLLM gateway, scoped to the tenant's team.
+# The module talks only to the LiteLLM admin API. It creates nothing in Azure and receives the
+# Azure OpenAI endpoint, key and deployment name as static inputs, so there is no cloud-side setup
+# to perform ahead of time.
+requiresBackplane: false
+---
+
+# Azure OpenAI Model Backend Building Block
+
+This building block registers an existing Azure OpenAI deployment as a model entry on the LiteLLM
+gateway. It is the Azure entry in the model layer of the AI platform architecture, next to
+`stackit/model-serving` for STACKIT, and it is what makes the architecture's claim of two cloud
+providers true.
+
+The module is thin on purpose. It creates one `litellm_model` resource and no Azure resources at
+all, which is why it declares `requiresBackplane: false` and needs no Azure identity. The platform
+team creates the Azure OpenAI resource and its deployment once, outside this module, and passes the
+endpoint, the key and the deployment name in as static inputs.
+
+The `team_id` input scopes the entry to one LiteLLM team, so the gateway offers the model to that
+tenant alone and attributes its spend to that team. In the AI landing zone the team ID comes from
+the platform tenant ID that `ai/model-access` produces, so the application team fills in nothing.
+
+Azure OpenAI addresses a **deployment**, not a model. The provider joins `custom_llm_provider` and
+`base_model` into `azure/<base_model>`, so `azure_deployment_name` must carry the Azure deployment
+name rather than the underlying model name.
+
+Application teams keep calling the LiteLLM gateway. The Azure credential stays on the gateway, so
+the platform team can rotate it without a change on the application side.
+
+The `ncecere/litellm` provider is pinned to exactly `2.0.1`. This is a deliberate exception to the
+hub rule that provider constraints use `>=`, and `versions.tf` explains why.
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.12.0 |
+| <a name="requirement_litellm"></a> [litellm](#requirement\_litellm) | = 2.0.1 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [litellm_model.this](https://registry.terraform.io/providers/ncecere/litellm/2.0.1/docs/resources/model) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_azure_deployment_name"></a> [azure\_deployment\_name](#input\_azure\_deployment\_name) | Name of the model deployment in the Azure OpenAI resource, for example 'gpt-4o'. Azure routes on the deployment name, not on the model name. | `string` | n/a | yes |
+| <a name="input_azure_openai_api_key"></a> [azure\_openai\_api\_key](#input\_azure\_openai\_api\_key) | Key of the Azure OpenAI resource. LiteLLM stores it and sends it upstream in the 'api-key' header. | `string` | n/a | yes |
+| <a name="input_azure_openai_api_version"></a> [azure\_openai\_api\_version](#input\_azure\_openai\_api\_version) | Azure OpenAI data plane API version. '2024-10-21' is the latest dated GA version of the inference API. | `string` | `"2024-10-21"` | no |
+| <a name="input_azure_openai_endpoint"></a> [azure\_openai\_endpoint](#input\_azure\_openai\_endpoint) | Endpoint of the Azure OpenAI resource, for example 'https://my-aoai.openai.azure.com'. LiteLLM calls the deployment under this host. | `string` | n/a | yes |
+| <a name="input_litellm_api_base"></a> [litellm\_api\_base](#input\_litellm\_api\_base) | Base URL of the LiteLLM gateway, for example 'https://litellm.example.com'. The provider talks to the admin API under this URL. | `string` | n/a | yes |
+| <a name="input_litellm_api_key"></a> [litellm\_api\_key](#input\_litellm\_api\_key) | LiteLLM admin key the provider authenticates with. It needs permission to register models. | `string` | n/a | yes |
+| <a name="input_mode"></a> [mode](#input\_mode) | What the deployment is used for. LiteLLM accepts 'chat', 'completion', 'embedding', 'audio\_speech', 'audio\_transcription', 'image\_generation', 'video\_generation', 'batch' and 'rerank'. | `string` | `"chat"` | no |
+| <a name="input_model_name"></a> [model\_name](#input\_model\_name) | Name the model is offered under on the LiteLLM gateway. Application teams pass this name in the 'model' field of their requests. | `string` | n/a | yes |
+| <a name="input_team_id"></a> [team\_id](#input\_team\_id) | ID of the LiteLLM team the model is registered for. Only that team can call the model. Leave unset to register the model for the whole gateway. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_api_base"></a> [api\_base](#output\_api\_base) | OpenAI-compatible base URL of the LiteLLM gateway, including the '/v1' suffix. Calls to this model go here, not to the Azure endpoint. |
+| <a name="output_model_id"></a> [model\_id](#output\_model\_id) | ID LiteLLM gave the model entry. |
+| <a name="output_model_name"></a> [model\_name](#output\_model\_name) | Name to pass in the 'model' field of a request to the gateway. |
+| <a name="output_summary"></a> [summary](#output\_summary) | Summary with the model name and the endpoint to call it on. |
+<!-- END_TF_DOCS -->

modules/ai/azure-openai/buildingblock/SUMMARY.md.tftpl

@@ -0,0 +1,27 @@
+# Azure OpenAI Model: **${model_name}**
+
+## Details
+
+| Property | Value |
+|----------|-------|
+| **API Base URL** | `${api_base}` |
+| **Model name** | `${model_name}` |
+| **Azure deployment** | `${deployment_name}` |
+| **Azure endpoint** | `${azure_endpoint}` |
+| **Azure API version** | `${azure_api_version}` |
+| **Model ID** | `${model_id}` |
+
+## Calling the model
+
+Call the LiteLLM gateway, not the Azure endpoint. Send your own virtual key as a bearer token and
+pass the model name in the `model` field:
+
+```sh
+curl "${api_base}/chat/completions" \
+  -H "Authorization: Bearer $VIRTUAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "${model_name}", "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+The Azure credential stays on the gateway. Your application never sees it and never talks to Azure
+directly, so the platform team can rotate the credential without a change on your side.

modules/ai/azure-openai/buildingblock/main.tf

@@ -0,0 +1,24 @@
+locals {
+  # LiteLLM's OpenAI-compatible routes live under '/v1'. The gateway also answers without the
+  # prefix, but OpenAI client libraries expect it, so the output carries it.
+  api_base = "${trimsuffix(var.litellm_api_base, "/")}/v1"
+}
+
+resource "litellm_model" "this" {
+  model_name          = var.model_name
+  custom_llm_provider = "azure"
+
+  # The provider joins these two into '<custom_llm_provider>/<base_model>' and sends the result to
+  # LiteLLM. Azure OpenAI addresses a deployment, not a model, so base_model carries the Azure
+  # deployment name and the request goes to 'azure/<deployment name>'.
+  base_model = var.azure_deployment_name
+
+  model_api_base = var.azure_openai_endpoint
+  model_api_key  = var.azure_openai_api_key
+  api_version    = var.azure_openai_api_version
+  mode           = var.mode
+
+  # When a team ID is given, LiteLLM offers the model to that team alone. The gateway keeps one
+  # entry per tenant, and the spend of each entry is attributed to its team.
+  team_id = var.team_id
+}

modules/ai/azure-openai/buildingblock/outputs.tf

@@ -0,0 +1,26 @@
+output "model_name" {
+  value       = litellm_model.this.model_name
+  description = "Name to pass in the 'model' field of a request to the gateway."
+}
+
+output "model_id" {
+  value       = litellm_model.this.id
+  description = "ID LiteLLM gave the model entry."
+}
+
+output "api_base" {
+  value       = local.api_base
+  description = "OpenAI-compatible base URL of the LiteLLM gateway, including the '/v1' suffix. Calls to this model go here, not to the Azure endpoint."
+}
+
+output "summary" {
+  description = "Summary with the model name and the endpoint to call it on."
+  value = templatefile("${path.module}/SUMMARY.md.tftpl", {
+    model_name        = litellm_model.this.model_name
+    model_id          = litellm_model.this.id
+    api_base          = local.api_base
+    deployment_name   = var.azure_deployment_name
+    azure_endpoint    = var.azure_openai_endpoint
+    azure_api_version = var.azure_openai_api_version
+  })
+}

modules/ai/azure-openai/buildingblock/provider.tf

@@ -0,0 +1,4 @@
+provider "litellm" {
+  api_base = var.litellm_api_base
+  api_key  = var.litellm_api_key
+}

modules/ai/azure-openai/buildingblock/variables.tf

@@ -0,0 +1,49 @@
+variable "litellm_api_base" {
+  type        = string
+  description = "Base URL of the LiteLLM gateway, for example 'https://litellm.example.com'. The provider talks to the admin API under this URL."
+}
+
+variable "litellm_api_key" {
+  type        = string
+  sensitive   = true
+  description = "LiteLLM admin key the provider authenticates with. It needs permission to register models."
+}
+
+variable "azure_openai_endpoint" {
+  type        = string
+  description = "Endpoint of the Azure OpenAI resource, for example 'https://my-aoai.openai.azure.com'. LiteLLM calls the deployment under this host."
+}
+
+variable "azure_openai_api_key" {
+  type        = string
+  sensitive   = true
+  description = "Key of the Azure OpenAI resource. LiteLLM stores it and sends it upstream in the 'api-key' header."
+}
+
+variable "azure_openai_api_version" {
+  type        = string
+  default     = "2024-10-21"
+  description = "Azure OpenAI data plane API version. '2024-10-21' is the latest dated GA version of the inference API."
+}
+
+variable "azure_deployment_name" {
+  type        = string
+  description = "Name of the model deployment in the Azure OpenAI resource, for example 'gpt-4o'. Azure routes on the deployment name, not on the model name."
+}
+
+variable "model_name" {
+  type        = string
+  description = "Name the model is offered under on the LiteLLM gateway. Application teams pass this name in the 'model' field of their requests."
+}
+
+variable "mode" {
+  type        = string
+  default     = "chat"
+  description = "What the deployment is used for. LiteLLM accepts 'chat', 'completion', 'embedding', 'audio_speech', 'audio_transcription', 'image_generation', 'video_generation', 'batch' and 'rerank'."
+}
+
+variable "team_id" {
+  type        = string
+  default     = null
+  description = "ID of the LiteLLM team the model is registered for. Only that team can call the model. Leave unset to register the model for the whole gateway."
+}

modules/ai/azure-openai/buildingblock/versions.tf

@@ -0,0 +1,15 @@
+terraform {
+  required_version = ">= 1.12.0"
+
+  required_providers {
+    litellm = {
+      source = "ncecere/litellm"
+      # Exact pin, a deliberate exception to the hub rule that provider constraints use '>='.
+      # ncecere/litellm is a community provider with a single maintainer, and it has changed
+      # resource behaviour inside a minor release before: v1.2.0 replaced the id of litellm_key
+      # with a hash of the key. The same pin is used by modules/ai/model-access, so both modules
+      # move to a new provider release together, after a review of the changelog.
+      version = "= 2.0.1"
+    }
+  }
+}