microsoft/mosaic-apim

microsoft/mosaic-apim

Description: Model Orchestration, Stewardship, Allocation, Insights, and Chargeback

Language: Python

License: MIT

Stars: 2

Forks: 1

Open issues: 0

Created: 2026-08-12T18:10:10Z

Pushed: 2026-09-05T19:41:41Z

Default branch: main

Fork: no

Archived: no

README:

MOSAIC

Model Orchestration, Stewardship, Allocation, Insights, and Chargeback

MOSAIC is a self-service control plane and administrator/developer experience for Azure API Management's AI gateway capabilities. It stores desired governance state, plans how that state should map to APIM, and presents telemetry from Azure Monitor. It does not proxy model traffic or replace APIM.

This release adds model publishing on top of gateway, model endpoint, and MCP server onboarding: administrators register Entra principals and MOSAIC access groups, bring an existing API Management service under MOSAIC, register the Azure OpenAI and Azure AI Foundry endpoints it fronts, see the models deployed on them — along with whether the gateway can actually call each one — register MCP servers directly to record the tools they declare, and then expose a chosen model through a gateway, all without reading policy XML or opening the Azure portal.

Publishing is the first thing MOSAIC writes to API Management. It writes only through a reviewed, deterministic plan and an explicit apply, only to a gateway an administrator has switched to manage, and it rolls back exactly what it created if a step fails. See [ADR 0010](docs/adr/0010-publishing-models-into-apim.md), which records what that cost.

Architecture and trust boundaries

flowchart LR
Admin[Administrator browser] -->|Entra token with Admin role| Web[MOSAIC web]
User[End-user browser] -->|Entra token with User role| Portal[MOSAIC portal]
Web -->|Bearer token| API[MOSAIC API]
Portal -->|Bearer token| API
API -->|Managed identity| Cosmos[(Cosmos DB desired and observed state)]
API -->|Secret URI only| KV[Key Vault]
API -. read-only ARM .-> Foundry[Registered Azure AI model endpoints]
API -->|read ARM, and write on explicit apply| APIM[Registered API Management gateways]
APIM -->|Runtime model traffic, gateway managed identity| Foundry
APIM --> Monitor[Azure Monitor / App Insights / Log Analytics]
API --> Monitor
Web --> Monitor
Portal --> Monitor

The administrator console and the end-user portal are separate applications with separate Entra registrations and separate app roles, so they are independently governable. The portal reaches only /api/v1/portal/*, and every route there is scoped to the caller's own token — none of them accept a subject or requester parameter. See [ADR 0008](docs/adr/0008-portal-identity-and-role-separation.md).

| Concern | Source of truth | MOSAIC responsibility | | --- | --- | --- | | Governance intent | Cosmos DB | Store tenant-scoped desired state and audit mutations | | Runtime traffic and enforcement | APIM | Observe and explain; write only through a reviewed plan and an explicit apply | | Identity objects and authentication | Microsoft Entra ID | Store object IDs only; validate tokens and app roles | | Credentials | Key Vault | Store secret URIs only, never secret values | | Foundry deployments | Existing Azure AI/Foundry resources | Enumerate deployed models read-only; report, never grant, the gateway's runtime access | | Traffic/token telemetry | Azure Monitor stack | Emit application telemetry; query/chargeback is deferred |

MOSAIC never silently substitutes in-memory data or local authentication in Azure. Both are explicit local/test modes and application startup rejects them when MOSAIC_ENVIRONMENT=azure.

What is implemented

• Python 3.12 FastAPI API with OpenAPI, structured JSON logging, Azure Monitor OpenTelemetry,

correlation IDs, anonymous /healthz and dependency-aware /readyz

• Entra issuer, audience, signature, tenant, expiry, and algorithm validation, with app-role

authorization decided per route: Admin for every administrative route, User for the end-user portal surface

• Principal, group, and membership CRUD with validation, stable errors, and audit events
• Multi-gateway onboarding: register any existing API Management service by resource ID, verify

access, and mirror its APIs, endpoints, products, subscriptions, users, groups, backends, and named value metadata into Cosmos

• Entitlements as desired state: grants to a user, group, or application over a model API, MCP

server, product, or model deployment; token and request limits; catalog visibility; access requests; and effective-access resolution that reports whether a grant arrived directly or through a group

• Model endpoint onboarding: register Azure OpenAI and Azure AI Foundry resources, verify MOSAIC's

control-plane access, discover the deployments and available models on them, and report — per registered gateway — whether that gateway's managed identity can actually call them

• MCP server registration: register a Model Context Protocol server by URL, connect to it as a

read-only client, and record the tools it declares — including the input schemas, output schemas, and behaviour annotations that API Management's management plane does not expose

• MCP servers already present in a registered gateway are detected and counted
• Plain-language policy view: policy XML is parsed in memory and reduced to a digest plus redacted

semantic facets, so administrators never see markup and MOSAIC never stores it

• AI surface detection that identifies which APIs and backends front large language models, across

Azure OpenAI, Azure AI Foundry, Azure AI inference, OpenAI, Anthropic, Google Vertex AI, and AWS Bedrock

• MCP server discovery, and import of selected model APIs and MCP servers from a synchronised

gateway into MOSAIC's own desired state

• Model publishing: expose an observed deployment through a gateway by creating its policy fragment,

backend, API, operations, API policy, product, product link, and subscription — through a persisted deterministic plan, an explicit apply, per-step results, and a rollback that deletes only the resources that apply created

• Async repository abstraction with explicit in-memory and Cosmos implementations
• React/TypeScript/Vite administrator console using Fluent UI, React Router, TanStack Query, and

MSAL, with responsive navigation and persisted light/dark/system themes

• Runtime browser configuration; Azure IDs and service URLs are not baked into the web image
• Typed APIM read and write...