Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
477bf14
Add post-call delivery configuration and related models to VoiceAgent…
howieleung Nov 3, 2026
5617188
Merge branch 'main' into feature/azure-ai-projects/vnext
howieleung Nov 4, 2026
b97869f
Merge branch 'main' into feature/azure-ai-projects/vnext
howieleung Nov 4, 2026
bc618b3
Update documentation and enhance Telephony provider options
howieleung Nov 4, 2026
ce6dcd7
Add live conversation operations to BetaVoiceAgents
howieleung Nov 4, 2026
28af106
Refactor code structure for improved readability and maintainability
howieleung Nov 4, 2026
fb0f1f4
Update CrossLanguageVersion and commit reference in configuration files
howieleung Nov 5, 2026
f82e399
[azure-ai-projects] Refresh voice agent recordings for sub_protocol (…
xitzhang Nov 5, 2026
80cb81e
Enhance model reference graph generation and reporting features
howieleung Nov 5, 2026
2a25938
Merge branch 'main' into feature/azure-ai-projects/vnext
howieleung Nov 5, 2026
bcb497a
Merge branch 'feature/azure-ai-projects/vnext' of https://github.com/…
howieleung Nov 5, 2026
9563727
Merge branch 'main' into feature/azure-ai-projects/vnext
howieleung Nov 5, 2026
b1a4661
Merge branch 'feature/azure-ai-projects/vnext' of https://github.com/…
howieleung Nov 5, 2026
81dcbb3
Add BetaVoiceAgentsLiveConversationsOperations and update public methods
howieleung Nov 5, 2026
32aa3d5
Bump version to 2.11.0 and update telephony call job paths in tests
howieleung Nov 5, 2026
bf14fa4
Update cspell configuration and timestamp format in GenerateModelRefe…
howieleung Nov 6, 2026
e9ea759
[azure-ai-projects] Add GPT Live WebSocket clients and samples (#49631)
xitzhang Nov 6, 2026
a68b1d5
Handle both asyncio and standard TimeoutError
howieleung Nov 6, 2026
52c8e24
Add TelephonyCampaignDatasetReference model and campaign operations
howieleung Nov 6, 2026
5649a95
Update CHANGELOG for version 2.11.0: refine feature descriptions, adj…
howieleung Nov 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .vscode/cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -593,6 +593,22 @@
"runid"
]
},
{
"filename": "sdk/ai/azure-ai-projects/**",
"words": [
"brise",
"flitz",
"harema",
"juni",
"nira",
"noeul",
"nuri",
"orgid",
"shida",
"unmute",
"unmuted"
]
},
{
"filename": [
"sdk/ai/azure-ai-projects/tests.yml",
Expand Down
8 changes: 4 additions & 4 deletions eng/emitter-package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion eng/emitter-package.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,6 @@
"@azure-tools/typespec-client-generator-core": "~0.73.0",
"@azure-tools/typespec-azure-portal-core": "~0.73.0",
"@azure-tools/typespec-liftr-base": "0.13.0",
"@azure-tools/openai-typespec": "1.28.0"
"@azure-tools/openai-typespec": "1.34.1"
}
}
Original file line number Diff line number Diff line change
@@ -1,123 +1,19 @@
---
name: azure-ai-projects-model-reference-graph
description: 'Generate and analyze the azure-ai-projects model reference graph from models/_models.py through model references, inheritance, runtime ownership, and public operation methods. WHEN: find which operations use a model; trace model dependencies; generate model-reference-graph.json; generate model-reference-trees.txt; investigate unused or orphaned generated models; assess whether a TypeSpec model may be removable. DO NOT USE FOR: deleting generated models automatically; packages other than azure-ai-projects. INVOKES: GenerateModelReferenceGraph.ps1, Python JSON validation, git diff checks.'
argument-hint: 'Optionally provide a model name to inspect after generating the graph'
description: 'Generate the azure-ai-projects model reference graph, trace operation dependencies, and identify unreferenced models. Writes validated, timestamped JSON and TXT reports to the user temp folder. Use for model-reference graphs, unused models, or TypeSpec removal investigation; not automatic model deletion or other packages.'
argument-hint: 'Optional model name'
---

# Generate the azure-ai-projects model reference graph

Run this workflow from `sdk\ai\azure-ai-projects`.

## 1. Check prerequisites

Confirm the package root and required files:

```powershell
git rev-parse --show-prefix
Test-Path .\.github\skills\azure-ai-projects-model-reference-graph\scripts\GenerateModelReferenceGraph.ps1
Test-Path .\azure\ai\projects\models\_models.py
```

The Git prefix must be `sdk/ai/azure-ai-projects/`. Stop and report the missing prerequisite if either file does not exist.

Prefer the active virtual environment's Python. Use `.\.venv\Scripts\python.exe` when it exists; otherwise use `python`.

## 2. Generate the graph

```powershell
.\.github\skills\azure-ai-projects-model-reference-graph\scripts\GenerateModelReferenceGraph.ps1 `
-PythonExecutable .\.venv\Scripts\python.exe
```

The script produces:

- `model-reference-graph.json`: structured data keyed by every class in `_models.py`.
- `model-reference-trees.txt`: readable reverse-reference trees rooted at every model.

Do not edit generated artifacts manually. Rerun the script after SDK emission or model changes.

## 3. Interpret the graph

For each model, follow children toward public operations:

```text
ChildModel
`- BaseModel [base class]
`- RequestOrResponseModel
`- SomeOperations.method [operation]
```

Edge and marker meanings:

- An unmarked model child directly references its parent through a field, annotation, decorator, or other model declaration.
- `[base class]` traverses from a derived model to its base type.
- `[derived class]` traverses from a base model to a derived type.
- `[operation]` is a public sync/async-deduplicated operation method.
- `[cycle]` stops a circular model relationship.
- `[already expanded]` identifies a shared branch already rendered under the same root.

The JSON entry additionally contains direct and indirect model referrers, bases, derived models, operation references, paths, public-export status, and non-operation references.

Some runtime ownership is not expressible through Python method annotations. The generator maintains an explicit, reviewed ownership table for WebSocket protocol messages, custom polling results, and flattened request bodies. Do not add a mapping based only on similar names. Verify the owning endpoint, handwritten patch, protocol documentation, or generated method implementation first.

## 4. Inspect a requested model

When the user supplies a model name, report:

1. Its base and derived models.
2. Models that reference it directly and indirectly.
3. Every public operation it reaches, distinguishing direct references from inherited or transitive paths.
4. At least one representative path from the operation to the requested model.
5. Non-operation references from patches, tests, or samples.

Use PowerShell for a focused JSON lookup:

```powershell
$graph = Get-Content .\model-reference-graph.json -Raw | ConvertFrom-Json -AsHashtable
$graph.models['<ModelName>'] | ConvertTo-Json -Depth 10
```

## 5. Validate generated artifacts

Run all checks after generation:

```powershell
$tokens = $null
$errors = $null
[System.Management.Automation.Language.Parser]::ParseFile(
(Resolve-Path '.\.github\skills\azure-ai-projects-model-reference-graph\scripts\GenerateModelReferenceGraph.ps1'),
[ref]$tokens,
[ref]$errors
) | Out-Null
if ($errors.Count) { throw ($errors.Message -join [Environment]::NewLine) }

python -m json.tool .\model-reference-graph.json > $null
git diff --check -- .\.github\skills\azure-ai-projects-model-reference-graph\scripts\GenerateModelReferenceGraph.ps1 .\model-reference-graph.json .\model-reference-trees.txt
```

Also verify the summary against the structured graph:
Run from `sdk\ai\azure-ai-projects`:

```powershell
$graph = Get-Content .\model-reference-graph.json -Raw | ConvertFrom-Json -AsHashtable
$withoutOperations = @($graph.models.GetEnumerator() | Where-Object { $_.Value.pathsToOperations.Count -eq 0 })
if ($withoutOperations.Count -ne $graph.metadata.modelsWithoutOperationPaths) {
throw 'The tree summary does not match the structured graph.'
}
.\.github\skills\azure-ai-projects-model-reference-graph\scripts\GenerateModelReferenceGraph.ps1
```

## 6. Apply removal safeguards

Operation reachability is not proof that a model is safe or unsafe to remove. Before proposing removal, verify all of the following:

- Public export status in `models/__init__.py`.
- References from `_patch.py`, `_unions.py`, samples, and tests.
- Base classes, derived classes, and discriminator registration.
- Runtime protocol roles such as WebSocket events and LRO polling bodies.
- The corresponding TypeSpec declaration and all TypeSpec references.
- API review impact after regenerating the SDK.

Never delete generated classes directly from `_models.py`. Remove or correct the TypeSpec source, regenerate the SDK, rerun this skill, and run package validation.

## 7. Report results
Add `-ModelName '<ModelName>'` when inspecting a specific model.

Report the model count, models with and without operation paths, requested model paths, explicit runtime ownership mappings used, and validation results. Clearly label static-analysis limitations and any model requiring TypeSpec or runtime review.
The script handles prerequisites, Python selection, report generation, validation,
and summaries. Report its results and both absolute output paths.
Unreferenced models require TypeSpec/runtime/API review, not automatic deletion.
Loading
Loading