Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python
27.1 KB
Raw Blame
import asyncio
from typing import Any

import pytest
from pydantic import BaseModel, TypeAdapter

import dspy
from dspy.adapters.types.tool import Tool, ToolCallResults, ToolCalls, convert_input_schema_to_tool_args
from dspy.clients.lm15_boundary import request_kwargs
from dspy.lm15 import Message, Request, ToolResultPart, tool_result


# Test fixtures
def dummy_function(x: int, y: str = "hello") -> str:
    """A dummy function for testing.

    Args:
        x: An integer parameter
        y: A string parameter
    """
    return f"{y} {x}"


class DummyModel(BaseModel):
    field1: str = "hello"
    field2: int


def dummy_with_pydantic(model: DummyModel) -> str:
    """A dummy function that accepts a Pydantic model."""
    return f"{model.field1} {model.field2}"


class Address(BaseModel):
    street: str
    city: str
    zip_code: str
    is_primary: bool = False


class ContactInfo(BaseModel):
    email: str
    phone: str | None = None
    addresses: list[Address]


class UserProfile(BaseModel):
    user_id: int
    name: str
    age: int | None = None
    contact: ContactInfo
    tags: list[str] = []


class Note(BaseModel):
    content: str
    author: str


def complex_dummy_function(profile: UserProfile, priority: int, notes: list[Note] | None = None) -> dict[str, Any]:
    """Process user profile with complex nested structure.

    Args:
        profile: User profile containing nested contact and address information
        priority: Priority level of the processing
        notes: Optional processing notes
    """
    primary_address = next(
        (addr for addr in profile.contact.addresses if addr.is_primary), profile.contact.addresses[0]
    )

    return {
        "user_id": profile.user_id,
        "name": profile.name,
        "priority": priority,
        "primary_address": primary_address.model_dump(),
        "notes": notes,
    }


async def async_dummy_function(x: int, y: str = "hello") -> str:
    """An async dummy function for testing.

    Args:
        x: An integer parameter
        y: A string parameter
    """
    await asyncio.sleep(0.1)  # Simulate some async work
    return f"{y} {x}"


async def async_dummy_with_pydantic(model: DummyModel) -> str:
    """An async dummy function that accepts a Pydantic model."""
    await asyncio.sleep(0.1)  # Simulate some async work
    return f"{model.field1} {model.field2}"


async def async_complex_dummy_function(
    profile: UserProfile,
    priority: int,
    notes: list[Note] | None = None,
) -> dict[str, Any]:
    """Process user profile with complex nested structure asynchronously.

    Args:
        profile: User profile containing nested contact and address information
        priority: Priority level of the processing
        notes: Optional processing notes
    """
    # Simulate some async processing work
    await asyncio.sleep(0.1)

    primary_address = next(
        (addr for addr in profile.contact.addresses if addr.is_primary), profile.contact.addresses[0]
    )

    # Simulate more async work after finding primary address
    await asyncio.sleep(0.1)

    return {
        "user_id": profile.user_id,
        "name": profile.name,
        "priority": priority,
        "primary_address": primary_address.model_dump(),
        "notes": notes,
    }


def test_basic_initialization():
    tool = Tool(name="test_tool", desc="A test tool", args={"param1": {"type": "string"}}, func=lambda x: x)
    assert tool.name == "test_tool"
    assert tool.desc == "A test tool"
    assert tool.args == {"param1": {"type": "string"}}
    assert callable(tool.func)


def test_tool_from_function():
    tool = Tool(dummy_function)

    assert tool.name == "dummy_function"
    assert "A dummy function for testing" in tool.desc
    assert "x" in tool.args
    assert "y" in tool.args
    assert tool.args["x"]["type"] == "integer"
    assert tool.args["y"]["type"] == "string"
    assert tool.args["y"]["default"] == "hello"


def test_tool_defaults_are_json_serializable():
    import datetime
    import enum
    import json
    from decimal import Decimal

    class Unit(enum.Enum):
        CELSIUS = "celsius"
        FAHRENHEIT = "fahrenheit"

    def forecast(
        city: str,
        unit: Unit = Unit.CELSIUS,
        start: datetime.date = datetime.date(2026, 1, 2),
        price: Decimal = Decimal("1.5"),
        factor: float = Decimal("0.1"),
    ) -> str:
        return city

    tool = Tool(forecast)
    assert tool.args["unit"]["default"] == "celsius"
    assert tool.args["start"]["default"] == "2026-01-02"
    assert tool.args["price"]["default"] == 1.5
    assert tool.args["factor"]["default"] == 0.1
    assert tool(city="x", price=tool.args["price"]["default"], factor=tool.args["factor"]["default"]) == "x"
    json.dumps(tool.format_as_litellm_function_call())


def test_tool_defaults_without_json_form_are_kept():
    def scale(data: bytes = b"\xff") -> str:
        return "ok"

    tool = Tool(scale)
    assert tool.args["data"]["default"] == b"\xff"


def test_format_as_litellm_function_call_excludes_defaulted_args_from_required():
    # `x` has no default and must be required; `y` has a default and must be optional.
    tool = Tool(dummy_function)

    function_call = tool.format_as_litellm_function_call()
    parameters = function_call["function"]["parameters"]

    assert parameters["required"] == ["x"]
    assert "y" not in parameters["required"]
    # The default is still advertised on the property itself.
    assert parameters["properties"]["y"]["default"] == "hello"


def test_tool_from_class():
    class Foo:
        def __init__(self, user_id: str):
            self.user_id = user_id

        def __call__(self, a: int, b: int) -> int:
            """Add two numbers."""
            return a + b

    tool = Tool(Foo("123"))
    assert tool.name == "Foo"
    assert tool.desc == "Add two numbers."
    assert tool.args == {"a": {"type": "integer"}, "b": {"type": "integer"}}


def test_tool_from_function_with_pydantic():
    tool = Tool(dummy_with_pydantic)

    assert tool.name == "dummy_with_pydantic"
    assert "model" in tool.args
    assert tool.args["model"]["type"] == "object"
    assert "field1" in tool.args["model"]["properties"]
    assert "field2" in tool.args["model"]["properties"]
    assert tool.args["model"]["properties"]["field1"]["default"] == "hello"


def test_tool_from_function_with_pydantic_nesting():
    tool = Tool(complex_dummy_function)

    assert tool.name == "complex_dummy_function"

    assert "profile" in tool.args
    assert "priority" in tool.args
    assert "notes" in tool.args
    assert tool.args["profile"]["type"] == "object"
    assert tool.args["profile"]["properties"]["user_id"]["type"] == "integer"
    assert tool.args["profile"]["properties"]["name"]["type"] == "string"
    assert tool.args["profile"]["properties"]["age"]["anyOf"] == [{"type": "integer"}, {"type": "null"}]
    assert tool.args["profile"]["properties"]["contact"]["type"] == "object"
    assert tool.args["profile"]["properties"]["contact"]["properties"]["email"]["type"] == "string"

    # Reference should be resolved for nested pydantic models
    assert "$defs" not in str(tool.args["notes"])
    assert tool.args["notes"]["anyOf"][0]["type"] == "array"
    assert tool.args["notes"]["anyOf"][0]["items"]["type"] == "object"
    assert tool.args["notes"]["anyOf"][0]["items"]["properties"]["content"]["type"] == "string"
    assert tool.args["notes"]["anyOf"][0]["items"]["properties"]["author"]["type"] == "string"


def test_tool_callable():
    tool = Tool(dummy_function)
    result = tool(x=42, y="hello")
    assert result == "hello 42"


def test_tool_with_pydantic_callable():
    tool = Tool(dummy_with_pydantic)
    model = DummyModel(field1="test", field2=123)
    result = tool(model=model)
    assert result == "test 123"


def test_invalid_function_call():
    tool = Tool(dummy_function)
    with pytest.raises(ValueError):
        tool(x="not an integer", y="hello")


def test_parameter_desc():
    tool = Tool(dummy_function, arg_desc={"x": "The x parameter"})
    assert tool.args["x"]["description"] == "The x parameter"


def test_tool_with_default_args_without_type_hints():
    def foo(x=100):
        return x

    tool = Tool(foo)
    assert tool.args["x"]["default"] == 100
    assert not hasattr(tool.args["x"], "type")


def test_tool_call_parses_args():
    tool = Tool(dummy_with_pydantic)

    args = {
        "model": {
            "field1": "hello",
            "field2": 123,
        }
    }

    result = tool(**args)
    assert result == "hello 123"


def test_tool_call_parses_nested_list_of_pydantic_model():
    def dummy_function(x: list[list[DummyModel]]):
        return x

    tool = Tool(dummy_function)
    args = {
        "x": [
            [
                {
                    "field1": "hello",
                    "field2": 123,
                }
            ]
        ]
    }

    result = tool(**args)
    assert result == [[DummyModel(field1="hello", field2=123)]]


def test_tool_call_kwarg():
    def fn(x: int, **kwargs):
        return kwargs

    tool = Tool(fn)

    assert tool(x=1, y=2, z=3) == {"y": 2, "z": 3}


def test_tool_str():
    def add(x: int, y: int = 0) -> int:
        """Add two integers."""
        return x + y

    tool = Tool(add)
    assert (
        str(tool)
        == "add, whose description is <desc>Add two integers.</desc>. It takes arguments {'x': {'type': 'integer'}, 'y': {'type': 'integer', 'default': 0}}."
    )


@pytest.mark.asyncio
async def test_async_tool_from_function():
    tool = Tool(async_dummy_function)

    assert tool.name == "async_dummy_function"
    assert "An async dummy function for testing" in tool.desc
    assert "x" in tool.args
    assert "y" in tool.args
    assert tool.args["x"]["type"] == "integer"
    assert tool.args["y"]["type"] == "string"
    assert tool.args["y"]["default"] == "hello"

    # Test async call
    result = await tool.acall(x=42, y="hello")
    assert result == "hello 42"


@pytest.mark.asyncio
async def test_async_tool_with_pydantic():
    tool = Tool(async_dummy_with_pydantic)

    assert tool.name == "async_dummy_with_pydantic"
    assert "model" in tool.args
    assert tool.args["model"]["type"] == "object"
    assert "field1" in tool.args["model"]["properties"]
    assert "field2" in tool.args["model"]["properties"]

    # Test async call with pydantic model
    model = DummyModel(field1="test", field2=123)
    result = await tool.acall(model=model)
    assert result == "test 123"

    # Test async call with dict
    result = await tool.acall(model={"field1": "test", "field2": 123})
    assert result == "test 123"


@pytest.mark.asyncio
async def test_async_tool_with_complex_pydantic():
    tool = Tool(async_complex_dummy_function)

    profile = UserProfile(
        user_id=1,
        name="Test User",
        contact=ContactInfo(
            email="[email protected]",
            addresses=[
                Address(street="123 Main St", city="Test City", zip_code="12345", is_primary=True),
                Address(street="456 Side St", city="Test City", zip_code="12345"),
            ],
        ),
    )

    result = await tool.acall(profile=profile, priority=1, notes=[Note(content="Test note", author="Test author")])
    assert result["user_id"] == 1
    assert result["name"] == "Test User"
    assert result["priority"] == 1
    assert result["notes"] == [Note(content="Test note", author="Test author")]
    assert result["primary_address"]["street"] == "123 Main St"


@pytest.mark.asyncio
async def test_async_tool_invalid_call():
    tool = Tool(async_dummy_function)
    with pytest.raises(ValueError):
        await tool.acall(x="not an integer", y="hello")


@pytest.mark.asyncio
async def test_async_tool_with_kwargs():
    async def fn(x: int, **kwargs):
        return kwargs

    tool = Tool(fn)

    result = await tool.acall(x=1, y=2, z=3)
    assert result == {"y": 2, "z": 3}


@pytest.mark.asyncio
async def test_async_concurrent_calls():
    """Test that multiple async tools can run concurrently."""
    all_started = asyncio.Event()
    started = set()

    async def wait_for_peers(x: int, y: str) -> str:
        started.add(x)
        if len(started) == 5:
            all_started.set()
        await all_started.wait()
        return f"{y} {x}"

    tool = Tool(wait_for_peers)
    tasks = [tool.acall(x=i, y=f"hello{i}") for i in range(5)]
    # No call can finish until all five have entered. The timeout only bounds a deadlock.
    results = await asyncio.wait_for(asyncio.gather(*tasks), timeout=10)

    # Verify results, `asyncio.gather` returns results in the order of the tasks
    assert results == [f"hello{i} {i}" for i in range(5)]


@pytest.mark.filterwarnings("ignore::RuntimeWarning")
def test_async_tool_call_in_sync_mode():
    tool = Tool(async_dummy_function)
    with dspy.context(allow_tool_async_sync_conversion=False):
        with pytest.raises(ValueError, match=r".*acall.*allow_tool_async_sync_conversion.*"):
            result = tool(x=1, y="hello")

    with dspy.context(allow_tool_async_sync_conversion=True):
        result = tool(x=1, y="hello")
        assert result == "hello 1"


@pytest.mark.asyncio
async def test_async_tool_sync_call_within_running_loop():
    tool = Tool(async_dummy_function)
    with dspy.context(allow_tool_async_sync_conversion=True):
        with pytest.raises(ValueError, match=r".*await tool\.acall.*"):
            tool(x=1, y="hello")


TOOL_CALL_TEST_CASES = [
    ([], {"tool_calls": []}),
    (
        [{"name": "search", "args": {"query": "hello"}}],
        {
            "tool_calls": [{"name": "search", "args": {"query": "hello"}}],
        },
    ),
    (
        [
            {"name": "search", "args": {"query": "hello"}},
            {"name": "translate", "args": {"text": "world", "lang": "fr"}},
        ],
        {
            "tool_calls": [
                {"name": "search", "args": {"query": "hello"}},
                {"name": "translate", "args": {"text": "world", "lang": "fr"}},
            ],
        },
    ),
    (
        [{"name": "get_time", "args": {}}],
        {
            "tool_calls": [{"name": "get_time", "args": {}}],
        },
    ),
]


@pytest.mark.parametrize("tool_calls_data,expected", TOOL_CALL_TEST_CASES)
def test_tool_calls_format_basic(tool_calls_data, expected):
    """Test ToolCalls.format with various basic scenarios."""
    tool_calls_list = [ToolCalls.ToolCall(**data) for data in tool_calls_data]
    tool_calls = ToolCalls(tool_calls=tool_calls_list)
    result = tool_calls.format()

    assert result == expected


def test_tool_calls_format_from_dict_list():
    """Test format works with ToolCalls created from from_dict_list."""
    tool_calls_dicts = [
        {"name": "search", "args": {"query": "hello"}},
        {"name": "translate", "args": {"text": "world", "lang": "fr"}},
    ]

    tool_calls = ToolCalls.from_dict_list(tool_calls_dicts)
    result = tool_calls.format()

    assert len(result["tool_calls"]) == 2
    assert result["tool_calls"][0]["name"] == "search"
    assert result["tool_calls"][1]["name"] == "translate"


def test_tool_calls_preserves_ids_from_dict_list_and_format_omits_ids():
    tool_calls = ToolCalls.from_dict_list(
        [
            {"id": "call_1", "name": "search", "args": {"query": "hello"}},
            {"name": "translate", "args": {"text": "world", "lang": "fr"}},
        ]
    )

    assert tool_calls.tool_calls[0].id == "call_1"
    assert tool_calls.tool_calls[1].id is None

    formatted = tool_calls.format()["tool_calls"]
    assert "id" not in formatted[0]
    assert "id" not in formatted[1]


def test_tool_calls_json_schema_omits_internal_id_field():
    schema = TypeAdapter(ToolCalls).json_schema()

    assert "tool_call_results" not in schema["properties"]
    assert "id" not in schema["$defs"]["ToolCall"]["properties"]
    assert schema["$defs"]["ToolCall"]["properties"]["args"]["additionalProperties"] is True
    assert schema["$defs"]["ToolCall"]["required"] == ["name", "args"]


def test_tool_calls_can_carry_results_without_formatting_them_for_lm():
    tool_call = ToolCalls.ToolCall(id="call_1", name="search", args={"query": "hello"})
    results = ToolCallResults.from_tool_calls_and_values([tool_call], [{"answer": "world"}])
    tool_calls = ToolCalls(tool_calls=[tool_call], tool_call_results=results)

    assert "tool_call_results" not in tool_calls.format()
    assert tool_calls.model_dump(mode="json")["tool_call_results"] == {
        "tool_call_results": [
            {"call_id": "call_1", "name": "search", "value": {"answer": "world"}, "is_error": False}
        ]
    }


def test_tool_call_results_from_tool_calls_and_values():
    tool_calls = [
        ToolCalls.ToolCall(id="call_1", name="search", args={"query": "hello"}),
        ToolCalls.ToolCall(id="call_2", name="fetch", args={"url": "https://example.com"}),
    ]

    results = ToolCallResults.from_tool_calls_and_values(
        tool_calls,
        [{"items": [1, 2]}, "failed"],
        is_errors=[False, True],
    )

    assert results.tool_call_results[0].call_id == "call_1"
    assert results.tool_call_results[0].name == "search"
    assert results.tool_call_results[0].value == {"items": [1, 2]}
    assert results.tool_call_results[0].is_error is False
    assert results.tool_call_results[1].call_id == "call_2"
    assert results.tool_call_results[1].name == "fetch"
    assert results.tool_call_results[1].value == "failed"
    assert results.tool_call_results[1].is_error is True


def test_tool_call_results_history_serialization_round_trip():
    tool_call = ToolCalls.ToolCall(id="call_1", name="search", args={"query": "hello"})
    results = ToolCallResults.from_tool_calls_and_values(
        [tool_call],
        [{"answer": "world"}],
    )
    tool_calls = ToolCalls(tool_calls=[tool_call], tool_call_results=results)

    history = dspy.History(messages=[{"tool_calls": tool_calls}])
    dumped = history.model_dump(mode="json")
    restored = dspy.History.model_validate(dumped)

    assert dumped == {
        "messages": [
            {
                "tool_calls": {
                    "tool_calls": [
                        {"name": "search", "args": {"query": "hello"}}
                    ],
                    "tool_call_results": {
                        "tool_call_results": [
                            {"call_id": "call_1", "name": "search", "value": {"answer": "world"}, "is_error": False}
                        ]
                    },
                }
            }
        ]
    }
    assert restored.messages == dumped["messages"]


def test_tool_call_results_can_round_trip_as_native_tool_result_message():
    tool_call = ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})
    results = ToolCallResults.from_tool_calls_and_values([tool_call], ['{"items": ["cat"]}'])
    result = results.tool_call_results[0]

    message = Message.tool(tool_result(result.call_id, result.value, name=result.name))

    assert len(message.parts) == 1
    assert isinstance(message.parts[0], ToolResultPart)
    assert message.parts[0].id == "call_1"
    assert message.parts[0].name == "search"
    assert message.parts[0].content[0].text == '{"items": ["cat"]}'

    request = Request(model="test-model", messages=[message])
    assert request_kwargs(request, "chat")["messages"] == [
        {"role": "tool", "content": '{"items": ["cat"]}', "tool_call_id": "call_1"}
    ]


def test_toolcalls_vague_match():
    """
    Test that ToolCalls can parse the data with slightly off format:

    - a single dict with "name" and "args"
    - a list of dicts with "name" and "args"
    - invalid input (should raise ValueError)
    """
    # Single dict with "name" and "args" should parse as one ToolCall
    data_single = {"name": "search", "args": {"query": "hello"}}
    tc = ToolCalls.model_validate(data_single)
    assert isinstance(tc, ToolCalls)
    assert len(tc.tool_calls) == 1
    assert tc.tool_calls[0].name == "search"
    assert tc.tool_calls[0].args == {"query": "hello"}

    # List of dicts with "name" and "args" should parse as multiple ToolCalls
    data_list = [
        {"name": "search", "args": {"query": "hello"}},
        {"name": "translate", "args": {"text": "world", "lang": "fr"}},
    ]
    tc = ToolCalls.model_validate(data_list)
    assert isinstance(tc, ToolCalls)
    assert len(tc.tool_calls) == 2
    assert tc.tool_calls[0].name == "search"
    assert tc.tool_calls[1].name == "translate"

    # Dict with "tool_calls" key containing a list of dicts
    data_tool_calls = {
        "tool_calls": [
            {"name": "search", "args": {"query": "hello"}},
            {"name": "get_time", "args": {}},
        ]
    }
    tc = ToolCalls.model_validate(data_tool_calls)
    assert isinstance(tc, ToolCalls)
    assert len(tc.tool_calls) == 2
    assert tc.tool_calls[0].name == "search"
    assert tc.tool_calls[1].name == "get_time"

    # Top-level "arguments" should be accepted as an alias for "args".
    tc = ToolCalls.model_validate({"name": "search", "arguments": {"query": "hello"}})
    assert len(tc.tool_calls) == 1
    assert tc.tool_calls[0].name == "search"
    assert tc.tool_calls[0].args == {"query": "hello"}

    # List entries with "arguments" should normalize to ToolCall.args.
    tc = ToolCalls.model_validate(
        [
            {"name": "search", "arguments": {"query": "hello"}},
            {"name": "get_time", "arguments": {}},
        ]
    )
    assert len(tc.tool_calls) == 2
    assert tc.tool_calls[0].args == {"query": "hello"}
    assert tc.tool_calls[1].args == {}

    # "tool_calls" wrappers may also use "arguments".
    tc = ToolCalls.model_validate({"tool_calls": [{"name": "search", "arguments": {"query": "hello"}}]})
    assert len(tc.tool_calls) == 1
    assert tc.tool_calls[0].args == {"query": "hello"}

    # Provider-style nested function.arguments should accept dict and JSON-string values.
    tc = ToolCalls.model_validate(
        {"type": "function", "function": {"name": "search", "arguments": {"query": "hello"}}}
    )
    assert len(tc.tool_calls) == 1
    assert tc.tool_calls[0].args == {"query": "hello"}

    tc = ToolCalls.model_validate(
        {"type": "function", "function": {"name": "search", "arguments": '{"query":"hello"}'}}
    )
    assert len(tc.tool_calls) == 1
    assert tc.tool_calls[0].args == {"query": "hello"}

    # Invalid input should raise ValueError
    with pytest.raises(ValueError):
        ToolCalls.model_validate({"foo": "bar"})
    with pytest.raises(ValueError):
        ToolCalls.model_validate([{"foo": "bar"}])
    with pytest.raises(ValueError, match="function value"):
        ToolCalls.from_dict_list([{"function": "bad"}])


def test_tool_convert_input_schema_to_tool_args_no_input_params():
    args, arg_types, arg_desc = convert_input_schema_to_tool_args(schema={"properties": {}})
    assert args == {}
    assert arg_types == {}
    assert arg_desc == {}


def test_tool_convert_input_schema_to_tool_args_lang_chain():
    # Example from langchain docs:
    # https://web.archive.org/web/20250723101359/https://api.python.langchain.com/en/latest/tools/langchain_core.tools.tool.html
    args, arg_types, arg_desc = convert_input_schema_to_tool_args(
        schema={
            "title": "fooSchema",
            "description": "The foo.",
            "type": "object",
            "properties": {
                "bar": {
                    "title": "Bar",
                    "description": "The bar.",
                    "type": "string",
                },
                "baz": {
                    "title": "Baz",
                    "type": "integer",
                },
            },
            "required": [
                "baz",
            ],
        }
    )
    assert args == {
        "bar": {"title": "Bar", "description": "The bar.", "type": "string"},
        "baz": {"title": "Baz", "type": "integer"},
    }
    assert arg_types == {
        "bar": str,
        "baz": int,
    }
    assert arg_desc == {
        "bar": "The bar.",
        "baz": "No description provided. (Required)",
    }




def test_tool_call_execute():
    def get_weather(city: str) -> str:
        return f"The weather in {city} is sunny"

    def add_numbers(a: int, b: int) -> int:
        return a + b

    tools = [
        dspy.Tool(get_weather),
        dspy.Tool(add_numbers)
    ]

    tool_call = dspy.ToolCalls.ToolCall(name="get_weather", args={"city": "Berlin"})
    result = tool_call.execute(functions=tools)
    assert result == "The weather in Berlin is sunny"

    # Test individual tool call with function dict
    tool_call2 = dspy.ToolCalls.ToolCall(name="add_numbers", args={"a": 7, "b": 13})
    result2 = tool_call2.execute(functions={"add_numbers": add_numbers})
    assert result2 == 20

    # Test individual tool call with no arguments
    def get_pi():
        return 3.14159

    tool_call3 = dspy.ToolCalls.ToolCall(name="get_pi", args={})
    result3 = tool_call3.execute(functions={"get_pi": get_pi})
    assert result3 == 3.14159

    # Test error case
    tool_call4 = dspy.ToolCalls.ToolCall(name="nonexistent", args={})
    with pytest.raises(ValueError) as exc_info:
        tool_call4.execute(functions=tools)
    assert "not found" in str(exc_info.value)


def test_tool_call_execute_with_local_functions():
    def main():
        def local_add(a: int, b: int) -> int:
            return a + b

        def local_multiply(x: int, y: int) -> int:
            return x * y

        # Test individual execution with local function
        tool_call1 = dspy.ToolCalls.ToolCall(name="local_add", args={"a": 10, "b": 15})
        result1 = tool_call1.execute()  # Should find local function automatically
        assert result1 == 25

        tool_call2 = dspy.ToolCalls.ToolCall(name="local_multiply", args={"x": 4, "y": 7})
        result2 = tool_call2.execute()  # Should find local function automatically
        assert result2 == 28

        # Test locals take precedence over globals
        try:
            globals()["local_add"] = lambda a, b: a + b + 1000
            precedence_call = dspy.ToolCalls.ToolCall(name="local_add", args={"a": 1, "b": 2})
            result = precedence_call.execute()
            assert result == 3  # Should use local function (1+2=3), not global (1+2+1000=1003)
        finally:
            globals().pop("local_add", None)

    main()


def test_tool_calls_none_and_empty_dict_mean_no_calls():
    """`"tool_calls": null` / `{}` are how JSON-mode models say "no tool calls
    this turn" -- they must parse like `[]`, not raise AdapterParseError (#10612)."""
    for empty in (None, {}):
        calls = dspy.ToolCalls.model_validate(empty)
        assert calls.tool_calls == []
    # And through the wrapping form: {"tool_calls": None}
    calls = dspy.ToolCalls.model_validate({"tool_calls": None})
    assert calls.tool_calls == []


def test_tool_calls_none_reaches_empty_tool_calls_semantics():
    """End-to-end: ReActV2 with a JSON-mode model writing `"tool_calls": null`
    must take the usual empty_tool_calls path (like `[]`), not a parse error."""
    adapter = dspy.JSONAdapter()
    lm = dspy.utils.DummyLM([{"next_thought": "Nothing to call.", "tool_calls": None}] * 2, adapter=adapter)
    with dspy.context(lm=lm, adapter=adapter):
        try:
            dspy.ReActV2("question -> answer", tools=[])(question="hi")
            raised = None
        except Exception as e:
            raised = e
    assert raised is not None
    assert "empty_tool_calls" in str(raised), f"expected empty_tool_calls semantics, got: {raised}"