Python: Update docs for middleware layering refactor and Anthropic client split

[LEDazzio01]

Motivation and Context

Fixes #4789.

PR #4746 refactored the middleware layering in the Python SDK and split the Anthropic client into raw/public variants. This PR updates documentation artifacts to reflect those changes.

Description

python/packages/anthropic/AGENTS.md

• Added RawAnthropicClient to the main classes listing
• Added a "Client Architecture" section with an ASCII diagram showing the standard layer stack
• Updated import path examples to include RawAnthropicClient

python/packages/core/AGENTS.md

• Added a "Chat Client Layer Architecture" section documenting:
  • The standard layer ordering: FunctionInvocationLayer → ChatMiddlewareLayer → ChatTelemetryLayer → Raw/BaseChatClient
  • Key behaviors: chat middleware runs per inner model call (inside the function loop), chat middleware stays outside telemetry, per-call middleware routing via client_kwargs={"middleware": [...]}
  • The Raw vs Public client pattern that providers follow

Docs confirmed unchanged (no stale references found)

• docs/decisions/0007-agent-filtering-middleware.md — C#-focused ADR, no Python layer ordering references
• docs/decisions/0016-python-context-middleware.md — About context providers/hooks, no middleware layer references
• python/AGENTS.md — General index, no middleware-specific content
• No function_middleware references found in any markdown documentation

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
• Is this a breaking change? No — documentation only

[Copilot]

Pull request overview

Updates Python package documentation to reflect the middleware layering refactor and (intended) Anthropic raw/public client split described in #4746 / #4789.

Changes:

• Added a new “Chat Client Layer Architecture” section to python/packages/core/AGENTS.md describing the layer stack and per-call middleware routing.
• Expanded python/packages/anthropic/AGENTS.md with a “Client Architecture” section and updated class/import listings to mention a raw client.

Reviewed changes

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

File	Description
python/packages/core/AGENTS.md	Adds an architecture section documenting the chat client layer stack and per-call middleware routing.
python/packages/anthropic/AGENTS.md	Updates Anthropic package docs to describe client architecture and add raw/public client references.

[LEDazzio01]

Thanks for the thorough review, @copilot!

All 6 comments reference the same root cause: this docs PR intentionally documents the changes introduced by PR #4746

Specifically:

• RawAnthropicClient is introduced and exported by PR Python: [BREAKING] Refactor middleware layering and split Anthropic raw client #4746 (see the __init__.py diff)
• The middleware layer reordering (FunctionInvocationLayer → ChatMiddlewareLayer → ChatTelemetryLayer → Raw/Base) is the new ordering established by PR Python: [BREAKING] Refactor middleware layering and split Anthropic raw client #4746
• Chat middleware running per inner model call is confirmed by PR Python: [BREAKING] Refactor middleware layering and split Anthropic raw client #4746's tests (e.g., test_combined_middleware_with_tool_loop and test_run_level_chat_and_function_middleware_split_per_function_loop_round)

This PR was created to address issue #4789, which was filed as a follow-up docs task for PR #4746. It should be merged after #4746 lands.

I'll update the PR description to note this dependency explicitly.

[eavanvalkenburg]

Appreciate the enthousiasm, but that issue was supposed to go to our docs repo, so closing this.