Skip to content

Python: export the six orchestrations names the runtime already serves - #10170

Merged
Eduard van Valkenburg (eavanvalkenburg) merged 1 commit into
microsoft:mainfrom
lxcxjxhx:fix/orchestrations-stub-reexports
Nov 9, 2026
Merged

Eduard van Valkenburg (eavanvalkenburg) merged 1 commit into
microsoft:mainfrom
lxcxjxhx:fix/orchestrations-stub-reexports

Conversation

@lxcxjxhx

Copy link
Copy Markdown
Contributor

Motivation & Context

agent_framework/orchestrations/__init__.py is a lazy re-export namespace: it serves the names in its _IMPORTS list through __getattr__, and __init__.pyi declares the same surface to type checkers. The two lists disagree — six names exist at runtime but are absent from the stub:

BaseGroupChatOrchestrator
GroupChatResponseReceivedEvent
OrchestrationState
TerminationCondition
clean_conversation_for_handoff
create_completion_message

Consequence: from agent_framework.orchestrations import BaseGroupChatOrchestrator works when the extra is installed, but a type checker resolves the module through the .pyi and reports an unknown import symbol — so users who follow the orchestrations samples get a red squiggle on correct code, and anyone reading the stub concludes the API is smaller than it is.

Description & Review Guide

  • What are the major changes? Adds the six missing names to the stub's import block and __all__, in the same ASCII order the file already uses. Nothing else moves; the runtime module is untouched.
  • What is the impact of these changes? The stub describes the API the runtime already exposes. No behavior change at runtime (__init__.py is not touched), and the .pyi gains only names that agent_framework_orchestrations already exports.
  • What do you want reviewers to focus on? Whether the stub is meant to be a subset (e.g. only the "documented" names). If so, the runtime _IMPORTS list is the thing to trim instead — say which direction you want and I will send that.

Evidence:

$ python pr-work/_tools/stub_reexport_check.py .
stub-pairs=22  drift=1
   .../agent_framework/orchestrations  stub-only=[]  runtime-only=['BaseGroupChatOrchestrator',
       'GroupChatResponseReceivedEvent', 'OrchestrationState', 'TerminationCondition',
       'clean_conversation_for_handoff', 'create_completion_message']
# after the change
stub-pairs=22  drift=0

$ grep -n "TerminationCondition" python/packages/orchestrations/agent_framework_orchestrations/__init__.py
29:    TerminationCondition,
110:    "TerminationCondition",

The other five are defined in python/packages/orchestrations/agent_framework_orchestrations/:

_base_group_chat_orchestrator.py:58   TerminationCondition: TypeAlias = Callable[[list[Message]], bool | Awaitable[bool]]
_base_group_chat_orchestrator.py:74   GroupChatResponseReceivedEvent
_base_group_chat_orchestrator.py:129  BaseGroupChatOrchestrator
_orchestration_state.py:34            OrchestrationState
_orchestrator_helpers.py:22           clean_conversation_for_handoff
_orchestrator_helpers.py:71           create_completion_message

ruff check on the touched file: clean.

Related Issue

N/A - trivial change. One stub file, twelve added lines, no runtime code and no design decision; the alternative direction (trim _IMPORTS) is raised above rather than chosen silently.

AI Assistance

  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: the mismatch was found with a static check that compares each __init__.pyi __all__ against the sibling runtime _IMPORTS; the six definitions and the package-level export of TerminationCondition were then confirmed by hand with the greps above. The description was written from those results.

Contribution Checklist

  • The code builds clean without any errors or warnings — the stub parses, ruff check passes, and no runtime module changed.
  • All unit tests pass, and I have added new tests where possible — no test added: the file is a type stub, and the repository's stub coverage is enforced by tooling rather than unit tests.
  • The PR follows the Contribution Guidelines.
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change exception.
  • This is not a breaking change — it adds declarations for names that already exist.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are identified for the stub update declaring six existing runtime exports for type checkers.

No open issues 🎉

What changed in this PR

Aligns the orchestrations type stub with the API already exposed by the runtime, allowing type checkers to recognize six previously undeclared exports.

Changes:

  • Adds the six missing names to the stub’s import block and __all__, preserving ASCII ordering.
  • Leaves runtime code and behavior unchanged.
File Description
python/​packages/​core/​agent_framework/​orchestrations/​__init__.pyi Declares six existing runtime exports in the type-checking surface.

Review effort: Balanced

Merged via the queue into microsoft:main with commit 0c979ff Nov 9, 2026
55 checks passed

This branch was previously deployed

1 inactive deployment
github-app-auth — f63fd4f7 Deployed Nov 7, 2026 by lxcxjxhx via team_check #8942
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants