chore: Update code snippets in docs (audio and builders components) #10156

vblagoje · 2025-11-27T15:38:10Z

Update of audio and builder pydocs components to ensure:

snippets in pydocs are actually valid executable python scripts
are up to date with current models etc
running these scripts doesn't raise any exceptions/errors etc

vercel · 2025-11-27T15:38:15Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
haystack-docs	Ignored	Preview		Dec 11, 2025 1:51pm

vblagoje · 2025-11-27T15:39:21Z

@anakin87 @dfokina this is ongoing effort, a bit of updates every day until we ensure all snippets are runnable without errors. And easier to review as well.

coveralls · 2025-11-27T15:44:28Z

Pull Request Test Coverage Report for Build 20135386210

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

0 of 0 changed or added relevant lines in 0 files are covered.
24 unchanged lines in 2 files lost coverage.
Overall coverage remained the same at 92.133%

Files with Coverage Reduction	New Missed Lines	%
components/builders/chat_prompt_builder.py	2	98.21%
components/generators/chat/hugging_face_local.py	22	85.51%

Totals
Change from base Build 20129510245:	0.0%
Covered Lines:	14124
Relevant Lines:	15330

💛 - Coveralls

anakin87

I have the impression that we should clarify the goal of this task.

In general, I would like to avoid errors in snippets, but also readability for users seem relevant to me.

(@dfokina can probably judge this better than me)

haystack/components/audio/whisper_local.py

anakin87 · 2025-11-27T15:40:39Z

haystack/components/audio/whisper_remote.py


-    whisper = RemoteWhisperTranscriber(api_key=Secret.from_token("<your-api-key>"), model="tiny")
-    transcription = whisper.run(sources=["path/to/audio/file"])
+    whisper = RemoteWhisperTranscriber(api_key=Secret.from_env_var("OPENAI_API_KEY"), model="whisper-1")


I am not sure... Secret.from_token("<your-api-key>") was a meaningful placeholder.
Secret.from_env_var("OPENAI_API_KEY") is just the default value. (If we want to go this route, we can just remove the api_key parameter from the example)

We can just use whisper = RemoteWhisperTranscriber(model="whisper-1")
If you think it's helpful, add a comment about setting the OPENAI_API_KEY env var.

haystack/components/builders/chat_prompt_builder.py

releasenotes/notes/fix-pydoc-examples-audio-builders-7b1d2d945099bb16.yaml

vblagoje · 2025-11-27T16:09:04Z

I have the impression that we should clarify the goal of this task.

In general, I would like to avoid errors in snippets, but also readability for users seem relevant to me.

(@dfokina can probably judge this better than me)

@anakin87 the goal is to make sure that pydocs are not just some hand-waving examples that actually don't work. As in usage of tiny whisper model that doesn't exist on OpenAI provider endpoint. We want to actually run these snippets nightly and confirm they are actually valid, executable scripts - to minimize the drift from pydocs and reality.

anakin87 · 2025-11-28T07:33:00Z

@anakin87 the goal is to make sure that pydocs are not just some hand-waving examples that actually don't work. As in usage of tiny whisper model that doesn't exist on OpenAI provider endpoint. We want to actually run these snippets nightly and confirm they are actually valid, executable scripts - to minimize the drift from pydocs and reality.

Yes, I understand. I just have the impression that testing everything without compromising user learning experience is challenging. But let's keep this work going and see how it evolves.

vblagoje · 2025-11-28T08:36:03Z

@anakin87 the goal is to make sure that pydocs are not just some hand-waving examples that actually don't work. As in usage of tiny whisper model that doesn't exist on OpenAI provider endpoint. We want to actually run these snippets nightly and confirm they are actually valid, executable scripts - to minimize the drift from pydocs and reality.

Yes, I understand. I just have the impression that testing everything without compromising user learning experience is challenging. But let's keep this work going and see how it evolves.

Totally, not taking this to extreme that every single pydoc code snippet has to run or.... but where it makes sense and it doesn't compromise learning experience. There is a way to tag snippet not to be run so where it is highly impractical to actually run the snippet we mark it so.

vblagoje · 2025-11-28T12:14:09Z

@dfokina I'll let you decide here for these changes. I'm ok with whatever you think is the best direction for audio and builders and in the meantime I'll remove the reno note that should def. not be there

This reverts commit 18733fa.

dfokina · 2025-11-28T12:25:56Z

@vblagoje @anakin87 I don't mind these changes honestly, I still think the examples are meaningful for the audience, plus we add some more explanations in the documentation guides. Our goal was always to make the code immediately runnable, which is not possible yet for the snippets inside the guides, so there are these placeholders, so why not use actual files and values in the docstrings :)

anakin87 · 2025-11-28T13:20:18Z

haystack/components/builders/chat_prompt_builder.py

    # no parameter init, we don't use any runtime template variables
    prompt_builder = ChatPromptBuilder()
-    llm = OpenAIChatGenerator(api_key=Secret.from_token("<your-api-key>"), model="gpt-4o-mini")
+    llm = OpenAIChatGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY"), model="gpt-5-mini")


Same as above.
We can just use llm = OpenAIChatGenerator(model="gpt-5-mini")
If you think it's helpful, add a comment about setting the OPENAI_API_KEY env var.

anakin87 · 2025-12-11T13:36:09Z

haystack/components/builders/chat_prompt_builder.py

+    # Output example (truncated):
+    # {'llm': {'replies': [ChatMessage(...)]}}

-    >> {'llm': {'replies': [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[TextContent(text=


Let's just restore this message

Still figuring out what is going on here @anakin87 as script fails with the current format. Let me see how we can avoid script failure and keep >> intact

I'm also OK with having # instead of >>

Ok because otherwise the script trips on these free standing "strings within quotes"

FAILED docs-website/reference/haystack-api/builders_api.md:snippet14 (line 395) — rc=1 --- stderr --- File "/var/folders/p0/1zhdwlps7399hytqp4_bzhk80000gn/T/doc_snippet_tests/docs-website__reference__haystack-api__builders_api.md__snippet_14.py", line 27 "Berlin is the capital city of Germany and one of the most vibrant ^

So I need to put them under comments.

anakin87

👍

vblagoje added 2 commits November 27, 2025 16:29

Update code snippets in docs

0a90946

Add reno note

18733fa

vblagoje requested a review from a team as a code owner November 27, 2025 15:38

vblagoje requested review from anakin87 and removed request for a team November 27, 2025 15:38

vblagoje requested review from dfokina and removed request for anakin87 November 27, 2025 15:38

github-actions bot added the type:documentation Improvements on the docs label Nov 27, 2025

vblagoje requested a review from anakin87 November 27, 2025 15:38

anakin87 requested changes Nov 27, 2025

View reviewed changes

Revert "Add reno note"

3e20eec

This reverts commit 18733fa.

anakin87 added the ignore-for-release-notes PRs with this flag won't be included in the release notes. label Nov 28, 2025

anakin87 reviewed Nov 28, 2025

View reviewed changes

Merge branch 'main' into doc_snippets_update

f64b6e1

vercel bot deployed to Preview December 11, 2025 10:43 View deployment

vblagoje added 4 commits December 11, 2025 11:45

PR feedback

91021fd

Minor fix

3041e04

No Secrets between us

b68eaec

Comments format update

1f1cc5d

anakin87 reviewed Dec 11, 2025

View reviewed changes

Restore output format

2c21ce4

anakin87 approved these changes Dec 11, 2025

View reviewed changes

Script output, needs to be commented

3d42fa2

vblagoje merged commit 4a56d52 into main Dec 11, 2025
24 checks passed

vblagoje deleted the doc_snippets_update branch December 11, 2025 14:06

chore: Update code snippets in docs (audio and builders components) #10156

chore: Update code snippets in docs (audio and builders components) #10156

Uh oh!

Conversation

vblagoje commented Nov 27, 2025

Uh oh!

vercel bot commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vblagoje commented Nov 27, 2025

Uh oh!

coveralls commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 20135386210

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

anakin87 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anakin87 Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anakin87 Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vblagoje commented Nov 27, 2025

Uh oh!

anakin87 commented Nov 28, 2025

Uh oh!

vblagoje commented Nov 28, 2025

Uh oh!

vblagoje commented Nov 28, 2025

Uh oh!

dfokina commented Nov 28, 2025

Uh oh!

anakin87 Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

vblagoje Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

anakin87 Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

vblagoje Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

anakin87 Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

vblagoje Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

anakin87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vercel bot commented Nov 27, 2025 •

edited

Loading

coveralls commented Nov 27, 2025 •

edited

Loading

anakin87 left a comment •

edited

Loading

anakin87 Nov 27, 2025 •

edited

Loading