typechat 0.0.5__tar.gz → 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. typechat-0.1.0/PKG-INFO +253 -0
  2. typechat-0.1.0/README.md +221 -0
  3. {typechat-0.0.5 → typechat-0.1.0}/examples/README.md +10 -0
  4. typechat-0.1.0/examples/sentiment/README.md +39 -0
  5. typechat-0.1.0/examples/sentiment/non_interactive.py +37 -0
  6. {typechat-0.0.5 → typechat-0.1.0}/package-lock.json +5 -2
  7. {typechat-0.0.5 → typechat-0.1.0}/package.json +4 -1
  8. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/__about__.py +1 -1
  9. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/__init__.py +21 -1
  10. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/interactive.py +1 -1
  11. typechat-0.1.0/src/typechat/_internal/model.py +437 -0
  12. typechat-0.1.0/src/typechat/_internal/result.py +38 -0
  13. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/translator.py +31 -7
  14. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/ts_conversion/python_type_to_ts_nodes.py +79 -6
  15. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/validator.py +4 -4
  16. typechat-0.1.0/tests/__snapshots__/test_inline_comments/test_dataclass_inline_comments.schema.d.ts +9 -0
  17. typechat-0.1.0/tests/__snapshots__/test_inline_comments/test_doc_takes_priority_over_inline.schema.d.ts +9 -0
  18. typechat-0.1.0/tests/__snapshots__/test_inline_comments/test_typeddict_inline_comments.schema.d.ts +8 -0
  19. typechat-0.1.0/tests/__snapshots__/test_newtype/test_newtype_1.schema.d.ts +11 -0
  20. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_translator.ambr +33 -0
  21. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_tuples_1/test_tuples_1.schema.d.ts +4 -0
  22. typechat-0.1.0/tests/test_client_model.py +183 -0
  23. typechat-0.1.0/tests/test_create_language_model.py +126 -0
  24. typechat-0.1.0/tests/test_failure.py +243 -0
  25. typechat-0.1.0/tests/test_inline_comments.py +364 -0
  26. typechat-0.1.0/tests/test_interactive.py +79 -0
  27. typechat-0.1.0/tests/test_keyless_model.py +294 -0
  28. typechat-0.1.0/tests/test_multimodal_model.py +513 -0
  29. typechat-0.1.0/tests/test_newtype.py +53 -0
  30. typechat-0.1.0/tests/test_prompt_types.py +104 -0
  31. typechat-0.1.0/tests/test_schema_documentation.py +48 -0
  32. typechat-0.1.0/tests/test_sentiment_non_interactive.py +147 -0
  33. {typechat-0.0.5 → typechat-0.1.0}/tests/test_translator.py +39 -0
  34. {typechat-0.0.5 → typechat-0.1.0}/tests/test_tuples_1.py +6 -2
  35. typechat-0.0.5/PKG-INFO +0 -105
  36. typechat-0.0.5/README.md +0 -73
  37. typechat-0.0.5/examples/sentiment/README.md +0 -21
  38. typechat-0.0.5/src/typechat/_internal/model.py +0 -226
  39. typechat-0.0.5/src/typechat/_internal/result.py +0 -21
  40. {typechat-0.0.5 → typechat-0.1.0}/.gitignore +0 -0
  41. {typechat-0.0.5 → typechat-0.1.0}/LICENSE +0 -0
  42. {typechat-0.0.5 → typechat-0.1.0}/examples/calendar/README.md +0 -0
  43. {typechat-0.0.5 → typechat-0.1.0}/examples/calendar/demo.py +0 -0
  44. {typechat-0.0.5 → typechat-0.1.0}/examples/calendar/input.txt +0 -0
  45. {typechat-0.0.5 → typechat-0.1.0}/examples/calendar/schema.py +0 -0
  46. {typechat-0.0.5 → typechat-0.1.0}/examples/coffeeShop/README.md +0 -0
  47. {typechat-0.0.5 → typechat-0.1.0}/examples/coffeeShop/demo.py +0 -0
  48. {typechat-0.0.5 → typechat-0.1.0}/examples/coffeeShop/input.txt +0 -0
  49. {typechat-0.0.5 → typechat-0.1.0}/examples/coffeeShop/input2.txt +0 -0
  50. {typechat-0.0.5 → typechat-0.1.0}/examples/coffeeShop/schema.py +0 -0
  51. {typechat-0.0.5 → typechat-0.1.0}/examples/drawing/__init__.py +0 -0
  52. {typechat-0.0.5 → typechat-0.1.0}/examples/drawing/demo.py +0 -0
  53. {typechat-0.0.5 → typechat-0.1.0}/examples/drawing/input.txt +0 -0
  54. {typechat-0.0.5 → typechat-0.1.0}/examples/drawing/render.py +0 -0
  55. {typechat-0.0.5 → typechat-0.1.0}/examples/drawing/schema.py +0 -0
  56. {typechat-0.0.5 → typechat-0.1.0}/examples/healthData/README.md +0 -0
  57. {typechat-0.0.5 → typechat-0.1.0}/examples/healthData/demo.py +0 -0
  58. {typechat-0.0.5 → typechat-0.1.0}/examples/healthData/input.txt +0 -0
  59. {typechat-0.0.5 → typechat-0.1.0}/examples/healthData/schema.py +0 -0
  60. {typechat-0.0.5 → typechat-0.1.0}/examples/healthData/translator.py +0 -0
  61. {typechat-0.0.5 → typechat-0.1.0}/examples/math/README.md +0 -0
  62. {typechat-0.0.5 → typechat-0.1.0}/examples/math/demo.py +0 -0
  63. {typechat-0.0.5 → typechat-0.1.0}/examples/math/input.txt +0 -0
  64. {typechat-0.0.5 → typechat-0.1.0}/examples/math/program.py +0 -0
  65. {typechat-0.0.5 → typechat-0.1.0}/examples/math/schema.py +0 -0
  66. {typechat-0.0.5 → typechat-0.1.0}/examples/math/schemaV2.py +0 -0
  67. {typechat-0.0.5 → typechat-0.1.0}/examples/multiSchema/README.md +0 -0
  68. {typechat-0.0.5 → typechat-0.1.0}/examples/multiSchema/agents.py +0 -0
  69. {typechat-0.0.5 → typechat-0.1.0}/examples/multiSchema/demo.py +0 -0
  70. {typechat-0.0.5 → typechat-0.1.0}/examples/multiSchema/input.txt +0 -0
  71. {typechat-0.0.5 → typechat-0.1.0}/examples/multiSchema/router.py +0 -0
  72. {typechat-0.0.5 → typechat-0.1.0}/examples/music/README.md +0 -0
  73. {typechat-0.0.5 → typechat-0.1.0}/examples/music/client.py +0 -0
  74. {typechat-0.0.5 → typechat-0.1.0}/examples/music/demo.py +0 -0
  75. {typechat-0.0.5 → typechat-0.1.0}/examples/music/input.txt +0 -0
  76. {typechat-0.0.5 → typechat-0.1.0}/examples/music/schema.py +0 -0
  77. {typechat-0.0.5 → typechat-0.1.0}/examples/music/spotipyWrapper.py +0 -0
  78. {typechat-0.0.5 → typechat-0.1.0}/examples/restaurant/README.md +0 -0
  79. {typechat-0.0.5 → typechat-0.1.0}/examples/restaurant/demo.py +0 -0
  80. {typechat-0.0.5 → typechat-0.1.0}/examples/restaurant/input.txt +0 -0
  81. {typechat-0.0.5 → typechat-0.1.0}/examples/restaurant/schema.py +0 -0
  82. {typechat-0.0.5 → typechat-0.1.0}/examples/sentiment/demo.py +0 -0
  83. {typechat-0.0.5 → typechat-0.1.0}/examples/sentiment/input.txt +0 -0
  84. {typechat-0.0.5 → typechat-0.1.0}/examples/sentiment/schema.py +0 -0
  85. {typechat-0.0.5 → typechat-0.1.0}/notebooks/calendar.ipynb +0 -0
  86. {typechat-0.0.5 → typechat-0.1.0}/notebooks/coffeeShop.ipynb +0 -0
  87. {typechat-0.0.5 → typechat-0.1.0}/notebooks/healthData.ipynb +0 -0
  88. {typechat-0.0.5 → typechat-0.1.0}/notebooks/math.ipynb +0 -0
  89. {typechat-0.0.5 → typechat-0.1.0}/notebooks/music.ipynb +0 -0
  90. {typechat-0.0.5 → typechat-0.1.0}/notebooks/restaurant.ipynb +0 -0
  91. {typechat-0.0.5 → typechat-0.1.0}/notebooks/sentiment.ipynb +0 -0
  92. {typechat-0.0.5 → typechat-0.1.0}/pyproject.toml +0 -0
  93. {typechat-0.0.5 → typechat-0.1.0}/pyrightconfig.json +0 -0
  94. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/__init__.py +0 -0
  95. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/ts_conversion/__init__.py +0 -0
  96. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/ts_conversion/ts_node_to_string.py +0 -0
  97. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/_internal/ts_conversion/ts_type_nodes.py +0 -0
  98. {typechat-0.0.5 → typechat-0.1.0}/src/typechat/py.typed +0 -0
  99. {typechat-0.0.5 → typechat-0.1.0}/tests/__init__.py +0 -0
  100. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.11_snapshots__/test_conflicting_names_1/test_conflicting_names_1.schema.d.ts +0 -0
  101. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.11_snapshots__/test_hello_world/test_generic_alias1.schema.d.ts +0 -0
  102. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.12+_snapshots__/test_generic_alias_3/test_generic_alias3.schema.d.ts +0 -0
  103. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.12+_snapshots__/test_generic_alias_4/test_generic_alias4.schema.d.ts +0 -0
  104. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.12+_snapshots__/test_type_alias_syntax/test_type_alias_union1.schema.d.ts +0 -0
  105. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.12_snapshots__/test_conflicting_names_1/test_conflicting_names_1.schema.d.ts +0 -0
  106. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.12_snapshots__/test_hello_world/test_generic_alias1.schema.d.ts +0 -0
  107. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.13_snapshots__/test_conflicting_names_1/test_conflicting_names_1.schema.d.ts +0 -0
  108. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.13_snapshots__/test_hello_world/test_generic_alias1.schema.d.ts +0 -0
  109. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.14_snapshots__/test_conflicting_names_1/test_conflicting_names_1.schema.d.ts +0 -0
  110. {typechat-0.0.5 → typechat-0.1.0}/tests/__py3.14_snapshots__/test_hello_world/test_generic_alias1.schema.d.ts +0 -0
  111. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_abstract_collections/test_abstract_collections.schema.d.ts +0 -0
  112. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_coffeeshop/test_coffeeshop_schema.schema.d.ts +0 -0
  113. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_dataclasses/test_data_classes.schema.d.ts +0 -0
  114. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_generic_alias_1/test_generic_alias1.schema.d.ts +0 -0
  115. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_generic_alias_2/test_generic_alias2.schema.d.ts +0 -0
  116. {typechat-0.0.5 → typechat-0.1.0}/tests/__snapshots__/test_tuple_errors_1/test_tuples_2.schema.d.ts +0 -0
  117. {typechat-0.0.5 → typechat-0.1.0}/tests/coffeeshop_deprecated.py +0 -0
  118. {typechat-0.0.5 → typechat-0.1.0}/tests/test_abstract_collections.py +0 -0
  119. {typechat-0.0.5 → typechat-0.1.0}/tests/test_coffeeshop.py +0 -0
  120. {typechat-0.0.5 → typechat-0.1.0}/tests/test_conflicting_names_1.py +0 -0
  121. {typechat-0.0.5 → typechat-0.1.0}/tests/test_dataclasses.py +0 -0
  122. {typechat-0.0.5 → typechat-0.1.0}/tests/test_generic_alias_1.py +0 -0
  123. {typechat-0.0.5 → typechat-0.1.0}/tests/test_generic_alias_2.py +0 -0
  124. {typechat-0.0.5 → typechat-0.1.0}/tests/test_generic_alias_3.py +0 -0
  125. {typechat-0.0.5 → typechat-0.1.0}/tests/test_generic_alias_4.py +0 -0
  126. {typechat-0.0.5 → typechat-0.1.0}/tests/test_hello_world.py +0 -0
  127. {typechat-0.0.5 → typechat-0.1.0}/tests/test_model.py +0 -0
  128. {typechat-0.0.5 → typechat-0.1.0}/tests/test_tuple_errors_1.py +0 -0
  129. {typechat-0.0.5 → typechat-0.1.0}/tests/test_type_alias_syntax.py +0 -0
  130. {typechat-0.0.5 → typechat-0.1.0}/tests/test_validator.py +0 -0
  131. {typechat-0.0.5 → typechat-0.1.0}/tests/utilities.py +0 -0
@@ -0,0 +1,253 @@
1
+ Metadata-Version: 2.5
2
+ Name: typechat
3
+ Version: 0.1.0
4
+ Summary: TypeChat is a library that makes it easy to build natural language interfaces using types.
5
+ Project-URL: Documentation, https://github.com/microsoft/TypeChat#readme
6
+ Project-URL: Issues, https://github.com/microsoft/TypeChat/issues
7
+ Project-URL: Source, https://github.com/microsoft/TypeChat
8
+ Author: Microsoft Corporation
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Programming Language :: Python
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: Implementation :: CPython
17
+ Classifier: Programming Language :: Python :: Implementation :: PyPy
18
+ Requires-Python: >=3.11
19
+ Requires-Dist: httpx>=0.27.0
20
+ Requires-Dist: pydantic-core>=2.16.3
21
+ Requires-Dist: pydantic>=2.5.2
22
+ Requires-Dist: typing-extensions>=4.10.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: coverage[toml]>=6.5; extra == 'dev'
25
+ Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
26
+ Requires-Dist: pytest<9,>=8.0.2; extra == 'dev'
27
+ Requires-Dist: syrupy>=5.0.0; extra == 'dev'
28
+ Provides-Extra: examples
29
+ Requires-Dist: python-dotenv>=1.0.0; extra == 'examples'
30
+ Requires-Dist: spotipy; extra == 'examples'
31
+ Description-Content-Type: text/markdown
32
+
33
+ # TypeChat
34
+
35
+ TypeChat is a library that makes it easy to build natural language interfaces using types.
36
+
37
+ Building natural language interfaces has traditionally been difficult.
38
+ These apps often relied on complex decision trees to determine intent and collect the required inputs to take action.
39
+ Large language models (LLMs) have made this easier by enabling us to take natural language input from a user and match to intent.
40
+ This has introduced its own challenges, including the need to constrain the model's reply for safety,
41
+ structure responses from the model for further processing, and ensuring that the reply from the model is valid.
42
+ Prompt engineering aims to solve these problems, but comes with a steep learning curve and increased fragility as the prompt increases in size.
43
+
44
+ TypeChat replaces _prompt engineering_ with _schema engineering_.
45
+
46
+ Simply define types that represent the intents supported in your natural language application.
47
+ That could be as simple as an interface for categorizing sentiment or more complex examples like types for a shopping cart or music application.
48
+ For example, to add additional intents to a schema, a developer can add additional types into a discriminated union.
49
+ To make schemas hierarchical, a developer can use a "meta-schema" to choose one or more sub-schemas based on user input.
50
+
51
+ After defining your types, TypeChat takes care of the rest by:
52
+
53
+ 1. Constructing a prompt to the LLM using types.
54
+ 2. Validating the LLM response conforms to the schema. If the validation fails, repair the non-conforming output through further language model interaction.
55
+ 3. Summarizing succinctly (without use of a LLM) the instance and confirm that it aligns with user intent.
56
+
57
+ Types are all you need!
58
+
59
+ ## Getting Started
60
+
61
+ Install TypeChat:
62
+
63
+ ```sh
64
+ pip install typechat
65
+ ```
66
+
67
+ To use TypeChat in an existing backend without an interactive chat loop, follow the
68
+ [non-interactive Python quickstart](../site/src/docs/python/non-interactive.md).
69
+ It includes a [standalone sentiment example](./examples/sentiment/non_interactive.py) and an async function you can call from application code.
70
+
71
+ You can also develop TypeChat from source, which needs [Python >=3.11](https://www.python.org/downloads/),
72
+ [hatch](https://hatch.pypa.io/1.6/install/), and [Node.js >=24.22.1](https://nodejs.org/en/download):
73
+
74
+ ```sh
75
+ git clone https://github.com/microsoft/TypeChat
76
+ cd TypeChat/python
77
+ hatch shell
78
+ npm ci
79
+ ```
80
+
81
+ To see TypeChat in action, we recommend exploring the
82
+ [TypeChat example projects](https://github.com/microsoft/TypeChat/tree/main/python/examples).
83
+ You can try them on your local machine or in a GitHub Codespace.
84
+
85
+ To learn more about TypeChat, visit the
86
+ [documentation](https://microsoft.github.io/TypeChat/docs/python/basic-usage/)
87
+ which includes more information on TypeChat and how to get started.
88
+
89
+ ## Reusing model authentication
90
+
91
+ For keyless Azure OpenAI requests, pass a synchronous or asynchronous bearer-token
92
+ provider to `create_azure_openai_language_model` with `api_key=None`. If your app
93
+ already has a configured asynchronous OpenAI or Azure OpenAI client, use
94
+ `create_openai_language_model_from_client` instead.
95
+
96
+ Both paths reuse authentication supplied by your application without adding SDK
97
+ dependencies to TypeChat or requiring TypeChat-specific environment-variable names.
98
+ Existing API-key and environment-based calls are unchanged. See the
99
+ [token-provider example](../site/src/docs/python/basic-usage.md#using-a-bearer-token-provider)
100
+ and [configured-client example](../site/src/docs/python/basic-usage.md#reusing-an-already-configured-client)
101
+ for ownership, retry, and error behavior.
102
+
103
+ All four model factories accept a keyword-only `temperature` option. It defaults
104
+ to `0.0`, preserving existing behavior. Pass `temperature=None` to omit the
105
+ parameter entirely and use the configured client's or service's default, for
106
+ example with reasoning models that reject explicit sampling parameters. This
107
+ does not disable reasoning, change authentication, or select a different API.
108
+
109
+ ## Text and image prompts
110
+
111
+ Both built-in Chat Completions models and the configured-client adapter accept
112
+ typed text/image parts in `PromptSection.content`. Existing whole-string prompts
113
+ remain supported without migration.
114
+
115
+ The following example demonstrates both `model.complete` and translator context;
116
+ applications can use either call independently. Supply your own hosted image URL
117
+ and already-base64-encoded image data:
118
+
119
+ ```python
120
+ from typing_extensions import TypedDict
121
+
122
+ from typechat import (
123
+ PromptSection,
124
+ Result,
125
+ TypeChatJsonTranslator,
126
+ TypeChatLanguageModel,
127
+ TypeChatValidator,
128
+ )
129
+
130
+
131
+ class ImageDescription(TypedDict):
132
+ description: str
133
+
134
+
135
+ async def inspect_images(
136
+ model: TypeChatLanguageModel, image_base64: str
137
+ ) -> tuple[Result[str], Result[ImageDescription]]:
138
+ context: list[PromptSection] = [
139
+ {"role": "user", "content": [
140
+ {"type": "text", "text": "Use these images as context."},
141
+ {"type": "image_url", "image_url": {"url": "https://example.com/photo.png"}},
142
+ {"type": "image_url", "image_url": {
143
+ "url": f"data:image/png;base64,{image_base64}",
144
+ "detail": "low",
145
+ }},
146
+ ]},
147
+ ]
148
+ text = await model.complete(context)
149
+ translator = TypeChatJsonTranslator(model, TypeChatValidator(ImageDescription), ImageDescription)
150
+ data = await translator.translate("Describe the images.", prompt_preamble=context)
151
+ return text, data
152
+ ```
153
+
154
+ The public dictionary types are `TextPromptContent` (`{"type": "text", "text": str}`),
155
+ `ImagePromptContent` (`{"type": "image_url", "image_url": ImageUrl}`), and `ImageUrl`
156
+ with a required nonempty `url: str` and optional `detail: "auto" | "low" | "high"`.
157
+ `PromptContent` is a string or an ordered list of these tagged parts, not a list of
158
+ bare strings. Text works in system, user, and assistant messages; images are
159
+ supported only in user messages. Malformed input produces a content-free `Failure`
160
+ locating the section or part before authentication or dispatch.
161
+
162
+ `translate` still takes a string request. Its preamble stays before the generated
163
+ schema/request message, and image context is preserved during validation and repair.
164
+ Successful model completions remain text-only. Authentication, HTTP controls, and
165
+ configured-client ownership remain unchanged.
166
+
167
+ TypeChat only forwards image references: it does not fetch, decode, resize, or
168
+ validate image contents. Supported formats (such as PNG, JPEG, or WebP), URL
169
+ accessibility, image counts, detail support, and size/resolution limits depend on
170
+ your provider and model. No image-processing or provider SDK dependency is added.
171
+ See [text and image usage](../site/src/docs/python/basic-usage.md#text-and-image-prompts)
172
+ for the complete prompt type definitions and limitations.
173
+
174
+ ## Documenting schema fields
175
+
176
+ Trailing Python comments on directly declared `TypedDict` and dataclass fields become
177
+ documentation in the generated TypeScript schema:
178
+
179
+ ```python
180
+ from typing import Annotated
181
+ from typing_extensions import Doc, TypedDict
182
+
183
+ class Point(TypedDict):
184
+ x: int # X-coordinate
185
+ y: Annotated[int, Doc("Y-coordinate")] # Explicit documentation takes precedence.
186
+ ```
187
+
188
+ Explicit `Annotated` documentation, supplied through `Doc` or a string, takes precedence
189
+ over an inline comment, including when that explicit documentation is empty.
190
+ Comments are recognized using Python's tokenizer, so `#` inside a string literal is not
191
+ treated as documentation. For multiline field declarations, put the comment on the final line.
192
+ `# type: ignore` directives, including those with bracketed error codes, are not treated
193
+ as field documentation.
194
+
195
+ Source inspection is read-only and supports nested class definitions with multiline strings.
196
+ If source is unavailable, such as for dynamically created types or deployments without source files,
197
+ conversion continues using the type annotations
198
+ and explicit documentation without inline comments. If available source cannot be parsed,
199
+ the problem is reported in `TypeScriptSchemaConversionResult.errors` rather than silently
200
+ discarding the comments.
201
+
202
+ ## Accessing failed output
203
+
204
+ `Failure` retains its existing `message` and can also carry an unvalidated `value: object` and
205
+ `response_text: str | None`. Validators return the rejected input in `value`; translators also retain
206
+ the original model text, including when it is not valid JSON:
207
+
208
+ ```python
209
+ from typechat import Failure
210
+
211
+ result = await translator.translate(request)
212
+ if isinstance(result, Failure):
213
+ if result.has_value:
214
+ rejected = result.value
215
+ # Validate or repair this value before treating it as the target type.
216
+ original_response = result.response_text
217
+ ```
218
+
219
+ Check `has_value` before using `value`. It distinguishes unavailable data from a rejected `None`,
220
+ `False`, `0`, or empty string. An unavailable value is represented by an internal missing-value marker,
221
+ not `None`. Custom validators can supply their own payloads using
222
+ `Failure(message, value=rejected, response_text=text)`, and the translator preserves those payloads.
223
+ `Failure(message)` remains valid, and payload fields are omitted from its representation.
224
+ Use `isinstance` with `Success` or `Failure` to distinguish outcomes, not the presence of `value`.
225
+
226
+ On final failure, automatic repair retains the latest rejected candidate and available response text,
227
+ not a full attempt history. If a repair response cannot be parsed, `value` can come from an earlier
228
+ attempt than `response_text`. An initial network failure has no candidate value. Successful results,
229
+ error messages, and repair limits are unchanged, including Python's existing repair of malformed JSON.
230
+
231
+ Rejected values and response text may contain sensitive output. Do not log or serialize them blindly.
232
+
233
+ ## Contributing
234
+
235
+ This project welcomes contributions and suggestions. Most contributions require you to agree to a
236
+ Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
237
+ the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
238
+
239
+ When you submit a pull request, a CLA bot will automatically determine whether you need to provide
240
+ a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
241
+ provided by the bot. You will only need to do this once across all repos using our CLA.
242
+
243
+ This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
244
+ For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
245
+ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
246
+
247
+ ## Trademarks
248
+
249
+ This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
250
+ trademarks or logos is subject to and must follow
251
+ [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
252
+ Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
253
+ Any use of third-party trademarks or logos are subject to those third-party's policies.
@@ -0,0 +1,221 @@
1
+ # TypeChat
2
+
3
+ TypeChat is a library that makes it easy to build natural language interfaces using types.
4
+
5
+ Building natural language interfaces has traditionally been difficult.
6
+ These apps often relied on complex decision trees to determine intent and collect the required inputs to take action.
7
+ Large language models (LLMs) have made this easier by enabling us to take natural language input from a user and match to intent.
8
+ This has introduced its own challenges, including the need to constrain the model's reply for safety,
9
+ structure responses from the model for further processing, and ensuring that the reply from the model is valid.
10
+ Prompt engineering aims to solve these problems, but comes with a steep learning curve and increased fragility as the prompt increases in size.
11
+
12
+ TypeChat replaces _prompt engineering_ with _schema engineering_.
13
+
14
+ Simply define types that represent the intents supported in your natural language application.
15
+ That could be as simple as an interface for categorizing sentiment or more complex examples like types for a shopping cart or music application.
16
+ For example, to add additional intents to a schema, a developer can add additional types into a discriminated union.
17
+ To make schemas hierarchical, a developer can use a "meta-schema" to choose one or more sub-schemas based on user input.
18
+
19
+ After defining your types, TypeChat takes care of the rest by:
20
+
21
+ 1. Constructing a prompt to the LLM using types.
22
+ 2. Validating the LLM response conforms to the schema. If the validation fails, repair the non-conforming output through further language model interaction.
23
+ 3. Summarizing succinctly (without use of a LLM) the instance and confirm that it aligns with user intent.
24
+
25
+ Types are all you need!
26
+
27
+ ## Getting Started
28
+
29
+ Install TypeChat:
30
+
31
+ ```sh
32
+ pip install typechat
33
+ ```
34
+
35
+ To use TypeChat in an existing backend without an interactive chat loop, follow the
36
+ [non-interactive Python quickstart](../site/src/docs/python/non-interactive.md).
37
+ It includes a [standalone sentiment example](./examples/sentiment/non_interactive.py) and an async function you can call from application code.
38
+
39
+ You can also develop TypeChat from source, which needs [Python >=3.11](https://www.python.org/downloads/),
40
+ [hatch](https://hatch.pypa.io/1.6/install/), and [Node.js >=24.22.1](https://nodejs.org/en/download):
41
+
42
+ ```sh
43
+ git clone https://github.com/microsoft/TypeChat
44
+ cd TypeChat/python
45
+ hatch shell
46
+ npm ci
47
+ ```
48
+
49
+ To see TypeChat in action, we recommend exploring the
50
+ [TypeChat example projects](https://github.com/microsoft/TypeChat/tree/main/python/examples).
51
+ You can try them on your local machine or in a GitHub Codespace.
52
+
53
+ To learn more about TypeChat, visit the
54
+ [documentation](https://microsoft.github.io/TypeChat/docs/python/basic-usage/)
55
+ which includes more information on TypeChat and how to get started.
56
+
57
+ ## Reusing model authentication
58
+
59
+ For keyless Azure OpenAI requests, pass a synchronous or asynchronous bearer-token
60
+ provider to `create_azure_openai_language_model` with `api_key=None`. If your app
61
+ already has a configured asynchronous OpenAI or Azure OpenAI client, use
62
+ `create_openai_language_model_from_client` instead.
63
+
64
+ Both paths reuse authentication supplied by your application without adding SDK
65
+ dependencies to TypeChat or requiring TypeChat-specific environment-variable names.
66
+ Existing API-key and environment-based calls are unchanged. See the
67
+ [token-provider example](../site/src/docs/python/basic-usage.md#using-a-bearer-token-provider)
68
+ and [configured-client example](../site/src/docs/python/basic-usage.md#reusing-an-already-configured-client)
69
+ for ownership, retry, and error behavior.
70
+
71
+ All four model factories accept a keyword-only `temperature` option. It defaults
72
+ to `0.0`, preserving existing behavior. Pass `temperature=None` to omit the
73
+ parameter entirely and use the configured client's or service's default, for
74
+ example with reasoning models that reject explicit sampling parameters. This
75
+ does not disable reasoning, change authentication, or select a different API.
76
+
77
+ ## Text and image prompts
78
+
79
+ Both built-in Chat Completions models and the configured-client adapter accept
80
+ typed text/image parts in `PromptSection.content`. Existing whole-string prompts
81
+ remain supported without migration.
82
+
83
+ The following example demonstrates both `model.complete` and translator context;
84
+ applications can use either call independently. Supply your own hosted image URL
85
+ and already-base64-encoded image data:
86
+
87
+ ```python
88
+ from typing_extensions import TypedDict
89
+
90
+ from typechat import (
91
+ PromptSection,
92
+ Result,
93
+ TypeChatJsonTranslator,
94
+ TypeChatLanguageModel,
95
+ TypeChatValidator,
96
+ )
97
+
98
+
99
+ class ImageDescription(TypedDict):
100
+ description: str
101
+
102
+
103
+ async def inspect_images(
104
+ model: TypeChatLanguageModel, image_base64: str
105
+ ) -> tuple[Result[str], Result[ImageDescription]]:
106
+ context: list[PromptSection] = [
107
+ {"role": "user", "content": [
108
+ {"type": "text", "text": "Use these images as context."},
109
+ {"type": "image_url", "image_url": {"url": "https://example.com/photo.png"}},
110
+ {"type": "image_url", "image_url": {
111
+ "url": f"data:image/png;base64,{image_base64}",
112
+ "detail": "low",
113
+ }},
114
+ ]},
115
+ ]
116
+ text = await model.complete(context)
117
+ translator = TypeChatJsonTranslator(model, TypeChatValidator(ImageDescription), ImageDescription)
118
+ data = await translator.translate("Describe the images.", prompt_preamble=context)
119
+ return text, data
120
+ ```
121
+
122
+ The public dictionary types are `TextPromptContent` (`{"type": "text", "text": str}`),
123
+ `ImagePromptContent` (`{"type": "image_url", "image_url": ImageUrl}`), and `ImageUrl`
124
+ with a required nonempty `url: str` and optional `detail: "auto" | "low" | "high"`.
125
+ `PromptContent` is a string or an ordered list of these tagged parts, not a list of
126
+ bare strings. Text works in system, user, and assistant messages; images are
127
+ supported only in user messages. Malformed input produces a content-free `Failure`
128
+ locating the section or part before authentication or dispatch.
129
+
130
+ `translate` still takes a string request. Its preamble stays before the generated
131
+ schema/request message, and image context is preserved during validation and repair.
132
+ Successful model completions remain text-only. Authentication, HTTP controls, and
133
+ configured-client ownership remain unchanged.
134
+
135
+ TypeChat only forwards image references: it does not fetch, decode, resize, or
136
+ validate image contents. Supported formats (such as PNG, JPEG, or WebP), URL
137
+ accessibility, image counts, detail support, and size/resolution limits depend on
138
+ your provider and model. No image-processing or provider SDK dependency is added.
139
+ See [text and image usage](../site/src/docs/python/basic-usage.md#text-and-image-prompts)
140
+ for the complete prompt type definitions and limitations.
141
+
142
+ ## Documenting schema fields
143
+
144
+ Trailing Python comments on directly declared `TypedDict` and dataclass fields become
145
+ documentation in the generated TypeScript schema:
146
+
147
+ ```python
148
+ from typing import Annotated
149
+ from typing_extensions import Doc, TypedDict
150
+
151
+ class Point(TypedDict):
152
+ x: int # X-coordinate
153
+ y: Annotated[int, Doc("Y-coordinate")] # Explicit documentation takes precedence.
154
+ ```
155
+
156
+ Explicit `Annotated` documentation, supplied through `Doc` or a string, takes precedence
157
+ over an inline comment, including when that explicit documentation is empty.
158
+ Comments are recognized using Python's tokenizer, so `#` inside a string literal is not
159
+ treated as documentation. For multiline field declarations, put the comment on the final line.
160
+ `# type: ignore` directives, including those with bracketed error codes, are not treated
161
+ as field documentation.
162
+
163
+ Source inspection is read-only and supports nested class definitions with multiline strings.
164
+ If source is unavailable, such as for dynamically created types or deployments without source files,
165
+ conversion continues using the type annotations
166
+ and explicit documentation without inline comments. If available source cannot be parsed,
167
+ the problem is reported in `TypeScriptSchemaConversionResult.errors` rather than silently
168
+ discarding the comments.
169
+
170
+ ## Accessing failed output
171
+
172
+ `Failure` retains its existing `message` and can also carry an unvalidated `value: object` and
173
+ `response_text: str | None`. Validators return the rejected input in `value`; translators also retain
174
+ the original model text, including when it is not valid JSON:
175
+
176
+ ```python
177
+ from typechat import Failure
178
+
179
+ result = await translator.translate(request)
180
+ if isinstance(result, Failure):
181
+ if result.has_value:
182
+ rejected = result.value
183
+ # Validate or repair this value before treating it as the target type.
184
+ original_response = result.response_text
185
+ ```
186
+
187
+ Check `has_value` before using `value`. It distinguishes unavailable data from a rejected `None`,
188
+ `False`, `0`, or empty string. An unavailable value is represented by an internal missing-value marker,
189
+ not `None`. Custom validators can supply their own payloads using
190
+ `Failure(message, value=rejected, response_text=text)`, and the translator preserves those payloads.
191
+ `Failure(message)` remains valid, and payload fields are omitted from its representation.
192
+ Use `isinstance` with `Success` or `Failure` to distinguish outcomes, not the presence of `value`.
193
+
194
+ On final failure, automatic repair retains the latest rejected candidate and available response text,
195
+ not a full attempt history. If a repair response cannot be parsed, `value` can come from an earlier
196
+ attempt than `response_text`. An initial network failure has no candidate value. Successful results,
197
+ error messages, and repair limits are unchanged, including Python's existing repair of malformed JSON.
198
+
199
+ Rejected values and response text may contain sensitive output. Do not log or serialize them blindly.
200
+
201
+ ## Contributing
202
+
203
+ This project welcomes contributions and suggestions. Most contributions require you to agree to a
204
+ Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
205
+ the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
206
+
207
+ When you submit a pull request, a CLA bot will automatically determine whether you need to provide
208
+ a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
209
+ provided by the bot. You will only need to do this once across all repos using our CLA.
210
+
211
+ This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
212
+ For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
213
+ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
214
+
215
+ ## Trademarks
216
+
217
+ This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
218
+ trademarks or logos is subject to and must follow
219
+ [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
220
+ Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
221
+ Any use of third-party trademarks or logos are subject to those third-party's policies.
@@ -108,6 +108,16 @@ AZURE_OPENAI_API_KEY=...
108
108
 
109
109
  Examples can be found in the `examples` directory.
110
110
 
111
+ To classify one text input without starting an interactive session, run the
112
+ [non-interactive sentiment example](./sentiment/non_interactive.py) from the `python` directory:
113
+
114
+ ```sh
115
+ python examples/sentiment/non_interactive.py "TypeChat is awesome!"
116
+ ```
117
+
118
+ For an explanation of how to call the same async function from an existing backend, see the
119
+ [Python quickstart](../../site/src/docs/python/non-interactive.md).
120
+
111
121
  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.
112
122
 
113
123
  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.
@@ -0,0 +1,39 @@
1
+ # Sentiment
2
+
3
+ The Sentiment example shows how to match user intent to a set of nouns, in this case categorizing user sentiment of the input as negative, neutral, or positive with the [`SentimentResponse`](./schema.py) type.
4
+
5
+ # Try Sentiment
6
+ To run the Sentiment example, follow the instructions in the [examples README](../README.md#step-1-configure-your-development-environment).
7
+
8
+ # Usage
9
+ Example prompts can be found in [`input.txt`](./input.txt).
10
+
11
+ For example, given the following input statement:
12
+
13
+ **Input**:
14
+ ```
15
+ 😀> TypeChat is awesome!
16
+ ```
17
+
18
+ **Output**:
19
+ ```
20
+ The sentiment is positive
21
+ ```
22
+
23
+ # Non-interactive usage
24
+
25
+ The self-contained [`non_interactive.py`](./non_interactive.py) example accepts one text argument, prints the validated result as JSON, and exits without prompting for input.
26
+ After configuring the environment as described in the [examples README](../README.md), run it from the `python` directory:
27
+
28
+ ```sh
29
+ python examples/sentiment/non_interactive.py "TypeChat is awesome!"
30
+ ```
31
+
32
+ Example output:
33
+
34
+ ```json
35
+ {"sentiment": "positive"}
36
+ ```
37
+
38
+ The example exposes an async `classify_sentiment` function for use in an existing backend and surfaces translation failures as exceptions.
39
+ See the [Python quickstart](../../../site/src/docs/python/non-interactive.md) for setup, error handling, and application integration.
@@ -0,0 +1,37 @@
1
+ import argparse
2
+ import asyncio
3
+ import json
4
+ import os
5
+ from dataclasses import asdict, dataclass
6
+ from typing import Literal
7
+
8
+ from dotenv import dotenv_values
9
+ from typechat import Failure, TypeChatJsonTranslator, TypeChatValidator, create_language_model
10
+
11
+
12
+ @dataclass
13
+ class Sentiment:
14
+ sentiment: Literal["negative", "neutral", "positive"]
15
+
16
+
17
+ async def classify_sentiment(text: str, translator: TypeChatJsonTranslator[Sentiment]) -> Sentiment:
18
+ result = await translator.translate(text)
19
+ if isinstance(result, Failure):
20
+ raise RuntimeError(result.message)
21
+ return result.value
22
+
23
+
24
+ async def main(text: str) -> None:
25
+ settings = {**dotenv_values(), **os.environ}
26
+ async with create_language_model(settings) as model:
27
+ validator = TypeChatValidator(Sentiment)
28
+ translator = TypeChatJsonTranslator(model, validator, Sentiment)
29
+ result = await classify_sentiment(text, translator)
30
+ print(json.dumps(asdict(result)))
31
+
32
+
33
+ if __name__ == "__main__":
34
+ parser = argparse.ArgumentParser(description="Classify one text request without starting a chat REPL.")
35
+ parser.add_argument("text", help="The text to classify.")
36
+ args = parser.parse_args()
37
+ asyncio.run(main(args.text))
@@ -1,15 +1,18 @@
1
1
  {
2
2
  "name": "typechat-py",
3
- "version": "0.0.4",
3
+ "version": "0.1.0",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "typechat-py",
9
- "version": "0.0.4",
9
+ "version": "0.1.0",
10
10
  "license": "MIT",
11
11
  "devDependencies": {
12
12
  "pyright": "1.1.358"
13
+ },
14
+ "engines": {
15
+ "node": ">=24.22.1"
13
16
  }
14
17
  },
15
18
  "node_modules/fsevents": {
@@ -1,13 +1,16 @@
1
1
  {
2
2
  "name": "typechat-py",
3
3
  "private": true,
4
- "version": "0.0.4",
4
+ "version": "0.1.0",
5
5
  "description": "TypeChat is a library that makes it easy to build natural language interfaces using types.",
6
6
  "scripts": {
7
7
  "check": "pyright"
8
8
  },
9
9
  "author": "Microsoft",
10
10
  "license": "MIT",
11
+ "engines": {
12
+ "node": ">=24.22.1"
13
+ },
11
14
  "devDependencies": {
12
15
  "pyright": "1.1.358"
13
16
  }
@@ -1,4 +1,4 @@
1
1
  # SPDX-FileCopyrightText: Microsoft Corporation
2
2
  #
3
3
  # SPDX-License-Identifier: MIT
4
- __version__ = "0.0.5"
4
+ __version__ = "0.1.0"
@@ -2,7 +2,20 @@
2
2
  #
3
3
  # SPDX-License-Identifier: MIT
4
4
 
5
- from typechat._internal.model import PromptSection, TypeChatLanguageModel, create_language_model, create_openai_language_model, create_azure_openai_language_model
5
+ from typechat._internal.model import (
6
+ ChatCompletionClient,
7
+ ImagePromptContent,
8
+ ImageUrl,
9
+ PromptContent,
10
+ PromptSection,
11
+ TextPromptContent,
12
+ TokenProvider,
13
+ TypeChatLanguageModel,
14
+ create_language_model,
15
+ create_openai_language_model,
16
+ create_azure_openai_language_model,
17
+ create_openai_language_model_from_client,
18
+ )
6
19
  from typechat._internal.result import Failure, Result, Success
7
20
  from typechat._internal.translator import TypeChatJsonTranslator
8
21
  from typechat._internal.ts_conversion import python_type_to_typescript_schema
@@ -17,9 +30,16 @@ __all__ = [
17
30
  "Failure",
18
31
  "Result",
19
32
  "python_type_to_typescript_schema",
33
+ "PromptContent",
20
34
  "PromptSection",
35
+ "TextPromptContent",
36
+ "ImagePromptContent",
37
+ "ImageUrl",
38
+ "TokenProvider",
39
+ "ChatCompletionClient",
21
40
  "create_language_model",
22
41
  "create_openai_language_model",
23
42
  "create_azure_openai_language_model",
43
+ "create_openai_language_model_from_client",
24
44
  "process_requests",
25
45
  ]
@@ -12,7 +12,7 @@ async def process_requests(interactive_prompt: str, input_file_name: str | None,
12
12
  process_request: Async callback function that is invoked for each interactive input or each line in text file.
13
13
  """
14
14
  if input_file_name is not None:
15
- with open(input_file_name, "r") as file:
15
+ with open(input_file_name, "r", encoding="utf-8") as file:
16
16
  lines = filter(str.rstrip, file)
17
17
  for line in lines:
18
18
  if line.startswith("# "):