Skip to content

Support_XAI.md

Latest commit

 

History

History
50 lines (41 loc) · 4.57 KB

Support_XAI.md

File metadata and controls

50 lines (41 loc) · 4.57 KB

Support for xAI Responses API

This document outlines the end-to-end plan for evolving the library into a multi-provider client that supports both OpenAI and xAI Responses APIs.

1. Renaming & Packaging

  • Rename all modules to the Responses namespace and adjust directory structure to match (lib/responses/*.ex).
  • (Removed) Provide a compatibility layer (OpenAI.Responses) that delegates to the new modules and emits deprecation warnings; mark for removal in a future major release.
  • Update mix.exs project module, application atom (:responses), metadata (name, description, links), and any config references that currently mention openai_responses.
  • Migrate runtime configuration keys to config :responses, ... while still reading legacy keys for backward compatibility, logging a warning when used.
  • Run formatter and compilation to confirm the rename is complete and no stale aliases remain.

2. Provider Abstraction Core

  • Implement lightweight provider registry (Responses.Provider, Responses.Provider.OpenAI, Responses.Provider.XAI) exposing base URL, credential sources, and warning metadata.
  • Resolve providers by model identifier (provider:model or heuristic prefixes) without maintaining alias maps or defaults.
  • Refactor request/streaming/cost helpers to derive base URL, credentials, and pricing via the resolved provider; responses carry provider info for downstream consumers.
  • Emit provider-specific warnings (e.g., xAI instructions) while forwarding requests unchanged.
  • Document supported prefixes, example usage, and guidance for extending the provider heuristics when new models appear.

3. Model Routing & Discovery

  • Route explicit provider:model identifiers directly to the chosen provider without additional aliasing.
  • Support prefix-based provider inference (gpt-*, o1*, o3*, o4-mini* → OpenAI; grok-* → xAI) and ensure follow-up calls reuse the resolved provider.
  • Document the identifier rules and add regression tests covering both prefixed and inferred models.
  • Update Responses.list_models/1 and /2 to fetch provider-specific listings, leaving combined listings for future consideration if needed.

4. Capability Validation & Feedback

  • Emit provider-specific warnings for unsupported options (e.g., instructions with xAI) while still forwarding the request.
  • Provide an opt-out path for provider warnings (provider_warnings: :ignore or global config) and document the behaviour.
  • Add regression tests covering warnings for provider-incompatible options.
  • Rewrite role: :developer messages to :system when targeting xAI while emitting a warning so applications can update their prompts deliberately.

5. Authentication & Configuration

  • Support provider-specific credentials via config/env lookup with clear errors when unset; base URL overrides are independent per provider.
  • Document configuration patterns for mixed-provider usage and migration from the single-provider setup.

6. Pricing & Telemetry

  • Extend Responses.Pricing to store OpenAI and xAI token prices; ensure cost calculations select the correct provider and surface an error if pricing data is missing.
  • Include provider metadata in telemetry hooks so downstream systems can differentiate usage by provider.
  • Add tests validating pricing for representative models across providers and guard against missing pricing entries.

7. Documentation & Tutorials

  • Refresh the README introduction, examples, and configuration guidance to reflect multi-provider support and provider discovery helpers.
  • Update tutorial.livemd, usage-rules.md, and supporting guides with provider-prefixed model examples, warning behaviour, and Responses.list_models/2 semantics.
  • Insert CHANGELOG entries under [Unreleased] covering the multi-provider documentation pass and the new list_models contract.
  • Review existing guides (e.g., AGENTS.md) for OpenAI-only assumptions and document the additional provider credentials.

8. Testing & Release Readiness

  • Update all unit and integration tests to use the new namespace and cover provider resolution, capability validation, and pricing behavior.
  • Add mocked HTTP tests validating both OpenAI and xAI request flows, including streaming scenarios.
  • Verify Credo, Dialyzer, formatter, and ExDoc outputs after the rename and provider abstraction changes.
  • Prepare migration guidance in README/CHANGELOG detailing code changes required by downstream users and confirm package metadata (hex.pm, repository URL) matches the new project identity.