Skip to content

Python: Declare every lazy namespace export in its type stub - #9750

Draft
Naveen Chatlapalli (1aifanatic) wants to merge 2 commits into
microsoft:mainfrom
1aifanatic:contrib/python-namespace-stub-drift
Draft

Naveen Chatlapalli (1aifanatic) wants to merge 2 commits into
microsoft:mainfrom
1aifanatic:contrib/python-namespace-stub-drift

Conversation

@1aifanatic

Copy link
Copy Markdown
Contributor

Motivation & Context

The agent_framework.<namespace> modules re-export connector classes lazily through _IMPORTS and __getattr__. Each has an __init__.pyi so type checkers see the same names. Four of them have drifted:

namespace exported at runtime, missing from the stub
agent_framework.anthropic RawClaudeAgent
agent_framework.foundry FoundryAgentOptions
agent_framework.orchestrations BaseGroupChatOrchestrator, GroupChatResponseReceivedEvent, OrchestrationState, TerminationCondition, clean_conversation_for_handoff, create_completion_message
agent_framework.hyperlight no __init__.pyi at all, so every export is Any

All of these imports work at runtime. For example, the RawClaudeAgent docstring itself shows from agent_framework.anthropic import RawClaudeAgent. On main, pyright 1.1.408 rejects the first three groups with "RawClaudeAgent" is unknown import symbol (8 errors for the names above).

Description & Review Guide

  • What are the major changes?
    • Add the missing names to the anthropic, foundry and orchestrations stubs.
    • Add agent_framework/hyperlight/__init__.pyi, following the monty stub.
    • Add packages/core/tests/core/test_namespace_stubs.py. For every namespace that declares _IMPORTS, it parses __init__.py and __init__.pyi with ast and checks three things: the stub exists, its imports and __all__ match _IMPORTS, and each name comes from the same distribution package. It needs no optional connector installed.
  • What is the impact of these changes? Type stubs only; runtime behavior is unchanged.
  • What do you want reviewers to focus on? Whether the test should live in core, as here, or with the release tooling.

Verification:

  • The new test fails on main for anthropic, foundry, hyperlight and orchestrations, and passes for all 22 namespaces with this change.
  • pyright on the probe imports goes from 8 errors to 0.
  • HyperlightCodeActProvider now resolves to its class instead of Any.
  • Every _IMPORTS name in every namespace resolves at runtime with all workspace packages installed.

Related Issue

N/A - trivial change: the stubs are meant to mirror _IMPORTS, and this adds the names they are missing without changing any runtime export.

AI Assistance

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

AI assistance details: Claude Code helped find the drift by comparing each namespace's _IMPORTS with its stub, write the stub updates and test, and draft this description.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • 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 or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

🤖 Generated with Claude Code

agent_framework.anthropic, .foundry and .orchestrations export names at
runtime that their __init__.pyi stubs omit, and .hyperlight has no stub, so
type checkers reject imports that work. Add the missing names, add a
hyperlight stub, and test that every lazy namespace's _IMPORTS matches its
stub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 27, 2026 12:35
@agent-framework-automation agent-framework-automation Bot added the python Usage: [Issues, PRs], Target: Python label Oct 27, 2026

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

The changes preserve runtime behavior, and the only remaining feedback is a minor test-helper organization issue.

1 open issue
What changed in this PR

This PR aligns Python’s lazy namespace type stubs with existing runtime exports, improving type-checker visibility without changing runtime behavior.

Changes:

  • Add missing exports to the Anthropic, Foundry, and orchestrations stubs.
  • Introduce the Hyperlight namespace stub.
  • Add static regression coverage for stub existence, exported names, and source-package alignment without requiring optional connectors.
File Description
python/​packages/​core/​tests/​core/​test_namespace_stubs.py Checks lazy namespace exports against their stubs.
python/​packages/​core/​agent_framework/​orchestrations/​__init__.pyi Declares six missing orchestration exports.
python/​packages/​core/​agent_framework/​hyperlight/​__init__.pyi Adds typing declarations for all six namespace exports.
python/​packages/​core/​agent_framework/​foundry/​__init__.pyi Exports FoundryAgentOptions.
python/​packages/​core/​agent_framework/​anthropic/​__init__.pyi Exports RawClaudeAgent.

Review effort: Balanced

This branch was previously deployed

1 inactive deployment
github-app-auth — 9282d1bb Deployed Nov 6, 2026 by 1aifanatic via add_label #27331
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.

2 participants