diff --git a/python/README.md b/python/README.md index 47794706..51f4291c 100644 --- a/python/README.md +++ b/python/README.md @@ -54,6 +54,20 @@ To learn more about TypeChat, visit the [documentation](https://microsoft.github.io/TypeChat/docs/python/basic-usage/) which includes more information on TypeChat and how to get started. +## Reusing model authentication + +For keyless Azure OpenAI requests, pass a synchronous or asynchronous bearer-token +provider to `create_azure_openai_language_model` with `api_key=None`. If your app +already has a configured asynchronous OpenAI or Azure OpenAI client, use +`create_openai_language_model_from_client` instead. + +Both paths reuse authentication supplied by your application without adding SDK +dependencies to TypeChat or requiring TypeChat-specific environment-variable names. +Existing API-key and environment-based calls are unchanged. See the +[token-provider example](../site/src/docs/python/basic-usage.md#using-a-bearer-token-provider) +and [configured-client example](../site/src/docs/python/basic-usage.md#reusing-an-already-configured-client) +for ownership, retry, and error behavior. + ## Documenting schema fields Trailing Python comments on directly declared `TypedDict` and dataclass fields become diff --git a/python/src/typechat/__init__.py b/python/src/typechat/__init__.py index e2267ede..241f1cfc 100644 --- a/python/src/typechat/__init__.py +++ b/python/src/typechat/__init__.py @@ -2,7 +2,16 @@ # # SPDX-License-Identifier: MIT -from typechat._internal.model import PromptSection, TypeChatLanguageModel, create_language_model, create_openai_language_model, create_azure_openai_language_model +from typechat._internal.model import ( + ChatCompletionClient, + PromptSection, + TokenProvider, + TypeChatLanguageModel, + create_language_model, + create_openai_language_model, + create_azure_openai_language_model, + create_openai_language_model_from_client, +) from typechat._internal.result import Failure, Result, Success from typechat._internal.translator import TypeChatJsonTranslator from typechat._internal.ts_conversion import python_type_to_typescript_schema @@ -18,8 +27,11 @@ "Result", "python_type_to_typescript_schema", "PromptSection", + "TokenProvider", + "ChatCompletionClient", "create_language_model", "create_openai_language_model", "create_azure_openai_language_model", + "create_openai_language_model_from_client", "process_requests", ] diff --git a/python/src/typechat/_internal/model.py b/python/src/typechat/_internal/model.py index 42e412a1..7b92ed1c 100644 --- a/python/src/typechat/_internal/model.py +++ b/python/src/typechat/_internal/model.py @@ -1,5 +1,8 @@ import asyncio import json +import re +from collections.abc import Awaitable, Callable, Sequence +from inspect import isawaitable from types import TracebackType from typing_extensions import AsyncContextManager, Literal, Protocol, Self, TypedDict, cast, override @@ -16,6 +19,8 @@ class PromptSection(TypedDict): role: Literal["system", "user", "assistant"] content: str +TokenProvider = Callable[[], str | Awaitable[str]] + class TypeChatLanguageModel(Protocol): async def complete(self, prompt: str | list[PromptSection]) -> Result[str]: """ @@ -28,6 +33,71 @@ async def complete(self, prompt: str | list[PromptSection]) -> Result[str]: """ ... +class _ClientMessage(Protocol): + @property + def content(self) -> str | None: ... + +class _ClientChoice(Protocol): + @property + def message(self) -> _ClientMessage: ... + +class _ClientCompletion(Protocol): + @property + def choices(self) -> Sequence[_ClientChoice]: ... + +class _ClientCompletions(Protocol): + @property + def create(self) -> Callable[..., Awaitable[_ClientCompletion]]: + # SDK methods have overloaded parameters; require the awaited response shape. + ... + +class _ClientChat(Protocol): + @property + def completions(self) -> _ClientCompletions: ... + +class ChatCompletionClient(Protocol): + """An asynchronous OpenAI-compatible Chat Completions client supplied by the caller.""" + @property + def chat(self) -> _ClientChat: ... + +class _ClientLanguageModel(TypeChatLanguageModel): + _client: ChatCompletionClient + _model: str + + def __init__(self, client: ChatCompletionClient, model: str): + super().__init__() + self._client = client + self._model = model + + @override + async def complete(self, prompt: str | list[PromptSection]) -> Result[str]: + messages = [{"role": "user", "content": prompt}] if isinstance(prompt, str) else prompt + completion = await self._client.chat.completions.create( + model=self._model, + messages=messages, + temperature=0.0, + n=1, + stream=False, + ) + if not completion.choices: + return Failure("Client completion returned no choices.") + content = completion.choices[0].message.content + if not isinstance(content, str): + return Failure("Client completion returned no text content.") + return Success(content) + +def create_openai_language_model_from_client(client: ChatCompletionClient, model: str) -> TypeChatLanguageModel: + """ + Adapts an already configured asynchronous OpenAI-compatible Chat Completions client. + + TypeChat does not import an SDK, reconfigure or close the client, or add retries or timeouts. + Exceptions raised by the client propagate unchanged. The caller supplies the model name, + or the deployment name for Azure OpenAI. + """ + if not model.strip(): + raise ValueError("The client model or deployment name must not be empty.") + return _ClientLanguageModel(client, model) + _TRANSIENT_ERROR_CODES = [ 429, 500, @@ -58,12 +128,21 @@ class HttpxLanguageModel(TypeChatLanguageModel, AsyncContextManager): # Set to 0 or a negative value to disable the limit. max_response_bytes: int = 100 * 1024 * 1024 _async_client: httpx.AsyncClient + _token_provider: TokenProvider | None - def __init__(self, url: str, headers: dict[str, str], default_params: dict[str, str]): + def __init__( + self, + url: str, + headers: dict[str, str], + default_params: dict[str, str], + *, + token_provider: TokenProvider | None = None, + ): super().__init__() self.url = url self.headers = headers self.default_params = default_params + self._token_provider = token_provider self._async_client = httpx.AsyncClient() @override @@ -85,10 +164,18 @@ async def complete(self, prompt: str | list[PromptSection]) -> Success[str] | Fa retry_count = 0 while True: try: + request_headers = headers + if self._token_provider is not None: + token = self._token_provider() + if isawaitable(token): + token = await token + if not isinstance(token, str) or re.fullmatch(r"[\x21-\x7e]+", token) is None: + return Failure("Token provider must return a nonempty, header-safe bearer-token string.") + request_headers = {**headers, "Authorization": f"Bearer {token}"} async with self._async_client.stream( "POST", self.url, - headers=headers, + headers=request_headers, json=body, timeout=self.timeout_seconds, ) as response: @@ -209,14 +296,27 @@ def create_openai_language_model(api_key: str, model: str, endpoint: str = "http } return HttpxLanguageModel(url=endpoint, headers=headers, default_params=default_params) -def create_azure_openai_language_model(api_key: str, endpoint: str) -> HttpxLanguageModel: +def create_azure_openai_language_model( + api_key: str | None, + endpoint: str, + *, + token_provider: TokenProvider | None = None, +) -> HttpxLanguageModel: """ Creates a language model encapsulation of an Azure OpenAI REST API endpoint. Args: - api_key: The Azure OpenAI API key. + api_key: The Azure OpenAI API key, or None when using a token provider. endpoint: The Azure OpenAI REST API endpoint. + token_provider: An optional synchronous or asynchronous bearer-token provider. + Invoked for each request attempt; the provider is responsible for caching and renewal. """ + if token_provider is not None: + if api_key is not None: + raise ValueError("Specify either an API key or a token provider, not both.") + return HttpxLanguageModel(url=endpoint, headers={}, default_params={}, token_provider=token_provider) + if api_key is None: + raise ValueError("Specify an API key or a token provider.") headers = { # Needed when using managed identity "Authorization": f"Bearer {api_key}", diff --git a/python/tests/test_client_model.py b/python/tests/test_client_model.py new file mode 100644 index 00000000..ade6ff55 --- /dev/null +++ b/python/tests/test_client_model.py @@ -0,0 +1,183 @@ +import asyncio +import subprocess +import sys +from collections.abc import Iterator, Sequence +from dataclasses import dataclass +from typing_extensions import Literal, TypedDict + +import pytest +import typechat + + +@dataclass +class _Message: + content: str | None + + +@dataclass +class _Choice: + message: _Message + + +@dataclass +class _Completion: + choices: list[_Choice] + + +class _Request(TypedDict): + model: str + messages: list[typechat.PromptSection] + temperature: float + n: int + stream: Literal[False] + + +class _Completions: + requests: list[_Request] + _responses: Iterator[_Completion | BaseException] + + def __init__(self, responses: Sequence[_Completion | BaseException]): + super().__init__() + self.requests = [] + self._responses = iter(responses) + + async def create( + self, + *, + model: str, + messages: list[typechat.PromptSection], + temperature: float, + n: int, + stream: Literal[False], + ) -> _Completion: + self.requests.append({ + "model": model, + "messages": messages.copy(), + "temperature": temperature, + "n": n, + "stream": stream, + }) + response = next(self._responses) + if isinstance(response, BaseException): + raise response + return response + + +@dataclass +class _Chat: + completions: _Completions + + +@dataclass +class _Client: + chat: _Chat + timeout: float = 42.0 + closed: bool = False + + async def close(self) -> None: + self.closed = True + + +def _completion(content: str | None) -> _Completion: + return _Completion([_Choice(_Message(content))]) + + +def test_reuses_the_configured_client_and_normalizes_string_prompts(): + client = _Client(_Chat(_Completions([_completion("first"), _completion("second")]))) + model = typechat.create_openai_language_model_from_client(client, model="azure-deployment") + + async def run() -> None: + assert await model.complete("first prompt") == typechat.Success("first") + assert await model.complete("second prompt") == typechat.Success("second") + + asyncio.run(run()) + assert client.timeout == 42.0 + assert not client.closed + assert client.chat.completions.requests == [ + { + "model": "azure-deployment", + "messages": [{"role": "user", "content": prompt}], + "temperature": 0.0, + "n": 1, + "stream": False, + } + for prompt in ["first prompt", "second prompt"] + ] + + +def test_forwards_prompt_sections_without_mutating_them(): + client = _Client(_Chat(_Completions([_completion("reply")]))) + model = typechat.create_openai_language_model_from_client(client, "gpt-test") + prompt: list[typechat.PromptSection] = [ + {"role": "system", "content": "Instructions"}, + {"role": "user", "content": "Question"}, + {"role": "assistant", "content": "Previous reply"}, + ] + original = prompt.copy() + + assert asyncio.run(model.complete(prompt)) == typechat.Success("reply") + assert client.chat.completions.requests[0]["messages"] == original + assert prompt == original + + +@pytest.mark.parametrize("completion", [_Completion([]), _completion(None)]) +def test_missing_text_is_an_explicit_failure(completion: _Completion): + client = _Client(_Chat(_Completions([completion]))) + model = typechat.create_openai_language_model_from_client(client, "gpt-test") + result = asyncio.run(model.complete("hi")) + assert isinstance(result, typechat.Failure) + assert "Client completion returned no" in result.message + + +def test_empty_text_remains_a_successful_completion(): + client = _Client(_Chat(_Completions([_completion("")]))) + model = typechat.create_openai_language_model_from_client(client, "gpt-test") + assert asyncio.run(model.complete("hi")) == typechat.Success("") + + +@pytest.mark.parametrize("exception", [RuntimeError("Client request failed."), asyncio.CancelledError()]) +def test_client_errors_propagate_without_extra_retries(exception: BaseException): + client = _Client(_Chat(_Completions([exception]))) + model = typechat.create_openai_language_model_from_client(client, "gpt-test") + + with pytest.raises(type(exception)) as raised: + asyncio.run(model.complete("hi")) + + assert raised.value is exception + assert len(client.chat.completions.requests) == 1 + assert not client.closed + + +@pytest.mark.parametrize("model_name", ["", " "]) +def test_requires_a_model_or_deployment_name(model_name: str): + client = _Client(_Chat(_Completions([]))) + with pytest.raises(ValueError, match="must not be empty"): + typechat.create_openai_language_model_from_client(client, model_name) + + +@dataclass +class _Response: + value: str + + +def test_client_adapter_preserves_translation_validation_and_repair(): + client = _Client(_Chat(_Completions([ + _completion('{"wrong": "field"}'), + _completion('{"value": "repaired"}'), + ]))) + model = typechat.create_openai_language_model_from_client(client, "gpt-test") + translator = typechat.TypeChatJsonTranslator(model, typechat.TypeChatValidator(_Response), _Response) + + assert asyncio.run(translator.translate("Get a value")) == typechat.Success(_Response("repaired")) + requests = client.chat.completions.requests + assert len(requests) == 2 + assert [message["role"] for message in requests[1]["messages"]] == ["user", "assistant", "user"] + + +def test_typechat_import_does_not_require_provider_sdks(): + subprocess.run([ + sys.executable, + "-c", + "import sys; sys.modules['openai'] = None; sys.modules['azure'] = None; " + + "import typechat; assert callable(typechat.create_openai_language_model_from_client)", + ], check=True) diff --git a/python/tests/test_create_language_model.py b/python/tests/test_create_language_model.py index 62dbe01c..8c25dc12 100644 --- a/python/tests/test_create_language_model.py +++ b/python/tests/test_create_language_model.py @@ -4,6 +4,7 @@ These only inspect the constructed model, so no request is sent. """ +import pytest import typechat def test_openai_organization_is_sent_as_organization_header(): @@ -38,3 +39,57 @@ def test_openai_organization_takes_precedence_over_openai_org(): } ) assert model.headers["OpenAI-Organization"] == "org-123" + + +def test_azure_positional_api_key_arguments_keep_legacy_headers(): + model = typechat.create_azure_openai_language_model("azure-test-key", "https://example.invalid/chat/completions") + assert model.headers == { + "Authorization": "Bearer azure-test-key", + "api-key": "azure-test-key", + } + assert model.default_params == {} + + +def test_azure_keyword_api_key_arguments_keep_legacy_headers(): + model = typechat.create_azure_openai_language_model( + api_key="azure-test-key", + endpoint="https://example.invalid/chat/completions", + ) + assert model.headers["api-key"] == "azure-test-key" + assert model.headers["Authorization"] == "Bearer azure-test-key" + + +def test_azure_environment_factory_does_not_interpret_identity_as_a_provider(): + model = typechat.create_language_model({ + "AZURE_OPENAI_API_KEY": "identity", + "AZURE_OPENAI_ENDPOINT": "https://example.invalid/chat/completions", + }) + assert model.headers["api-key"] == "identity" + assert model.headers["Authorization"] == "Bearer identity" + + +def test_openai_environment_configuration_still_takes_precedence_over_azure(): + model = typechat.create_language_model({ + "OPENAI_API_KEY": "openai-test-key", + "OPENAI_MODEL": "gpt-test", + "AZURE_OPENAI_API_KEY": "azure-test-key", + "AZURE_OPENAI_ENDPOINT": "https://example.invalid/chat/completions", + }) + assert model.url == "https://api.openai.com/v1/chat/completions" + assert model.default_params == {"model": "gpt-test"} + assert model.headers["Authorization"] == "Bearer openai-test-key" + assert "api-key" not in model.headers + + +def test_azure_rejects_ambiguous_authentication(): + with pytest.raises(ValueError, match="not both"): + typechat.create_azure_openai_language_model( + "azure-test-key", + "https://example.invalid/chat/completions", + token_provider=lambda: "token", + ) + + +def test_azure_requires_authentication(): + with pytest.raises(ValueError, match="API key or a token provider"): + typechat.create_azure_openai_language_model(None, "https://example.invalid/chat/completions") diff --git a/python/tests/test_keyless_model.py b/python/tests/test_keyless_model.py new file mode 100644 index 00000000..375ffcbc --- /dev/null +++ b/python/tests/test_keyless_model.py @@ -0,0 +1,294 @@ +import asyncio +import json +import threading +from collections.abc import Awaitable, Callable +from unittest.mock import Mock + +import httpx +import pytest +import typechat + + +Handler = Callable[[httpx.Request], httpx.Response] + + +@pytest.fixture +def mock_client(monkeypatch: pytest.MonkeyPatch) -> Callable[[Handler], httpx.AsyncClient]: + async_client = httpx.AsyncClient + + def create(handler: Handler) -> httpx.AsyncClient: + client = async_client(transport=httpx.MockTransport(handler)) + monkeypatch.setattr(httpx, "AsyncClient", lambda: client) + return client + + return create + + +def _completion(content: str = "Hello!") -> dict[str, list[dict[str, dict[str, str]]]]: + return {"choices": [{"message": {"role": "assistant", "content": content}}]} + + +def test_sync_token_provider_is_called_for_each_completion(mock_client: Callable[[Handler], httpx.AsyncClient]): + requests: list[httpx.Request] = [] + tokens = iter(["first-token", "second-token"]) + + def handler(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(200, json=_completion()) + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + api_key=None, + endpoint="https://example.invalid/chat/completions?api-version=test", + token_provider=lambda: next(tokens), + ) + + async def run() -> None: + async with model: + assert await model.complete("first prompt") == typechat.Success("Hello!") + assert await model.complete("second prompt") == typechat.Success("Hello!") + + asyncio.run(run()) + assert [request.headers["Authorization"] for request in requests] == [ + "Bearer first-token", + "Bearer second-token", + ] + assert all("api-key" not in request.headers for request in requests) + assert model.headers == {} + assert json.loads(requests[0].content) == { + "messages": [{"role": "user", "content": "first prompt"}], + "temperature": 0.0, + "n": 1, + } + + +def test_async_token_provider_is_awaited_on_each_retry(mock_client: Callable[[Handler], httpx.AsyncClient]): + requests: list[httpx.Request] = [] + statuses = iter([429, 500, 200]) + token_count = 0 + + async def provider() -> str: + nonlocal token_count + await asyncio.sleep(0) + token_count += 1 + return f"token-{token_count}" + + def handler(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(next(statuses), json=_completion()) + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=provider, + ) + model.retry_pause_seconds = 0 + model.max_retry_attempts = 2 + + async def run() -> None: + async with model: + assert await model.complete("hi") == typechat.Success("Hello!") + + asyncio.run(run()) + assert token_count == 3 + assert [request.headers["Authorization"] for request in requests] == [ + "Bearer token-1", + "Bearer token-2", + "Bearer token-3", + ] + assert all("api-key" not in request.headers for request in requests) + + +def test_provider_can_return_a_future(mock_client: Callable[[Handler], httpx.AsyncClient]): + requests: list[httpx.Request] = [] + + def provider() -> Awaitable[str]: + future: asyncio.Future[str] = asyncio.get_running_loop().create_future() + future.set_result("future-token") + return future + + def handler(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(200, json=_completion()) + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=provider, + ) + + async def run() -> None: + async with model: + assert await model.complete("hi") == typechat.Success("Hello!") + + asyncio.run(run()) + assert requests[0].headers["Authorization"] == "Bearer future-token" + + +@pytest.mark.parametrize("token", [ + "", " ", None, b"not-a-string", "bad token", " token", "token ", "token\n", "token\r", + "token\r\n", "token\tother", "token\u0000", "token\u001f", "token\u007f", "token\u0080", + "token\u0100", "\u00a0token", "token\u2028", +]) +def test_invalid_tokens_fail_without_a_request( + mock_client: Callable[[Handler], httpx.AsyncClient], + token: object, +): + def handler(request: httpx.Request) -> httpx.Response: + pytest.fail("An invalid token must not reach the endpoint.") + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, + "https://example.invalid/chat/completions", + token_provider=Mock(return_value=token), + ) + + async def run() -> None: + async with model: + assert await model.complete("hi") == typechat.Failure( + "Token provider must return a nonempty, header-safe bearer-token string." + ) + + asyncio.run(run()) + + +def test_async_malformed_token_is_not_sent_or_exposed(mock_client: Callable[[Handler], httpx.AsyncClient]): + async def provider() -> str: + return "credential-marker-must-not-leak\n" + + def handler(request: httpx.Request) -> httpx.Response: + pytest.fail("A malformed token must not reach the endpoint.") + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=provider, + ) + + async def run() -> None: + async with model: + result = await model.complete("hi") + assert result == typechat.Failure("Token provider must return a nonempty, header-safe bearer-token string.") + assert isinstance(result, typechat.Failure) + assert "credential-marker" not in result.message + + asyncio.run(run()) + + +def test_printable_ascii_token_boundaries_are_preserved(mock_client: Callable[[Handler], httpx.AsyncClient]): + requests: list[httpx.Request] = [] + + def handler(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(200, json=_completion()) + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=lambda: "!~", + ) + + async def run() -> None: + async with model: + assert await model.complete("hi") == typechat.Success("Hello!") + + asyncio.run(run()) + assert requests[0].headers["Authorization"] == "Bearer !~" + + +def test_thread_safe_blocking_provider_can_be_offloaded(mock_client: Callable[[Handler], httpx.AsyncClient]): + provider_threads: list[int] = [] + requests: list[httpx.Request] = [] + + def blocking_token_provider() -> str: + provider_threads.append(threading.get_ident()) + return "thread-token" + + async def provider() -> str: + return await asyncio.to_thread(blocking_token_provider) + + def handler(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(200, json=_completion()) + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=provider, + ) + + async def run() -> None: + event_loop_thread = threading.get_ident() + async with model: + assert await model.complete("hi") == typechat.Success("Hello!") + assert len(provider_threads) == 1 + assert provider_threads[0] != event_loop_thread + + asyncio.run(run()) + assert requests[0].headers["Authorization"] == "Bearer thread-token" + + +def test_provider_failure_uses_existing_failure_handling(mock_client: Callable[[Handler], httpx.AsyncClient]): + def provider() -> str: + raise ValueError("Token acquisition failed.") + + def handler(request: httpx.Request) -> httpx.Response: + pytest.fail("Token acquisition failed before the request.") + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=provider, + ) + model.max_retry_attempts = 0 + + async def run() -> None: + async with model: + assert await model.complete("hi") == typechat.Failure("Token acquisition failed.") + + asyncio.run(run()) + + +def test_provider_cancellation_propagates(mock_client: Callable[[Handler], httpx.AsyncClient]): + async def provider() -> str: + raise asyncio.CancelledError() + + def handler(request: httpx.Request) -> httpx.Response: + pytest.fail("A cancelled token acquisition must not reach the endpoint.") + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=provider, + ) + + async def run() -> None: + async with model: + with pytest.raises(asyncio.CancelledError): + await model.complete("hi") + + asyncio.run(run()) + + +def test_provider_path_preserves_http_limits(mock_client: Callable[[Handler], httpx.AsyncClient]): + requests: list[httpx.Request] = [] + + def handler(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(200, json=_completion("x" * 5000)) + + mock_client(handler) + model = typechat.create_azure_openai_language_model( + None, "https://example.invalid/chat/completions", token_provider=lambda: "token", + ) + model.timeout_seconds = 7 + model.max_response_bytes = 100 + + async def run() -> None: + async with model: + result = await model.complete("hi") + assert isinstance(result, typechat.Failure) + assert "maximum allowed size" in result.message + + asyncio.run(run()) + assert len(requests) == 1 + assert requests[0].extensions["timeout"] == { + "connect": 7, + "read": 7, + "write": 7, + "pool": 7, + } diff --git a/site/src/docs/python/basic-usage.md b/site/src/docs/python/basic-usage.md index 46bae5b5..1ba85f41 100644 --- a/site/src/docs/python/basic-usage.md +++ b/site/src/docs/python/basic-usage.md @@ -80,7 +80,12 @@ def create_openai_language_model( ): ... -def create_azure_openai_language_model(api_key: str, endpoint: str): ... +def create_azure_openai_language_model( + api_key: str | None, + endpoint: str, + *, + token_provider: TokenProvider | None = None +): ... ``` For even more convenience, TypeChat also provides a function to infer whether @@ -97,6 +102,87 @@ pass them in. Based on whether `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` is set, you'll get a model of the appropriate type. +#### Using a bearer-token provider + +For keyless Azure OpenAI authentication, pass `api_key=None` and an existing +token provider directly. `TokenProvider` is a callable returning either a token +string or an awaitable token string, so both synchronous and asynchronous +providers work: + +```py +from typechat import create_azure_openai_language_model + +model = create_azure_openai_language_model( + api_key=None, + endpoint=chat_completions_endpoint, + token_provider=token_provider, +) +``` + +The endpoint is the full deployment Chat Completions URL, including its +`api-version` query parameter. The provider is called for every HTTP attempt, +including retries, and this authentication path sends only an `Authorization: +Bearer ...` header, not an `api-key` header. The provider owns credential +acquisition, caching, renewal, and cleanup. TypeChat does not cache tokens or +require an Azure Identity dependency. + +API keys and token providers are mutually exclusive. Return the raw token without +a `Bearer ` prefix. Non-string/empty tokens and tokens containing whitespace, +control characters, or non-ASCII characters produce a fixed, credential-free +`Failure` before an authorization header is constructed or a request is sent. Provider exceptions use the +existing HTTP model retry/failure behavior; cancellation propagates. + +Synchronous providers execute on the event-loop thread and should be nonblocking. +Prefer an asynchronous provider for network I/O. For an existing thread-safe +`blocking_token_provider` that returns a token string, offload it explicitly: + +```py +import asyncio + +async def token_provider() -> str: + return await asyncio.to_thread(blocking_token_provider) +``` + +Pass this wrapper as `token_provider` to the factory. The blocking provider owns +its I/O timeouts and thread safety; cancelling the wrapper does not forcibly stop +work already running in the thread. The model's HTTP timeout does not bound token +acquisition. Do not offload providers that create loop-bound futures or otherwise +require the running event loop: pass those directly and return their awaitable. +TypeChat does not automatically move synchronous providers to a worker thread. + +Existing API-key calls, positional arguments, environment-variable handling, +and legacy headers are unchanged. In particular, setting +`AZURE_OPENAI_API_KEY=identity` does not activate a credential provider. + +#### Reusing an already configured client + +If your application already has an `AsyncOpenAI`, `AsyncAzureOpenAI`, or +compatible asynchronous Chat Completions client, adapt that instance directly: + +```py +from typechat import create_openai_language_model_from_client + +model = create_openai_language_model_from_client( + openai_client, + model="my-model-or-azure-deployment", +) +``` + +The adapter uses `client.chat.completions.create` and reads +`choices[0].message.content`. It requires no environment variables and adds no +SDK dependency to TypeChat. It sends TypeChat's prompt sections with +`temperature=0.0`, `n=1`, and `stream=False`; the caller supplies the model or +Azure deployment name. + +Your client's endpoint, API version, authentication, retries, and timeouts +remain configured by your application. TypeChat does not reconfigure or close +the client, or add another retry/timeout layer. Client exceptions and +cancellation propagate unchanged. Missing choices or text produce a `Failure`. +The adapter is for Chat Completions, not the Responses API. + +Pass either model to `TypeChatJsonTranslator` as usual. Schema generation, +validation, and repair behavior remain unchanged. + #### Using OpenAI-compatible gateways TypeChat works with any service that exposes the OpenAI Chat Completions API. @@ -120,8 +206,9 @@ OPENAI_MODEL= OPENAI_ENDPOINT=https://api.orcarouter.ai/v1/chat/completions ``` -The `TypeChatLanguageModel` returned by these functions has a few writable -attributes you might find useful: +The HTTP models returned by `create_language_model`, +`create_openai_language_model`, and `create_azure_openai_language_model` have a +few writable attributes you might find useful: - `max_retry_attempts` - `retry_pause_seconds`