From e6ea73d50c461d74ba62d97620c63b8968a9b659 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Mon, 6 Jul 2026 09:24:38 +0200 Subject: [PATCH 1/3] fix(ci): skip tim-kleyersburg.de in link validator (bot-blocked 403, site is live) The community PHP client author link (docs/weaviate/client-libraries/community.md) returns 200 in a browser but 403s GitHub-runner traffic via linkinator, failing PR link validation. Add it to the shared domainsToIgnore list, matching the existing convention for db-engines.com and similar bot-protected domains. --- _build_scripts/link-validator.js | 1 + 1 file changed, 1 insertion(+) diff --git a/_build_scripts/link-validator.js b/_build_scripts/link-validator.js index eed9c516..2b3c8715 100644 --- a/_build_scripts/link-validator.js +++ b/_build_scripts/link-validator.js @@ -51,6 +51,7 @@ const domainsToIgnore = [ 'https://static.scarf.sh', 'https://www.snowflake.com', 'https://stackoverflow.com/', + 'https://www.tim-kleyersburg.de/', // 403s automated requests (site loads fine in a browser); community PHP client author link 'https://towardsdatascience.com/', 'https://voyageai.com/', 'https://weaviateagents.featurebase.app', From 4998f52e4a5a3b714461742dfe78f98cef406247 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Mon, 6 Jul 2026 09:41:23 +0200 Subject: [PATCH 2/3] fix(ci): use built-in GITHUB_TOKEN for version fetch instead of expired PAT The custom GH_API_TOKEN secret (a PAT) expired, so update-config-versions.js got 401 Unauthorized from the GitHub API and failed the whole job at the 'Update versions from GitHub' step in both PR link validation and the production Build-and-deploy workflow. Switch both to the built-in secrets.GITHUB_TOKEN, matching llms_txt_tests.yml, which already fetches the same public release listings successfully. The env var name GH_API_TOKEN is unchanged so the script needs no edit; GITHUB_TOKEN never expires and needs no rotation. --- .github/workflows/branch.yaml | 4 ++-- .github/workflows/pull_requests.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/branch.yaml b/.github/workflows/branch.yaml index 84d3b48d..418dee41 100644 --- a/.github/workflows/branch.yaml +++ b/.github/workflows/branch.yaml @@ -10,7 +10,7 @@ jobs: name: Build and Deploy runs-on: ubuntu-latest env: - GH_API_TOKEN: ${{ secrets.GH_API_TOKEN }} + GH_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} SLACK_BOT: ${{ secrets.SLACK_BOT }} NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} GOOGLE_CONTAINER_ID: ${{ secrets.GOOGLE_CONTAINER_ID }} @@ -26,7 +26,7 @@ jobs: yarn install - name: Update versions from GitHub env: - GH_API_TOKEN: ${{ secrets.GH_API_TOKEN }} + GH_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | node _build_scripts/update-config-versions.js - name: Build Docusarus project diff --git a/.github/workflows/pull_requests.yaml b/.github/workflows/pull_requests.yaml index ae19053c..7548a6c5 100644 --- a/.github/workflows/pull_requests.yaml +++ b/.github/workflows/pull_requests.yaml @@ -21,7 +21,7 @@ jobs: yarn install - name: Update versions from GitHub env: - GH_API_TOKEN: ${{ secrets.GH_API_TOKEN }} + GH_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | node _build_scripts/update-config-versions.js - name: Build a dev version From 7d55f67386ecb32f3150a9eddda78d72b848790e Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Mon, 6 Jul 2026 13:40:32 +0200 Subject: [PATCH 3/3] docs(query-agent): make search-mode filtering a required argument The Query Agent service now requires the search-mode `filtering` argument to be "recall" or "precision"; the latest client (weaviate-agents 1.6.0) still defaults it to None and sends null, so every `.search()` call that omits `filtering` fails with a 422. Document `filtering` as required (recommending "recall") and pass `filtering="recall"` in every initial search-mode snippet (Python + TypeScript); the precision FilteringExample and pagination/ask calls are unchanged. --- _includes/code/llms-txt/python/query_agent.py | 2 +- _includes/code/python/quickstart.short.query_agent.py | 2 +- docs/query-agent/_includes/code/query_agent.mts | 4 ++++ docs/query-agent/_includes/code/query_agent.py | 6 ++++-- .../query-agent/_includes/code/query_agent_get_started.py | 1 + docs/query-agent/_includes/code/quickstart.mts | 1 + docs/query-agent/_includes/code/quickstart.py | 3 ++- docs/query-agent/_includes/code/search_mode.mts | 3 +++ docs/query-agent/_includes/code/search_mode.py | 5 +++++ docs/query-agent/guides/search_mode.md | 8 +++++--- 10 files changed, 27 insertions(+), 8 deletions(-) diff --git a/_includes/code/llms-txt/python/query_agent.py b/_includes/code/llms-txt/python/query_agent.py index 7b2c3412..77a26afb 100644 --- a/_includes/code/llms-txt/python/query_agent.py +++ b/_includes/code/llms-txt/python/query_agent.py @@ -28,7 +28,7 @@ print(response.final_answer) # Retrieval only (no generation) -search_response = qa.search("sci-fi movies", limit=5) +search_response = qa.search("sci-fi movies", filtering="recall", limit=5) # END llms_query_agent assert response.final_answer diff --git a/_includes/code/python/quickstart.short.query_agent.py b/_includes/code/python/quickstart.short.query_agent.py index 07cafb32..05663434 100644 --- a/_includes/code/python/quickstart.short.query_agent.py +++ b/_includes/code/python/quickstart.short.query_agent.py @@ -18,7 +18,7 @@ qa = QueryAgent(client=client, collections=["Movie"]) # Step 2.3: Perform a query using Search Mode - response = qa.search("Find a cool sci-fi movie.", limit=1) + response = qa.search("Find a cool sci-fi movie.", filtering="recall", limit=1) # highlight-end # Print the response diff --git a/docs/query-agent/_includes/code/query_agent.mts b/docs/query-agent/_includes/code/query_agent.mts index 61cd6890..f5a042d5 100644 --- a/docs/query-agent/_includes/code/query_agent.mts +++ b/docs/query-agent/_includes/code/query_agent.mts @@ -141,6 +141,7 @@ clothingResponse.display(); // START BasicSearchQuery // Perform a search using Search Mode (retrieval only, no answer generation) const basicSearchResponse = await qa.search("Find me some vintage shoes under $70", { + filtering: "recall", limit: 10 }) @@ -154,6 +155,7 @@ for (const obj of basicSearchResponse.searchResults.objects) { // Diversity ranking needs a vectorizer it can resolve. Scope the call to a // single collection with a target vector so the agent knows what to use. const diversitySearchResponse = await qa.search("summer shoes", { + filtering: "recall", limit: 10, diversityWeight: 0.5, collections: [{ @@ -179,6 +181,7 @@ basicResponse.display(); // START SearchModeResponseStructure // SearchModeResponse structure for TypeScript const searchResponse = await qa.search("winter boots for under $100", { + filtering: "recall", limit: 5 }) @@ -206,6 +209,7 @@ for (const obj of searchResponse.searchResults.objects) { // Search with pagination const responsePage1 = await qa.search( "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", { + filtering: "recall", limit: 3, }) diff --git a/docs/query-agent/_includes/code/query_agent.py b/docs/query-agent/_includes/code/query_agent.py index e8df3d9c..bd58dac5 100644 --- a/docs/query-agent/_includes/code/query_agent.py +++ b/docs/query-agent/_includes/code/query_agent.py @@ -211,7 +211,7 @@ # START BasicSearchQuery # Perform a search using Search Mode (retrieval only, no answer generation) -search_response = qa.search("Find me some vintage shoes under $70", limit=10) +search_response = qa.search("Find me some vintage shoes under $70", filtering="recall", limit=10) # Access the search results for obj in search_response.search_results.objects: @@ -220,7 +220,7 @@ # START SearchModeResponseStructure # SearchModeResponse structure for Python -search_response = qa.search("winter boots for under $100", limit=5) +search_response = qa.search("winter boots for under $100", filtering="recall", limit=5) # Access different parts of the response print(f"Original query: {search_response.searches[0].query}") @@ -244,6 +244,7 @@ # Search with pagination response_page_1 = qa.search( "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", + filtering="recall", limit=3, ) @@ -269,6 +270,7 @@ # START DiversityRanking search_response = qa.search( "summer shoes", + filtering="recall", limit=10, diversity_weight=0.5, collections=[ diff --git a/docs/query-agent/_includes/code/query_agent_get_started.py b/docs/query-agent/_includes/code/query_agent_get_started.py index 2cf55a8d..9abaea4b 100644 --- a/docs/query-agent/_includes/code/query_agent_get_started.py +++ b/docs/query-agent/_includes/code/query_agent_get_started.py @@ -135,6 +135,7 @@ # START SearchMode search_response = agent.search( "Find me some vintage shoes under $70", + filtering="recall", limit=10, ) diff --git a/docs/query-agent/_includes/code/quickstart.mts b/docs/query-agent/_includes/code/quickstart.mts index 727b5c93..0693851c 100644 --- a/docs/query-agent/_includes/code/quickstart.mts +++ b/docs/query-agent/_includes/code/quickstart.mts @@ -51,6 +51,7 @@ qa = new QueryAgent(client, { // START BasicSearchQuery const searchResponse = await qa.search( "Find me some vintage shoes under $70", { + filtering: "recall", limit: 10, }); // END BasicSearchQuery diff --git a/docs/query-agent/_includes/code/quickstart.py b/docs/query-agent/_includes/code/quickstart.py index 73af640c..013cc3ce 100644 --- a/docs/query-agent/_includes/code/quickstart.py +++ b/docs/query-agent/_includes/code/quickstart.py @@ -53,7 +53,8 @@ # START BasicSearchQuery search_response = qa.search( - "Find me some vintage shoes under $70", + "Find me some vintage shoes under $70", + filtering="recall", limit=10 ) # END BasicSearchQuery diff --git a/docs/query-agent/_includes/code/search_mode.mts b/docs/query-agent/_includes/code/search_mode.mts index fc9f355b..e07231ec 100644 --- a/docs/query-agent/_includes/code/search_mode.mts +++ b/docs/query-agent/_includes/code/search_mode.mts @@ -39,6 +39,7 @@ await populateWeaviate(client); // START BasicSearchMode const searchResponse = await qa.search("Find me some vintage shoes under $70", { + filtering: "recall", limit: 10, }); @@ -50,6 +51,7 @@ for (const obj of searchResponse.searchResults.objects) { // START DiversityRanking const diversitySearchResponse = await qa.search("summer shoes", { + filtering: "recall", limit: 10, diversityWeight: 0.5, collections: [{ @@ -67,6 +69,7 @@ for (const obj of diversitySearchResponse.searchResults.objects) { // Search with pagination const responsePage1 = await qa.search( "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", { + filtering: "recall", limit: 3, }); diff --git a/docs/query-agent/_includes/code/search_mode.py b/docs/query-agent/_includes/code/search_mode.py index d1bab68d..281fdb03 100644 --- a/docs/query-agent/_includes/code/search_mode.py +++ b/docs/query-agent/_includes/code/search_mode.py @@ -41,6 +41,7 @@ # START BasicSearchMode search_response = qa.search( query="Find me some vintage shoes under $70", + filtering="recall", limit=10, ) @@ -62,6 +63,7 @@ search_response = qa.search( "summer shoes", + filtering="recall", limit=10, diversity_weight=0.5, ) @@ -74,6 +76,7 @@ # Search with pagination response_page_1 = qa.search( "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", + filtering="recall", limit=3, ) @@ -135,6 +138,7 @@ # START AsyncSearch await async_qa.search( query="Find me some vintage shoes under $70", + filtering="recall", limit=10, ) # END AsyncSearch @@ -161,6 +165,7 @@ async def _async_run_for_testing(): await async_qa.search( query="Find me some vintage shoes under $70", + filtering="recall", limit=10, ) await async_client.close() diff --git a/docs/query-agent/guides/search_mode.md b/docs/query-agent/guides/search_mode.md index ff4d6a24..d2e87a6b 100644 --- a/docs/query-agent/guides/search_mode.md +++ b/docs/query-agent/guides/search_mode.md @@ -67,7 +67,7 @@ The `.search()` method accepts several arguments: | `query` | `str \| list[ChatMessage]` | The user query you want the agent to search with. This can be a simple string (`"Find me some vintage shoes under $70"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../reference/multi_turn_conversations.md). | | `collections` | `list[str \| QueryAgentCollectionConfig] \| None` | The name(s) of the collections to search. You can pass one or many collection names as a list of strings (e.g., `["ECommerce", "BookSales"]`), or provide collection configuration objects for more control. If specified in the `ask` method, it will overwrite those defined in the instantiation of `QueryAgent`. [See the page on collection configuration for more detail](../reference/advanced_collections.md). | | `limit` | `int` | The maximum number of results returned in this page of results. Defaults to `20`. Use [`.next()`](#pagination) to fetch additional pages. | -| `filtering` | `Literal["recall", "precision"]` | Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. See [Customized filtering](#customized-filtering) below. | +| `filtering` | `Literal["recall", "precision"]` | **Required.** Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. Pass `"recall"` for most cases. See [Customized filtering](#customized-filtering) below. | | `diversity_weight` | `float \| None` | A value between `0.0` and `1.0` that biases the result ranking towards diversity using Maximal Marginal Relevance (MMR). See [Diversity ranking](#diversity-ranking) below. | @@ -77,7 +77,7 @@ The `.search()` method accepts several arguments: | `query` | `string \| ChatMessage[]` | The user query you want the agent to search with. This can be a simple string (`"Find me some vintage shoes under $70"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../reference/multi_turn_conversations.md). | | `collections` | `(string \| QueryAgentCollectionConfig)[]` | The name(s) of the collections to search. You can pass one or many collection names as a list of strings (e.g., `["ECommerce", "BookSales"]`), or provide collection configuration objects for more control. If specified in the `ask` method, it will overwrite those defined in the instantiation of `QueryAgent`. [See the page on collection configuration for more detail](../reference/advanced_collections.md). | | `limit` | `number` | The maximum number of results returned in this page of results. Defaults to `20`. Use [`.next()`](#pagination) to fetch additional pages. | -| `filtering` | `"recall" \| "precision"` | Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. See [Customized filtering](#customized-filtering) below. | +| `filtering` | `"recall" \| "precision"` | **Required.** Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. Pass `"recall"` for most cases. See [Customized filtering](#customized-filtering) below. | | `diversityWeight` | `number` | A value between `0.0` and `1.0` that biases the result ranking towards diversity using Maximal Marginal Relevance (MMR). See [Diversity ranking](#diversity-ranking) below. | @@ -89,7 +89,9 @@ For more advanced searches, you can also specify _additional filters_ within the Search Mode uses query rewriting to transform your original query into one or multiple Weaviate queries, each with either a search query, metadata filters, or both. The `filtering` parameter controls how many Weaviate queries are generated. -- **`"recall"`** (default): Generates multiple Weaviate queries spanning different filters and interpretations of the user query. You should use these when you prefer to get results, even if they don't match every criteria in your query. +`filtering` is a required argument; pass either `"recall"` or `"precision"`. `"recall"` is recommended when you want more results. + +- **`"recall"`** (recommended): Generates multiple Weaviate queries spanning different filters and interpretations of the user query. You should use these when you prefer to get results, even if they don't match every criteria in your query. - **`"precision"`**: Generates a single Weaviate query targeting the most likely interpretation of the user query. You should use this when you want the results to follow your query intent closely, even if that means potentially receiving no results.