Skip to content

Add dependency-free Python token providers and client adapters - #516

Merged
robgruen merged 2 commits into
mainfrom
dev/robgruen/python-keyless-auth-216
Nov 4, 2026
Merged

robgruen merged 2 commits into
mainfrom
dev/robgruen/python-keyless-auth-216

Conversation

@robgruen

@robgruen robgruen commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Summary

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.0 AsyncOpenAI 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.

Review follow-up (2026-11-03)

4ead963 addresses both review threads:

  • 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.

Preserve existing API-key factories and environment behavior while adding opt-in bearer token providers and configured async client reuse.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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.

2 open issues
What changed in this PR

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.

Review effort: Max

Comment thread python/src/typechat/_internal/model.py Resolved
Comment thread site/src/docs/python/basic-usage.md Resolved
Reject non-header-safe provider values before constructing authorization headers, with fixed credential-free failures. Cover malformed async/sync values, valid ASCII boundaries, and explicit asyncio.to_thread offloading while preserving loop-bound Future providers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@robgruen
robgruen marked this pull request as ready for review November 4, 2026 01:33
Copilot AI max review requested due to automatic review settings November 4, 2026 01:33
@robgruen
robgruen merged commit d90e69c into main Nov 4, 2026
13 checks passed

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Low severity 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.

2 resolved since last review

Review effort: Max

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants