chore: import upstream snapshot with attribution

python/.github/skills/python-development/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: python-development
+description: >
+  Coding standards, conventions, and patterns for developing Python code in the
+  Agent Framework repository. Use this when writing or modifying Python source
+  files in the python/ directory.
+---
+
+# Python Development Standards
+
+## File Header
+
+Every `.py` file must start with:
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+```
+
+## Type Annotations
+
+- Always specify return types and parameter types
+- Use `Type | None` instead of `Optional[Type]`
+- Use `from __future__ import annotations` to enable postponed evaluation
+- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)`
+- Use `Mapping` instead of `MutableMapping` for read-only input parameters
+- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods
+    But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes
+- Internal private helpers may be used across `agent_framework*` modules when intentional; use a targeted
+  `# pyright: ignore[reportPrivateUsage]` instead of making the helper public just to satisfy pyright.
+- Do not add trivial pass-through or one-line helper functions solely to appease typing. Prefer targeted ignores,
+  casts, or clearer annotations over adding runtime overhead without a design benefit.
+
+## Function Parameters
+
+- Positional parameters: up to 3 fully expected parameters
+- Use keyword-only arguments (after `*`) for optional parameters
+- Provide string-based overrides to avoid requiring extra imports:
+
+```python
+def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:
+    if isinstance(tool_mode, str):
+        tool_mode = ChatToolMode(tool_mode)
+```
+
+- Avoid shadowing built-ins (use `next_handler` instead of `next`)
+- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters
+
+## Docstrings
+
+Use Google-style docstrings for all public APIs:
+
+```python
+def equal(arg1: str, arg2: str) -> bool:
+    """Compares two strings and returns True if they are the same.
+
+    Args:
+        arg1: The first string to compare.
+        arg2: The second string to compare.
+
+    Returns:
+        True if the strings are the same, False otherwise.
+
+    Raises:
+        ValueError: If one of the strings is empty.
+    """
+```
+
+- Always document Agent Framework specific exceptions
+- Explicitly use `Keyword Args` when applicable
+- Only document standard Python exceptions when the condition is non-obvious
+
+## Import Structure
+
+```python
+# Core
+from agent_framework import Agent, Message, tool
+
+# Components
+from agent_framework.observability import enable_sensitive_telemetry
+
+# Connectors (lazy-loaded)
+from agent_framework.openai import OpenAIChatClient
+from agent_framework.foundry import FoundryChatClient
+```
+
+## Public API and Exports
+
+In `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit
+`__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid
+`from module import *`.
+
+Do not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a
+public import surface (for example, `agent_framework.observability`) should define `__all__`.
+
+```python
+__all__ = ["Agent", "Message", "ChatResponse"]
+
+from ._agents import Agent
+from ._types import Message, ChatResponse
+```
+
+Special case: the root `agent_framework/__init__.py` uses lazy runtime exports. For root public API changes:
+- Add the symbol to `_LAZY_MODULE_EXPORTS` and keep `_LAZY_EXPORTS` derived from it.
+- Keep the explicit runtime `__all__` synchronized; it is still required for `from agent_framework import *`.
+- Add the same public symbol to `agent_framework/__init__.pyi` so pyright, mypy, and editors see the typed surface.
+- Put runtime deprecation behavior in the owning module via that module's `__getattr__`; avoid root-level
+  special-case branches for individual deprecated exports.
+- Identity aliases are appropriate in `.pyi` stubs because they mark re-exported names for type checkers; avoid them
+  in runtime `.py` modules unless there is a specific compatibility reason.
+
+## Performance Guidelines
+
+- Cache expensive computations (e.g., JSON schema generation)
+- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths
+- Avoid redundant serialization — compute once, reuse
+
+## Style
+
+- Line length: 120 characters
+- Format only files you changed, not the entire codebase
+- Prefer attributes over inheritance when parameters are mostly the same
+- Async by default — assume everything is asynchronous
+
+## Naming Conventions for Connectors
+
+- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services
+- `_parse_<object>_from_<source>` for methods that process data from external services