language-model-common 2.0.91__tar.gz → 2.0.92__tar.gz

{language_model_common-2.0.91/language_model_common.egg-info → language_model_common-2.0.92}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: language-model-common
-Version: 2.0.91
+Version: 2.0.92
 Summary: Provides the underlying framework to enhance langchain and add loading configurations
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0

language_model_common-2.0.92/VERSION

@@ -0,0 +1 @@
+2.0.92

{language_model_common-2.0.91 → language_model_common-2.0.92/language_model_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: language-model-common
-Version: 2.0.91
+Version: 2.0.92
 Summary: Provides the underlying framework to enhance langchain and add loading configurations
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/converters/streaming_manager.py

@@ -379,6 +379,15 @@ class LangGraphStreamingManager(StreamContextMixin):
             )
             if chunk:
                 yield chunk
+        elif name == "mcp_tool_heartbeat":
+            data = dict(event.get("data", {}))
+            chunk = chat_request_wrapper.create_tool_heartbeat_sse_event(
+                request_id=request_information.request_id,
+                tool_name=data.get("tool_name", "unknown"),
+                elapsed_seconds=float(data.get("elapsed_seconds", 0.0)),
+            )
+            if chunk:
+                yield chunk
         else:
             logger.debug("Skipped custom event: %s", name)
 

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/converters/tool_event_handlers.py

@@ -36,6 +36,20 @@ from languagemodelcommon.utilities.tool_display_name_mapper import ToolDisplayNa
 logger = logging.getLogger(__name__)
 logger.setLevel(SRC_LOG_LEVELS.LLM)
 
+# Cap on the tool result/error text forwarded to the response.output_item.done
+# SSE event, so a tool that echoes back large content (e.g. a full skill body)
+# doesn't bloat every trace event; full output remains available via the
+# existing debug-file-writer path for cases that need it.
+TOOL_END_OUTPUT_TRACE_MAX_CHARS = 2000
+
+
+def _truncate_for_trace(
+    text: str, *, max_chars: int = TOOL_END_OUTPUT_TRACE_MAX_CHARS
+) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + f"...[truncated {len(text) - max_chars} chars]"
+
 
 class ToolEventHandler(StreamContextMixin):
     def __init__(
@@ -161,23 +175,32 @@ class ToolEventHandler(StreamContextMixin):
                     tool_name,
                 )
 
+            tool_message_content: str = (
+                convert_message_content_into_string(tool_message=tool_message)
+                if tool_message
+                else ""
+            )
+            artifact: Optional[Any] = tool_message.artifact
+            # tool_message.status only flips to "error" for an uncaught exception;
+            # meta-tools like call_tool catch their own failures and report them via
+            # the artifact instead (see CallToolTool), so check both signals.
+            is_error: bool = tool_message.status == "error" or (
+                isinstance(artifact, dict) and artifact.get("is_error") is True
+            )
+
             tool_end_event = chat_request_wrapper.create_tool_end_sse_event(
                 request_id=request_information.request_id,
                 tool_name=tool_name,
                 tool_input=tool_input,
                 runtime_seconds=runtime_seconds,
+                output=_truncate_for_trace(tool_message_content)
+                if tool_message_content
+                else None,
+                is_error=is_error,
             )
             if tool_end_event:
                 yield tool_end_event
 
-            tool_message_content: str = (
-                convert_message_content_into_string(tool_message=tool_message)
-                if tool_message
-                else ""
-            )
-
-            artifact: Optional[Any] = tool_message.artifact
-
             logger.debug(
                 "Tool %s has artifact of type %s: %s",
                 tool_name,

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/mcp/mcp_client/langchain_adapter.py

@@ -62,6 +62,7 @@ def mcp_tool_to_langchain_tool(
     server_name: str | None = None,
     session_pool: McpSessionPool | None = None,
     tool_list_cache: ToolListCache | None = None,
+    heartbeat_interval_seconds: float = 15.0,
 ) -> BaseTool:
     """Convert an MCP Tool to a LangChain BaseTool.
 
@@ -84,6 +85,7 @@ def mcp_tool_to_langchain_tool(
         mcp_callbacks=mcp_callbacks,
         session_pool=session_pool,
         tool_list_cache=tool_list_cache,
+        heartbeat_interval_seconds=heartbeat_interval_seconds,
     )
     handler = build_interceptor_chain(
         base_handler=execute_tool, tool_interceptors=tool_interceptors

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/mcp/mcp_client/tool_invocation.py

@@ -1,9 +1,12 @@
 """Tool invocation — interceptor chain and raw MCP tool calls."""
 
+import asyncio
+import contextlib
 import logging
 from collections.abc import Awaitable, Callable
 from typing import Any
 
+from langchain_core.callbacks.manager import adispatch_custom_event
 from mcp.types import CallToolResult
 from pydantic import ValidationError
 
@@ -174,8 +177,6 @@ async def _execute_tool_as_task(
     Raises TaskProtocolError if the server does not respond with a valid
     CreateTaskResult (e.g., returns a plain CallToolResult instead).
     """
-    from langchain_core.callbacks.manager import adispatch_custom_event
-
     try:
         create_result = await session.experimental.call_tool_as_task(
             name, arguments, ttl=60000
@@ -222,12 +223,69 @@ async def _execute_tool_as_task(
     return result
 
 
+async def _execute_tool_call_with_heartbeat(
+    *,
+    session: Any,
+    name: str,
+    arguments: dict[str, Any],
+    progress_callback: Any,
+    server_name: str,
+    heartbeat_interval_seconds: float,
+) -> CallToolResult:
+    """Call ``session.call_tool``, emitting a synthetic ``mcp_tool_heartbeat``
+    custom event every ``heartbeat_interval_seconds`` while the call is in
+    flight, regardless of whether the tool reports real progress.
+
+    Uses ``asyncio.shield`` so a heartbeat tick's wait_for timeout never
+    cancels the underlying tool call -- only the local wait is abandoned and
+    retried on the same call_task. If this coroutine itself is cancelled
+    (e.g. the overall chat turn is aborted), the inner call_task is
+    cancelled too rather than left running in the background.
+    """
+    call_task: "asyncio.Task[CallToolResult]" = asyncio.ensure_future(
+        session.call_tool(name, arguments, progress_callback=progress_callback)
+    )
+    elapsed_seconds = 0.0
+    try:
+        while True:
+            try:
+                return await asyncio.wait_for(
+                    asyncio.shield(call_task), timeout=heartbeat_interval_seconds
+                )
+            except asyncio.TimeoutError:
+                elapsed_seconds += heartbeat_interval_seconds
+                try:
+                    await adispatch_custom_event(
+                        "mcp_tool_heartbeat",
+                        {
+                            "server_name": server_name,
+                            "tool_name": name,
+                            "elapsed_seconds": elapsed_seconds,
+                        },
+                    )
+                except RuntimeError as e:
+                    logger.debug(
+                        "Skipping mcp_tool_heartbeat event dispatch: %s (tool=%s)",
+                        e,
+                        name,
+                    )
+    finally:
+        # Ensure call_task is never left orphaned, whether this coroutine
+        # exits via CancelledError, a return, or any other exception raised
+        # from the loop body (e.g. adispatch_custom_event).
+        if not call_task.done():
+            call_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await call_task
+
+
 def _make_execute_tool(
     *,
     config: MCPConnectionConfig,
     mcp_callbacks: _MCPCallbacks,
     session_pool: McpSessionPool | None = None,
     tool_list_cache: ToolListCache | None = None,
+    heartbeat_interval_seconds: float = 15.0,
 ) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:
     """Create an execute_tool handler that opens a session and calls the tool.
 
@@ -285,10 +343,13 @@ def _make_execute_tool(
                         )
                         if tool_list_cache is not None:
                             await tool_list_cache.invalidate_async(key=cache_key)
-                return await session.call_tool(
-                    request.name,
-                    request.args,
+                return await _execute_tool_call_with_heartbeat(
+                    session=session,
+                    name=request.name,
+                    arguments=request.args,
                     progress_callback=mcp_callbacks.progress_callback,
+                    server_name=request.server_name,
+                    heartbeat_interval_seconds=heartbeat_interval_seconds,
                 )
             except Exception:
                 await session_pool.evict(effective_config)
@@ -324,16 +385,22 @@ def _make_execute_tool(
                         )
                         if tool_list_cache is not None:
                             await tool_list_cache.invalidate_async(key=cache_key)
-                        result = await session.call_tool(
-                            request.name,
-                            request.args,
+                        result = await _execute_tool_call_with_heartbeat(
+                            session=session,
+                            name=request.name,
+                            arguments=request.args,
                             progress_callback=mcp_callbacks.progress_callback,
+                            server_name=request.server_name,
+                            heartbeat_interval_seconds=heartbeat_interval_seconds,
                         )
                 else:
-                    result = await session.call_tool(
-                        request.name,
-                        request.args,
+                    result = await _execute_tool_call_with_heartbeat(
+                        session=session,
+                        name=request.name,
+                        arguments=request.args,
                         progress_callback=mcp_callbacks.progress_callback,
+                        server_name=request.server_name,
+                        heartbeat_interval_seconds=heartbeat_interval_seconds,
                     )
             except Exception as e:
                 captured_exception = e
@@ -355,6 +422,7 @@ async def call_mcp_tool_raw(
     tool_interceptors: list[ToolCallInterceptor] | None = None,
     session_pool: McpSessionPool | None = None,
     tool_list_cache: ToolListCache | None = None,
+    heartbeat_interval_seconds: float = 15.0,
 ) -> CallToolResult:
     """Call an MCP tool and return the raw CallToolResult.
 
@@ -374,6 +442,7 @@ async def call_mcp_tool_raw(
         mcp_callbacks=mcp_callbacks,
         session_pool=session_pool,
         tool_list_cache=tool_list_cache,
+        heartbeat_interval_seconds=heartbeat_interval_seconds,
     )
     handler = build_interceptor_chain(
         base_handler=execute_tool, tool_interceptors=tool_interceptors

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/mcp/mcp_tool_provider.py

@@ -6,6 +6,7 @@ from typing import Any, Dict, List
 
 import httpx
 from httpx import HTTPStatusError
+from langchain_core.callbacks.manager import adispatch_custom_event
 from langchain_core.tools import BaseTool
 from mcp import ClientSession
 from mcp.types import (
@@ -210,6 +211,24 @@ class MCPToolProvider:
         logger.info(
             f"MCP Tool Progress - Server: {context.server_name}, Progress: {progress}, Total: {total}, Message: {message}"
         )
+        try:
+            await adispatch_custom_event(
+                "mcp_task_progress",
+                {
+                    "task_id": "",
+                    "status": f"{progress:g}/{total:g}" if total else f"{progress:g}",
+                    "message": message,
+                    "server_name": context.server_name,
+                    "tool_name": context.tool_name,
+                },
+            )
+        except RuntimeError as e:
+            logger.debug(
+                "Skipping mcp_task_progress event dispatch: %s (server=%s, tool=%s)",
+                e,
+                context.server_name,
+                context.tool_name,
+            )
 
     def _build_connection_config(self, tool_config: AgentConfig) -> MCPConnectionConfig:
         """Build an MCPConnectionConfig from an AgentConfig."""
@@ -285,6 +304,7 @@ class MCPToolProvider:
                 ],
                 server_name=tool_config.name,
                 tool_list_cache=self.tool_list_cache,
+                heartbeat_interval_seconds=self.environment_variables.mcp_tool_heartbeat_interval_seconds,
             )
             tools.append(langchain_tool)
 
@@ -451,6 +471,7 @@ class MCPToolProvider:
                         server_name=tool_config.name,
                         session_pool=session_pool,
                         tool_list_cache=self.tool_list_cache,
+                        heartbeat_interval_seconds=self.environment_variables.mcp_tool_heartbeat_interval_seconds,
                     )
                     for mcp_tool in mcp_tools
                 ]
@@ -1010,6 +1031,7 @@ class MCPToolProvider:
             ],
             session_pool=session_pool,
             tool_list_cache=self.tool_list_cache,
+            heartbeat_interval_seconds=self.environment_variables.mcp_tool_heartbeat_interval_seconds,
         )
 
     async def fetch_mcp_app_embed(

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/models/model_factory.py

@@ -152,7 +152,7 @@ class ModelFactory:
         return model_name.startswith(("anthropic.", "us.anthropic."))
 
     @staticmethod
-    def _resolve_anthropic_bedrock_max_tokens(model_name: str) -> int | None:
+    def _resolve_anthropic_bedrock_max_tokens(*, model_name: str) -> int | None:
         """Look up the real max_output_tokens for a Bedrock Anthropic model ID.
 
         ``ChatAnthropicBedrock`` inherits ``ChatAnthropic.set_default_max_tokens``,
@@ -174,6 +174,11 @@ class ModelFactory:
                 _get_default_model_profile,
             )
         except ImportError:
+            logger.warning(
+                "langchain_aws._get_default_model_profile unavailable; "
+                "falling back to unset max_tokens for %s",
+                model_name,
+            )
             return None
         profile = _get_default_model_profile(model_name)
         max_output_tokens = profile.get("max_output_tokens")
@@ -192,8 +197,12 @@ class ModelFactory:
         from pydantic import SecretStr
         import boto3
 
+        model_parameters_dict = dict(model_parameters_dict)
+
         if "max_tokens" not in model_parameters_dict:
-            resolved_max_tokens = self._resolve_anthropic_bedrock_max_tokens(model_name)
+            resolved_max_tokens = self._resolve_anthropic_bedrock_max_tokens(
+                model_name=model_name
+            )
             if resolved_max_tokens is not None:
                 model_parameters_dict["max_tokens"] = resolved_max_tokens
                 logger.info(

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/structures/openai/request/chat_completion_api_request_wrapper.py

@@ -67,6 +67,7 @@ class ChatCompletionApiRequestWrapper(ChatRequestWrapper):
         enable_debug_logging: bool,
         environment_variables: "LanguageModelCommonEnvironmentVariables",
         emit_task_progress: bool | None = None,
+        emit_tool_heartbeat: bool | None = None,
     ) -> None:
         """
         Wraps an OpenAI /chat/completions request to provide a consistent interface for different request types.
@@ -84,6 +85,11 @@ class ChatCompletionApiRequestWrapper(ChatRequestWrapper):
             if emit_task_progress is not None
             else environment_variables.emit_task_progress_in_chat_completions
         )
+        self._emit_tool_heartbeat: bool = (
+            emit_tool_heartbeat
+            if emit_tool_heartbeat is not None
+            else environment_variables.emit_tool_heartbeat_in_chat_completions
+        )
         self._debug_prefixes = environment_variables.debug_prefixes
         self._apply_debug_prefix_toggle()
 
@@ -278,6 +284,23 @@ class ChatCompletionApiRequestWrapper(ChatRequestWrapper):
             source="task_progress",
         )
 
+    @override
+    def create_tool_heartbeat_sse_event(
+        self,
+        *,
+        request_id: str,
+        tool_name: str,
+        elapsed_seconds: float,
+    ) -> str | None:
+        if not self._emit_tool_heartbeat:
+            return None
+        return self.create_sse_message(
+            request_id=request_id,
+            content=f"\n[Still running {tool_name}... ({elapsed_seconds:.0f}s)]\n",
+            usage_metadata=None,
+            source="tool_heartbeat",
+        )
+
     @override
     def create_non_streaming_response(
         self,

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/structures/openai/request/chat_request_wrapper.py

@@ -272,6 +272,21 @@ class ChatRequestWrapper(abc.ABC):
         """
         return None
 
+    def create_tool_heartbeat_sse_event(
+        self,
+        *,
+        request_id: str,
+        tool_name: str,
+        elapsed_seconds: float,
+    ) -> str | None:
+        """Emit a synthetic heartbeat while a tool call is in flight without
+        reporting real progress.
+
+        The default implementation returns None (no-op).  Subclasses override
+        to emit the event in their respective SSE formats.
+        """
+        return None
+
     def create_tool_start_sse_event(
         self,
         *,
@@ -294,9 +309,17 @@ class ChatRequestWrapper(abc.ABC):
         tool_name: str,
         tool_input: dict[str, Any] | None,
         runtime_seconds: float | None,
+        output: str | None = None,
+        is_error: bool = False,
     ) -> str | None:
         """Emit an SSE event when a tool finishes execution.
 
+        ``output`` is the tool's own result/error text (already converted to a
+        plain string and truncated by the caller) and ``is_error`` reflects the
+        underlying ToolMessage's status, so consumers can distinguish a tool
+        that ran to completion from one that failed without having to parse
+        free-text content.
+
         The default implementation returns None (no-op).  Subclasses that
         support structured tool events (e.g. Responses API) override this
         to emit a typed SSE frame the client can use for status updates.

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/structures/openai/request/responses_api_request_wrapper.py

@@ -338,8 +338,16 @@ class ResponsesApiRequestWrapper(ChatRequestWrapper):
         tool_name: str,
         tool_input: Dict[str, Any] | None,
         runtime_seconds: float | None,
+        output: str | None = None,
+        is_error: bool = False,
     ) -> str | None:
-        """Emit a ``response.output_item.done`` event with a ``function_call`` item."""
+        """Emit a ``response.output_item.done`` event with a ``function_call`` item.
+
+        Includes ``runtime_seconds`` and the tool's own ``output``/``is_error``
+        so consuming UIs (e.g. baileyai-skills-service's Stream events panel)
+        can show how long a call took and surface failures, rather than only
+        ever seeing a "completed" status with no result.
+        """
         event: Dict[str, Any] = {
             "type": "response.output_item.done",
             "output_index": 0,
@@ -350,7 +358,10 @@ class ResponsesApiRequestWrapper(ChatRequestWrapper):
                 "call_id": f"call_{request_id}_{tool_name}",
                 "name": tool_name,
                 "arguments": json.dumps(tool_input) if tool_input else "",
-                "status": "completed",
+                "status": "failed" if is_error else "completed",
+                "runtime_seconds": runtime_seconds,
+                "output": output or "",
+                "is_error": is_error,
             },
         }
         return f"data: {json.dumps(event)}\n\n"
@@ -373,6 +384,29 @@ class ResponsesApiRequestWrapper(ChatRequestWrapper):
         }
         return f"data: {json.dumps(event)}\n\n"
 
+    @override
+    def create_tool_heartbeat_sse_event(
+        self,
+        *,
+        request_id: str,
+        tool_name: str,
+        elapsed_seconds: float,
+    ) -> str | None:
+        """Emit a synthetic heartbeat as a ``task.progress`` SSE event.
+
+        Reuses the exact same wire format as create_task_progress_sse_event
+        so existing consumers (e.g. baileyai-skills-service's frontend, which
+        already treats any `type: "task.progress"` payload as a non-content
+        trace event) require no changes.
+        """
+        event: Dict[str, Any] = {
+            "type": "task.progress",
+            "task_id": "",
+            "status": "in_progress",
+            "message": f"Still running {tool_name}... ({elapsed_seconds:.0f}s)",
+        }
+        return f"data: {json.dumps(event)}\n\n"
+
     @staticmethod
     def _convert_usage_to_response_usage(
         usages: list[UsageMetadata],

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/tools/mcp/call_tool_tool.py

@@ -98,7 +98,7 @@ class CallToolTool(BaseTool):
         if entry is None:
             return (
                 f"Tool '{name}' not found. Use search_tools to find available tools.",
-                None,
+                {"is_error": True},
             )
 
         try:
@@ -122,9 +122,16 @@ class CallToolTool(BaseTool):
                 session_token=self.session_token,
             )
 
+            # Surface the *inner* tool's own error status (result.isError), not just
+            # transport-level failures — CallToolTool itself never raises for a
+            # rejected/invalid call, so this is the only place that signal exists.
             artifact: dict[str, Any] | None = None
-            if app_embed is not None:
-                artifact = {"mcp_app_embed": app_embed}
+            if app_embed is not None or result.isError:
+                artifact = {}
+                if app_embed is not None:
+                    artifact["mcp_app_embed"] = app_embed
+                if result.isError:
+                    artifact["is_error"] = True
 
             return text, artifact
         except AuthorizationNeededException:
@@ -138,4 +145,4 @@ class CallToolTool(BaseTool):
                 entry.server_name,
                 error_detail,
             )
-            return f"Error calling tool '{name}': {error_detail}", None
+            return f"Error calling tool '{name}': {error_detail}", {"is_error": True}

{language_model_common-2.0.91 → language_model_common-2.0.92}/languagemodelcommon/utilities/environment/language_model_common_environment_variables.py

@@ -17,6 +17,7 @@ logger = logging.getLogger(__name__)
 DEFAULT_STREAMING_BUFFER_FLUSH_INTERVAL_SECONDS = 0.05
 DEFAULT_LANGGRAPH_MAX_CONCURRENCY = 4
 DEFAULT_LANGGRAPH_RECURSION_LIMIT = 100
+DEFAULT_MCP_TOOL_HEARTBEAT_INTERVAL_SECONDS = 15.0
 
 # Default generic error message when not exposing technical details
 DEFAULT_GENERIC_ERROR_MESSAGE = (
@@ -289,6 +290,34 @@ class LanguageModelCommonEnvironmentVariables(
         """Timeout in seconds for tool calls."""
         return int(os.environ.get("TOOL_CALL_TIMEOUT_SECONDS", "600"))
 
+    @property
+    def mcp_tool_heartbeat_interval_seconds(self) -> float:
+        """Interval in seconds between synthetic heartbeat events emitted
+        while an MCP tool call is in flight without reporting progress."""
+        value = os.environ.get("MCP_TOOL_HEARTBEAT_INTERVAL_SECONDS")
+        if value is None:
+            return DEFAULT_MCP_TOOL_HEARTBEAT_INTERVAL_SECONDS
+        try:
+            parsed = float(value)
+            return max(1.0, parsed)
+        except ValueError:
+            logger.warning(
+                "Invalid MCP_TOOL_HEARTBEAT_INTERVAL_SECONDS value '%s'; using default=%s",
+                value,
+                DEFAULT_MCP_TOOL_HEARTBEAT_INTERVAL_SECONDS,
+            )
+            return DEFAULT_MCP_TOOL_HEARTBEAT_INTERVAL_SECONDS
+
+    @property
+    def emit_tool_heartbeat_in_chat_completions(self) -> bool:
+        """When True, synthetic MCP tool heartbeats are emitted as content
+        deltas in the Chat Completions streaming format. Separate from
+        emit_task_progress_in_chat_completions so enabling one does not
+        change the volume/behavior of the other."""
+        return self.str2bool(
+            os.environ.get("EMIT_TOOL_HEARTBEAT_IN_CHAT_COMPLETIONS", "false")
+        )
+
     @property
     def app_login_uri(self) -> str:
         value = os.environ.get("APP_LOGIN_URI")

language_model_common-2.0.91/VERSION

@@ -1 +0,0 @@
-2.0.91