Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 13 additions & 1 deletion python/src/typechat/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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",
]
108 changes: 104 additions & 4 deletions python/src/typechat/_internal/model.py
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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]:
"""
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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}",
Expand Down
183 changes: 183 additions & 0 deletions python/tests/test_client_model.py
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading