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/mem0/agent_framework_mem0/_provider.py

@@ -121,9 +121,9 @@ class Mem0Provider(ContextProvider):
         messages_list = [*request_messages_list, *response_messages_list]
 
         messages: list[dict[str, str]] = [
-            {"role": message.role.value, "content": message.text}
+            {"role": message.role, "content": message.text}
             for message in messages_list
-            if message.role.value in {"user", "assistant", "system"} and message.text and message.text.strip()
+            if message.role in {"user", "assistant", "system"} and message.text and message.text.strip()
         ]
 
         if messages:
@@ -176,7 +176,7 @@ class Mem0Provider(ContextProvider):
         line_separated_memories = "\n".join(memory.get("memory", "") for memory in memories)
 
         return Context(
-            messages=[ChatMessage(role="user", text=f"{self.context_prompt}\n{line_separated_memories}")]
+            messages=[ChatMessage("user", [f"{self.context_prompt}\n{line_separated_memories}"])]
             if line_separated_memories
             else None
         )

python/packages/mem0/tests/test_mem0_context_provider.py

@@ -7,7 +7,7 @@ import sys
 from unittest.mock import AsyncMock, patch
 
 import pytest
-from agent_framework import ChatMessage, Content, Context, Role
+from agent_framework import ChatMessage, Content, Context
 from agent_framework.exceptions import ServiceInitializationError
 from agent_framework.mem0 import Mem0Provider
 
@@ -36,9 +36,9 @@ def mock_mem0_client() -> AsyncMock:
 def sample_messages() -> list[ChatMessage]:
     """Create sample chat messages for testing."""
     return [
-        ChatMessage(role=Role.USER, text="Hello, how are you?"),
-        ChatMessage(role=Role.ASSISTANT, text="I'm doing well, thank you!"),
-        ChatMessage(role=Role.SYSTEM, text="You are a helpful assistant"),
+        ChatMessage("user", ["Hello, how are you?"]),
+        ChatMessage("assistant", ["I'm doing well, thank you!"]),
+        ChatMessage("system", ["You are a helpful assistant"]),
     ]
 
 
@@ -191,7 +191,7 @@ class TestMem0ProviderMessagesAdding:
     async def test_messages_adding_fails_without_filters(self, mock_mem0_client: AsyncMock) -> None:
         """Test that invoked fails when no filters are provided."""
         provider = Mem0Provider(mem0_client=mock_mem0_client)
-        message = ChatMessage(role=Role.USER, text="Hello!")
+        message = ChatMessage("user", ["Hello!"])
 
         with pytest.raises(ServiceInitializationError) as exc_info:
             await provider.invoked(message)
@@ -201,7 +201,7 @@ class TestMem0ProviderMessagesAdding:
     async def test_messages_adding_single_message(self, mock_mem0_client: AsyncMock) -> None:
         """Test adding a single message."""
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
-        message = ChatMessage(role=Role.USER, text="Hello!")
+        message = ChatMessage("user", ["Hello!"])
 
         await provider.invoked(message)
 
@@ -288,9 +288,9 @@ class TestMem0ProviderMessagesAdding:
         """Test that empty or invalid messages are filtered out."""
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
         messages = [
-            ChatMessage(role=Role.USER, text=""),  # Empty text
-            ChatMessage(role=Role.USER, text="   "),  # Whitespace only
-            ChatMessage(role=Role.USER, text="Valid message"),
+            ChatMessage("user", [""]),  # Empty text
+            ChatMessage("user", ["   "]),  # Whitespace only
+            ChatMessage("user", ["Valid message"]),
         ]
 
         await provider.invoked(messages)
@@ -303,8 +303,8 @@ class TestMem0ProviderMessagesAdding:
         """Test that mem0 client is not called when no valid messages exist."""
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
         messages = [
-            ChatMessage(role=Role.USER, text=""),
-            ChatMessage(role=Role.USER, text="   "),
+            ChatMessage("user", [""]),
+            ChatMessage("user", ["   "]),
         ]
 
         await provider.invoked(messages)
@@ -318,7 +318,7 @@ class TestMem0ProviderModelInvoking:
     async def test_model_invoking_fails_without_filters(self, mock_mem0_client: AsyncMock) -> None:
         """Test that invoking fails when no filters are provided."""
         provider = Mem0Provider(mem0_client=mock_mem0_client)
-        message = ChatMessage(role=Role.USER, text="What's the weather?")
+        message = ChatMessage("user", ["What's the weather?"])
 
         with pytest.raises(ServiceInitializationError) as exc_info:
             await provider.invoking(message)
@@ -328,7 +328,7 @@ class TestMem0ProviderModelInvoking:
     async def test_model_invoking_single_message(self, mock_mem0_client: AsyncMock) -> None:
         """Test invoking with a single message."""
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
-        message = ChatMessage(role=Role.USER, text="What's the weather?")
+        message = ChatMessage("user", ["What's the weather?"])
 
         # Mock search results
         mock_mem0_client.search.return_value = [
@@ -369,7 +369,7 @@ class TestMem0ProviderModelInvoking:
     async def test_model_invoking_with_agent_id(self, mock_mem0_client: AsyncMock) -> None:
         """Test invoking with agent_id."""
         provider = Mem0Provider(agent_id="agent123", mem0_client=mock_mem0_client)
-        message = ChatMessage(role=Role.USER, text="Hello")
+        message = ChatMessage("user", ["Hello"])
 
         mock_mem0_client.search.return_value = []
 
@@ -387,7 +387,7 @@ class TestMem0ProviderModelInvoking:
             mem0_client=mock_mem0_client,
         )
         provider._per_operation_thread_id = "operation_thread"
-        message = ChatMessage(role=Role.USER, text="Hello")
+        message = ChatMessage("user", ["Hello"])
 
         mock_mem0_client.search.return_value = []
 
@@ -399,7 +399,7 @@ class TestMem0ProviderModelInvoking:
     async def test_model_invoking_no_memories_returns_none_instructions(self, mock_mem0_client: AsyncMock) -> None:
         """Test that no memories returns context with None instructions."""
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
-        message = ChatMessage(role=Role.USER, text="Hello")
+        message = ChatMessage("user", ["Hello"])
 
         mock_mem0_client.search.return_value = []
 
@@ -416,7 +416,7 @@ class TestMem0ProviderModelInvoking:
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
         function_call = Content.from_function_call(call_id="1", name="test_func", arguments='{"arg1": "value1"}')
         message = ChatMessage(
-            role=Role.USER,
+            role="user",
             contents=[
                 Content.from_function_approval_response(
                     id="approval_1",
@@ -437,9 +437,9 @@ class TestMem0ProviderModelInvoking:
         """Test that empty message text is filtered out from query."""
         provider = Mem0Provider(user_id="user123", mem0_client=mock_mem0_client)
         messages = [
-            ChatMessage(role=Role.USER, text=""),
-            ChatMessage(role=Role.USER, text="Valid message"),
-            ChatMessage(role=Role.USER, text="   "),
+            ChatMessage("user", [""]),
+            ChatMessage("user", ["Valid message"]),
+            ChatMessage("user", ["   "]),
         ]
 
         mock_mem0_client.search.return_value = []
@@ -457,7 +457,7 @@ class TestMem0ProviderModelInvoking:
             context_prompt=custom_prompt,
             mem0_client=mock_mem0_client,
         )
-        message = ChatMessage(role=Role.USER, text="Hello")
+        message = ChatMessage("user", ["Hello"])
 
         mock_mem0_client.search.return_value = [{"memory": "Test memory"}]