Python: [BREAKING] Types API Review improvements (#3647)

* Replace Role and FinishReason classes with NewType + Literal

- Remove EnumLike metaclass from _types.py
- Replace Role class with NewType('Role', str) + RoleLiteral
- Replace FinishReason class with NewType('FinishReason', str) + FinishReasonLiteral
- Update all usages across codebase to use string literals
- Remove .value access patterns (direct string comparison now works)
- Add backward compatibility for legacy dict serialization format
- Update tests to reflect new string-based types

Addresses #3591, #3615

* Simplify ChatResponse and AgentResponse type hints (#3592)

- Remove overloads from ChatResponse.__init__
- Remove text parameter from ChatResponse.__init__
- Remove | dict[str, Any] from finish_reason and usage_details params
- Remove **kwargs from AgentResponse.__init__
- Both now accept ChatMessage | Sequence[ChatMessage] | None for messages
- Update docstrings and examples to reflect changes
- Fix tests that were using removed kwargs
- Fix Role type hint usage in ag-ui utils

* Remove text parameter from ChatResponseUpdate and AgentResponseUpdate (#3597)

- Remove text parameter from ChatResponseUpdate.__init__
- Remove text parameter from AgentResponseUpdate.__init__
- Remove **kwargs from both update classes
- Simplify contents parameter type to Sequence[Content] | None
- Update all usages to use contents=[Content.from_text(...)] pattern
- Fix imports in test files
- Update docstrings and examples

* Rename from_chat_response_updates to from_updates (#3593)

- ChatResponse.from_chat_response_updates → ChatResponse.from_updates
- ChatResponse.from_chat_response_generator → ChatResponse.from_update_generator
- AgentResponse.from_agent_run_response_updates → AgentResponse.from_updates

* Remove try_parse_value method from ChatResponse and AgentResponse (#3595)

- Remove try_parse_value method from ChatResponse
- Remove try_parse_value method from AgentResponse
- Remove try_parse_value calls from from_updates and from_update_generator methods
- Update samples to use try/except with response.value instead
- Update tests to use response.value pattern
- Users should now use response.value with try/except for safe parsing

* Add agent_id to AgentResponse and clarify author_name documentation (#3596)

- Add agent_id parameter to AgentResponse class
- Document that author_name is on ChatMessage objects, not responses
- Update ChatResponse docstring with author_name note
- Update AgentResponse docstring with author_name note

* Simplify ChatMessage.__init__ signature (#3618)

- Make contents a positional argument accepting Sequence[Content | str]
- Auto-convert strings in contents to TextContent
- Remove overloads, keep text kwarg for backward compatibility with serialization
- Update _parse_content_list to handle string items
- Update all usages across codebase to use new format: ChatMessage("role", ["text"])

* Allow Content as input on run and get_response

- Update prepare_messages and normalize_messages to accept Content
- Update type signatures in _agents.py and _clients.py
- Add tests for Content input handling

* Fix ChatMessage usage across packages and samples

Update all remaining ChatMessage(role=..., text=...) to use new
ChatMessage('role', ['text']) signature.

* Fix Role string usage and response format parsing

- Fix redis provider: remove .value access on string literals
- Fix durabletask ensure_response_format: set _response_format before accessing .value

* Fix ollama .value and ai_model_id issues, handle None in content list

- Fix ollama _chat_client: remove .value on string literals
- Fix ollama _chat_client: rename ai_model_id to model_id
- Fix _parse_content_list: skip None values gracefully

* Fix A2AAgent type signature to include Content

* Fix Role/FinishReason NewType dict annotations and improve test coverage to 95%

* Fix mypy errors for Role/FinishReason NewType usage

* Fix Role.TOOL and Role.ASSISTANT usage in _orchestrator_helpers.py

* Fix Role NewType usage in durabletask _models.py

python/packages/durabletask/tests/test_models.py

@@ -3,7 +3,6 @@
 """Unit tests for data models (RunRequest)."""
 
 import pytest
-from agent_framework import Role
 from pydantic import BaseModel
 
 from agent_framework_durabletask._models import RunRequest
@@ -22,7 +21,7 @@ class TestRunRequest:
 
         assert request.message == "Hello"
         assert request.correlation_id == "corr-001"
-        assert request.role == Role.USER
+        assert request.role == "user"
         assert request.response_format is None
         assert request.enable_tool_calls is True
         assert request.wait_for_response is True
@@ -33,7 +32,7 @@ class TestRunRequest:
         request = RunRequest(
             message="Hello",
             correlation_id="corr-002",
-            role=Role.SYSTEM,
+            role="system",
             response_format=schema,
             enable_tool_calls=False,
             wait_for_response=False,
@@ -41,7 +40,7 @@ class TestRunRequest:
 
         assert request.message == "Hello"
         assert request.correlation_id == "corr-002"
-        assert request.role == Role.SYSTEM
+        assert request.role == "system"
         assert request.response_format is schema
         assert request.enable_tool_calls is False
         assert request.wait_for_response is False
@@ -50,7 +49,7 @@ class TestRunRequest:
         """Ensure string role values are coerced into Role instances."""
         request = RunRequest(message="Hello", correlation_id="corr-003", role="system")  # type: ignore[arg-type]
 
-        assert request.role == Role.SYSTEM
+        assert request.role == "system"
 
     def test_to_dict_with_defaults(self) -> None:
         """Test to_dict with default values."""
@@ -71,7 +70,7 @@ class TestRunRequest:
         request = RunRequest(
             message="Hello",
             correlation_id="corr-005",
-            role=Role.ASSISTANT,
+            role="assistant",
             response_format=schema,
             enable_tool_calls=False,
             wait_for_response=False,
@@ -95,7 +94,7 @@ class TestRunRequest:
 
         assert request.message == "Hello"
         assert request.correlation_id == "corr-006"
-        assert request.role == Role.USER
+        assert request.role == "user"
         assert request.enable_tool_calls is True
         assert request.wait_for_response is True
 
@@ -122,7 +121,7 @@ class TestRunRequest:
 
         assert request.message == "Test"
         assert request.correlation_id == "corr-008"
-        assert request.role == Role.SYSTEM
+        assert request.role == "system"
         assert request.response_format is ModuleStructuredResponse
         assert request.enable_tool_calls is False
 
@@ -131,8 +130,8 @@ class TestRunRequest:
         data = {"message": "Test", "correlationId": "corr-009", "role": "reviewer"}
         request = RunRequest.from_dict(data)
 
-        assert request.role.value == "reviewer"
-        assert request.role != Role.USER
+        assert request.role == "reviewer"
+        assert request.role != "user"
 
     def test_from_dict_empty_message(self) -> None:
         """Test from_dict with empty message."""
@@ -140,7 +139,7 @@ class TestRunRequest:
 
         assert request.message == ""
         assert request.correlation_id == "corr-010"
-        assert request.role == Role.USER
+        assert request.role == "user"
 
     def test_from_dict_missing_correlation_id_raises(self) -> None:
         """Test from_dict raises when correlationId is missing."""
@@ -152,7 +151,7 @@ class TestRunRequest:
         original = RunRequest(
             message="Test message",
             correlation_id="corr-011",
-            role=Role.SYSTEM,
+            role="system",
             response_format=ModuleStructuredResponse,
             enable_tool_calls=False,
         )
@@ -232,7 +231,7 @@ class TestRunRequest:
         """Test round-trip to_dict and from_dict with correlationId."""
         original = RunRequest(
             message="Test message",
-            role=Role.SYSTEM,
+            role="system",
             correlation_id="corr-124",
         )
 
@@ -292,7 +291,7 @@ class TestRunRequest:
         """Test round-trip to_dict and from_dict with orchestration_id."""
         original = RunRequest(
             message="Test message",
-            role=Role.SYSTEM,
+            role="system",
             correlation_id="corr-129",
             orchestration_id="orch-123",
         )