Merge remote-tracking branch 'origin/main' into ags_declarative_vd

Author: victordibia

dotnet/src/Microsoft.AutoGen/Contracts/AgentId.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using System.Text.RegularExpressions;
 
 namespace Microsoft.AutoGen.Contracts;
 
@@ -16,6 +17,9 @@ namespace Microsoft.AutoGen.Contracts;
 [DebuggerDisplay($"AgentId(type=\"{nameof(Type)}\", key=\"{nameof(Key)}\")")]
 public struct AgentId
 {
+    private static readonly Regex TypeRegex = new(@"^[a-zA-Z_][a-zA-Z0-9_]*$", RegexOptions.Compiled);
+    private static readonly Regex KeyRegex = new(@"^[\x20-\x7E]+$", RegexOptions.Compiled); // ASCII 32-126
+
     /// <summary>
     /// An identifier that associates an agent with a specific factory function.
     /// Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
@@ -35,6 +39,16 @@ public struct AgentId
     /// <param name="key">Agent instance identifier.</param>
     public AgentId(string type, string key)
     {
+        if (string.IsNullOrWhiteSpace(type) || !TypeRegex.IsMatch(type))
+        {
+            throw new ArgumentException($"Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0-9, _) and cannot start with a number or contain spaces.");
+        }
+
+        if (string.IsNullOrWhiteSpace(key) || !KeyRegex.IsMatch(key))
+        {
+            throw new ArgumentException($"Invalid AgentId key: '{key}'. Must only contain ASCII characters 32-126.");
+        }
+
         Type = type;
         Key = key;
     }

dotnet/test/Microsoft.AutoGen.Core.Tests/AgentIdTests.cs

@@ -0,0 +1,109 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// AgentIdTests.cs
+using FluentAssertions;
+using Microsoft.AutoGen.Contracts;
+using Xunit;
+
+namespace Microsoft.AutoGen.Core.Tests;
+
+public class AgentIdTests()
+{
+    [Fact]
+    public void AgentIdShouldInitializeCorrectlyTest()
+    {
+        var agentId = new AgentId("TestType", "TestKey");
+
+        agentId.Type.Should().Be("TestType");
+        agentId.Key.Should().Be("TestKey");
+    }
+
+    [Fact]
+    public void AgentIdShouldConvertFromTupleTest()
+    {
+        var agentTuple = ("TupleType", "TupleKey");
+        var agentId = new AgentId(agentTuple);
+
+        agentId.Type.Should().Be("TupleType");
+        agentId.Key.Should().Be("TupleKey");
+    }
+
+    [Fact]
+    public void AgentIdShouldParseFromStringTest()
+    {
+        var agentId = AgentId.FromStr("ParsedType/ParsedKey");
+
+        agentId.Type.Should().Be("ParsedType");
+        agentId.Key.Should().Be("ParsedKey");
+    }
+
+    [Fact]
+    public void AgentIdShouldCompareEqualityCorrectlyTest()
+    {
+        var agentId1 = new AgentId("SameType", "SameKey");
+        var agentId2 = new AgentId("SameType", "SameKey");
+        var agentId3 = new AgentId("DifferentType", "DifferentKey");
+
+        agentId1.Should().Be(agentId2);
+        agentId1.Should().NotBe(agentId3);
+        (agentId1 == agentId2).Should().BeTrue();
+        (agentId1 != agentId3).Should().BeTrue();
+    }
+
+    [Fact]
+    public void AgentIdShouldGenerateCorrectHashCodeTest()
+    {
+        var agentId1 = new AgentId("HashType", "HashKey");
+        var agentId2 = new AgentId("HashType", "HashKey");
+        var agentId3 = new AgentId("DifferentType", "DifferentKey");
+
+        agentId1.GetHashCode().Should().Be(agentId2.GetHashCode());
+        agentId1.GetHashCode().Should().NotBe(agentId3.GetHashCode());
+    }
+
+    [Fact]
+    public void AgentIdShouldConvertExplicitlyFromStringTest()
+    {
+        var agentId = (AgentId)"ConvertedType/ConvertedKey";
+
+        agentId.Type.Should().Be("ConvertedType");
+        agentId.Key.Should().Be("ConvertedKey");
+    }
+
+    [Fact]
+    public void AgentIdShouldReturnCorrectToStringTest()
+    {
+        var agentId = new AgentId("ToStringType", "ToStringKey");
+
+        agentId.ToString().Should().Be("ToStringType/ToStringKey");
+    }
+
+    [Fact]
+    public void AgentIdShouldCompareInequalityCorrectlyTest()
+    {
+        var agentId1 = new AgentId("Type1", "Key1");
+        var agentId2 = new AgentId("Type2", "Key2");
+
+        (agentId1 != agentId2).Should().BeTrue();
+    }
+
+    [Fact]
+    public void AgentIdShouldRejectInvalidNamesTest()
+    {
+        // Invalid: 'Type' cannot start with a number and must only contain a-z, 0-9, or underscores.
+        Action invalidType = () => new AgentId("123InvalidType", "ValidKey");
+        invalidType.Should().Throw<ArgumentException>("Agent type cannot start with a number and must only contain alphanumeric letters or underscores.");
+
+        Action invalidTypeWithSpaces = () => new AgentId("Invalid Type", "ValidKey");
+        invalidTypeWithSpaces.Should().Throw<ArgumentException>("Agent type cannot contain spaces.");
+
+        Action invalidTypeWithSpecialChars = () => new AgentId("Invalid@Type", "ValidKey");
+        invalidTypeWithSpecialChars.Should().Throw<ArgumentException>("Agent type cannot contain special characters.");
+
+        // Invalid: 'Key' must contain only ASCII characters 32 (space) to 126 (~).
+        Action invalidKey = () => new AgentId("ValidType", "InvalidKey💀");
+        invalidKey.Should().Throw<ArgumentException>("Agent key must only contain ASCII characters between 32 (space) and 126 (~).");
+
+        Action validCase = () => new AgentId("Valid_Type", "Valid_Key_123");
+        validCase.Should().NotThrow("This is a correctly formatted AgentId.");
+    }
+}

dotnet/test/Microsoft.AutoGen.Core.Tests/AgentMetaDataTests.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// AgentMetaDataTests.cs
+using FluentAssertions;
+using Microsoft.AutoGen.Contracts;
+using Xunit;
+
+namespace Microsoft.AutoGen.Core.Tests;
+
+public class AgentMetadataTests()
+{
+    [Fact]
+    public void AgentMetadataShouldInitializeCorrectlyTest()
+    {
+        var metadata = new AgentMetadata("TestType", "TestKey", "TestDescription");
+
+        metadata.Type.Should().Be("TestType");
+        metadata.Key.Should().Be("TestKey");
+        metadata.Description.Should().Be("TestDescription");
+    }
+}

python/packages/autogen-core/src/autogen_core/models/_model_client.py

@@ -22,9 +22,10 @@ class ModelFamily:
     O1 = "o1"
     GPT_4 = "gpt-4"
     GPT_35 = "gpt-35"
+    R1 = "r1"
     UNKNOWN = "unknown"
 
-    ANY: TypeAlias = Literal["gpt-4o", "o1", "gpt-4", "gpt-35", "unknown"]
+    ANY: TypeAlias = Literal["gpt-4o", "o1", "gpt-4", "gpt-35", "r1", "unknown"]
 
     def __new__(cls, *args: Any, **kwargs: Any) -> ModelFamily:
         raise TypeError(f"{cls.__name__} is a namespace class and cannot be instantiated.")

python/packages/autogen-core/src/autogen_core/models/_types.py

@@ -8,11 +8,25 @@
 
 
 class SystemMessage(BaseModel):
+    """System message contains instructions for the model coming from the developer.
+
+    .. note::
+
+        Open AI is moving away from using 'system' role in favor of 'developer' role.
+        See `Model Spec <https://cdn.openai.com/spec/model-spec-2024-05-08.html#definitions>`_ for more details.
+        However, the 'system' role is still allowed in their API and will be automatically converted to 'developer' role
+        on the server side.
+        So, you can use `SystemMessage` for developer messages.
+
+    """
+
     content: str
     type: Literal["SystemMessage"] = "SystemMessage"
 
 
 class UserMessage(BaseModel):
+    """User message contains input from end users, or a catch-all for data provided to the model."""
+
     content: Union[str, List[Union[str, Image]]]
 
     # Name of the agent that sent this message
@@ -22,6 +36,8 @@ class UserMessage(BaseModel):
 
 
 class AssistantMessage(BaseModel):
+    """Assistant message are sampled from the language model."""
+
     content: Union[str, List[FunctionCall]]
 
     # Name of the agent that sent this message
@@ -31,11 +47,15 @@ class AssistantMessage(BaseModel):
 
 
 class FunctionExecutionResult(BaseModel):
+    """Function execution result contains the output of a function call."""
+
     content: str
     call_id: str
 
 
 class FunctionExecutionResultMessage(BaseModel):
+    """Function execution result message contains the output of multiple function calls."""
+
     content: List[FunctionExecutionResult]
 
     type: Literal["FunctionExecutionResultMessage"] = "FunctionExecutionResultMessage"
@@ -69,8 +89,23 @@ class ChatCompletionTokenLogprob(BaseModel):
 
 
 class CreateResult(BaseModel):
+    """Create result contains the output of a model completion."""
+
     finish_reason: FinishReasons
+    """The reason the model finished generating the completion."""
+
     content: Union[str, List[FunctionCall]]
+    """The output of the model completion."""
+
     usage: RequestUsage
+    """The usage of tokens in the prompt and completion."""
+
     cached: bool
+    """Whether the completion was generated from a cached response."""
+
     logprobs: Optional[List[ChatCompletionTokenLogprob] | None] = None
+    """The logprobs of the tokens in the completion."""
+
+    thought: Optional[str] = None
+    """The reasoning text for the completion if available. Used for reasoning models
+    and additional text content besides function calls."""

python/packages/autogen-ext/pyproject.toml

@@ -120,6 +120,7 @@ dev = [
     "autogen_test_utils",
     "langchain-experimental",
     "pandas-stubs>=2.2.3.241126",
+    "httpx>=0.28.1",
 ]
 
 [tool.ruff]

python/packages/autogen-ext/src/autogen_ext/agents/magentic_one/_magentic_one_coder_agent.py

@@ -12,10 +12,9 @@
     2. When you need to perform some task with code, use the code to perform the task and output the result. Finish the task smartly.
 Solve the task step by step if you need to. If a plan is not provided, explain your plan first. Be clear which step uses code, and which step uses your language skill.
 When using code, you must indicate the script type in the code block. The user cannot provide any other feedback or perform any other action beyond executing the code you suggest. The user can't modify your code. So do not suggest incomplete code which requires users to modify. Don't use a code block if it's not intended to be executed by the user.
-If you want the user to save the code in a file before executing it, put # filename: <filename> inside the code block as the first line. Don't include multiple code blocks in one response. Do not ask users to copy and paste the result. Instead, use 'print' function for the output when relevant. Check the execution result returned by the user.
+Don't include multiple code blocks in one response. Do not ask users to copy and paste the result. Instead, use the 'print' function for the output when relevant. Check the execution result returned by the user.
 If the result indicates there is an error, fix the error and output the code again. Suggest the full code instead of partial code or code changes. If the error can't be fixed or if the task is not solved even after the code is executed successfully, analyze the problem, revisit your assumption, collect additional info you need, and think of a different approach to try.
-When you find an answer, verify the answer carefully. Include verifiable evidence in your response if possible.
-Reply "TERMINATE" in the end when everything is done."""
+When you find an answer, verify the answer carefully. Include verifiable evidence in your response if possible."""
 
 
 class MagenticOneCoderAgent(AssistantAgent):

python/packages/autogen-ext/src/autogen_ext/models/_utils/parse_r1_content.py

@@ -0,0 +1,33 @@
+import warnings
+from typing import Tuple
+
+
+def parse_r1_content(content: str) -> Tuple[str | None, str]:
+    """Parse the content of an R1-style message that contains a `<think>...</think>` field."""
+    # Find the start and end of the think field
+    think_start = content.find("<think>")
+    think_end = content.find("</think>")
+
+    if think_start == -1 or think_end == -1:
+        warnings.warn(
+            "Could not find <think>..</think> field in model response content. " "No thought was extracted.",
+            UserWarning,
+            stacklevel=2,
+        )
+        return None, content
+
+    if think_end < think_start:
+        warnings.warn(
+            "Found </think> before <think> in model response content. " "No thought was extracted.",
+            UserWarning,
+            stacklevel=2,
+        )
+        return None, content
+
+    # Extract the think field
+    thought = content[think_start + len("<think>") : think_end].strip()
+
+    # Extract the rest of the content, skipping the think field.
+    content = content[think_end + len("</think>") :].strip()
+
+    return thought, content

python/packages/autogen-ext/src/autogen_ext/models/azure/_azure_ai_client.py

@@ -12,6 +12,7 @@
     FinishReasons,
     FunctionExecutionResultMessage,
     LLMMessage,
+    ModelFamily,
     ModelInfo,
     RequestUsage,
     SystemMessage,
@@ -55,6 +56,8 @@
     AzureAIChatCompletionClientConfig,
 )
 
+from .._utils.parse_r1_content import parse_r1_content
+
 create_kwargs = set(getfullargspec(ChatCompletionsClient.complete).kwonlyargs)
 AzureMessage = Union[AzureSystemMessage, AzureUserMessage, AzureAssistantMessage, AzureToolMessage]
 
@@ -354,11 +357,17 @@ async def create(
                 finish_reason = choice.finish_reason  # type: ignore
             content = choice.message.content or ""
 
+        if isinstance(content, str) and self._model_info["family"] == ModelFamily.R1:
+            thought, content = parse_r1_content(content)
+        else:
+            thought = None
+
         response = CreateResult(
             finish_reason=finish_reason,  # type: ignore
             content=content,
             usage=usage,
             cached=False,
+            thought=thought,
         )
 
         self.add_usage(usage)
@@ -464,11 +473,17 @@ async def create_stream(
             prompt_tokens=prompt_tokens,
         )
 
+        if isinstance(content, str) and self._model_info["family"] == ModelFamily.R1:
+            thought, content = parse_r1_content(content)
+        else:
+            thought = None
+
         result = CreateResult(
             finish_reason=finish_reason,
             content=content,
             usage=usage,
             cached=False,
+            thought=thought,
         )
 
         self.add_usage(usage)