langchain-dev-utils 1.4.2__tar.gz → 1.4.4__tar.gz

langchain_dev_utils-1.4.4/AGENTS.md

@@ -0,0 +1,285 @@
+# Agentic Coding Guidelines for langchain-dev-utils
+
+This file provides guidelines for AI agents working in this repository.
+
+## Project Overview
+
+A Python utility library for LangChain and LangGraph development. Uses hatchling build system, uv for package management, ruff for linting, and pytest for testing.
+
+**Current Version:** 1.4.4
+
+---
+
+## Build/Lint/Test Commands
+
+### Package Management (uv)
+```bash
+# Install dependencies
+uv sync
+
+# Install with optional dependencies
+uv sync --extra standard
+
+# Install dev dependencies
+uv sync --group dev
+
+# Install test dependencies
+uv sync --group tests
+
+# Install docs dependencies
+uv sync --group docs
+```
+
+### Linting & Formatting (ruff)
+```bash
+# Check linting
+uv run ruff check .
+
+# Check specific file
+uv run ruff check src/langchain_dev_utils/path/to/file.py
+
+# Fix auto-fixable issues
+uv run ruff check --fix .
+
+# Format code
+uv run ruff format .
+
+# Format specific file
+uv run ruff format src/langchain_dev_utils/path/to/file.py
+```
+
+### Testing (pytest)
+```bash
+# Run all tests
+uv run pytest
+
+# Run with verbose output
+uv run pytest -v
+
+# Run specific test file
+uv run pytest tests/test_agent.py
+
+# Run specific test function
+uv run pytest tests/test_agent.py::test_prebuilt_agent
+
+# Run specific test class
+uv run pytest tests/test_chat_models.py::TestImageProcessing
+
+# Run with asyncio support (automatically configured)
+uv run pytest -s
+
+# Run tests matching pattern
+uv run pytest -k "test_load"
+```
+
+### Build
+```bash
+# Build package
+uv build
+
+# Build wheel only
+uv build --wheel
+```
+
+### Documentation
+```bash
+# Serve docs locally
+mkdocs serve
+
+# Build docs
+mkdocs build
+
+# Deploy docs
+mkdocs gh-deploy
+```
+
+---
+
+## Code Style Guidelines
+
+### Imports
+- Use absolute imports for external packages
+- Use relative imports within the package (e.g., `from ..chat_models import ...`)
+- Group imports: stdlib → third-party → local
+- Ruff handles import sorting automatically
+
+### Type Hints
+- Use type hints for all function parameters and return types
+- Use `Optional[Type]` or `Type | None` for nullable types (both acceptable)
+- Use `Any` sparingly and only when necessary
+- Use `Sequence`, `Mapping` for generic collections
+- Use generics with TypeVars where appropriate
+
+### Naming Conventions
+- `snake_case` for functions, methods, variables
+- `PascalCase` for classes
+- `UPPER_CASE` for constants
+- `_leading_underscore` for private/internal functions
+- Leading double underscore for name mangling when needed
+
+### Docstrings
+- Use Google-style docstrings
+- Include Args, Returns, Raises sections for public functions
+- Include Examples section for complex functions
+- Keep docstrings under 100 characters per line when possible
+
+### Code Structure
+- Maximum line length: 88 characters (ruff enforces, E501 ignored)
+- Use trailing commas in multi-line structures
+- Two blank lines between top-level functions/classes
+- One blank line between methods
+
+### Error Handling
+- Use specific exception types, not bare `except:`
+- Provide descriptive error messages with f-strings
+- Use `raise ValueError(msg)` pattern with descriptive messages
+- Avoid bare `raise` statements
+
+### Async Code
+- Use `pytest.mark.asyncio` for async test functions
+- Use `async`/`await` consistently
+- Prefer `asyncio` primitives from standard library
+
+### Ruff Configuration
+- Enabled rules: E, F, I, PGH003, T201
+- Import sorting (I) is enforced
+- No print statements in production code (T201)
+
+---
+
+## Testing Guidelines
+
+- Tests live in `tests/` directory
+- Test files named `test_*.py`
+- Test functions named `test_*`
+- Use pytest fixtures for setup/teardown
+- Use `pytest.mark.asyncio` for async tests
+- Mock external API calls in unit tests
+- Integration tests use actual APIs (marked implicitly by test names)
+- Tests use `langchain-tests` for standard integration test suites
+
+---
+
+## Project Structure
+
+```
+langchain-dev-utils/
+├── src/langchain_dev_utils/      # Source code
+│   ├── agents/                   # Agent utilities
+│   │   ├── factory.py            # Agent creation functions
+│   │   ├── wrap.py               # Agent wrapping utilities
+│   │   └── middleware/           # Agent middleware components
+│   │       ├── format_prompt.py      # Format prompt middleware
+│   │       ├── handoffs.py           # Multi-agent handoff middleware
+│   │       ├── model_fallback.py     # Model fallback middleware
+│   │       ├── model_router.py       # Model routing middleware
+│   │       ├── plan.py               # Planning middleware
+│   │       ├── summarization.py      # Message summarization middleware
+│   │       ├── tool_call_repair.py   # Tool call repair middleware
+│   │       ├── tool_emulator.py      # LLM tool emulator middleware
+│   │       └── tool_selection.py     # LLM tool selector middleware
+│   ├── chat_models/              # Chat model utilities
+│   │   ├── base.py               # Base chat model classes
+│   │   ├── types.py              # Type definitions
+│   │   └── adapters/             # Model provider adapters
+│   ├── embeddings/               # Embedding utilities
+│   │   ├── base.py               # Base embedding classes
+│   │   └── adapters/             # Embedding provider adapters
+│   ├── graph/                    # Graph utilities
+│   │   ├── parallel.py           # Parallel graph construction
+│   │   ├── sequential.py         # Sequential graph construction
+│   │   └── types.py              # Graph type definitions
+│   ├── message_convert/          # Message conversion utilities
+│   │   ├── content.py            # Content conversion
+│   │   └── format.py             # Message formatting
+│   ├── pipeline/                 # Pipeline utilities (deprecated since v1.4.0, will be removed in v1.5.0)
+│   │   ├── parallel.py
+│   │   ├── sequential.py
+│   │   └── types.py
+│   └── tool_calling/             # Tool calling utilities
+│       ├── human_in_the_loop.py  # Human review functionality
+│       └── utils.py              # Tool calling utilities
+├── tests/                        # Test files
+├── docs/                         # Documentation (MkDocs)
+│   ├── en/                       # English documentation
+│   └── zh/                       # Chinese documentation
+├── pyproject.toml                # Project configuration
+├── uv.lock                       # Dependency lock file
+└── mkdocs.yml                    # MkDocs configuration
+```
+
+---
+
+## Middleware Components
+
+The `agents.middleware` module provides reusable middleware components for agent enhancement:
+
+| Middleware | Purpose |
+|------------|---------|
+| `SummarizationMiddleware` | Summarizes long message histories |
+| `LLMToolSelectorMiddleware` | Uses LLM to select appropriate tools |
+| `PlanMiddleware` | Adds planning capabilities to agents |
+| `ModelFallbackMiddleware` | Provides fallback to alternative models |
+| `LLMToolEmulator` | Emulates tool calling for models without native support |
+| `ModelRouterMiddleware` | Routes requests to different models based on criteria |
+| `ToolCallRepairMiddleware` | Repairs malformed tool calls |
+| `FormatPromptMiddleware` | Formats prompts with templates |
+| `HandoffAgentMiddleware` | Enables multi-agent handoff workflows |
+
+---
+
+## Dependencies
+
+### Core Dependencies
+- `langchain>=1.2.0` - LangChain framework
+- `langchain-core>=1.2.5` - Core LangChain components
+- `langgraph>=1.0.0` - LangGraph for graph-based workflows
+
+### Optional Dependencies (standard)
+- `jinja2>=3.1.6` - Template engine for prompt formatting
+- `json-repair>=0.53.1` - JSON repair utilities
+- `langchain-openai` - OpenAI integration
+
+### Dev Dependencies
+- `langchain-model-profiles>=0.0.5` - Model profile management
+- `ruff>=0.14.5` - Linting and formatting
+
+### Docs Dependencies
+- `jupyter>=1.1.1` - Jupyter notebook support
+- `mkdocs-material>=9.7.0` - Material theme for MkDocs
+- `mkdocs-static-i18n>=1.3.0` - Internationalization support
+
+### Test Dependencies
+- `python-dotenv>=1.1.1` - Environment variable management
+- `langchain-tests>=1.0.0` - Standard LangChain test suite
+- `langchain-deepseek>=1.0.0` - DeepSeek model integration
+- `langchain-qwq>=0.3.0` - QwQ model integration
+- `langchain-ollama>=1.0.0` - Ollama integration
+- `langchain-community>=0.4.1` - Community model integrations
+- `dashscope>=1.25.12` - Alibaba DashScope integration
+
+**Python version:** >=3.11
+
+---
+
+## Documentation
+
+- Documentation is built with MkDocs using the Material theme
+- Supports internationalization (English and Chinese)
+- Hosted at: https://tbice123123.github.io/langchain-dev-utils/
+- Source files located in `docs/en/` and `docs/zh/`
+
+---
+
+## Release Checklist
+
+When preparing a new release:
+
+1. Update version in `src/langchain_dev_utils/__init__.py`
+2. Update version in `pyproject.toml` if needed
+3. Run full test suite: `uv run pytest`
+4. Run linting: `uv run ruff check .`
+5. Run formatting: `uv run ruff format .`
+6. Build package: `uv build`
+7. Update documentation if needed
+8. Tag release in git

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-dev-utils
-Version: 1.4.2
+Version: 1.4.4
 Summary: A practical utility library for LangChain and LangGraph development
 Project-URL: Source Code, https://github.com/TBice123123/langchain-dev-utils
 Project-URL: repository, https://github.com/TBice123123/langchain-dev-utils
@@ -102,4 +102,7 @@ Visit the [GitHub repository](https://github.com/TBice123123/langchain-dev-utils
 <div align="center">
   <p>Developed with ❤️ and ☕</p>
   <p>If this project helps you, please give us a ⭐️</p>
-</div>
+</div>
+
+
+

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/README.md

@@ -83,4 +83,7 @@ Visit the [GitHub repository](https://github.com/TBice123123/langchain-dev-utils
 <div align="center">
   <p>Developed with ❤️ and ☕</p>
   <p>If this project helps you, please give us a ⭐️</p>
-</div>
+</div>
+
+
+

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langchain-dev-utils"
-version = "1.4.2"
+version = "1.4.4"
 description = "A practical utility library for LangChain and LangGraph development"
 readme = "README.md"
 authors = [{ name = "tiebingice", email = "tiebingice123@outlook.com" }]
@@ -39,7 +39,6 @@ python_functions = ["test_*"]
 
 [dependency-groups]
 dev = [
-    "dashscope>=1.25.9",
     "langchain-model-profiles>=0.0.5",
     "ruff>=0.14.5",
 ]
@@ -55,6 +54,7 @@ tests = [
     "langchain-qwq>=0.3.0",
     "langchain-ollama>=1.0.0",
     "langchain-community>=0.4.1",
+    "dashscope>=1.25.12",
 ]
 
 

langchain_dev_utils-1.4.4/src/langchain_dev_utils/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.4.4"

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/src/langchain_dev_utils/agents/factory.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable, Sequence
+from typing import Annotated, Any, Callable, Generic, Sequence
 
 from langchain.agents import create_agent as _create_agent
 from langchain.agents.middleware.types import (
@@ -6,21 +6,34 @@ from langchain.agents.middleware.types import (
     AgentState,
     ResponseT,
     StateT_co,
-    _InputAgentState,
-    _OutputAgentState,
 )
 from langchain.agents.structured_output import ResponseFormat
-from langchain_core.messages import SystemMessage
+from langchain_core.messages import AnyMessage, SystemMessage
 from langchain_core.tools import BaseTool
 from langgraph.cache.base import BaseCache
+from langgraph.graph.message import add_messages
 from langgraph.graph.state import CompiledStateGraph
 from langgraph.store.base import BaseStore
 from langgraph.types import Checkpointer
 from langgraph.typing import ContextT
+from typing_extensions import NotRequired, Required, TypedDict
 
 from ..chat_models import load_chat_model
 
 
+class _InputAgentState(TypedDict):  # noqa: PYI049
+    """Input state schema for the agent."""
+
+    messages: Required[Annotated[list[AnyMessage | dict[str, Any]], add_messages]]
+
+
+class _OutputAgentState(TypedDict, Generic[ResponseT]):  # noqa: PYI049
+    """Output state schema for the agent."""
+
+    messages: Required[Annotated[list[AnyMessage], add_messages]]
+    structured_response: NotRequired[ResponseT]
+
+
 def create_agent(  # noqa: PLR0915
     model: str,
     tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/src/langchain_dev_utils/agents/middleware/handoffs.py

@@ -25,14 +25,16 @@ class AgentConfig(TypedDict):
     handoffs: list[str] | Literal["all"]
 
 
-def _create_handoffs_tool(agent_name: str, tool_description: Optional[str] = None):
+def _create_handoffs_tool(
+    agent_name: str, tool_description: Optional[str] = None
+) -> BaseTool:
     """Create a tool for handoffs to a specified agent.
 
     Args:
         agent_name (str): The name of the agent to transfer to.
 
     Returns:
-        BaseTool: A tool instance for handoffs to the specified agent.
+        BaseTool: The tool instance for handoffs to the specified agent.
     """
 
     tool_name = f"transfer_to_{agent_name}"
@@ -67,13 +69,13 @@ def _get_default_active_agent(state: dict[str, AgentConfig]) -> Optional[str]:
 
 def _transform_agent_config(
     config: dict[str, AgentConfig],
-    handoffs_tools: list[BaseTool],
+    handoffs_tool_map: dict[str, BaseTool],
 ) -> dict[str, AgentConfig]:
     """Transform the agent config to add handoffs tools.
 
     Args:
         config (dict[str, AgentConfig]): The agent config.
-        handoffs_tools (list[BaseTool]): The list of handoffs tools.
+        handoffs_tool_map (dict[str, BaseTool]): The dict of {agent name: handoffs tool}.
 
     Returns:
         dict[str, AgentConfig]: The transformed agent config.
@@ -96,8 +98,8 @@ def _transform_agent_config(
         if handoffs == "all":
             handoff_tools = [
                 handoff_tool
-                for handoff_tool in handoffs_tools
-                if handoff_tool.name != f"transfer_to_{agent_name}"
+                for transfer_to_agent, handoff_tool in handoffs_tool_map.items()
+                if transfer_to_agent != agent_name
             ]
         else:
             if not isinstance(handoffs, list):
@@ -105,14 +107,13 @@ def _transform_agent_config(
                     f"handoffs for agent {agent_name} must be a list of agent names or 'all'"
                 )
 
+            if agent_name in handoffs:
+                raise ValueError(f"agent {agent_name} cannot handoff to itself")
+
             handoff_tools = [
                 handoff_tool
-                for handoff_tool in handoffs_tools
-                if handoff_tool.name
-                in [
-                    f"transfer_to_{_handoff_agent_name}"
-                    for _handoff_agent_name in handoffs
-                ]
+                for transfer_to_agent, handoff_tool in handoffs_tool_map.items()
+                if transfer_to_agent in handoffs
             ]
 
         new_config[agent_name]["tools"] = [
@@ -158,28 +159,28 @@ class HandoffAgentMiddleware(AgentMiddleware):
         if handoffs_tool_overrides is None:
             handoffs_tool_overrides = {}
 
-        handoffs_tools = []
+        handoffs_tool_map = {}
+
         for agent_name in agents_config.keys():
             if not handoffs_tool_overrides.get(agent_name):
-                handoffs_tools.append(
-                    _create_handoffs_tool(
-                        agent_name,
-                        custom_handoffs_tool_descriptions.get(agent_name),
-                    )
+                handoffs_tool_map[agent_name] = _create_handoffs_tool(
+                    agent_name,
+                    custom_handoffs_tool_descriptions.get(agent_name),
                 )
+
             else:
-                handoffs_tools.append(
-                    cast(BaseTool, handoffs_tool_overrides.get(agent_name))
+                handoffs_tool_map[agent_name] = cast(
+                    BaseTool, handoffs_tool_overrides.get(agent_name)
                 )
 
         self.default_agent_name = default_agent_name
         self.agents_config = _transform_agent_config(
             agents_config,
-            handoffs_tools,
+            handoffs_tool_map,
         )
 
         all_tools = [
-            *handoffs_tools,
+            *handoffs_tool_map.values(),
         ]
 
         for agent_name in agents_config:

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/src/langchain_dev_utils/chat_models/base.py

@@ -1,6 +1,6 @@
 from typing import Any, Optional, cast
 
-from langchain.chat_models.base import _SUPPORTED_PROVIDERS, _init_chat_model_helper
+from langchain.chat_models import init_chat_model
 from langchain_core.language_models.chat_models import BaseChatModel
 from langchain_core.utils import from_env
 
@@ -28,8 +28,7 @@ def _parse_model(model: str, model_provider: Optional[str]) -> tuple[str, str]:
     Raises:
         ValueError: If unable to infer model provider
     """
-    support_providers = list(_MODEL_PROVIDERS_DICT.keys()) + list(_SUPPORTED_PROVIDERS)
-    if not model_provider and ":" in model and model.split(":")[0] in support_providers:
+    if not model_provider and ":" in model:
         model_provider = model.split(":")[0]
         model = ":".join(model.split(":")[1:])
     if not model_provider:
@@ -71,7 +70,7 @@ def _load_chat_model_helper(
                 kwargs.update({"profile": model_profiles[model]})
         return chat_model(model=model, **kwargs)
 
-    return _init_chat_model_helper(model, model_provider=model_provider, **kwargs)
+    return init_chat_model(model, model_provider=model_provider, **kwargs)
 
 
 def register_model_provider(

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/src/langchain_dev_utils/chat_models/types.py

@@ -1,6 +1,7 @@
-from typing import Any, Literal, NotRequired, TypedDict, Union
+from typing import Any, Literal, Union
 
 from langchain_core.language_models.chat_models import BaseChatModel
+from typing_extensions import NotRequired, TypedDict
 
 ChatModelType = Union[type[BaseChatModel], Literal["openai-compatible"]]
 

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/src/langchain_dev_utils/embeddings/base.py

@@ -1,7 +1,8 @@
-from typing import Any, Literal, NotRequired, Optional, TypedDict, Union
+from typing import Any, Literal, Optional, Union
 
-from langchain.embeddings.base import _SUPPORTED_PROVIDERS, Embeddings, init_embeddings
+from langchain.embeddings.base import Embeddings, init_embeddings
 from langchain_core.utils import from_env
+from typing_extensions import NotRequired, TypedDict
 
 from langchain_dev_utils._utils import (
     _check_pkg_install,
@@ -11,6 +12,7 @@ from langchain_dev_utils._utils import (
 
 _EMBEDDINGS_PROVIDERS_DICT = {}
 
+
 EmbeddingsType = Union[type[Embeddings], Literal["openai-compatible"]]
 
 
@@ -218,10 +220,6 @@ def load_embeddings(
     """
     if provider is None:
         provider, model = _parse_model_string(model)
-    if provider not in list(_EMBEDDINGS_PROVIDERS_DICT.keys()) + list(
-        _SUPPORTED_PROVIDERS
-    ):
-        raise ValueError(f"Provider {provider} not registered")
 
     if provider in _EMBEDDINGS_PROVIDERS_DICT:
         embeddings = _EMBEDDINGS_PROVIDERS_DICT[provider]["embeddings_model"]

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/src/langchain_dev_utils/tool_calling/human_in_the_loop.py

@@ -1,8 +1,9 @@
-from typing import Any, Callable, Optional, TypedDict, Union, overload
+from typing import Any, Callable, Optional, Union, overload
 
 from langchain_core.tools import BaseTool
 from langchain_core.tools import tool as create_tool
 from langgraph.types import interrupt
+from typing_extensions import TypedDict
 
 
 class InterruptParams(TypedDict):

{langchain_dev_utils-1.4.2 → langchain_dev_utils-1.4.4}/tests/test_handoffs_middleware.py

@@ -136,10 +136,6 @@ async def test_handoffs_middleware_async():
                 handoffs_tool_overrides=handoffs_tool_map,
             )
         ],
-        tools=[
-            get_current_time,
-            run_code,
-        ],
         checkpointer=InMemorySaver(),
     )