Python: all: Review and standardize exception documentation

[eavanvalkenburg]

Objective

Review all exception usage and documentation across the Python agent framework to ensure consistency and completeness.

Background

As part of the Python API review (issue #2902, item 9), we identified a need to standardize exception documentation practices.

Tasks

1. Audit Current State

   • Review all raise statements across the codebase (546+ identified across 140 files)
   • Review all Raises: sections in docstrings (55 files currently have them)
   • Document current patterns and inconsistencies

2. Define Documentation Guidelines

   • Standard Python exceptions (TypeError, ValueError, KeyError, etc.): Only document when the condition is non-obvious or when it provides value to API users
   • Framework exceptions (AgentInitializationError, AgentExecutionException, etc.): Always document with clear descriptions
   • Format: Use standard Raises: ExceptionType: Description format

3. Update Documentation

   • Apply guidelines to all public API methods
   • Ensure consistency across the codebase
   • Focus on user-facing APIs first

4. Review Exception Types

   • Review custom exceptions in /packages/core/agent_framework/exceptions.py
   • Ensure appropriate exception types are used throughout
   • Consider if any new exception types are needed

Success Criteria

• Clear guidelines documented for when to document exceptions
• Consistent exception documentation across all public APIs
• All framework-defined exceptions are properly documented

Closes #2902 (item 9)