Add new tool calling capability by filintod · Pull Request #822 · dapr/python-sdk

filintod · 2025-07-29T02:32:47Z

Description

Implement conversation new alpha2 version with tool calling. As new protos are more complex, added DevEx helpers and tests.

Issue reference

Part of 1.16 dapr/dapr#8553

Please reference the issue this PR will close: #[issue number]

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

Code compiles correctly
Created/updated tests
Extended the documentation

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod · 2025-08-06T15:35:30Z

@elena-kolevska not sure if you are still working on this to review? I kind of redid the proto changes you had before, there has also been some changes on dapr master about it

elena-kolevska

Thanks for the contribution @filintod :)

I left few initial comments, will try to do a deeper review of the actual implementation as soon as possible.

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod · 2025-08-12T14:00:31Z

@elena-kolevska @acroca , as I was closing the feedback items, I was wondering if leaving all those converstation-specific classes in _request.py is ok or should I refactor the conversation ones to a _conversation.py file?

lmk

elena-kolevska · 2025-08-12T15:07:31Z

@elena-kolevska @acroca , as I was closing the feedback items, I was wondering if leaving all those converstation-specific classes in _request.py is ok or should I refactor the conversation ones to a _conversation.py file?

lmk

We already started separating domain-specific stuff in their own files (crypto, jobs, streaming subscriptions...), and I think it's a good practice we should continue. Thanks for suggesting it, Filinto! 🙏

elena-kolevska · 2025-08-12T15:08:11Z

@filintod there are some test and lint failures, pls ping me when they're fixed so I can rerun them.

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod · 2025-08-14T17:12:38Z

@acroca @elena-kolevska this should be ready now

Some example README refactor/lint Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod · 2025-08-30T21:49:31Z

ran tox -e ruff to fix the format count mismatch shown on the lint error. I thought tox -e flake8 green meant that it was ok, but now I know.

codecov · 2025-09-03T10:07:38Z

Codecov Report

❌ Patch coverage is 91.83246% with 78 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.33%. Comparing base (bffb749) to head (bc3dcf0).
⚠️ Report is 40 commits behind head on main.

Files with missing lines	Patch %	Lines
dapr/clients/grpc/_conversation_helpers.py	85.29%	75 Missing ⚠️
dapr/clients/grpc/conversation.py	99.03%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #822      +/-   ##
==========================================
+ Coverage   86.63%   87.33%   +0.70%     
==========================================
  Files          84       93       +9     
  Lines        4473     6143    +1670     
==========================================
+ Hits         3875     5365    +1490     
- Misses        598      778     +180

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

elena-kolevska

Last change request.. Small, but I believe it's really important

elena-kolevska · 2025-09-03T10:26:00Z

+def execute_registered_tool(name: str, params: Union[Params, str] = None) -> Any:
+    """Execute a registered tool."""
+    if isinstance(params, str):
+        params = json.loads(params)


This is a vulnerable part of our code, so we need to add at least some basic validation, and probably consider sanitisation for the future

Also, let's please add a detailed docstring explaining the vulnerability and giving some suggestions to developers on writing safe functions that validate the LLM input.
I know you said you'd be sending a docs PR, but I think it's important to have this here as well.

elena-kolevska · 2025-09-03T10:42:40Z

Is this planned to be included in 1.16? If so, we would need to cherrypick it in the 1.16 branch.

…rs that codecov pointed out Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

…ts for them to validate Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod · 2025-09-03T17:41:21Z

@elena-kolevska ptal, thanks

elena-kolevska · 2025-09-03T21:45:56Z

Why do we need two files for this? Let's either merge them or try to find a more descriptive name than one ending in _more

ok, it was just getting too big. I'll merge and check the error on python 3.13 shown in CI

ok please take another look

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

Signed-off-by: Elena Kolevska <elena@kolevska.com>

elena-kolevska

I did a quick fix of the linter, but there are still some typing errors

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod · 2025-09-04T14:15:41Z

sorry @elena-kolevska , I did changed something to fix an issue in a test breaking on 3.13, but looks like it broke 3.9. I need to have pre-commit for the future. It "must" be good now.

elena-kolevska · 2025-09-04T17:31:00Z

Merged! 🎉 Thanks for your contribution and your patience @filintod :)

* initial Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * fixes after proto change upstream Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * minor name changes and cleanup unused function Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * refactors, updates to readme, linting Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * feedback Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * feedback, updates Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * fix import in examples Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * cleanup, import, lint, more conversation helpers Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * clarify README, minor test import changes, copyright Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * feedback DRY test_conversation file Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * lint Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * move conversation classes in _response module to conversation module. Some example README refactor/lint Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * minor readme change Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * Update daprdocs/content/en/python-sdk-docs/python-client.md Co-authored-by: Albert Callarisa <albert@acroca.com> Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * lint Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * updates to fix issue with tool calling helper when dealing with classes instead of dataclasses, and also with serializatin output of the tool back to the LLM Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * coalesce conv helper tests, fix typing lint Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * make indent line method doc more dev friendly Co-authored-by: Elena Kolevska <elena-kolevska@users.noreply.github.com> Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * tackle some feedback, still missing unit tests Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * add unit test to convert_value_to_struct Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * more unit tests per feedback Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * make async version of unit test conversation Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * add some information how to run markdown tests with a different runtime Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * ran tox -e ruff, even though tox -e flake8 was fine Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * add tests to increase coverage in conversation and conversation_helpers that codecov pointed out Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * add more information on execute registered tools, also added more tests for them to validate Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * fix test failing on py 1.13. Merge two unit test files per feedback Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * Linter Signed-off-by: Elena Kolevska <elena@kolevska.com> * fix typing issue with UnionType in py3.9 Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> --------- Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> Signed-off-by: Elena Kolevska <elena@kolevska.com> Co-authored-by: Albert Callarisa <albert@acroca.com> Co-authored-by: Elena Kolevska <elena-kolevska@users.noreply.github.com> Co-authored-by: Elena Kolevska <elena@kolevska.com>

) * initial * fixes after proto change upstream * minor name changes and cleanup unused function * refactors, updates to readme, linting * feedback * feedback, updates * fix import in examples * cleanup, import, lint, more conversation helpers * clarify README, minor test import changes, copyright * feedback DRY test_conversation file * lint * move conversation classes in _response module to conversation module. Some example README refactor/lint * minor readme change * Update daprdocs/content/en/python-sdk-docs/python-client.md * lint * updates to fix issue with tool calling helper when dealing with classes instead of dataclasses, and also with serializatin output of the tool back to the LLM * coalesce conv helper tests, fix typing lint * make indent line method doc more dev friendly * tackle some feedback, still missing unit tests * add unit test to convert_value_to_struct * more unit tests per feedback * make async version of unit test conversation * add some information how to run markdown tests with a different runtime * ran tox -e ruff, even though tox -e flake8 was fine * add tests to increase coverage in conversation and conversation_helpers that codecov pointed out * add more information on execute registered tools, also added more tests for them to validate * fix test failing on py 1.13. Merge two unit test files per feedback * Linter * fix typing issue with UnionType in py3.9 --------- Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> Signed-off-by: Elena Kolevska <elena@kolevska.com> Co-authored-by: Albert Callarisa <albert@acroca.com> Co-authored-by: Elena Kolevska <elena-kolevska@users.noreply.github.com> Co-authored-by: Elena Kolevska <elena@kolevska.com>

* 1.16.0-rc1 Signed-off-by: Elena Kolevska <elena@kolevska.com> * [Conversation API - Alpha2] Add new tool calling capability (#822) (#832) * initial * fixes after proto change upstream * minor name changes and cleanup unused function * refactors, updates to readme, linting * feedback * feedback, updates * fix import in examples * cleanup, import, lint, more conversation helpers * clarify README, minor test import changes, copyright * feedback DRY test_conversation file * lint * move conversation classes in _response module to conversation module. Some example README refactor/lint * minor readme change * Update daprdocs/content/en/python-sdk-docs/python-client.md * lint * updates to fix issue with tool calling helper when dealing with classes instead of dataclasses, and also with serializatin output of the tool back to the LLM * coalesce conv helper tests, fix typing lint * make indent line method doc more dev friendly * tackle some feedback, still missing unit tests * add unit test to convert_value_to_struct * more unit tests per feedback * make async version of unit test conversation * add some information how to run markdown tests with a different runtime * ran tox -e ruff, even though tox -e flake8 was fine * add tests to increase coverage in conversation and conversation_helpers that codecov pointed out * add more information on execute registered tools, also added more tests for them to validate * fix test failing on py 1.13. Merge two unit test files per feedback * Linter * fix typing issue with UnionType in py3.9 --------- Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> Signed-off-by: Elena Kolevska <elena@kolevska.com> Co-authored-by: Albert Callarisa <albert@acroca.com> Co-authored-by: Elena Kolevska <elena-kolevska@users.noreply.github.com> Co-authored-by: Elena Kolevska <elena@kolevska.com> * update docs with tool calling helpers info (#838) Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> * 1.16.0rc2 Signed-off-by: Elena Kolevska <elena@kolevska.com> * use latest durabletask (#840) Signed-off-by: Cassandra Coyle <cassie@diagrid.io> * 1.16.0 Signed-off-by: Elena Kolevska <elena@kolevska.com> * Adds support for interceptors and concurrency_options arguments in the workflow engine (#841) Signed-off-by: Albert Callarisa <albert@diagrid.io> * Implement multi-app workflows (#844) * feat: Adds support for cross-app calls. Signed-off-by: Albert Callarisa <albert@diagrid.io> * Use durabletask alpha.9 Signed-off-by: Albert Callarisa <albert@diagrid.io> * Added examples for error scenarios in multi-app workflow Signed-off-by: Albert Callarisa <albert@diagrid.io> * Remove unnecessary hardcoded ports Signed-off-by: Albert Callarisa <albert@diagrid.io> --------- Signed-off-by: Albert Callarisa <albert@diagrid.io> * chore: Rename wait_until_ready to wait_for_sidecar (#843) Signed-off-by: Albert Callarisa <albert@diagrid.io> Co-authored-by: Elena Kolevska <elena-kolevska@users.noreply.github.com> * 1.16.1rc1 (#846) Signed-off-by: Albert Callarisa <albert@diagrid.io> --------- Signed-off-by: Elena Kolevska <elena@kolevska.com> Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com> Signed-off-by: Cassandra Coyle <cassie@diagrid.io> Signed-off-by: Albert Callarisa <albert@diagrid.io> Co-authored-by: Elena Kolevska <elena@kolevska.com> Co-authored-by: Filinto Duran <1373693+filintod@users.noreply.github.com> Co-authored-by: Albert Callarisa <albert@acroca.com> Co-authored-by: Elena Kolevska <elena-kolevska@users.noreply.github.com> Co-authored-by: Albert Callarisa <albert@diagrid.io>

marcduiker · 2025-11-18T11:35:50Z

@holopin-bot @filintod Thank you! Here's a digital badge as a small token of appreciation.

holopin-bot · 2025-11-18T11:35:53Z

Congratulations @filintod, the maintainer of this repository has issued you a badge! Here it is: https://holopin.io/claim/cmi4hz7rd000djs04wn4tt3ro

This badge can only be claimed by you, so make sure that your GitHub account is linked to your Holopin account. You can manage those preferences here: https://holopin.io/account.
Or if you're new to Holopin, you can simply sign up with GitHub, which will do the trick!

filintod added 2 commits July 28, 2025 21:32

initial

fdff6cf

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

fixes after proto change upstream

bbf381c

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod marked this pull request as ready for review August 1, 2025 00:04

filintod requested review from a team as code owners August 1, 2025 00:04

filintod commented Aug 1, 2025

View reviewed changes

Comment thread dapr/clients/base.py

filintod added 2 commits July 31, 2025 20:09

minor name changes and cleanup unused function

dbf6f56

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

refactors, updates to readme, linting

7a9a6cf

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

acroca reviewed Aug 7, 2025

View reviewed changes

elena-kolevska requested changes Aug 7, 2025

View reviewed changes

Comment thread examples/conversation/conversation_alpha2.py

Comment thread pyproject.toml Outdated

Comment thread examples/conversation/README.md

filintod added 3 commits August 7, 2025 11:35

Merge branch 'main' into filinto/tool-calling

e412740

Merge branch 'main' into filinto/tool-calling

08fdcab

feedback

287d4b7

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod added 2 commits August 13, 2025 20:08

feedback, updates

b548c00

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

fix import in examples

975df5d

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod commented Aug 14, 2025

View reviewed changes

Comment thread tox.ini

filintod added 4 commits August 14, 2025 08:15

cleanup, import, lint, more conversation helpers

6bbb0f5

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

clarify README, minor test import changes, copyright

8697b8e

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

feedback DRY test_conversation file

5d16fb5

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

lint

d0703ae

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod requested a review from elena-kolevska August 14, 2025 17:12

filintod requested a review from acroca August 14, 2025 17:13

filintod added 2 commits August 16, 2025 09:11

move conversation classes in _response module to conversation module.

e10d2d8

Some example README refactor/lint Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

minor readme change

3854bbd

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod mentioned this pull request Aug 17, 2025

update for Dapr 1.16 conversation SDK Python quickstart dapr/quickstarts#1215

Merged

4 tasks

elena-kolevska requested changes Sep 3, 2025

View reviewed changes

Merge branch 'main' into filinto/tool-calling

6ae63f4

elena-kolevska added this to the v1.16 milestone Sep 3, 2025

filintod changed the base branch from main to release-1.16 September 3, 2025 14:23

filintod changed the base branch from release-1.16 to main September 3, 2025 14:24

filintod added 2 commits September 3, 2025 12:08

add tests to increase coverage in conversation and conversation_helpe…

1e3baec

…rs that codecov pointed out Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

add more information on execute registered tools, also added more tes…

924541c

…ts for them to validate Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod requested a review from elena-kolevska September 3, 2025 17:40

elena-kolevska reviewed Sep 3, 2025

View reviewed changes

fix test failing on py 1.13. Merge two unit test files per feedback

9dd3bbf

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod requested a review from elena-kolevska September 4, 2025 00:53

Linter

5e1bab3

Signed-off-by: Elena Kolevska <elena@kolevska.com>

elena-kolevska requested changes Sep 4, 2025

View reviewed changes

fix typing issue with UnionType in py3.9

bc3dcf0

Signed-off-by: Filinto Duran <1373693+filintod@users.noreply.github.com>

filintod requested a review from elena-kolevska September 4, 2025 14:14

elena-kolevska approved these changes Sep 4, 2025

View reviewed changes

elena-kolevska merged commit 41f44c5 into dapr:main Sep 4, 2025
19 of 20 checks passed

filintod mentioned this pull request Sep 4, 2025

tool calling cherry-pick of PR 822 for tool calling in 1.16 #832

Merged

3 tasks

Conversation

filintod commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue reference

Checklist

Uh oh!

Uh oh!

filintod commented Aug 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elena-kolevska left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

filintod commented Aug 12, 2025

Uh oh!

elena-kolevska commented Aug 12, 2025

Uh oh!

elena-kolevska commented Aug 12, 2025

Uh oh!

Uh oh!

filintod commented Aug 14, 2025

Uh oh!

filintod commented Aug 30, 2025

Uh oh!

codecov Bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

elena-kolevska left a comment

Choose a reason for hiding this comment

Uh oh!

elena-kolevska Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

elena-kolevska Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

elena-kolevska commented Sep 3, 2025

Uh oh!

filintod commented Sep 3, 2025

Uh oh!

elena-kolevska Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

filintod Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

filintod Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

elena-kolevska left a comment

Choose a reason for hiding this comment

Uh oh!

filintod commented Sep 4, 2025

Uh oh!

Uh oh!

elena-kolevska commented Sep 4, 2025

Uh oh!

marcduiker commented Nov 18, 2025

Uh oh!

holopin-bot Bot commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

filintod commented Jul 29, 2025 •

edited

Loading

codecov Bot commented Sep 3, 2025 •

edited

Loading