# providers.openai


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## The provider

`complete()` is a single round-trip: translate one OpenAI Chat
Completions response into a
[`Turn`](https://slashpablo.github.io/nbdialog/core.html#turn). The
tool-dispatch loop lives in
[`nbdialog.core.run_completion`](https://slashpablo.github.io/nbdialog/core.html#run_completion),
not here — every chat-completion provider that supports tools would
otherwise re-implement the same dance.

Construction is cheap and side-effect-free; credentials and config are
resolved lazily inside `_get_client`. Endpoint and deployment have no
defaults — set them via env or pass explicitly:

``` python
# option 1: env vars (recommended)
# export AZURE_OPENAI_ENDPOINT=https://your-resource.cognitiveservices.azure.com
# export AZURE_OPENAI_DEPLOYMENT=your-deployment-name
# export AZURE_API_KEY=...
set_provider(OpenAIProvider())

# option 2: explicit
set_provider(OpenAIProvider(endpoint="https://...", deployment="gpt-5.4"))
```

------------------------------------------------------------------------

<a
href="https://github.com/slashpablo/nbdialog/blob/main/nbdialog/providers/openai.py#L11"
target="_blank" style="float:right; font-size:smaller">source</a>

### OpenAIProvider

``` python

def OpenAIProvider(
    deployment:str | None=None, endpoint:str | None=None, api_version:str='2024-12-01-preview',
    api_key_env:str='AZURE_API_KEY', max_completion_tokens:int=16384
):

```

*OpenAI Chat Completions over the `openai` SDK. `complete()` is one
round-trip — driven by
[`run_completion`](https://slashpablo.github.io/nbdialog/core.html#run_completion)
when tools are involved.*

``` python
p = OpenAIProvider(endpoint="https://demo", deployment="gpt-5.4")
p.deployment, p._client  # client is lazy — None until the first complete()
```

    ('gpt-5.4', None)

Smoke test — only runs when credentials are present, so the doc build
stays green without them.

``` python
if all(os.environ.get(k) for k in ("AZURE_API_KEY", "AZURE_OPENAI_ENDPOINT", "AZURE_OPENAI_DEPLOYMENT")):
    print(OpenAIProvider().complete([{"role":"user","content":"ping"}]))
```

    Turn(text='pong', tool_calls=[], usage={'completion_tokens': 5, 'prompt_tokens': 7, 'total_tokens': 12, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}, 'latency_checkpoint': {'engine_tbt_ms': 16, 'engine_ttft_ms': 99, 'engine_ttlt_ms': 180, 'pre_inference_ms': 130, 'service_tbt_ms': 17, 'service_ttft_ms': 299, 'service_ttlt_ms': 374, 'total_duration_ms': 254, 'user_visible_ttft_ms': 169}}, finish_reason='stop')