[FEATURE] SDK helpers for multimodal workflows with Collections

[ramkumarkoppu]

Confirmation of Request Source

• I confirm that this feature request is for the xAI SDK Python library (e.g., client features, SDK methods, or documentation) and not for the xAI API itself (e.g., model capabilities or API changes).

Describe the feature you'd like

Add SDK convenience methods for common multimodal patterns:

1. Helper to store text + local image path reference together
2. Utility to reconstruct image paths from search results
3. Example code for vision + collections workflows

This would help developers working around the current text-only
Collections limitation until the API supports image storage natively.

Additional Context

No response

[Abhishek21g]

Proposed API: xai_sdk.multimodal_collections

Working on #78 on branch feature/collections-multimodal. Proposed thin helpers that compose existing Collections + chat APIs (no new gRPC surface):

Schema + upload

• DEFAULT_IMAGE_PATH_FIELD ("image_path")
• multimodal_field_definitions() — collection schema with optional inject_into_chunk
• build_multimodal_fields() / prepare_multimodal_upload()
• upload_multimodal_document() + upload_multimodal_document_async() — wrap collections.upload_document with UTF-8 text + path metadata

Search → vision bridge

• document_fields_by_file_id() (+ async) — batch_get_documents for match file IDs
• resolve_image_paths() / resolve_multimodal_search_results() — fields-first, chunk-content fallback
• local_image_data_url() + multimodal_user_message() — feed resolved paths into chat.image()

Rationale

Collections documents are text-only today; storing a local image path in document fields (with optional inject-into-chunk) lets developers run RAG search, recover paths, and run vision follow-up without waiting for native image indexing.

Happy to adjust field naming, validation, or whether upload helpers live on Client.collections vs a standalone module before the PR lands.