Python: Fix PropertySchema.to_json_schema() not recursing into nested array items / object properties

[exp-ouroborous]

Motivation and Context

PropertySchema.to_json_schema() renames kind → type (and drops empty enum placeholders) only in its top-level properties loop. Nested schemas — array items, nested object properties (which serialize in the named-list shape) — keep kind and empty enum, producing JSON Schema that OpenAI rejects ("schema must have a 'type' key"). Reproduced on 1.0.0rc2.

Description

• Fixes Python: [Bug]: PropertySchema.to_json_schema() doesn't recurse into array items — nested "kind" not renamed to "type", nested empty "enum" kept #7198
• Adds _normalize_nested_schemas / _normalize_schema_node: recursively applies the same conversion the top-level loop performs — kind → type, empty-enum removal, named-list properties → dict with a required array — at every depth.
• Minimal repro from the issue now produces "items": {"type": "string"} instead of "items": {"kind": "string", "enum": []}.
• New tests: array-of-strings items, array-of-objects with nested properties.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible (test_declarative_models.py: 98 passed)
• Is this a breaking change? No — previously-invalid output becomes valid; schemas without nesting are byte-identical.

[Copilot]

Pull request overview

This pull request addresses a Python bug in PropertySchema.to_json_schema() where nested schemas (array items, nested object properties) were not normalized (kind→type, empty enum removal), producing JSON Schema that structured-output providers reject. The change set also introduces a sizeable set of new “research” docs and a new .NET learning/sandbox project (dotnet/learn/AgentLearn), plus repo-level editor/gitignore tweaks.

Changes:

• Python: add recursive schema normalization for nested items / properties, and add regression tests.
• Add dotnet/learn/AgentLearn sample app + integration tests for learning framework workflows/HITL/OTel.
• Add research/ documentation and VS Code / gitignore convenience updates.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
research/README.md	Adds a top-level README describing the research/ folder.
research/python/agentic-capabilities.md	Adds Python agentic capabilities research document.
research/dotnet/agentic-capabilities.md	Adds .NET agentic capabilities research document.
research/agentic-capabilities-overview.md	Adds cross-language agentic capabilities overview research document.
python/packages/declarative/tests/test_declarative_models.py	Adds regression tests for nested schema normalization.
python/packages/declarative/agent_framework_declarative/_models.py	Implements recursive nested schema normalization in to_json_schema().
dotnet/samples/run.bash	Adds helper script to run a .NET sample with .env variables loaded.
dotnet/learn/README.md	Adds documentation for the new AgentLearn project.
dotnet/learn/Directory.Packages.props	Disables central package management within dotnet/learn.
dotnet/learn/Directory.Build.targets	Isolates learn projects from parent build targets.
dotnet/learn/Directory.Build.props	Isolates learn projects from parent build props.
dotnet/learn/CLAUDE.md	Adds project guidance/conventions for dotnet/learn.
dotnet/learn/AgentLearn/tests/integration/StoryGeneratorWorkflowTests.cs	Adds HITL workflow integration tests.
dotnet/learn/AgentLearn/tests/integration/MockChatClientHelper.cs	Adds shared mock IChatClient helper for integration tests.
dotnet/learn/AgentLearn/tests/integration/JokeWriterWorkflowTests.cs	Adds workflow integration tests for single/sequential/concurrent joke flows.
dotnet/learn/AgentLearn/tests/integration/AgentLearn.IntegrationTests.csproj	Adds integration test project definition.
dotnet/learn/AgentLearn/TaskKinds/StoryGenerator/StoryGenerator.http	Adds REST client requests for StoryGenerator.
dotnet/learn/AgentLearn/TaskKinds/StoryGenerator/StoryGenerator.cs	Adds StoryGenerator task kind (models/executors/agent/workflow/handler/DI).
dotnet/learn/AgentLearn/TaskKinds/JokeWriter/JokeWriter.http	Adds REST client requests for JokeWriter.
dotnet/learn/AgentLearn/TaskKinds/JokeWriter/JokeWriter.cs	Adds JokeWriter task kind (models/executors/agents/workflows/handler/DI).
dotnet/learn/AgentLearn/Services/ITaskHandler.cs	Adds task-handler abstraction for dispatching requests by kind.
dotnet/learn/AgentLearn/Services/ChatClientFactory.cs	Adds multi-provider IChatClient factory + mock client.
dotnet/learn/AgentLearn/run.sh	Adds dev runner that starts Jaeger and runs AgentLearn.
dotnet/learn/AgentLearn/Properties/launchSettings.json	Adds local launch profiles for AgentLearn.
dotnet/learn/AgentLearn/Program.cs	Wires DI, OpenTelemetry, DevUI, OpenAI-compatible endpoints, and controllers.
dotnet/learn/AgentLearn/Models/TaskResponse.cs	Adds /task response DTO.
dotnet/learn/AgentLearn/Models/TaskRequest.cs	Adds /task request DTO.
dotnet/learn/AgentLearn/Models/TaskKind.cs	Adds task-kind enum for dispatch.
dotnet/learn/AgentLearn/Models/LlmOptions.cs	Adds configuration model for LLM provider selection.
dotnet/learn/AgentLearn/Models/AgentMode.cs	Adds workflow mode enum.
dotnet/learn/AgentLearn/Extensions/AIAgentBuilderExtensions.cs	Adds tool-invocation logging middleware extension.
dotnet/learn/AgentLearn/Controllers/TaskController.cs	Adds /task controller that routes to ITaskHandlers.
dotnet/learn/AgentLearn/CLAUDE.md	Adds AgentLearn-specific contributor guidance.
dotnet/learn/AgentLearn/appsettings.json	Adds default configuration for AgentLearn.
dotnet/learn/AgentLearn/appsettings.Development.json	Adds dev configuration (incl. debug logging).
dotnet/learn/AgentLearn/AgentLearn.csproj	Adds AgentLearn project definition and package references.
dotnet/learn/AgentLearn.sln	Adds solution file for AgentLearn.
dotnet/learn/.gitignore	Adds ignore rules for local .env variants.
CLAUDE.md	Adds/updates repo-level contributor guidance for Claude.
.vscode/settings.json	Sets VS Code dotnet.defaultSolution.
.gitignore	Ignores .workspaces/ directory.

[exp-ouroborous]

Note for reviewers: the other review threads (research/, dotnet/learn/, .vscode/settings.json) referenced unrelated files that were accidentally included from a stale fork base — the branch has been rebuilt as a single commit on top of main and those files are no longer part of this PR (now 2 files: _models.py + its tests).

[exp-ouroborous]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/declarative/agent_framework_declarative
_models.py	510	25	95%	28, 31, 64, 69, 231, 236, 549, 615, 623, 627, 650, 676, 700, 728, 838, 900, 1008, 1134, 1136, 1138, 1140, 1142, 1144, 1148, 1150
TOTAL	44860	5105	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9141	33 💤	0 ❌	0 🔥	2m 21s ⏱️

[peibekwe]

@exp-ouroborous thank you for authoring this fix. Can you please take a look at the comment and the Pyright type-check error failures.

[exp-ouroborous]

@peibekwe Both addressed: the Pyright errors are fixed and the unreachable dict branch removed in 7e3cdeb, and moonbox3's additionalProperties: false request is done in 74c2fb1 (verified live against the Responses API — details in the thread). Package checks are green again.