veris-ai 1.12.3__tar.gz → 1.14.0__tar.gz

{veris_ai-1.12.3 → veris_ai-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veris-ai
-Version: 1.12.3
+Version: 1.14.0
 Summary: A Python package for Veris AI tools
 Project-URL: Homepage, https://github.com/veris-ai/veris-python-sdk
 Project-URL: Bug Tracker, https://github.com/veris-ai/veris-python-sdk/issues

{veris_ai-1.12.3 → veris_ai-1.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "veris-ai"
-version = "1.12.3"
+version = "1.14.0"
 description = "A Python package for Veris AI tools"
 readme = "README.md"
 requires-python = ">=3.11"

{veris_ai-1.12.3 → veris_ai-1.14.0}/src/veris_ai/tool_mock.py

@@ -17,7 +17,16 @@ from typing import (
 
 from veris_ai.models import ResponseExpectation, ToolCallOptions
 from veris_ai.api_client import get_api_client
-from veris_ai.utils import convert_to_type, extract_json_schema, get_function_parameters
+from veris_ai.utils import (
+    convert_to_type,
+    execute_callback,
+    execute_combined_callback,
+    extract_json_schema,
+    get_function_parameters,
+    get_input_parameters,
+    launch_callback_task,
+    launch_combined_callback_task,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -238,13 +247,25 @@ class VerisSDK:
 
         return decorator
 
-    def mock(  # noqa: C901, PLR0915
+    def mock(  # noqa: C901, PLR0915, PLR0913
         self,
         mode: Literal["tool", "function"] = "tool",
         expects_response: bool | None = None,
         cache_response: bool | None = None,
+        input_callback: Callable[..., Any] | None = None,
+        output_callback: Callable[[Any], Any] | None = None,
+        combined_callback: Callable[..., Any] | None = None,
     ) -> Callable:
-        """Decorator for mocking tool calls."""
+        """Decorator for mocking tool calls.
+
+        Args:
+            mode: Whether to treat the function as a tool or function
+            expects_response: Whether the function expects a response
+            cache_response: Whether to cache the response
+            input_callback: Callable that receives input parameters as individual arguments
+            output_callback: Callable that receives the output value
+            combined_callback: Callable that receives both input parameters and mock_output
+        """
         response_expectation = (
             ResponseExpectation.NONE
             if (expects_response is False or (expects_response is None and mode == "function"))
@@ -273,9 +294,11 @@ class VerisSDK:
                         f"No session ID found, executing original function: {func.__name__}"
                     )
                     return await func(*args, **kwargs)
+
+                # Perform the mock call first
                 parameters = get_function_parameters(func, args, kwargs)
                 thread_id = _thread_id_context.get()
-                return await mock_tool_call_async(
+                result = await mock_tool_call_async(
                     func,
                     session_id,
                     parameters,
@@ -283,6 +306,14 @@ class VerisSDK:
                     thread_id,
                 )
 
+                # Launch callbacks as background tasks (non-blocking)
+                input_params = get_input_parameters(func, args, kwargs)
+                launch_callback_task(input_callback, input_params, unpack=True)
+                launch_callback_task(output_callback, result, unpack=False)
+                launch_combined_callback_task(combined_callback, input_params, result)
+
+                return result
+
             @wraps(func)
             def sync_wrapper(
                 *args: tuple[object, ...],
@@ -295,9 +326,11 @@ class VerisSDK:
                         f"No session ID found, executing original function: {func.__name__}"
                     )
                     return func(*args, **kwargs)
+
+                # Perform the mock call first
                 parameters = get_function_parameters(func, args, kwargs)
                 thread_id = _thread_id_context.get()
-                return mock_tool_call(
+                result = mock_tool_call(
                     func,
                     session_id,
                     parameters,
@@ -305,13 +338,34 @@ class VerisSDK:
                     thread_id,
                 )
 
+                # Execute callbacks synchronously (can't use async tasks in sync context)
+                input_params = get_input_parameters(func, args, kwargs)
+                execute_callback(input_callback, input_params, unpack=True)
+                execute_callback(output_callback, result, unpack=False)
+                execute_combined_callback(combined_callback, input_params, result)
+
+                return result
+
             # Return the appropriate wrapper based on whether the function is async
             return async_wrapper if is_async else sync_wrapper
 
         return decorator
 
-    def stub(self, return_value: Any) -> Callable:  # noqa: ANN401
-        """Decorator for stubbing toolw calls."""
+    def stub(
+        self,
+        return_value: Any,  # noqa: ANN401
+        input_callback: Callable[..., Any] | None = None,
+        output_callback: Callable[[Any], Any] | None = None,
+        combined_callback: Callable[..., Any] | None = None,
+    ) -> Callable:
+        """Decorator for stubbing tool calls.
+
+        Args:
+            return_value: The value to return when the function is stubbed
+            input_callback: Callable that receives input parameters as individual arguments
+            output_callback: Callable that receives the output value
+            combined_callback: Callable that receives both input parameters and mock_output
+        """
 
         def decorator(func: Callable) -> Callable:
             # Check if the original function is async
@@ -327,7 +381,15 @@ class VerisSDK:
                         f"No session ID found, executing original function: {func.__name__}"
                     )
                     return await func(*args, **kwargs)
+
                 logger.info(f"Stubbing function: {func.__name__}")
+
+                # Launch callbacks as background tasks (non-blocking)
+                input_params = get_input_parameters(func, args, kwargs)
+                launch_callback_task(input_callback, input_params, unpack=True)
+                launch_callback_task(output_callback, return_value, unpack=False)
+                launch_combined_callback_task(combined_callback, input_params, return_value)
+
                 return return_value
 
             @wraps(func)
@@ -337,7 +399,15 @@ class VerisSDK:
                         f"No session ID found, executing original function: {func.__name__}"
                     )
                     return func(*args, **kwargs)
+
                 logger.info(f"Stubbing function: {func.__name__}")
+
+                # Execute callbacks synchronously (can't use async tasks in sync context)
+                input_params = get_input_parameters(func, args, kwargs)
+                execute_callback(input_callback, input_params, unpack=True)
+                execute_callback(output_callback, return_value, unpack=False)
+                execute_combined_callback(combined_callback, input_params, return_value)
+
                 return return_value
 
             # Return the appropriate wrapper based on whether the function is async

{veris_ai-1.12.3 → veris_ai-1.14.0}/src/veris_ai/utils.py

@@ -1,4 +1,6 @@
+import asyncio
 import inspect
+import logging
 import sys
 import types
 import typing
@@ -18,6 +20,8 @@ from collections.abc import Callable
 
 from pydantic import BaseModel
 
+logger = logging.getLogger(__name__)
+
 
 def convert_to_type(value: object, target_type: type) -> object:
     """Convert a value to the specified type."""
@@ -303,3 +307,257 @@ def get_function_parameters(
             "type": str(get_type_hints(func).get(param_name, Any)),
         }
     return params_info
+
+
+# Callback utility functions
+
+
+def get_input_parameters(func: Callable, args: tuple, kwargs: dict) -> dict[str, Any]:
+    """Get the actual input parameters for callbacks.
+
+    Args:
+        func: The function being called
+        args: Positional arguments
+        kwargs: Keyword arguments
+
+    Returns:
+        Dictionary of parameter names to their actual values (not stringified),
+        excluding self and cls parameters. Preserves ctx if present.
+    """
+    sig = inspect.signature(func)
+    bound_args = sig.bind(*args, **kwargs)
+    bound_args.apply_defaults()
+
+    # Remove only self and cls - preserve ctx and all other parameters
+    params = dict(bound_args.arguments)
+    params.pop("self", None)
+    params.pop("cls", None)
+
+    return params
+
+
+def filter_callback_parameters(callback: Callable, params: dict[str, Any]) -> dict[str, Any]:
+    """Filter parameters to match what the callback can accept.
+
+    Args:
+        callback: The callback function to inspect
+        params: Dictionary of all available parameters
+
+    Returns:
+        Filtered dictionary containing only parameters the callback accepts
+    """
+    try:
+        sig = inspect.signature(callback)
+
+        # Check if callback accepts **kwargs (VAR_KEYWORD parameter)
+        has_var_keyword = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+
+        # If callback accepts **kwargs, pass all parameters
+        if has_var_keyword:
+            return params
+
+        # Otherwise, filter to only include parameters the callback accepts
+        accepted_params = {}
+        for param_name in sig.parameters:
+            if param_name in params:
+                accepted_params[param_name] = params[param_name]
+
+        return accepted_params
+    except (ValueError, TypeError):
+        # If we can't inspect the signature, pass all parameters
+        # and let the callback handle it (will fail if incompatible)
+        return params
+
+
+def execute_callback(
+    callback: Callable | None,
+    data: Any,  # noqa: ANN401
+    unpack: bool = False,
+) -> None:
+    """Execute a callback synchronously if provided.
+
+    Args:
+        callback: The callback callable to execute
+        data: The data to pass to the callback
+        unpack: If True and data is a dict, unpack it as keyword arguments
+
+    Note:
+        Exceptions in callbacks are caught and logged to prevent breaking the main flow.
+    """
+    if callback is None:
+        return
+
+    try:
+        if unpack and isinstance(data, dict):
+            # Filter parameters to match callback signature
+            filtered_data = filter_callback_parameters(callback, data)
+            callback(**filtered_data)
+        else:
+            callback(data)
+    except Exception as e:
+        logger.warning(f"Callback execution failed: {e}", exc_info=True)
+
+
+async def execute_callback_async(
+    callback: Callable | None,
+    data: Any,  # noqa: ANN401
+    unpack: bool = False,
+) -> None:
+    """Execute a callback asynchronously if provided.
+
+    Handles both sync and async callback callables.
+
+    Args:
+        callback: The callback callable to execute (can be sync or async)
+        data: The data to pass to the callback
+        unpack: If True and data is a dict, unpack it as keyword arguments
+
+    Note:
+        Exceptions in callbacks are caught and logged to prevent breaking the main flow.
+    """
+    if callback is None:
+        return
+
+    try:
+        if inspect.iscoroutinefunction(callback):
+            if unpack and isinstance(data, dict):
+                # Filter parameters to match callback signature
+                filtered_data = filter_callback_parameters(callback, data)
+                await callback(**filtered_data)
+            else:
+                await callback(data)
+        else:
+            if unpack and isinstance(data, dict):
+                # Filter parameters to match callback signature
+                filtered_data = filter_callback_parameters(callback, data)
+                result = callback(**filtered_data)
+            else:
+                result = callback(data)
+            # If the result is a coroutine (can happen with functools.partial), await it
+            if inspect.iscoroutine(result):
+                await result
+    except Exception as e:
+        logger.warning(f"Callback execution failed: {e}", exc_info=True)
+
+
+def launch_callback_task(
+    callback: Callable | None,
+    data: Any,  # noqa: ANN401
+    unpack: bool = False,
+) -> None:
+    """Launch a callback as a background task (fire-and-forget).
+
+    Args:
+        callback: The callback callable to execute (can be sync or async)
+        data: The data to pass to the callback
+        unpack: If True and data is a dict, unpack it as keyword arguments
+
+    Note:
+        This launches the callback without blocking. Errors are logged but won't
+        affect the main execution flow.
+    """
+    if callback is None:
+        return
+
+    async def _run_callback() -> None:
+        """Wrapper to run callback with error handling."""
+        try:
+            if inspect.iscoroutinefunction(callback):
+                if unpack and isinstance(data, dict):
+                    # Filter parameters to match callback signature
+                    filtered_data = filter_callback_parameters(callback, data)
+                    await callback(**filtered_data)
+                else:
+                    await callback(data)
+            else:
+                if unpack and isinstance(data, dict):
+                    # Filter parameters to match callback signature
+                    filtered_data = filter_callback_parameters(callback, data)
+                    result = callback(**filtered_data)
+                else:
+                    result = callback(data)
+                if inspect.iscoroutine(result):
+                    await result
+        except Exception as e:
+            logger.warning(f"Callback execution failed: {e}", exc_info=True)
+
+    # Create task without awaiting (fire-and-forget)
+    try:
+        asyncio.create_task(_run_callback())
+    except RuntimeError:
+        # If no event loop is running, log a warning
+        logger.warning("Cannot launch callback task: no event loop running")
+
+
+def execute_combined_callback(
+    callback: Callable | None,
+    input_params: dict[str, Any],
+    mock_output: Any,  # noqa: ANN401
+) -> None:
+    """Execute a combined callback synchronously with input parameters and mock output.
+
+    Args:
+        callback: The callback callable to execute
+        input_params: Dictionary of input parameters
+        mock_output: The output from the mock/stub call
+
+    Note:
+        Exceptions in callbacks are caught and logged to prevent breaking the main flow.
+    """
+    if callback is None:
+        return
+
+    try:
+        # Combine input params with mock_output
+        combined_data = {**input_params, "mock_output": mock_output}
+        # Filter parameters to match callback signature
+        filtered_data = filter_callback_parameters(callback, combined_data)
+        callback(**filtered_data)
+    except Exception as e:
+        logger.warning(f"Combined callback execution failed: {e}", exc_info=True)
+
+
+def launch_combined_callback_task(
+    callback: Callable | None,
+    input_params: dict[str, Any],
+    mock_output: Any,  # noqa: ANN401
+) -> None:
+    """Launch a combined callback as a background task (fire-and-forget).
+
+    Args:
+        callback: The callback callable to execute (can be sync or async)
+        input_params: Dictionary of input parameters
+        mock_output: The output from the mock/stub call
+
+    Note:
+        This launches the callback without blocking. Errors are logged but won't
+        affect the main execution flow.
+    """
+    if callback is None:
+        return
+
+    async def _run_callback() -> None:
+        """Wrapper to run combined callback with error handling."""
+        try:
+            # Combine input params with mock_output
+            combined_data = {**input_params, "mock_output": mock_output}
+            # Filter parameters to match callback signature
+            filtered_data = filter_callback_parameters(callback, combined_data)
+
+            if inspect.iscoroutinefunction(callback):
+                await callback(**filtered_data)
+            else:
+                result = callback(**filtered_data)
+                if inspect.iscoroutine(result):
+                    await result
+        except Exception as e:
+            logger.warning(f"Combined callback execution failed: {e}", exc_info=True)
+
+    # Create task without awaiting (fire-and-forget)
+    try:
+        asyncio.create_task(_run_callback())
+    except RuntimeError:
+        # If no event loop is running, log a warning
+        logger.warning("Cannot launch combined callback task: no event loop running")