✨ feat(common): add Qwen model support and refactor react_agent code into common module

- Add `common` package with shared components for LangGraph agents
- Implement Qwen model integration with DashScope API and region-based endpoints
- Update context default model to Qwen with colon separator syntax
- Refactor react_agent code: move context, tools, utils, models, prompts to common package
- Modify load_chat_model to support colon-separated model spec and Qwen models
- Update pyproject.toml dependencies to include langchain-qwq and common package
- Enhance .env.example with new API keys and configuration for Qwen and tracing
- Update tests with fixtures, centralized test data, and integration tests for Qwen and OpenAI
- Add comprehensive e2e tests validating ReAct pattern with tool usage and streaming support
- Improve unit tests for context configuration and error handling related to model loading

Author: webup

.env.example

@@ -1,11 +1,17 @@
-TAVILY_API_KEY=...
+# Region for model providers: prc, international
+REGION= 
 
-# To separate your traces from other application
-LANGSMITH_PROJECT=react-agent
+# OpenAI Compatible models
+OPENAI_API_KEY=sk-...
+# OPENAI_API_BASE=
 
-# The following depend on your selected configuration
+# DashScope (Qwen models)
+DASHSCOPE_API_KEY=sk-...
 
-## LLM choice:
-ANTHROPIC_API_KEY=....
-FIREWORKS_API_KEY=...
-OPENAI_API_KEY=...
+# LangSmith (tracing)
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_PROJECT=langgraph-up-react
+LANGCHAIN_API_KEY=lsv2_sk_...
+
+# Search Engines
+TAVILY_API_KEY=tvly-...

pyproject.toml

@@ -13,9 +13,9 @@ dependencies = [
     "langchain-openai>=0.1.22",
     "langchain-anthropic>=0.1.23",
     "langchain>=0.2.14",
-    "langchain-fireworks>=0.1.7",
     "python-dotenv>=1.0.1",
     "langchain-tavily>=0.1",
+    "langchain-qwq>=0.2.1",
 ]
 
 
@@ -27,10 +27,11 @@ requires = ["setuptools>=73.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-packages = ["langgraph.templates.react_agent", "react_agent"]
+packages = ["langgraph.templates.react_agent", "react_agent", "common"]
 [tool.setuptools.package-dir]
 "langgraph.templates.react_agent" = "src/react_agent"
 "react_agent" = "src/react_agent"
+"common" = "src/common"
 
 
 [tool.setuptools.package-data]
@@ -71,4 +72,5 @@ dev = [
     "pytest-asyncio>=0.23.0",
     "langgraph-sdk>=0.1.0",
     "mypy>=1.17.1",
+    "ruff>=0.9.10",
 ]

src/common/__init__.py

@@ -0,0 +1,17 @@
+"""Shared components for LangGraph agents."""
+
+from . import prompts
+from .context import Context
+from .models import create_qwen_model, get_supported_qwen_models
+from .tools import TOOLS, web_search
+from .utils import load_chat_model
+
+__all__ = [
+    "Context",
+    "create_qwen_model",
+    "get_supported_qwen_models",
+    "TOOLS",
+    "web_search",
+    "load_chat_model",
+    "prompts",
+]

src/react_agent/context.py src/common/context.pysrc/react_agent/context.py renamed to src/common/context.py

@@ -22,15 +22,15 @@ class Context:
     )
 
     model: Annotated[str, {"__template_metadata__": {"kind": "llm"}}] = field(
-        default="anthropic/claude-3-5-sonnet-20240620",
+        default="qwen:qwen-plus",
         metadata={
             "description": "The name of the language model to use for the agent's main interactions. "
-            "Should be in the form: provider/model-name."
+            "Should be in the form: provider:model-name."
         },
     )
 
     max_search_results: int = field(
-        default=10,
+        default=5,
         metadata={
             "description": "The maximum number of search results to return for each search query."
         },

src/common/models.py

@@ -0,0 +1,69 @@
+"""Custom model integrations for ReAct agent."""
+
+import os
+from typing import Any, List, Optional, Union
+
+from langchain_qwq import ChatQwen, ChatQwQ
+
+
+def create_qwen_model(
+    model_name: str,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    region: Optional[str] = None,
+    **kwargs: Any,
+) -> Union[ChatQwQ, ChatQwen]:
+    """Create a Qwen model with proper configuration.
+
+    Args:
+        model_name: The model name (e.g., 'qwq-32b-preview', 'qwen-plus')
+        api_key: DashScope API key (defaults to env var DASHSCOPE_API_KEY)
+        base_url: Custom base URL for API (optional)
+        region: Region setting ('prc' for China, 'international' for global)
+                Defaults to env var REGION
+        **kwargs: Additional model parameters
+
+    Returns:
+        Configured ChatQwQ instance for QwQ/QvQ models or ChatQwen for other Qwen models
+    """
+    # Get API key from env if not provided
+    if api_key is None:
+        api_key = os.getenv("DASHSCOPE_API_KEY")
+
+    # Get region from env if not provided
+    if region is None:
+        region = os.getenv("REGION")
+
+    # Set base URL based on region if not explicitly provided
+    if base_url is None and region:
+        if region.lower() == "prc":
+            # China mainland endpoint
+            base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+        elif region.lower() == "international":
+            # International endpoint
+            base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+
+    # Create model configuration
+    config = {"model": model_name, "api_key": api_key, **kwargs}
+
+    if base_url:
+        config["base_url"] = base_url
+
+    # Select the appropriate chat model based on model name
+    # Use ChatQwQ for QwQ and QvQ models, ChatQwen for other Qwen models
+    if model_name.startswith(("qwq", "qvq")):
+        return ChatQwQ(**config)
+    else:
+        return ChatQwen(**config)
+
+
+def get_supported_qwen_models() -> List[str]:
+    """Get list of supported Qwen models."""
+    return [
+        "qwen-plus",
+        "qwen-turbo",
+        "qwen-max",
+        "qwq-32b-preview",
+        "qvq-72b-preview",
+        # Add more Qwen models as they become available
+    ]

src/react_agent/prompts.py src/common/prompts.pysrc/react_agent/prompts.py renamed to src/common/prompts.py

@@ -11,10 +11,10 @@
 from langchain_tavily import TavilySearch
 from langgraph.runtime import get_runtime
 
-from react_agent.context import Context
+from common.context import Context
 
 
-async def search(query: str) -> Optional[dict[str, Any]]:
+async def web_search(query: str) -> Optional[dict[str, Any]]:
     """Search for general web results.
 
     This function performs a search using the Tavily search engine, which is designed
@@ -26,4 +26,4 @@ async def search(query: str) -> Optional[dict[str, Any]]:
     return cast(dict[str, Any], await wrapped.ainvoke({"query": query}))
 
 
-TOOLS: List[Callable[..., Any]] = [search]
+TOOLS: List[Callable[..., Any]] = [web_search]

src/react_agent/tools.py src/common/tools.pysrc/react_agent/tools.py renamed to src/common/tools.py

@@ -1,8 +1,13 @@
 """Utility & helper functions."""
 
+from typing import Union
+
 from langchain.chat_models import init_chat_model
 from langchain_core.language_models import BaseChatModel
 from langchain_core.messages import BaseMessage
+from langchain_qwq import ChatQwen, ChatQwQ
+
+from .models import create_qwen_model
 
 
 def get_message_text(msg: BaseMessage) -> str:
@@ -17,11 +22,19 @@ def get_message_text(msg: BaseMessage) -> str:
         return "".join(txts).strip()
 
 
-def load_chat_model(fully_specified_name: str) -> BaseChatModel:
+def load_chat_model(
+    fully_specified_name: str,
+) -> Union[BaseChatModel, ChatQwQ, ChatQwen]:
     """Load a chat model from a fully specified name.
 
     Args:
-        fully_specified_name (str): String in the format 'provider/model'.
+        fully_specified_name (str): String in the format 'provider:model'.
     """
-    provider, model = fully_specified_name.split("/", maxsplit=1)
+    provider, model = fully_specified_name.split(":", maxsplit=1)
+
+    # Handle Qwen models specially with dashscope integration
+    if provider.lower() == "qwen":
+        return create_qwen_model(model)
+
+    # Use standard langchain initialization for other providers
     return init_chat_model(model, model_provider=provider)

src/react_agent/utils.py src/common/utils.pysrc/react_agent/utils.py renamed to src/common/utils.py

@@ -11,10 +11,10 @@
 from langgraph.prebuilt import ToolNode
 from langgraph.runtime import Runtime
 
-from react_agent.context import Context
+from common.context import Context
+from common.tools import TOOLS
+from common.utils import load_chat_model
 from react_agent.state import InputState, State
-from react_agent.tools import TOOLS
-from react_agent.utils import load_chat_model
 
 # Define the function that calls the model
 

src/react_agent/graph.py

@@ -2,9 +2,14 @@
 
 import os
 from pathlib import Path
+from unittest.mock import AsyncMock, Mock
 
 import pytest
 from dotenv import load_dotenv
+from langchain_core.messages import AIMessage, HumanMessage
+from langgraph_sdk import get_client
+
+from tests.test_data import TestModels, TestUrls
 
 
 @pytest.fixture(scope="session", autouse=True)
@@ -24,3 +29,124 @@ def load_env():
 
     if missing_keys:
         pytest.skip(f"Missing required environment variables: {missing_keys}")
+
+
+@pytest.fixture
+def mock_model():
+    """Create a mock model for testing."""
+    mock = Mock()
+    mock.bind_tools.return_value = mock
+    mock.ainvoke = AsyncMock()
+    return mock
+
+
+@pytest.fixture
+def sample_ai_response():
+    """Create a sample AI response for testing."""
+    return AIMessage(
+        content="This is a test response from the AI model.", tool_calls=[]
+    )
+
+
+@pytest.fixture
+def sample_human_message():
+    """Create a sample human message for testing."""
+    return HumanMessage(content="This is a test message from human.")
+
+
+@pytest.fixture
+def test_context():
+    """Create a test context with common configuration."""
+    from common.context import Context
+
+    return Context(
+        model=TestModels.QWEN_PLUS,
+        system_prompt="You are a helpful AI assistant for testing.",
+    )
+
+
+@pytest.fixture
+async def langgraph_client():
+    """Create a LangGraph client for e2e testing."""
+    return get_client(url=TestUrls.LANGGRAPH_LOCAL)
+
+
+@pytest.fixture
+async def assistant_id(langgraph_client):
+    """Get the first available assistant ID for testing."""
+    assistants = await langgraph_client.assistants.search()
+    if not assistants:
+        pytest.skip("No assistants found for e2e testing")
+    return assistants[0]["assistant_id"]
+
+
+@pytest.fixture
+async def test_thread(langgraph_client):
+    """Create a test thread for e2e testing."""
+    thread = await langgraph_client.threads.create()
+    yield thread
+    # Cleanup could be added here if needed
+
+
+class TestHelpers:
+    """Helper methods for common test operations."""
+
+    @staticmethod
+    def assert_valid_response(
+        messages: list, expected_content: str | None = None, min_messages: int = 2
+    ):
+        """Assert that a response has valid structure and content."""
+        assert isinstance(messages, list), "Messages should be a list"
+        assert len(messages) >= min_messages, (
+            f"Should have at least {min_messages} messages"
+        )
+
+        # Check final message structure
+        final_message = messages[-1]
+        assert isinstance(final_message, dict) or hasattr(final_message, "content"), (
+            "Final message should have content attribute"
+        )
+
+        if expected_content:
+            content = str(
+                getattr(final_message, "content", final_message.get("content", ""))
+            ).lower()
+            assert expected_content.lower() in content, (
+                f"Expected '{expected_content}' in response content: {content[:200]}..."
+            )
+
+    @staticmethod
+    def assert_tool_usage(messages: list, tool_name: str = "web_search"):
+        """Assert that a specific tool was used in the conversation."""
+        tool_found = False
+        for msg in messages:
+            msg_dict = msg if isinstance(msg, dict) else msg.__dict__
+
+            # Check for tool calls
+            if msg_dict.get("tool_calls"):
+                for call in msg_dict["tool_calls"]:
+                    if isinstance(call, dict) and call.get("name") == tool_name:
+                        tool_found = True
+                        break
+
+            # Check for tool messages
+            if msg_dict.get("type") == "tool" and tool_name in str(
+                msg_dict.get("name", "")
+            ):
+                tool_found = True
+                break
+
+        assert tool_found, f"Tool '{tool_name}' should have been used in conversation"
+
+    @staticmethod
+    def create_input_state(content: str):
+        """Create an InputState for testing."""
+        from react_agent.state import InputState
+
+        return InputState(messages=[HumanMessage(content=content)])
+
+
+@pytest.fixture
+def test_helpers():
+    """Provide test helper methods."""
+    return TestHelpers