Add a distinct exception for generative query failures

[karthiksenv]

Generative-query failures currently raise the same WeaviateQueryError as ordinary searches, so applications cannot select RAG-specific troubleshooting by exception type.

Add WeaviateGenerativeQueryError as a subclass of WeaviateQueryError. Sync and async gRPC searches select it when the request contains the generative field, including deadline expiry and exhausted retries. Existing WeaviateQueryError handlers still catch it; message/error preserve the original details and exception chaining preserves the cause. Ordinary search, permission, and validation errors retain their existing behavior.

The exception identifies a failed generative request; it does not assume the provider caused the failure, since retrieval can also fail. The exception documentation includes a catch-order example and troubleshooting guidance.

Closes #818.

Validation:

• Before the fix: 26 regression cases failed because they received the generic exception; 6 compatibility cases passed.
• After the fix: all 36 targeted cases pass, covering all nine generate methods, sync/async clients, per-object/grouped/no-prompt requests, RPC errors, real client deadline expiry, retry exhaustion, and unchanged success/permission/validation/ordinary-query behavior.
• Real Weaviate 1.39.7 on Linux with a local OpenAI-compatible endpoint: both sync and async provider failures and deadline expiry raise the generic error on upstream 671f0a5c, and the specialized error with this patch. No external model service or API key is required.
• Repository-wide Ruff check, changed-file Ruff format/Flake8 checks, and Pyright 1.1.400 on the changed library files pass.
• Full Linux unit/mock suite: PYTEST_XDIST_AUTO_NUM_WORKERS=2 python -m pytest test mock_tests -q --tb=short — 646 passed, 1 skipped (Python 3.12.13). The run used a native-filesystem archive of the exact PR commit.

The development requirements pin Authlib 1.6.12 while package metadata requires >=1.7.1. The Windows regression environment used the CI-pinned dependencies; the full Linux suite and real-server comparison passed with dependencies satisfying package metadata. Two existing watchdog tests were unreliable on Windows; all three pass on Linux for both untouched upstream and the PR commit.

The upstream Main workflow currently reports action_required for this fork and needs maintainer approval to run. PR Security Lint passed.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[weaviate-git-bot]

To avoid any confusion in the future about your contribution to Weaviate, we work with a Contributor License Agreement. If you agree, you can simply add a comment to this PR that you agree with the CLA so that we can merge.

beep boop - the Weaviate bot 👋🤖

PS:
Are you already a member of the Weaviate Forum?

[karthiksenv]

I agree to the Weaviate Contributor License Agreement.

The Main CI workflow is awaiting maintainer approval. Could a maintainer approve the workflow and review this PR? The local Linux unit/mock suite passed with 646 tests passing and 1 skipped, and the before/after behavior was verified against Weaviate 1.39.7 for both sync and async clients.