feat(xai): xai_batch_chat tool — submit many completions to xAI Batch API

[Julientalbot]

Summary

Adds xai_batch_chat — a tool that wraps xAI's Batch API end-to-end (POST /v1/batches → add inline requests → poll → paginated retrieval) behind a single sync entry point. Use it to process dozens-to-thousands of chat completions in one shot at reduced pricing and with higher rate limits than the synchronous endpoint, with up to a 24h SLA per xAI.

Pairs with #23329 (xai_deferred_chat): deferred handles one long completion, batch handles many short-to-medium ones in parallel.

Why

The Batch API is the only xAI surface where the cost / rate-limit math actually works out for large evaluation, classification, or backfill workloads. Hermes' autonomous mode and delegation features can already orchestrate long-running tasks, but every call still hits the synchronous endpoint with full per-minute rate limits. With this tool an agent (or a cron-scheduled hermes session) can fan out, e.g., a 5 000-row classification job in one POST and walk away.

Changes (5 files, +820/-0)

tools/xai_batch_tool.py (new, ~440 LoC)

Single public entry point:

xai_batch_chat(
    requests: list[dict],          # each: {"prompt"|"messages", "system"?, "model"?, "request_id"?, "extra_body"?}
    *,
    name: str | None = None,       # batch display name (auto-generated if absent)
    model: str | None = None,      # default for any request without its own
    wait: bool = True,             # block until done? (default yes)
    max_wait_seconds: int | None = None,    # default: 86400 (24h, matches xAI SLA)
    poll_interval_seconds: float | None = None,  # default: 30s
) -> {
    "batch_id": str,
    "state": {"num_requests": int, "num_pending": int, "num_success": int, "num_error": int, ...},
    # Only when wait=True:
    "results": [{"request_id": str, "response": dict | None, "error": dict | None}, ...],
}

• Each request dict accepts either a prompt (with optional system) or a full messages list.
• Per-request model overrides the tool-level default.
• Caller-provided request_id survives round-trip; missing IDs are auto-generated as req-{i:05d}-{hex}.
• wait=False returns immediately after submit + add + state-fetch — useful for fire-and-forget patterns where the caller resumes polling later (e.g. cron-driven).
• Configurable via config.yaml:

  xai_batch:
    model: grok-4-1-fast-non-reasoning
    max_wait_seconds: 7200
    poll_interval_seconds: 60

• Reuses tools.xai_http.hermes_xai_user_agent for User-Agent.
• Self-registers via tools.registry.registry.register with check_fn gating on XAI_API_KEY.

tests/tools/test_xai_batch_tool.py (new, ~340 LoC)

19 unit tests using a scripted httpx.request fake (no real network):

• Requirements & schema: check_xai_batch_requirements returns the right state with/without XAI_API_KEY; schema advertises required + optional params correctly.
• Argument validation: empty requests, missing API key, requests missing both prompt and messages, negative max_wait_seconds.
• Submit semantics: full create → add wiring (verifies the inline payload shape — batch_request_id, batch_request: {method, url, body}); default model resolution; per-request model overrides; messages overrides prompt; HTTP 4xx surfaces.
• wait=False: returns after submit + state-fetch; no poll, no results.
• Poll: walks num_pending from 2 → 1 → 0 then proceeds; timeout via mocked time.monotonic.
• Results pagination: multi-page walk with pagination_token; missing results yield response: None for the unfound request_id (graceful degradation).
• Headers: Authorization: Bearer <key> and User-Agent: Hermes-Agent/<version> on every HTTP call.

Wiring

• toolsets.py: xai_batch_chat added to _HERMES_CORE_TOOLS; new xai_batch toolset.
• hermes_cli/tools_config.py: new xai_batch entry in CONFIGURABLE_TOOLSETS.
• tests/tools/test_registry.py: tools.xai_batch_tool added to the manual snapshot list (same convention as feat(xai): add x_search tool — search X via xAI Responses API #14541, feat(xai): add video generation tool — generate/edit/extend via xAI grok-imagine-video #14543, feat(xai): xai_deferred_chat tool — long-running completions via submit + poll #23329).

Validation

• pytest tests/tools/test_xai_batch_tool.py tests/tools/test_registry.py → 50/50 passing locally on top of current main.

Backward compatibility

• Pure addition. No existing modules touched beyond the three single-line additions to toolsets.py, tools_config.py, and the registry snapshot list.
• Tool is check_fn-gated on XAI_API_KEY — invisible to users without an xAI key.
• xai_batch is not in any default toolset roster; users opt in via tools_config or by enabling the toolset in their profile.

Scope deliberately not in this PR

• File-based input (uploading a JSONL via Files API for >50 000 requests). This first PR uses the inline POST /v1/batches/{id}/requests path only — the file path requires Files API plumbing that doesn't currently exist anywhere in the codebase.
• Image / video / multi-modal batch results. The result mapper picks response from the result envelope, which works for chat completions; a richer adapter that surfaces image_response.url / video_response.url / usage is a clean follow-up.
• Cancellation, listing, request-level metadata. xai_batch_chat is a one-shot orchestration tool. Exposing xai_batch_cancel(batch_id), xai_batch_list(), and xai_batch_get(batch_id) as separate tools is straightforward but would inflate this PR; happy to do those follow-ups.

[teknium1]

Thanks Julien. We're going to pass on this one. xAI's Batch API is an offline cost-optimization for users running large jobs — not really an agent-facing runtime tool. Exposing it as a model tool would add schema bloat for a capability that's better used as a CLI command or external script. If you want batch processing inside Hermes, the closer fit is the existing infrastructure. Closing with appreciation.