You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add dependency-free Python token providers and client adapters - #516
Addresses #216 with two additive, dependency-free Python integration paths:
Add a keyword-only token_provider option to create_azure_openai_language_model. Callers pass api_key=None and supply a synchronous or asynchronous provider.
Add create_openai_language_model_from_client for an already-configured asynchronous OpenAI-compatible Chat Completions client, including AsyncOpenAI and AsyncAzureOpenAI.
Export the structural ChatCompletionClient protocol and TokenProvider type.
Document both paths and add deterministic compatibility and integration tests.
Compatibility and behavior
Existing positional/keyword API-key calls, environment-variable handling, provider precedence, defaults, and legacy headers are unchanged. The literal environment value identity does not gain special behavior.
The new token-provider path sends only bearer authorization and resolves the provider for every HTTP attempt, including retries. Credential acquisition, caching, and renewal remain application responsibilities.
The existing HTTP timeout, response-size limit, retry behavior, and failure reporting are retained. Invalid tokens fail without sending a request; cancellation propagates.
The configured-client adapter preserves the caller's instance, endpoint, API version, authentication, timeouts, retries, and ownership. It does not close/reconfigure the client or add another retry/timeout layer.
Client SDK exceptions and cancellation propagate unchanged. Missing choices or text produce an explicit Failure; empty string completions remain successful text completions.
Translation, schema generation, validation, and repair are unchanged.
No runtime, optional, or development dependency manifests or lockfiles change. No SDK imports are added to TypeChat.
Validation
Run from python:
hatch run test tests\test_create_language_model.py tests\test_model.py tests\test_keyless_model.py tests\test_client_model.py tests\test_translator.py - 58 passed, including legacy arguments/headers, sync/async/Future providers, token rotation across retries, invalid tokens, failures, cancellation, HTTP limits, client ownership, and translator validation/repair.
npm run check - 0 errors, 0 warnings.
git diff --check and unchanged dependency-manifest checks passed.
An independent smoke test also passed with genuine OpenAI SDK 3.39.0AsyncOpenAI and AsyncAzureOpenAI clients: three mocked HTTP calls, fresh bearer tokens, preserved endpoint/API-version/application headers and client settings, and successful strict structural type checks. The SDK was installed only in a separate local tool environment; it is not a TypeChat dependency or a requirement for the repository tests.
Validation used Python 3.11.18 and the repository-pinned Node.js 24.22.1. The build, unit, and SDK-mock checks above were offline.
Manual live Azure identity validation (2026-11-03)
Tested commit: 4ead963. Both live paths were rerun after the review fix.
Both live checks passed against a real identity-configured Azure deployment:
Path
API
Input
Result
HTTP token provider
Chat Completions
Text
Passed
Configured AsyncAzureOpenAI client
Chat Completions
Text
Passed
Real Entra access-token acquisition and bearer-only request headers were observed; no Azure OpenAI API-key headers were used. Both outputs passed TypeChat schema validation on the first model request. There were two actual model requests, with no model-request retries or repairs required.
Not exercised: expiry-driven token renewal. These were manual live smoke tests, not additional CI requirements. Private endpoint, deployment, configuration, and credential details are intentionally omitted.
Reject malformed provider outputs with a full-string visible-ASCII check before constructing authorization headers. Whitespace, trailing newlines, control characters, non-ASCII values, and non-string/empty outputs return a fixed, credential-free failure without dispatch.
Document opt-in asyncio.to_thread wrapping for thread-safe blocking providers, provider-owned timeouts/cancellation limits, and keeping loop-bound Future providers on the event loop. Provider invocation semantics are unchanged.
Added malformed sync/async value, valid-boundary, worker-thread, and existing Future/cancellation regression coverage. 58 focused tests and strict Pyright passed; both real Entra HTTP/SDK paths passed again, with one validated model request each and no API-key headers.
No dependency manifests changed. Private endpoint and credential details remain omitted; expiry-driven renewal remains untested.
This is a draft for human review; no merge is requested.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Whitespace-containing bearer tokens can leak credentials through surfaced transport errors, and documentation lacks guidance for preventing blocking token providers from stalling the event loop.
Adds two dependency-free Python integration paths for #216, allowing applications to reuse their authentication setup without TypeChat-specific environment variables or SDK dependencies.
Changes:
Add synchronous and asynchronous bearer-token providers to the Azure OpenAI factory.
Add an adapter and structural protocol for caller-configured asynchronous Chat Completions clients.
Document both paths and add deterministic compatibility and integration tests.
File
Description
site/src/docs/python/basic-usage.md
Documents token providers, client reuse, ownership, and error behavior.
python/tests/test_keyless_model.py
Tests token resolution, retries, invalid values, cancellation, and HTTP limits.
python/tests/test_create_language_model.py
Adds legacy authentication compatibility and configuration checks.
python/tests/test_client_model.py
Tests client reuse, completion handling, exception propagation, and translator repair.
python/src/typechat/_internal/model.py
Implements token-provider authentication and the configured-client adapter.
python/src/typechat/__init__.py
Exports the new factory, token-provider type, and client protocol.
python/README.md
Introduces both integration paths and links to usage guidance.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The README’s relative integration-guide links resolve under PyPI instead of the TypeChat documentation and need absolute documentation URLs.
No open issues 🎉
1 previously missed issue
In code that hasn't changed since last review
Use absolute URLs for PyPI README integration links
python/README.md:68
This README is also the package description on PyPI, where these relative links resolve under pypi.org/project/site/ instead of to the TypeChat documentation. Use absolute documentation URLs so installed-package users can reach both integration guides.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses #216 with two additive, dependency-free Python integration paths:
token_provideroption tocreate_azure_openai_language_model. Callers passapi_key=Noneand supply a synchronous or asynchronous provider.create_openai_language_model_from_clientfor an already-configured asynchronous OpenAI-compatible Chat Completions client, includingAsyncOpenAIandAsyncAzureOpenAI.ChatCompletionClientprotocol andTokenProvidertype.Compatibility and behavior
identitydoes not gain special behavior.Failure; empty string completions remain successful text completions.Validation
Run from
python:hatch run test tests\test_create_language_model.py tests\test_model.py tests\test_keyless_model.py tests\test_client_model.py tests\test_translator.py- 58 passed, including legacy arguments/headers, sync/async/Future providers, token rotation across retries, invalid tokens, failures, cancellation, HTTP limits, client ownership, and translator validation/repair.npm run check- 0 errors, 0 warnings.git diff --checkand unchanged dependency-manifest checks passed.An independent smoke test also passed with genuine OpenAI SDK 3.39.0
AsyncOpenAIandAsyncAzureOpenAIclients: three mocked HTTP calls, fresh bearer tokens, preserved endpoint/API-version/application headers and client settings, and successful strict structural type checks. The SDK was installed only in a separate local tool environment; it is not a TypeChat dependency or a requirement for the repository tests.Validation used Python 3.11.18 and the repository-pinned Node.js 24.22.1. The build, unit, and SDK-mock checks above were offline.
Manual live Azure identity validation (2026-11-03)
Tested commit: 4ead963. Both live paths were rerun after the review fix.
Both live checks passed against a real identity-configured Azure deployment:
AsyncAzureOpenAIclientReal Entra access-token acquisition and bearer-only request headers were observed; no Azure OpenAI API-key headers were used. Both outputs passed TypeChat schema validation on the first model request. There were two actual model requests, with no model-request retries or repairs required.
Not exercised: expiry-driven token renewal. These were manual live smoke tests, not additional CI requirements. Private endpoint, deployment, configuration, and credential details are intentionally omitted.
Review follow-up (2026-11-03)
4ead963 addresses both review threads:
asyncio.to_threadwrapping for thread-safe blocking providers, provider-owned timeouts/cancellation limits, and keeping loop-bound Future providers on the event loop. Provider invocation semantics are unchanged.No dependency manifests changed. Private endpoint and credential details remain omitted; expiry-driven renewal remains untested.
This is a draft for human review; no merge is requested.