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
38 changes: 30 additions & 8 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,17 +68,35 @@ Existing API-key and environment-based calls are unchanged. See the
and [configured-client example](../site/src/docs/python/basic-usage.md#reusing-an-already-configured-client)
for ownership, retry, and error behavior.

## Using the Responses API

For new text and image integrations, pass `use_responses_api=True` to any model
factory or to `create_openai_language_model_from_client`. HTTP factories need
the complete Responses endpoint and a model/deployment name; Azure callers
supply that name with the `model` keyword. Configured clients need only
`responses.create` and remain application-owned, without a required SDK
dependency.

Existing calls still use Chat Completions. Endpoint paths do not select an API,
and automatic Responses-to-Chat fallback is deferred. Both APIs preserve
TypeChat's schema validation and bounded repair.

See the [Responses API guide](../site/src/docs/python/basic-usage.md#using-the-responses-api)
and [minimal HTTP/client example](./examples/responses/demo.py).

All four model factories accept a keyword-only `temperature` option. It defaults
to `0.0`, preserving existing behavior. Pass `temperature=None` to omit the
parameter entirely and use the configured client's or service's default, for
example with reasoning models that reject explicit sampling parameters. This
does not disable reasoning, change authentication, or select a different API.
to `0.0` for Chat Completions, preserving existing behavior. In Chat Completions
mode, pass `temperature=None` to omit the parameter entirely and use the
configured client's or service's default, for example with reasoning models
that reject explicit sampling parameters. Responses requests always omit
temperature, regardless of this option. This does not disable reasoning, change
authentication, or select a different API.

## Text and image prompts

Both built-in Chat Completions models and the configured-client adapter accept
typed text/image parts in `PromptSection.content`. Existing whole-string prompts
remain supported without migration.
Both built-in HTTP models and configured-client adapters accept typed text/image
parts in `PromptSection.content`, with Chat Completions or explicitly selected
Responses. Existing whole-string prompts remain supported without migration.

The following example demonstrates both `model.complete` and translator context;
applications can use either call independently. Supply your own hosted image URL
Expand Down Expand Up @@ -127,6 +145,11 @@ bare strings. Text works in system, user, and assistant messages; images are
supported only in user messages. Malformed input produces a content-free `Failure`
locating the section or part before authentication or dispatch.

Use the same public prompt types for either API. Responses models map tagged
user/system text to `input_text`, assistant text to `output_text`, and images to
`input_image` with a flat `image_url` string and optional `detail`, preserving
order, references, and omitted detail.

`translate` still takes a string request. Its preamble stays before the generated
schema/request message, and image context is preserved during validation and repair.
Successful model completions remain text-only. Authentication, HTTP controls, and
Expand All @@ -138,7 +161,6 @@ accessibility, image counts, detail support, and size/resolution limits depend o
your provider and model. No image-processing or provider SDK dependency is added.
See [text and image usage](../site/src/docs/python/basic-usage.md#text-and-image-prompts)
for the complete prompt type definitions and limitations.

## Documenting schema fields

Trailing Python comments on directly declared `TypedDict` and dataclass fields become
Expand Down
17 changes: 17 additions & 0 deletions python/examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ We recommend reading each example in the following order.
| Name | Description |
| ---- | ----------- |
| [Sentiment](https://github.com/microsoft/TypeChat/tree/main/python/examples/sentiment) | A sentiment classifier which categorizes user input as negative, neutral, or positive. This is TypeChat's "hello world!" |
| [Responses](./responses/demo.py) | Explicit Responses API selection for a one-shot HTTP request or an application-owned asynchronous client. |
| [Coffee Shop](https://github.com/microsoft/TypeChat/tree/main/python/examples/coffeeShop) | An intelligent agent for a coffee shop. This sample translates user intent is translated to a list of coffee order items.
| [Calendar](https://github.com/microsoft/TypeChat/tree/main/python/examples/calendar) | An intelligent scheduler. This sample translates user intent into a sequence of actions to modify a calendar. |
| [HealthData](https://github.com/microsoft/TypeChat/tree/main/python/examples/healthData) | The Health Data Agent shows how strongly typed **agents with history** could interact with a user to collect information needed for one or more data types ("form filling"). |
Expand Down Expand Up @@ -118,6 +119,22 @@ python examples/sentiment/non_interactive.py "TypeChat is awesome!"
For an explanation of how to call the same async function from an existing backend, see the
[Python quickstart](../../site/src/docs/python/non-interactive.md).

For a new text-only Responses integration, set `OPENAI_ENDPOINT` to the complete
Responses URL (for example `https://api.openai.com/v1/responses`) in addition to
`OPENAI_API_KEY` and `OPENAI_MODEL`, then run:

```sh
python examples/responses/demo.py "TypeChat is awesome!"
```

For Azure, use `AZURE_OPENAI_API_KEY`, the complete `AZURE_OPENAI_ENDPOINT` supported
by your resource/API version, and `--model your-deployment`. The example also
exports `classify_with_client` for an application-owned asynchronous Responses
client, without requiring an SDK dependency. See the
[Responses API guide](../../site/src/docs/python/basic-usage.md#using-the-responses-api)
for supported text/output contracts, authentication, limits, and deferred fallback.
The existing examples retain their Chat Completions defaults.

To run an example interactively, type `python examples/<example_name>/demo.py` from the example's directory and enter requests when prompted. Type `quit` or `exit` to end the session. You can also open in VS Code the selected example's directory and press <kbd>F5</kbd> to launch it in debug mode.

Note that there are various sample "prose" files (e.g. `input.txt`) provided in each `src` directory that can give a sense of what you can run.
Expand Down
49 changes: 49 additions & 0 deletions python/examples/responses/demo.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import argparse
import asyncio
import json
import os
from dataclasses import asdict, dataclass
from typing import Literal

from dotenv import dotenv_values
from typechat import (
Failure,
ResponsesClient,
Result,
TypeChatJsonTranslator,
TypeChatLanguageModel,
TypeChatValidator,
create_language_model,
create_openai_language_model_from_client,
)


@dataclass
class Sentiment:
sentiment: Literal["negative", "neutral", "positive"]


async def classify(text: str, model: TypeChatLanguageModel) -> Result[Sentiment]:
translator = TypeChatJsonTranslator(model, TypeChatValidator(Sentiment), Sentiment)
return await translator.translate(text)


async def classify_with_client(text: str, client: ResponsesClient, model: str) -> Result[Sentiment]:
return await classify(text, create_openai_language_model_from_client(client, model, use_responses_api=True))


async def main(text: str, model_name: str | None = None) -> None:
settings = {**dotenv_values(), **os.environ}
async with create_language_model(settings, use_responses_api=True, model=model_name) as model:
result = await classify(text, model)
if isinstance(result, Failure):
raise RuntimeError(result.message)
print(json.dumps(asdict(result.value)))


if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Classify text using an explicitly selected Responses API.")
parser.add_argument("text", help="The text to classify.")
parser.add_argument("--model", help="Explicit model or Azure deployment name (required for Azure).")
args = parser.parse_args()
asyncio.run(main(args.text, args.model))
2 changes: 2 additions & 0 deletions python/src/typechat/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

from typechat._internal.model import (
ChatCompletionClient,
ResponsesClient,
ImagePromptContent,
ImageUrl,
PromptContent,
Expand Down Expand Up @@ -37,6 +38,7 @@
"ImageUrl",
"TokenProvider",
"ChatCompletionClient",
"ResponsesClient",
"create_language_model",
"create_openai_language_model",
"create_azure_openai_language_model",
Expand Down
Loading
Loading