Type errors due to`list[Tool]` -> `ToolsType` change

[denisw]

Describe the bug

In v2.19, Haystack changed the type of the tools parameter from list[Tool] to list[Tool | Toolset] in multiple places, including the Agent and ToolsInvoker constructor. Unfortunately, this is a breaking change to the typings because List is invariant. This means that for example, the following code does not type-check because even though Tool is a subtype of Tool | Toolset, list[Tool] is not a subtype of list[Tool | Toolset]:

tool1: Tool = ...
tool2: Tool = ...
tools = [tool1, tool2]
invoker = ToolInvoker(tools=tools)

Error message

From Pyright:

error: Argument of type "list[Tool]" cannot be assigned to parameter "tools" of type "ToolsType" in function "__init__"
    Type "list[Tool]" is not assignable to type "ToolsType"
      "list[Tool]" is not assignable to "list[Tool | Toolset]"
        Type parameter "_T@list" is invariant, but "Tool" is not the same as "Tool | Toolset"
        Consider switching from "list" to "Sequence" which is covariant
      "list[Tool]" is not assignable to "Toolset" (reportArgumentType)

Expected behavior

No type error, as before.

Additional context

A solution could be to accept a Sequence[Tool | Toolset] instead, which would work because Sequence is covariant. However, this means that the implementation either has to work with tuples and other types of sequences or manually converts the parameter to a list using list(tools).

To Reproduce

See the code snippet above. I used Pyright v1.1.407.

FAQ Check

• Have you had a look at our new FAQ page?

[vblagoje]

Looks like you are right @denisw can we somehow perhaps redefine ToolsType and thus restore typing backward compatibility?
Perhaps smth like:

ToolLike: TypeAlias = Union[Tool, Toolset]
ToolsType: TypeAlias = Union[Sequence[ToolLike], Toolset]

[denisw]

@vblagoje I think this will have the same issue. I think these options would work:

# Option 1: Sequence
ToolsType: TypeAlias = Union[Sequence[Union[Tool, Toolset]], Toolset]

# Option 2: Multiple List types
ToolsType: TypeAlias = Union[List[Tool], List[Union[Tool, Toolset]], Toolset]

[vblagoje]

ok thank you @denisw - I'll set up an example usage scenario tomorrow and see if it works, please try out as well if you manage.

[vblagoje]

@denisw you are right again.

# Option 1: Sequence
ToolsType: TypeAlias = Union[Sequence[Union[Tool, Toolset]], Toolset]

solves the typing backward compatibility. Have a look draft PR. If you pull this branch and run:

pyright test/tools/test_tools_variance.py

you'll get clean bill from pyright: 0 errors, 0 warnings, 0 informations

Then, revert back ToolsType to previous definition:
ToolsType = Union[list[Union[Tool, Toolset]], Toolset] in haystack/tools/__init__.py

and then run:

pyright test/tools/test_tools_variance.py

again, you'll get:

(haystack_3.11) ➜  haystack git:(variance_fix) ✗ pyright test/tools/test_tools_variance.py
/Users/vblagoje/workspace/haystack/test/tools/test_tools_variance.py
  /Users/vblagoje/workspace/haystack/test/tools/test_tools_variance.py:79:33 - error: Argument of type "list[Tool]" cannot be assigned to parameter "tools" of type "ToolsType" in function "__init__"
    Type "list[Tool]" is not assignable to type "ToolsType"
      "list[Tool]" is not assignable to "list[Tool | Toolset]"
        Type parameter "_T@list" is invariant, but "Tool" is not the same as "Tool | Toolset"
        Consider switching from "list" to "Sequence" which is covariant
      "list[Tool]" is not assignable to "Toolset" (reportArgumentType)
  /Users/vblagoje/workspace/haystack/test/tools/test_tools_variance.py:157:33 - error: Argument of type "list[Tool]" cannot be assigned to parameter "tools" of type "ToolsType" in function "__init__"
    Type "list[Tool]" is not assignable to type "ToolsType"
      "list[Tool]" is not assignable to "list[Tool | Toolset]"
        Type parameter "_T@list" is invariant, but "Tool" is not the same as "Tool | Toolset"
        Consider switching from "list" to "Sequence" which is covariant
      "list[Tool]" is not assignable to "Toolset" (reportArgumentType)
2 errors, 0 warnings, 0 informations

confirming your findings. The scope of change in this PR is functionally minimal to show restored runtime and static backward compatibility with 2.18. The full PR will require more pydoc changes across the project and we'll coordinate on the next steps and rollout internally first and include the fix, most likely, in the next micro version. 🙏 cc @sjrl

[vblagoje]

Also @tstadel please be aware of this one and potential impact on your side - which should hopefully be none or minimal.

[vblagoje]

ToolsType: TypeAlias = Union[List[Tool], List[Toolset], List[Union[Tool, Toolset]], Toolset]
ToolsType: TypeAlias = Union[List[Tool], List[Union[Tool, Toolset]], Toolset]

also work!

[vblagoje]

Ok we'll most likely go with #9960 as it requires minimal changes across the hyastack repo itself and the entire ecosystem including https://github.com/deepset-ai/haystack-core-integrations/ and all the docs.