OpenAI client compatibility

Q6.5 qualifies OpenAI Python 2.32.0, the version in this repository's lockfile, against Q's actual FastAPI routes. Provider responses are synthetic: this proves transport and parameter propagation, not provider quality or universal model support. Use a matching deployed Q version. The machine-readable profile is checked against request schemas in required CI.

from openai import AsyncOpenAI
import os

client = AsyncOpenAI(
    api_key=os.environ["Q_API_KEY"],
    base_url=os.environ.get("Q_API_BASE_URL", "https://api.qdivision.ai/v1"),
    max_retries=0, timeout=60,
)
# Close with `async with client:` in the owning async application.

Qualified operationsCopy Anchor Link

The official client defaults embeddings to base64, which Q rejects with 422. Q's stable float response is retained. Token-ID inputs and token-ID batches are unsupported. Pin the model and dimensions using embedding contracts; selecting a provider model does not make its vectors interchangeable with another model's vectors.

models.list and models.retrieve are not qualified. Q's /models and /chat/models catalogues have Q-specific shapes; obtain an enabled model through the deployment's catalogue/configuration. Responses, legacy completions, stored-chat CRUD, Assistants/Threads, files, batches, fine-tuning, images, audio and Realtime operations are outside this profile. Similar route names do not imply compatibility. Other client languages/versions require their own conformance run.

Exact parametersCopy Anchor Link

Chat accepts model, messages, max_tokens, max_completion_tokens, temperature (0–2), top_p (0–1), frequency_penalty/presence_penalty (−2–2), n (1–10), stop (list of strings), stream, stream_options.include_usage, tools, tool_choice, parallel_tool_calls, response_format, seed and user. Token limits must be positive. max_completion_tokens retains Q's existing alias to gateway max_tokens; if both are supplied, max_tokens wins. It is not a native reasoning-token budget. Sampling, tools, JSON/schema output and seed behaviour depend on the selected provider. Raw JSON schema output is forwarded; it does not imply Q's independent claim or structured-output verification.

Messages accept role, text-or-null content, name, assistant tool_calls and tool tool_call_id. The qualified roles are system, developer, user, assistant and tool. Tool calls and replies retain their IDs/arguments through the gateway. Q returns model-selected calls; raw chat does not execute them. Content-part arrays, image/audio messages and legacy functions/function_call are unsupported. Use durable tool handoff for managed external execution.

Q extensions are top_k, tags, tenant_id, context_config, conversation_id and answer_mode. user and X-User-Id are attribution, never permission grants. API-key callers cannot change the authenticated tenant. The raw compatibility tests do not certify federated context or Answer Engine modes; use headless capabilities and machine answer streaming for their explicit contracts.

Embeddings accept input, optional model, dimensions, encoding_format="float", user, and Q extensions purpose/input_type (query or document). Batch/character limits are deployment settings exposed through capabilities. Usage is an estimate from Q's tokenizer, not a reconciled provider billing receipt. user is accepted but is not currently used by this endpoint for metering.

Unknown top-level request/message fields retain legacy behaviour: they are ignored. For example logprobs, store, metadata, reasoning_effort, service_tier, prediction and modalities are not supported or forwarded. Do not infer support from a successful HTTP response. New stream_options supports only include_usage and rejects unknown members. Scalar stop, multimodal content, base64 embeddings and token-ID inputs fail validation.

Streaming, errors and cancellationCopy Anchor Link

stream = await client.chat.completions.create(
    model=os.environ["Q_MODEL"],
    messages=[{"role": "user", "content": "A short synthetic example"}],
    stream=True, stream_options={"include_usage": True},
)
async with stream:
    async for chunk in stream:
        if chunk.choices:
            text = chunk.choices[0].delta.content or ""
        elif chunk.usage:
            total_tokens = chunk.usage.total_tokens

Q requests gateway usage for accounting; it exposes usage frames only when requested. Usage may be unavailable if the provider omits it or the connection closes early. Successful streams end with [DONE]. An error frame raises an official-client APIError; partial text is not success. Provider failures use safe messages without raw upstream error contents. Closing/cancelling the consumer releases Q's upstream iterator, but cannot undo already dispatched provider work or guarantee zero cost.

HTTP errors retain Q's error envelope, including code, correlation ID, outcome and retryability; official client exception classes classify HTTP status, and .body retains that envelope. This is not a promise of identical OpenAI error fields. Raw chat has no durable receipt/replay identity. Disable official-client automatic retries (max_retries=0); reconnecting by POST may repeat generation or tool selection. For reliable retry and explicit server cancellation, use the integration recipes and Q's durable runs.

Migration and verificationCopy Anchor Link

Existing float embeddings and list stop sequences keep their shapes. Tool history now reaches providers intact. New optional parallel_tool_calls is forwarded. Stream usage now follows explicit stream_options.include_usage; consumers needing usage should set it. Provider error detail is deliberately sanitised. No additional dependency or framework adapter is needed.

Run .venv/bin/python -m scripts.dev test integration tests/integration/test_openai_compatibility.py -q after the deterministic setup. Required integration CI runs this suite. Local conformance does not certify hosted deployment, proxies, latency, pricing or live models.