@ivannxbt/ai-config 0.1.0

package/.agents/skills/microsoft-foundry/models/deploy-model/customize/EXAMPLES.md

@@ -0,0 +1,90 @@
+# customize Examples
+
+## Example 1: Basic Deployment with Defaults
+
+**Scenario:** Deploy gpt-4o accepting all defaults for quick setup.
+**Config:** gpt-4o / GlobalStandard / 10K TPM / Dynamic Quota enabled
+**Result:** Deployment `gpt-4o` created in ~2-3 min with auto-upgrade enabled.
+
+## Example 2: Production Deployment with Custom Capacity
+
+**Scenario:** Deploy gpt-4o for production with high throughput.
+**Config:** gpt-4o / GlobalStandard / 50K TPM / Dynamic Quota / Name: `gpt-4o-production`
+**Result:** 50K TPM (500 req/10s). Suitable for moderate-to-high traffic production apps.
+
+## Example 3: PTU Deployment for High-Volume Workload
+
+**Scenario:** Deploy gpt-4o with reserved capacity (PTU) for predictable workload.
+**Config:** gpt-4o / ProvisionedManaged / 200 PTU (min 50, max 1000) / Priority Processing enabled
+**PTU sizing:** 40K input + 20K output tokens/min → ~100 PTU estimated → 200 PTU recommended (2x headroom)
+**Result:** Guaranteed throughput, fixed monthly cost. Use case: customer service bots, document pipelines.
+
+## Example 4: Development Deployment with Standard SKU
+
+**Scenario:** Deploy gpt-4o-mini for dev/testing with minimal cost.
+**Config:** gpt-4o-mini / Standard / 1K TPM / Name: `gpt-4o-mini-dev`
+**Result:** 1K TPM, 10 req/10s. Minimal pay-per-use cost for development and prototyping.
+
+## Example 5: Spillover Configuration
+
+**Scenario:** Deploy gpt-4o with spillover to handle peak load overflow.
+**Config:** gpt-4o / GlobalStandard / 20K TPM / Dynamic Quota / Spillover → `gpt-4o-backup`
+**Result:** Primary handles up to 20K TPM; overflow auto-redirects to backup deployment.
+
+## Example 6: Anthropic Model Deployment (claude-sonnet-4-6)
+
+**Scenario:** Deploy claude-sonnet-4-6 with customized settings.
+**Config:** claude-sonnet-4-6 / GlobalStandard / capacity 1 (MaaS) / Industry: Healthcare / No RAI policy (Anthropic manages content filtering)
+**Result:** User selected "Healthcare" as industry → tenant country code (US) and org name fetched automatically → deployed via ARM REST API with `modelProviderData` in ~2 min.
+
+---
+
+## Comparison Matrix
+
+| Scenario | Model | SKU | Capacity | Dynamic Quota | Priority | Spillover | Use Case |
+|----------|-------|-----|----------|:---:|:---:|:---:|----------|
+| Ex 1 | gpt-4o | GlobalStandard | 10K TPM | ✓ | - | - | Quick setup |
+| Ex 2 | gpt-4o | GlobalStandard | 50K TPM | ✓ | - | - | Production |
+| Ex 3 | gpt-4o | ProvisionedManaged | 200 PTU | - | ✓ | - | Predictable workload |
+| Ex 4 | gpt-4o-mini | Standard | 1K TPM | - | - | - | Dev/testing |
+| Ex 5 | gpt-4o | GlobalStandard | 20K TPM | ✓ | - | ✓ | Peak load |
+| Ex 6 | claude-sonnet-4-6 | GlobalStandard | 1 (MaaS) | - | - | - | Anthropic model |
+
+## Common Patterns
+
+### Dev → Staging → Production
+
+| Stage | Model | SKU | Capacity | Extras |
+|-------|-------|-----|----------|--------|
+| Dev | gpt-4o-mini | Standard | 1K TPM | — |
+| Staging | gpt-4o | GlobalStandard | 10K TPM | — |
+| Production | gpt-4o | GlobalStandard | 50K TPM | Dynamic Quota + Spillover |
+
+### Cost Optimization
+
+- **High priority:** gpt-4o, ProvisionedManaged, 100 PTU, Priority Processing
+- **Low priority:** gpt-4o-mini, Standard, 5K TPM
+
+---
+
+## Tips and Best Practices
+
+**Capacity:** Start conservative → monitor with Azure Monitor → scale gradually → use spillover for peaks.
+
+**SKU Selection:** Standard for dev → GlobalStandard + dynamic quota for variable production → ProvisionedManaged (PTU) for predictable load.
+
+**Cost:** Right-size capacity; use gpt-4o-mini where possible (80-90% accuracy at lower cost); enable dynamic quota; consider PTU for consistent high-volume.
+
+**Versions:** Auto-upgrade recommended; test new versions in staging first; pin only if compatibility requires it.
+
+**Content Filtering:** Start with DefaultV2; use custom policies only for specific needs; monitor filtered requests.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `QuotaExceeded` | Check usage with `az cognitiveservices usage list`, reduce capacity, try different SKU, check other regions, or use the [quota skill](../../../quota/quota.md) to request an increase |
+| Version not available for SKU | Check `az cognitiveservices account list-models --query "[?name=='gpt-4o'].version"`, use latest |
+| Deployment name exists | Skill auto-generates unique name (e.g., `gpt-4o-2`), or specify custom name |

package/.agents/skills/microsoft-foundry/models/deploy-model/customize/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: customize
+description: "Interactive guided deployment flow for Azure OpenAI models with full customization control. Step-by-step selection of model version, SKU (GlobalStandard/Standard/ProvisionedManaged), capacity, RAI policy (content filter), and advanced options (dynamic quota, priority processing, spillover). USE FOR: custom deployment, customize model deployment, choose version, select SKU, set capacity, configure content filter, RAI policy, deployment options, detailed deployment, advanced deployment, PTU deployment, provisioned throughput. DO NOT USE FOR: quick deployment to optimal region (use preset)."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.0.0"
+---
+
+# Customize Model Deployment
+
+Interactive guided workflow for deploying Azure OpenAI models with full customization control over version, SKU, capacity, content filtering, and advanced options.
+
+## Quick Reference
+
+| Property | Description |
+|----------|-------------|
+| **Flow** | Interactive step-by-step guided deployment |
+| **Customization** | Version, SKU, Capacity, RAI Policy, Advanced Options |
+| **SKU Support** | GlobalStandard, Standard, ProvisionedManaged, DataZoneStandard |
+| **Best For** | Precise control over deployment configuration |
+| **Authentication** | Azure CLI (`az login`) |
+| **Tools** | Azure CLI, MCP tools (optional) |
+
+## When to Use This Skill
+
+Use this skill when you need **precise control** over deployment configuration:
+
+- ✅ **Choose specific model version** (not just latest)
+- ✅ **Select deployment SKU** (GlobalStandard vs Standard vs PTU)
+- ✅ **Set exact capacity** within available range
+- ✅ **Configure content filtering** (RAI policy selection)
+- ✅ **Enable advanced features** (dynamic quota, priority processing, spillover)
+- ✅ **PTU deployments** (Provisioned Throughput Units)
+
+**Alternative:** Use `preset` for quick deployment to the best available region with automatic configuration.
+
+### Comparison: customize vs preset
+
+| Feature | customize | preset |
+|---------|---------------------|----------------------------|
+| **Focus** | Full customization control | Optimal region selection |
+| **Version Selection** | User chooses from available | Uses latest automatically |
+| **SKU Selection** | User chooses (GlobalStandard/Standard/PTU) | GlobalStandard only |
+| **Capacity** | User specifies exact value | Auto-calculated (50% of available) |
+| **RAI Policy** | User selects from options | Default policy only |
+| **Region** | Current region first, falls back to all regions if no capacity | Checks capacity across all regions upfront |
+| **Use Case** | Precise deployment requirements | Quick deployment to best region |
+
+## Prerequisites
+
+- Azure subscription with Cognitive Services Contributor or Owner role
+- Azure AI Foundry project resource ID (format: `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}`)
+- Azure CLI installed and authenticated (`az login`)
+- Optional: Set `PROJECT_RESOURCE_ID` environment variable
+
+## Workflow Overview
+
+### Complete Flow (14 Phases)
+
+```
+1. Verify Authentication
+2. Get Project Resource ID
+3. Verify Project Exists
+4. Get Model Name (if not provided)
+5. List Model Versions → User Selects
+6. List SKUs for Version → User Selects
+7. Get Capacity Range → User Configures
+   7b. If no capacity: Cross-Region Fallback → Query all regions → User selects region/project
+8. List RAI Policies → User Selects
+9. Configure Advanced Options (if applicable)
+10. Configure Version Upgrade Policy
+11. Generate Deployment Name
+12. Review Configuration
+13. Execute Deployment & Monitor
+```
+
+### Fast Path (Defaults)
+
+If user accepts all defaults (latest version, GlobalStandard SKU, recommended capacity, default RAI policy, standard upgrade policy), deployment completes in ~5 interactions.
+
+---
+
+## Phase Summaries
+
+> ⚠️ **MUST READ:** Before executing any phase, load [references/customize-workflow.md](references/customize-workflow.md) for the full scripts and implementation details. The summaries below describe *what* each phase does — the reference file contains the *how* (CLI commands, quota patterns, capacity formulas, cross-region fallback logic).
+
+| Phase | Action | Key Details |
+|-------|--------|-------------|
+| **1. Verify Auth** | Check `az account show`; prompt `az login` if needed | Verify correct subscription is active |
+| **2. Get Project ID** | Read `PROJECT_RESOURCE_ID` env var or prompt user | ARM resource ID format required |
+| **3. Verify Project** | Parse resource ID, call `az cognitiveservices account show` | Extracts subscription, RG, account, project, region |
+| **4. Get Model** | List models via `az cognitiveservices account list-models` | User selects from available or enters custom name |
+| **5. Select Version** | Query versions for chosen model | Recommend latest; user picks from list |
+| **6. Select SKU** | Query model catalog + subscription quota, show only deployable SKUs | ⚠️ Never hardcode SKU lists — always query live data |
+| **7. Configure Capacity** | Query capacity API, validate min/max/step, user enters value | Cross-region fallback if no capacity in current region |
+| **8. Select RAI Policy** | Present content filter options | Default: `Microsoft.DefaultV2` |
+| **9. Advanced Options** | Dynamic quota (GlobalStandard), priority processing (PTU), spillover | SKU-dependent availability |
+| **10. Upgrade Policy** | Choose: OnceNewDefaultVersionAvailable / OnceCurrentVersionExpired / NoAutoUpgrade | Default: auto-upgrade on new default |
+| **11. Deployment Name** | Auto-generate unique name, allow custom override | Validates format: `^[\w.-]{2,64}$` |
+| **12. Review** | Display full config summary, confirm before proceeding | User approves or cancels |
+| **13. Deploy & Monitor** | `az cognitiveservices account deployment create`, poll status | Timeout after 5 min; show endpoint + portal link |
+
+
+---
+
+## Error Handling
+
+### Common Issues and Resolutions
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| **Model not found** | Invalid model name | List available models with `az cognitiveservices account list-models` |
+| **Version not available** | Version not supported for SKU | Select different version or SKU |
+| **Insufficient quota** | Capacity > available quota | Skill auto-searches all regions; fails only if no region has quota |
+| **SKU not supported** | SKU not available in region | Cross-region fallback searches other regions automatically |
+| **Capacity out of range** | Invalid capacity value | **PREVENTED**: Skill validates min/max/step at input (Phase 7) |
+| **Deployment name exists** | Name conflict | Auto-incremented name generation |
+| **Authentication failed** | Not logged in | Run `az login` |
+| **Permission denied** | Insufficient permissions | Assign Cognitive Services Contributor role |
+| **Capacity query fails** | API/permissions/network error | **DEPLOYMENT BLOCKED**: Will not proceed without valid quota data |
+
+### Troubleshooting Commands
+
+```bash
+# Check deployment status
+az cognitiveservices account deployment show --name <account> --resource-group <rg> --deployment-name <name>
+
+# List all deployments
+az cognitiveservices account deployment list --name <account> --resource-group <rg> -o table
+
+# Check quota usage
+az cognitiveservices usage list --name <account> --resource-group <rg>
+
+# Delete failed deployment
+az cognitiveservices account deployment delete --name <account> --resource-group <rg> --deployment-name <name>
+```
+
+---
+
+## Selection Guides & Advanced Topics
+
+> For SKU comparison tables, PTU sizing formulas, and advanced option details, load [references/customize-guides.md](references/customize-guides.md).
+
+**SKU selection:** GlobalStandard (production/HA) → Standard (dev/test) → ProvisionedManaged (high-volume/guaranteed throughput) → DataZoneStandard (data residency).
+
+**Capacity:** TPM-based SKUs range from 1K (dev) to 100K+ (large production). PTU-based use formula: `(Input TPM × 0.001) + (Output TPM × 0.002) + (Requests/min × 0.1)`.
+
+**Advanced options:** Dynamic quota (GlobalStandard only), priority processing (PTU only, extra cost), spillover (overflow to backup deployment).
+
+---
+
+## Related Skills
+
+- **preset** - Quick deployment to best region with automatic configuration
+- **microsoft-foundry** - Parent skill for all Azure AI Foundry operations
+- **[quota](../../../quota/quota.md)** — For quota viewing, increase requests, and troubleshooting quota errors, defer to this skill instead of duplicating guidance
+- **rbac** - Manage permissions and access control
+
+---
+
+## Notes
+
+- Set `PROJECT_RESOURCE_ID` environment variable to skip prompt
+- Not all SKUs available in all regions; capacity varies by subscription/region/model
+- Custom RAI policies can be configured in Azure Portal
+- Automatic version upgrades occur during maintenance windows
+- Use Azure Monitor and Application Insights for production deployments

package/.agents/skills/microsoft-foundry/models/deploy-model/customize/references/customize-guides.md

@@ -0,0 +1,124 @@
+# Customize Guides — Selection Guides & Advanced Topics
+
+> Reference for: `models/deploy-model/customize/SKILL.md`
+
+## Selection Guides
+
+### How to Choose SKU
+
+| SKU | Best For | Cost | Availability |
+|-----|----------|------|--------------|
+| **GlobalStandard** | Production, high availability | Medium | Multi-region |
+| **Standard** | Development, testing | Low | Single region |
+| **ProvisionedManaged** | High-volume, predictable workloads | Fixed (PTU) | Reserved capacity |
+| **DataZoneStandard** | Data residency requirements | Medium | Specific zones |
+
+**Decision Tree:**
+```
+Do you need guaranteed throughput?
+├─ Yes → ProvisionedManaged (PTU)
+└─ No → Do you need high availability?
+        ├─ Yes → GlobalStandard
+        └─ No → Standard
+```
+
+### How to Choose Capacity
+
+**For TPM-based SKUs (GlobalStandard, Standard):**
+
+| Workload | Recommended Capacity |
+|----------|---------------------|
+| Development/Testing | 1K - 5K TPM |
+| Small Production | 5K - 20K TPM |
+| Medium Production | 20K - 100K TPM |
+| Large Production | 100K+ TPM |
+
+**For PTU-based SKUs (ProvisionedManaged):**
+
+Use the PTU calculator based on:
+- Input tokens per minute
+- Output tokens per minute
+- Requests per minute
+
+**Capacity Planning Tips:**
+- Start with recommended capacity
+- Monitor usage and adjust
+- Enable dynamic quota for flexibility
+- Consider spillover for peak loads
+
+### How to Choose RAI Policy
+
+| Policy | Filtering Level | Use Case |
+|--------|----------------|----------|
+| **Microsoft.DefaultV2** | Balanced | Most applications |
+| **Microsoft.Prompt-Shield** | Enhanced | Security-sensitive apps |
+| **Custom** | Configurable | Specific requirements |
+
+**Recommendation:** Start with `Microsoft.DefaultV2` and adjust based on application needs.
+
+---
+
+## Advanced Topics
+
+### PTU (Provisioned Throughput Units) Deployments
+
+**What is PTU?**
+- Reserved capacity with guaranteed throughput
+- Measured in PTU units, not TPM
+- Fixed cost regardless of usage
+- Best for high-volume, predictable workloads
+
+**PTU Calculator:**
+
+```
+Estimated PTU = (Input TPM × 0.001) + (Output TPM × 0.002) + (Requests/min × 0.1)
+
+Example:
+- Input: 10,000 tokens/min
+- Output: 5,000 tokens/min
+- Requests: 100/min
+
+PTU = (10,000 × 0.001) + (5,000 × 0.002) + (100 × 0.1)
+    = 10 + 10 + 10
+    = 30 PTU
+```
+
+**PTU Deployment:**
+```bash
+az cognitiveservices account deployment create \
+  --name <account-name> \
+  --resource-group <resource-group> \
+  --deployment-name <deployment-name> \
+  --model-name <model-name> \
+  --model-version <version> \
+  --model-format "OpenAI" \
+  --sku-name "ProvisionedManaged" \
+  --sku-capacity 100  # PTU units
+```
+
+### Spillover Configuration
+
+**Spillover Workflow:**
+1. Primary deployment receives requests
+2. When capacity reached, requests overflow to spillover target
+3. Spillover target must be same model or compatible
+4. Configure via deployment properties
+
+**Best Practices:**
+- Use spillover for peak load handling
+- Spillover target should have sufficient capacity
+- Monitor both deployments
+- Test failover behavior
+
+### Priority Processing
+
+**What is Priority Processing?**
+- Prioritizes your requests during high load
+- Available for ProvisionedManaged SKU
+- Additional charges apply
+- Ensures consistent performance
+
+**When to Use:**
+- Mission-critical applications
+- SLA requirements
+- High-concurrency scenarios