README

Azure OpenAI provider for the ubxty/core-ai stack. Microsoft Foundry v1 + traditional data-plane endpoints, multi-key failover, prompt caching, batch embeddings, structured output, and a complete set of CLI tools. One singleton (AzureManager), one facade (Azure), one configuration block (core-ai.azure_ai.*).

Table of contents

1. Why this package?
2. Installation
3. Configuration
4. Endpoint flavours
5. API versions
6. Multi-key failover
7. Quickstart
8. The AzureManager API
9. invoke() / converse() / converseStream()
10. The conversation() builder
11. Cost Optimisations (v2.1.x)
12. embed() — batch embeddings
13. Model catalogue
14. Provider filtering
15. Artisan commands
16. Events
17. Exceptions
18. Health check
19. Documentation
20. Testing
21. Contributing
22. Security
23. Changelog
24. License

Why this package?

ubxty/azure-ai is one of two providers built on the ubxty/core-ai abstraction (the other is ubxty/bedrock-ai). It concentrates everything Azure OpenAI-specific into a single Laravel-friendly package while inheriting:

• the retry trait (HasRetryLogic) with exponential backoff + Retry-After honouring,
• the response cache and embedding cache under core-ai.cache.*,
• the Idempotency-Key derivation,
• the conversation builder / token estimator / invocation logger.

So app code stays provider-neutral: Azure::invoke(...) and Bedrock::invoke(...) return arrays with the same shape; events are aliased to AiInvoked / AiKeyRotated / AiRateLimited; switching providers is a one-facade swap.

What this package adds on top:

• Two endpoint shapes in one client — traditional *.openai.azure.com data-plane and Microsoft Foundry v1 *.services.ai.azure.com/.../openai/v1 — both detected automatically from the endpoint URL.
• cache_control: { type: 'ephemeral' } markers injected at configured anchors (system, last_user) for Azure prompt caching.
• Per-deployment multi-key failover with Retry-After honouring and Bearer/api-key auth shimming.
• Batch embedding ingestion via the Azure OpenAI /embeddings route, with per-text SHA256 memoisation.
• Five artisan commands for chat, configuration, model listing, smoke test, and default-model management.

Installation

composer require ubxty/azure-ai

This pulls ubxty/core-ai ^2.1.3 transitively. The service provider is auto-discovered.

The package needs PHP 8.2+, Laravel 11 or 12, and an Azure subscription with at least one OpenAI model deployment. See docs/getting-started.md for the full setup including portal walkthrough and azure:configure wizard.

Configuration

The Azure block lives under core-ai.azure_ai.* in config/core-ai.php (consolidated in core-ai 2.0). Publish only if you want to customise:

php artisan vendor:publish --tag=core-ai-config

The minimal env-var setup:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=…
AZURE_OPENAI_API_VERSION=2024-10-21
AZURE_OPENAI_DEFAULT_MODEL=gpt-4o

For multi-key rotation, see Multi-key failover.

The full top-level layout:

'azure_ai' => [
    'default'  => 'default',                      // Connection name to use when none is specified
    'connections' => [
        'default' => [
            'keys' => [
                [
                    'label'      => 'Primary',
                    'endpoint'   => env('AZURE_OPENAI_ENDPOINT'),
                    'api_key'    => env('AZURE_OPENAI_API_KEY'),
                    'api_version' => env('AZURE_OPENAI_API_VERSION', '2024-10-21'),
                ],
            ],
        ],
    ],
    'defaults' => [
        'model'       => env('AZURE_OPENAI_DEFAULT_MODEL', ''),
        'image_model' => env('AZURE_OPENAI_DEFAULT_IMAGE_MODEL', ''),
    ],
    'retry' => [
        'max_retries' => 3,
        'base_delay'  => 2,                       // seconds, doubles each retry (capped by Retry-After)
    ],
    'cache' => [
        'models_ttl' => 3600,                     // Deployment catalogue cache (seconds)
        'response_ttl' => 0,                      // Memoised invoke/converse; reads core-ai.azure_ai.cache.response_ttl first, then core-ai.cache.response_ttl
        'embedding_ttl' => 604800,                // Embedding TTL (7 days); reads core-ai.azure_ai.cache.embedding_ttl first, then core-ai.cache.embedding_ttl
    ],
    'limits' => [
        'daily'   => null,                        // Hard cap in USD/day.  null disables.
        'monthly' => null,                        // Hard cap in USD/month.
    ],
    'prompt_caching' => [
        'points' => ['system', 'last_user'],      // Anchors for cache_control injection
    ],
    'providers' => [
        'disabled_providers'    => [],             // Globally disabled (e.g. ['Cohere'])
        'chat'  => ['disabled_providers' => []],
        'image' => ['disabled_providers' => []],
    ],
    'health_check' => [
        'enabled'   => false,
        'path'      => '/health/azure-openai',
        'middleware' => [],
    ],
    'logging' => [
        'channel' => env('LOG_CHANNEL_AI', null),  // null = use Laravel default
    ],
    'models' => [                                // Config-driven deployment catalogue
        'my-gpt-4o-deployment' => [
            'name'             => 'GPT-4o',
            'provider'         => 'OpenAI',
            'context_window'   => 128000,
            'max_tokens'       => 16384,
            'capabilities'     => ['text', 'vision'],
            'input_modalities' => ['text', 'image'],
            'is_active'        => true,
        ],
        // ...
    ],
],

Endpoint flavours

The client detects the endpoint flavour from the URL and routes accordingly:

The detection strips any trailing resource path:

https://resource.services.ai.azure.com/api/projects/p/openai/v1/chat/completions
                       ↓
base  = https://resource.services.ai.azure.com/api/projects/p/openai/v1
        normalised for the data plane to
        https://resource.services.ai.azure.com/api/projects/p

endpoints that look like the v1 flavour return an empty array from listDeployments() / listModels() if the AI Foundry project endpoint does not expose those routes — the package gracefully falls back to the configured default model.

See docs/endpoint-flavours.md for the regex detector, header rules, and a worked side-by-side comparison.

API versions

Each key can specify its own api_version. The default in AzureCredentialManager::normalizeKey() is 2024-06-01; the lazy default in AzureManager::embed() is 2024-10-21. Set per key:

'connections' => [
    'default' => [
        'keys' => [
            ['label' => 'Prod',  'endpoint' => '…', 'api_key' => '…', 'api_version' => '2024-10-21'],
            ['label' => 'Stage', 'endpoint' => '…', 'api_key' => '…', 'api_version' => '2024-06-01'],
        ],
    ],
],

Or via env (single-key mode):

AZURE_OPENAI_API_VERSION=2024-10-21

v1 (Foundry) endpoints ignore api_version — the URL has /v1/chat/completions with no ?api-version= query string.

Multi-key failover

Configure multiple endpoint + api_key + api_version tuples under connections.default.keys. The package rotates to the next key when the current one hits rate-limit or auth-failure (see docs/real-world-patterns.md §4 for failover patterns):

'connections' => [
    'default' => [
        'keys' => [
            [
                'label'       => 'Production',
                'endpoint'    => env('AZURE_OPENAI_ENDPOINT'),
                'api_key'     => env('AZURE_OPENAI_API_KEY'),
                'api_version' => env('AZURE_OPENAI_API_VERSION', '2024-10-21'),
            ],
            [
                'label'       => 'DR (different region)',
                'endpoint'    => env('AZURE_OPENAI_ENDPOINT_DR'),
                'api_key'     => env('AZURE_OPENAI_API_KEY_DR'),
                'api_version' => '2024-10-21',
            ],
        ],
    ],
],

Rotation triggers:

• 429 with retry budget exhausted on the current key.
• 401 (auth failure).

Total recovery before rotating:

• With Retry-After hint captured from the 429 header: usually 5-30 s.
• Without hint: exponential 2 s → 4 s → 8 s from retry.base_delay.

If all keys fail, AzureRateLimited fires and RateLimitException is thrown after every (keys[] × max_retries) combination is exhausted.

Quickstart

composer require ubxty/azure-ai
php artisan vendor:publish --tag=core-ai-config   # only if you want to customise
php artisan azure:configure                       # interactive wizard
php artisan azure:test                            # smoke test

In code:

use Ubxty\AzureAi\Facades\Azure;

// Single-turn
$result = Azure::invoke(
    modelId: 'gpt-4o',
    systemPrompt: 'You are a careful summariser.',
    userMessage: 'Q3 revenue was $4.2M, up 18% YoY.',
    maxTokens: 256,
    temperature: 0.2,
);

echo $result['response'];    // string
echo $result['cost'];        // USD, float
echo $result['input_tokens']; // int

Multi-turn:

$result = Azure::converse(
    modelId: 'gpt-4o',
    messages: [
        ['role' => 'user',      'content' => 'What is the capital of France?'],
        ['role' => 'assistant', 'content' => 'Paris.'],
        ['role' => 'user',      'content' => 'And Germany?'],
    ],
    systemPrompt: 'You are a geography expert.',
);

Streaming:

return Azure::converseStream(
    modelId: 'gpt-4o',
    messages: [['role' => 'user', 'content' => 'Tell me a story.']],
    onChunk: function (string $chunk) {
        echo $chunk;
        ob_flush();
    },
);

For SSE-backed streaming responses:

return Azure::converseStream(
    modelId: 'gpt-4o',
    messages: [['role' => 'user', 'content' => 'Tell me a story.']],
    onChunk: function (string $chunk) {
        echo $chunk;
    },
);

By DI:

class FooService
{
    public function __construct(private AzureManager $azure) {}

    public function handle(): array
    {
        return $this->azure->invoke('gpt-4o', '…', '…');
    }
}

The AzureManager API

AzureManager extends Ubxty\CoreAi\Manager\AbstractAiManager. Inherited methods (from the base contract):

Useful inherited helpers from core-ai (see ubxty/core-ai docs for full list):

• idempotencyKey($modelId, $content) — returns azure_openai_ai-<sha256(modelId|content)>. The Azure cache/key prefix is derived from cachePrefix() (which is strtolower(str_replace(' ', '_', platformName())) . '_ai').
• TokenEstimator::estimate($text) / TokenEstimator::estimateMultimodal($messages, $systemPrompt) — static pre-call token counters in Ubxty\CoreAi\Support\TokenEstimator.

Note: the following helpers exist on AbstractAiManager but are protected — not callable from app code:

• getConfiguredModels(?string $connection = null) — read the config models block, normalised.
• checkCostLimits($modelId, $pricing) — invoke guard; throws CostLimitExceededException if limits.daily or limits.monthly would be breached.
• trackCost($cost) — increment the spend ledger (uses an atomic lock to avoid races).

invoke() / converse() / converseStream()

invoke()

$response = Azure::invoke(
    modelId: 'gpt-4o',
    systemPrompt: 'You are a helpful assistant.',
    userMessage: 'Explain recursion in simple terms.',
    maxTokens: 512,
    temperature: 0.2,
);

// [
//     'response'      => 'Recursion is when a function calls itself…',
//     'input_tokens'  => 23,
//     'output_tokens' => 187,
//     'total_tokens'  => 210,
//     'cost'          => 0.0014,
//     'latency_ms'    => 1842,
//     'status'        => 'success',
//     'key_used'      => 'Primary',
//     'model_id'      => 'gpt-4o',
// ]

converse()

$response = Azure::converse(
    modelId: 'gpt-4o',
    messages: [
        ['role' => 'system',    'content' => 'You are a careful Q&A bot.'],
        ['role' => 'user',      'content' => 'What is 1 + 1?'],
        ['role' => 'assistant', 'content' => '2.'],
        ['role' => 'user',      'content' => 'Are you sure?'],
    ],
    systemPrompt: 'Override the system message…', // optional, overwrites any in $messages
    maxTokens: 256,
    temperature: 0.0,
);

Note: formatMessages() always prepends the explicit systemPrompt first, then iterates the messages array verbatim — system entries from the array are NOT dropped; both are sent to the provider.

converseStream()

$result = Azure::converseStream(
    modelId: 'gpt-4o',
    messages: [['role' => 'user', 'content' => 'Tell me a story.']],
    onChunk: function (string $chunk) {
        echo $chunk;
        ob_flush();
    },
);

After the stream completes, $result contains the full assembled response plus usage/latency.

Return shape (all three)

The conversation() builder

return Azure::conversation('gpt-4o')
    ->system('Translate the user message to Mandarin.')
    ->user('How do I open the trunk of a 2020 Camry?')
    ->maxTokens(2048)
    ->send();

Built-in fluent methods (inherited from Ubxty\CoreAi\Conversation\ConversationBuilder — model(), history(), schema(), userWithDocuments(), userWithAttachments(), image(), stream(), and getSchema() require ubxty/core-ai ^2.1.3):

Multimodal example

$result = Azure::conversation('gpt-4o')
    ->system('You extract line items from invoices.')
    ->user('Extract all items.')
    ->userWithImage('Anything I missed?', '/tmp/invoice.jpg')
    ->maxTokens(4096)
    ->send();

The image block is sent as image_url per the OpenAI vision wire format:

{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,…" } }

Documents don't have native OpenAI/Azure support — the package extracts text content and embeds it as a text part with [Document: name] prefix. For binary documents, the bytes are base64-encoded inline.

Cost Optimisations (v2.1.x)

Every lever in ubxty/core-ai is available to ubxty/azure-ai. Some Azure-specific behaviour:

See docs/caching-strategy.md for full reference with cost math.

Config

The TTL keys live under azure_ai.*, not at the top-level core-ai.cache.*. Set them in config/core-ai.php:

// config/core-ai.php
'azure_ai' => [
    'prompt_caching' => [
        'points' => ['system', 'last_user'],
    ],
    'cache' => [
        'response_ttl'  => 0,        // 0 = disabled; set to e.g. 3600 for memo
        'embedding_ttl' => 604800,   // 7 days
    ],
    // ...
],

The package does NOT bridge AZURE_OPENAI_PROMPT_CACHE_POINTS, AZURE_OPENAI_RESPONSE_CACHE_TTL, or AZURE_OPENAI_EMBEDDING_CACHE_TTL (no env(...) in the published config) — set the keys above directly. Publish with php artisan vendor:publish --tag=core-ai-config only if you want to customise.

Cost math (typical)

A gpt-4o call with a 600-token static system prompt + 100-token user message + 200-token output:

• Without caching: 700 input × $0.005/1k = $0.0035.
• With cache_control on system (subsequent calls within 5 min): 100 fresh × $0.005/1k + 600 cached × 10% × $0.005/1k = $0.0008.
• Network-blip retry: deduplicated server-side (same Idempotency-Key).

For embedding: a 1M-row corpus is single-shot cost if embedding_ttl ≥ 7 days. Re-runs are free.

embed() — batch embeddings

use Ubxty\AzureAi\Facades\Azure;

$corpus = [
    'The quick brown fox jumps over the lazy dog.',
    'To be or not to be, that is the question.',
];

$vectors = Azure::embed('text-embedding-3-small', $corpus, dimensions: 512);
// [
//     [0.0123, -0.0456, …],  // 512-dim
//     [0.0234, -0.0567, …],
// ]

Method signature

public function embed(
    string $deploymentId,
    array $texts,
    ?int $dimensions = null,
    ?string $user = null,
    ?string $connection = null,
): array;

Endpoint routing

The detection lives in AzureManager::isV1EndpointForEmbed() — same heuristic as the chat path.

Supported deployments

Cache

Per-row SHA256: azure_ai_embeddings_{sha256(deployment|dimensions|text)}. TTL: core-ai.azure_ai.cache.embedding_ttl first (falls back to core-ai.cache.embedding_ttl, default 7 days). See docs/embeddings.md for batch sizing, invalidation, and integration with vector stores (pgvector, Pinecone, etc.).

Model catalogue

Config-driven since 1.1.0 — no database. See docs/getting-started.md §4 for the full block. The package falls back to a live /openai/models call when the config block is empty; Foundry v1 endpoints return [] for that route and the call returns 0 models gracefully.

syncModels() since 1.1.0 is a no-op (returns the configured-model count); the live fetch fallback is fetchModels().

Provider filtering

'azure_ai' => [
    'providers' => [
        'disabled_providers' => [],                  // Globally disabled
        'chat'  => ['disabled_providers' => []],     // Picker/command only
        'image' => ['disabled_providers' => []],     // Picker/command only
    ],
],

Filter by Azure's group name (use az resource list --resource-type Microsoft.CognitiveServices/accounts/deployments -g … to discover). Example: hide legacy embeddings:

'providers' => [
    'disabled_providers' => ['Ada', 'GPT-3.5'],
],

Artisan commands

Events

AzureInvoked, AzureKeyRotated, AzureRateLimited extend the AiInvoked / AiKeyRotated / AiRateLimited events from ubxty/core-ai — they share the same payload shape so listeners work on both providers. See docs/real-world-patterns.md §10 for a full audit-log listener.

Payload of AzureInvoked:

new AzureInvoked(
    modelId: 'gpt-4o',
    inputTokens: 700,
    outputTokens: 200,
    cost: 0.0021,
    latencyMs: 1842,
    keyUsed: 'Primary',
);

Exceptions

All four extend Ubxty\CoreAi\Exceptions\AiException, which extends \RuntimeException.

Health check

'azure_ai' => [
    'health_check' => [
        'enabled'   => true,
        'path'      => '/health/azure-openai',
        'middleware' => ['auth:sanctum'],
    ],
],

Returns 200 { "status": "ok", "platform": "Azure OpenAI", "message": "…", "response_time_ms": 1234 } on success, 503 { "status": "error", "platform": "Azure OpenAI", "message": "…", "response_time_ms": 5678 } on failure. For Foundry v1 endpoints the check performs a minimal chat/completions POST instead of listDeployments() (which isn't exposed).

Documentation

The full documentation lives under docs/:

• docs/getting-started.md — Azure subscription + first call.
• docs/endpoint-flavours.md — Traditional vs Foundry v1, with URL detection rules and wire format differences.
• docs/caching-strategy.md — All 7 cost levers with worked cost math.
• docs/embeddings.md — embed() reference, batch sizing, vector-store integration.
• docs/real-world-patterns.md — 12 patterns distilled from real production usage.
• docs/faq.md — 25+ Q&A entries.

Testing

The package auto-discovers ubxty/core-ai (which provides the manager contract) and Laravel's facade helpers. To test without hitting the Azure API:

use Ubxty\AzureAi\Facades\Azure;

it('summarises a case', function () {
    $manager = Mockery::mock(AzureManager::class);
    $manager->shouldReceive('invoke')->andReturn([
        'response' => 'Sample response',
        'input_tokens' => 10,
        'output_tokens' => 5,
        'total_tokens' => 15,
        'cost' => 0.0001,
        'latency_ms' => 100,
        'status' => 'success',
        'key_used' => 'Mock',
        'model_id' => 'gpt-4o',
    ]);

    $this->app->instance(AzureManager::class, $manager);

    $response = $this->postJson('/api/summarise', ['text' => '…']);

    $response->assertOk();
});

For queue jobs that use Azure, replace the facade root with a fake returning a deterministic result. The package does not ship its own test utilities — rely on Laravel's Event::fake() and facade mocking.

Contributing

PRs are welcome. Conventions:

• Match the surrounding PSR-12 style.
• No new public methods without an entry in this README and (if non-trivial) the docs/ directory.
• Use Ravdeep Singh <info.ubxty@gmail.com> as the author for any commit. Do not add automated-tool trailers.
• Run composer validate before submitting.

Security

Vulnerabilities: email info.ubxty@gmail.com. Do not file public issues for security-relevant bugs.

The package never logs API keys, but endpoint URLs are logged at warning level on rotation. If your endpoint URL embeds sensitive routing data, scrub it before sharing output.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.