xAi Embedding Collection support

[Bortus-AI]

It does not seem to have any access to query Grok embedding collections.
https://docs.x.ai/developers/files/collections

[nexus-marbell]

Research Assessment: xAI Embedding Collections Support (Issue #48)

What the xAI Collections API Offers

xAI provides a two-layer API for document storage and semantic search:

1. Files API (https://api.x.ai/v1/files)

• Upload documents (PDF, text, code, CSV, JSON, etc. — 80+ MIME types, max 48MB/file)
• Standard CRUD operations on uploaded files
• Files can be attached to individual chat requests for ephemeral context, or added to Collections for persistent search

2. Collections API (two base URLs)

• Management operations via https://management-api.x.ai/v1/collections — create, list, get, update, delete collections; add/remove documents; attach metadata
• Search via https://api.x.ai/v1/documents/search — query across collections with three retrieval modes: hybrid (default), keyword, or semantic
• Metadata filtering — AIP-160 syntax with =, !=, <, >, AND, OR operators on document metadata fields
• Collection config — field definitions with required, unique, and inject_into_chunk options per metadata field

3. Collections Search as a Server-Side Tool

• xAI exposes collections search as a server-side tool named file_search (OpenAI Responses API compatible) or collections_search (xAI SDK native)
• The model autonomously decides when to search and formulates queries
• Requires the Responses API — tool definition: {"type": "file_search", "vector_store_ids": ["collection_id"], "max_num_results": 10}
• Citations returned in URI format: collections://collection_id/files/file_id

4. Authentication

• XAI_API_KEY — for file uploads and search queries
• XAI_MANAGEMENT_API_KEY — separate key with specific permissions for collection management (create, update, delete, add/remove documents)

5. Limits

• Max file size: 100MB (collection uploads) / 48MB (file attachments)
• Max files globally: 100,000
• Max total storage: 100GB

How This Maps to the Bridge's Tool Structure

The bridge currently translates Anthropic Messages API to xAI Chat Completions or Responses API. Collections support would be a new capability layer, not a modification of the existing translation pipeline. There are two distinct integration approaches:

Approach A: Passthrough Proxy Endpoints (Management + Direct Search)

Add new proxy endpoints to the bridge that forward collection management and search requests to xAI:

Bridge Endpoint	xAI Target	Purpose
POST /v1/collections	management-api.x.ai/v1/collections	Create collection
GET /v1/collections	management-api.x.ai/v1/collections	List collections
GET /v1/collections/{id}	management-api.x.ai/v1/collections/{id}	Get collection
PUT /v1/collections/{id}	management-api.x.ai/v1/collections/{id}	Update collection
DELETE /v1/collections/{id}	management-api.x.ai/v1/collections/{id}	Delete collection
POST /v1/collections/{id}/documents	management-api.x.ai/v1/collections/{id}/documents	Add document
DELETE /v1/collections/{id}/documents/{fid}	management-api.x.ai/v1/collections/{id}/documents/{fid}	Remove document
POST /v1/documents/search	api.x.ai/v1/documents/search	Search

These are pure passthrough — no Anthropic-to-OpenAI translation needed since they are xAI-native endpoints, not Anthropic API endpoints. The bridge adds auth header injection and error format normalization.

Approach B: Server-Side Tool Pass-Through (Responses API)

For models using the Responses API path (multi-agent models), the file_search tool can be passed through in the tools array. The bridge already has a Responses API handler. This requires:

• Detecting {"type": "file_search"} in the Anthropic tools array
• Passing it through to xAI's Responses API without enrichment (it is a server-side tool, not a client-side tool)
• Handling file_search_call output items in the response translation

This approach lets the model autonomously search collections during reasoning, which is the more powerful integration.

Approach C: Standalone Embeddings Endpoint

xAI also has POST /v1/embeddings for raw embedding generation. This would be a simple passthrough endpoint — no format translation needed since the embedding API follows OpenAI format. Claude Code does not natively call embedding endpoints, so this would only be useful for external tooling using the bridge as a general xAI proxy.

Estimated Complexity

Approach	Complexity	Files Changed	New Files
A: Passthrough proxy endpoints	Medium	main.py (route registration), manifest.json	New handlers/collections.py (~120 lines), new handlers/files.py (~60 lines)
B: Responses API file_search tool	Small	translation/responses_forward.py, translation/responses_reverse.py	None
C: Standalone /v1/embeddings	Small	main.py	New handlers/embeddings.py (~40 lines)
All three	Medium	4-5 existing files	3 new files (~220 lines total)

The bridge architecture cleanly supports this — new handlers follow the existing handlers/ module pattern, and the factory/enrichment pipeline is not affected (collections operations are not Anthropic tool translations).

Key Considerations

1. Two API keys: Collections management requires XAI_MANAGEMENT_API_KEY in addition to the existing XAI_API_KEY. This means a new env var and an additional httpx.AsyncClient with base_url="https://management-api.x.ai/v1".

2. Two base URLs: The management API uses management-api.x.ai while search uses api.x.ai. The bridge currently has a single httpx.AsyncClient pointed at api.x.ai. A second client is needed for management operations.

3. Not a translation problem: Unlike the core /v1/messages endpoint which requires Anthropic-to-OpenAI format translation, collections endpoints are xAI-native. The bridge acts as an authenticated proxy, not a translator.

4. Server-side tool integration (Approach B) is the highest value: It lets the model search collections during reasoning without explicit user orchestration. However, it only works with models routed through the Responses API path.

5. No Anthropic equivalent: Anthropic does not have a collections/file-search API. There is no "Anthropic format" to translate from. These endpoints extend the bridge beyond protocol translation into xAI feature access.

Blockers / Questions for Issue Author

1. Which operations are needed? The issue says "query Grok embedding collections" — is search-only sufficient, or do you also need collection management (create, upload, delete) through the bridge?
2. Server-side tool vs direct search? Should the model be able to autonomously search collections during reasoning (Approach B), or is explicit search via a dedicated endpoint sufficient (Approach A)?
3. Standalone embeddings? Is raw embedding generation (POST /v1/embeddings) also desired, or only the collections/search workflow?
4. Management API key: Do you have or plan to use a separate XAI_MANAGEMENT_API_KEY? This is required for collection management but not for search.

---

Research conducted by Nexus (claude_agent). No code changes — assessment only.

[vantasnerdan]

#47 Let's also plan the switch to XAI SDK completely replacing any use of Responses or Chat Completions as part of this PR.