typeagent-py 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

{typeagent_py-0.1.0.dist-info → typeagent_py-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typeagent-py
-Version: 0.1.0
+Version: 0.1.1
 Summary: TypeAgent implements an agentic memory framework.
 Author: Steven Lucco, Umesh Madan, Guido van Rossum
 Author-email: Guido van Rossum <gvanrossum@microsoft.com>

{typeagent_py-0.1.0.dist-info → typeagent_py-0.1.1.dist-info}/RECORD

@@ -48,8 +48,21 @@ typeagent/storage/sqlite/reltermsindex.py,sha256=VwmUH-awNZ5YeMZTuFVfKP-8G0WQQ1k
 typeagent/storage/sqlite/schema.py,sha256=c5-dff8wdIA37SegPOI-_h-w2eCPSnpnPQAC3vcNzYo,8061
 typeagent/storage/sqlite/semrefindex.py,sha256=eqHrQMyVdFS9HOXV1dLvp0bMs8JKoPQLmV46Cs0HQJM,5456
 typeagent/storage/sqlite/timestampindex.py,sha256=gnmmwgRKCwFi2iGzGJVe7Zz12rblB-5-5WZkqpDgySM,4764
-typeagent_py-0.1.0.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
-typeagent_py-0.1.0.dist-info/METADATA,sha256=BA3AfIIF4hAKz9m-WlqH3bC82lGGL6jaFS__1SyLuxs,1002
-typeagent_py-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-typeagent_py-0.1.0.dist-info/top_level.txt,sha256=uXuso6jrsvRIIZsh6WfAvTjk5wOgClsFUiiuo1hpFZ8,10
-typeagent_py-0.1.0.dist-info/RECORD,,
+typeagent_py-0.1.1.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+typechat/__about__.py,sha256=Qcvdg23chrwFVJ3cN1UPGeSSk37i-nAOPF2CQ6x1R4w,103
+typechat/__init__.py,sha256=cH0fRzr___j_COUgwiretNwsd3o_wY7hYqFQ5TkYefE,905
+typechat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typechat/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typechat/_internal/interactive.py,sha256=Z1kvHt88SnQw3CyfWbOXMXLB-JjrJE0n4o55mQcw3pI,1530
+typechat/_internal/model.py,sha256=zTjUg0kVTNYYj-xAU_dJDLyWEZA8GuekYTcr6CcIM2g,6975
+typechat/_internal/result.py,sha256=umzDE3PWSZmecGgVtig-Rb2vRw93fEcYb1Kazp5gv3o,511
+typechat/_internal/translator.py,sha256=VcUQR2zAd2YOQyO2OAiqwJe9pyDupAtuWZCfrOS4uLk,5149
+typechat/_internal/validator.py,sha256=RxIdA3mIhj9z66jTujVjqIC99ykEivWywAhqW4swAhw,2508
+typechat/_internal/ts_conversion/__init__.py,sha256=7fZHhPl1Km8TtvCDAJE_IathP0VrNjlJPS08J7xKIJg,1298
+typechat/_internal/ts_conversion/python_type_to_ts_nodes.py,sha256=cfI2VhZ3W1WERSQ3pabH7eg86wCgIAERQI_utdvaZfI,17909
+typechat/_internal/ts_conversion/ts_node_to_string.py,sha256=QnTVlmXLp7iozdyV4TEeaGT2bhHDHBGgMJGE3hk6ZEo,4260
+typechat/_internal/ts_conversion/ts_type_nodes.py,sha256=LWtX6k45Tuw48DYBYwy4k-nF2mqjzbHP3bpYKrW58r8,2053
+typeagent_py-0.1.1.dist-info/METADATA,sha256=uqdhYIaJpNKtD_YRUZrJglla7BHJdKg7-ObSLERZPBg,1002
+typeagent_py-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+typeagent_py-0.1.1.dist-info/top_level.txt,sha256=CvJe8hnRs8A7kg7LXtgnH6Uj5MsGftIb_aryk_aoE6M,19
+typeagent_py-0.1.1.dist-info/RECORD,,

{typeagent_py-0.1.0.dist-info → typeagent_py-0.1.1.dist-info}/top_level.txt

@@ -1 +1,2 @@
 typeagent
+typechat

typechat/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Microsoft Corporation
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.2"

typechat/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: Microsoft Corporation
+#
+# 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.result import Failure, Result, Success
+from typechat._internal.translator import TypeChatJsonTranslator
+from typechat._internal.ts_conversion import python_type_to_typescript_schema
+from typechat._internal.validator import TypeChatValidator
+from typechat._internal.interactive import process_requests
+
+__all__ = [
+    "TypeChatLanguageModel",
+    "TypeChatJsonTranslator",
+    "TypeChatValidator",
+    "Success",
+    "Failure",
+    "Result",
+    "python_type_to_typescript_schema",
+    "PromptSection",
+    "create_language_model",
+    "create_openai_language_model",
+    "create_azure_openai_language_model",
+    "process_requests",
+]

typechat/_internal/interactive.py

@@ -0,0 +1,37 @@
+from typing import Callable, Awaitable
+
+async def process_requests(interactive_prompt: str, input_file_name: str | None, process_request: Callable[[str], Awaitable[None]]):
+    """
+    A request processor for interactive input or input from a text file. If an input file name is specified,
+    the callback function is invoked for each line in file. Otherwise, the callback function is invoked for
+    each line of interactive input until the user types "quit" or "exit".
+    
+    Args:
+        interactive_prompt: Prompt to present to user.
+        input_file_name: Input text file name, if any.
+        process_request: Async callback function that is invoked for each interactive input or each line in text file.
+    """
+    if input_file_name is not None:
+        with open(input_file_name, "r") as file:
+            lines = filter(str.rstrip, file)
+            for line in lines:
+                if line.startswith("# "):
+                    continue
+                print(interactive_prompt + line)
+                await process_request(line)
+    else:
+        try:
+            # Use readline to enable input editing and history
+            import readline  # type: ignore
+        except ImportError:
+            pass
+        while True:
+            try:
+                line = input(interactive_prompt)
+            except EOFError:
+                print("\n")
+                break
+            if line.lower().strip() in ("quit", "exit"):
+                break
+            else:
+                await process_request(line)

typechat/_internal/model.py

@@ -0,0 +1,184 @@
+import asyncio
+from types import TracebackType
+from typing_extensions import AsyncContextManager, Literal, Protocol, Self, TypedDict, cast, override
+
+from typechat._internal.result import Failure, Result, Success
+
+import httpx
+
+class PromptSection(TypedDict):
+    """
+    Represents a section of an LLM prompt with an associated role. TypeChat uses the "user" role for
+    prompts it generates and the "assistant" role for previous LLM responses (which will be part of
+    the prompt in repair attempts). TypeChat currently doesn't use the "system" role.
+    """
+    role: Literal["system", "user", "assistant"]
+    content: str
+
+class TypeChatLanguageModel(Protocol):
+    async def complete(self, prompt: str | list[PromptSection]) -> Result[str]:
+        """
+        Represents a AI language model that can complete prompts.
+        
+        TypeChat uses an implementation of this protocol to communicate
+        with an AI service that can translate natural language requests to JSON
+        instances according to a provided schema.
+        The `create_language_model` function can create an instance.
+        """
+        ...
+
+_TRANSIENT_ERROR_CODES = [
+    429,
+    500,
+    502,
+    503,
+    504,
+]
+
+class HttpxLanguageModel(TypeChatLanguageModel, AsyncContextManager):
+    url: str
+    headers: dict[str, str]
+    default_params: dict[str, str]
+    # Specifies the maximum number of retry attempts.
+    max_retry_attempts: int = 3
+    # Specifies the delay before retrying in milliseconds.
+    retry_pause_seconds: float = 1.0
+    # Specifies how long a request should wait in seconds
+    # before timing out with a Failure.
+    timeout_seconds = 10
+    _async_client: httpx.AsyncClient
+
+    def __init__(self, url: str, headers: dict[str, str], default_params: dict[str, str]):
+        super().__init__()
+        self.url = url
+        self.headers = headers
+        self.default_params = default_params
+        self._async_client = httpx.AsyncClient()
+
+    @override
+    async def complete(self, prompt: str | list[PromptSection]) -> Success[str] | Failure:
+        headers = {
+            "Content-Type": "application/json",
+            **self.headers,
+        }
+
+        if isinstance(prompt, str):
+            prompt = [{"role": "user", "content": prompt}]
+
+        body = {
+            **self.default_params,
+            "messages": prompt,
+            "temperature": 0.0,
+            "n": 1,
+        }
+        retry_count = 0
+        while True:
+            try:
+                response = await self._async_client.post(
+                    self.url,
+                    headers=headers,
+                    json=body,
+                    timeout=self.timeout_seconds
+                )
+                if response.is_success:
+                    json_result = cast(
+                        dict[Literal["choices"], list[dict[Literal["message"], PromptSection]]],
+                        response.json()
+                    )
+                    return Success(json_result["choices"][0]["message"]["content"] or "")
+
+                if response.status_code not in _TRANSIENT_ERROR_CODES or retry_count >= self.max_retry_attempts:
+                    return Failure(f"REST API error {response.status_code}: {response.reason_phrase}")
+            except Exception as e:
+                if retry_count >= self.max_retry_attempts:
+                    return Failure(str(e) or f"{repr(e)} raised from within internal TypeChat language model.")
+
+            await asyncio.sleep(self.retry_pause_seconds)
+            retry_count += 1
+
+    @override
+    async def __aenter__(self) -> Self:
+        return self
+
+    @override
+    async def __aexit__(self, __exc_type: type[BaseException] | None, __exc_value: BaseException | None, __traceback: TracebackType | None) -> bool | None:
+        await self._async_client.aclose()
+
+    def __del__(self):
+        try:
+            asyncio.get_running_loop().create_task(self._async_client.aclose())
+        except Exception:
+            pass
+
+def create_language_model(vals: dict[str, str | None]) -> HttpxLanguageModel:
+    """
+    Creates a language model encapsulation of an OpenAI or Azure OpenAI REST API endpoint
+    chosen by a dictionary of variables (typically just `os.environ`).
+
+    If an `OPENAI_API_KEY` environment variable exists, an OpenAI model is constructed.
+    The `OPENAI_ENDPOINT` and `OPENAI_MODEL` environment variables must also be defined or an error will be raised.
+
+    If an `AZURE_OPENAI_API_KEY` environment variable exists, an Azure OpenAI model is constructed.
+    The `AZURE_OPENAI_ENDPOINT` environment variable must also be defined or an exception will be thrown.
+
+    If none of these key variables are defined, an exception is thrown.
+    @returns An instance of `TypeChatLanguageModel`.
+
+    Args:
+        vals: A dictionary of variables. Typically just `os.environ`.
+    """
+    
+    def required_var(name: str) -> str:
+        val = vals.get(name, None)
+        if val is None:
+            raise ValueError(f"Missing environment variable {name}.")
+        return val
+
+    if "OPENAI_API_KEY" in vals:
+        api_key = required_var("OPENAI_API_KEY")
+        model = required_var("OPENAI_MODEL")
+        endpoint = vals.get("OPENAI_ENDPOINT", None) or "https://api.openai.com/v1/chat/completions"
+        org = vals.get("OPENAI_ORG", None) or ""
+        return create_openai_language_model(api_key, model, endpoint, org)
+
+    elif "AZURE_OPENAI_API_KEY" in vals:
+        api_key=required_var("AZURE_OPENAI_API_KEY")
+        endpoint=required_var("AZURE_OPENAI_ENDPOINT")
+        return create_azure_openai_language_model(api_key, endpoint)
+    else:
+        raise ValueError("Missing environment variables for OPENAI_API_KEY or AZURE_OPENAI_API_KEY.")
+
+def create_openai_language_model(api_key: str, model: str, endpoint: str = "https://api.openai.com/v1/chat/completions", org: str = "") -> HttpxLanguageModel:
+    """
+    Creates a language model encapsulation of an OpenAI REST API endpoint.
+
+    Args:
+        api_key: The OpenAI API key.
+        model: The OpenAI model name.
+        endpoint: The OpenAI REST API endpoint.
+        org: The OpenAI organization.
+    """
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "OpenAI-Organization": org,
+    }
+    default_params = {
+        "model": model,
+    }
+    return HttpxLanguageModel(url=endpoint, headers=headers, default_params=default_params)
+
+def create_azure_openai_language_model(api_key: str, endpoint: str) -> HttpxLanguageModel:
+    """
+    Creates a language model encapsulation of an Azure OpenAI REST API endpoint.
+
+    Args:
+        api_key: The Azure OpenAI API key.
+        endpoint: The Azure OpenAI REST API endpoint.
+    """
+    headers = {
+        # Needed when using managed identity
+        "Authorization": f"Bearer {api_key}",
+        # Needed when using regular API key
+        "api-key": api_key,
+    }
+    return HttpxLanguageModel(url=endpoint, headers=headers, default_params={})

typechat/_internal/result.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+from typing_extensions import Generic, TypeAlias, TypeVar
+
+T = TypeVar("T", covariant=True)
+
+@dataclass
+class Success(Generic[T]):
+    "An object representing a successful operation with a result of type `T`."
+    value: T
+
+
+@dataclass
+class Failure:
+    "An object representing an operation that failed for the reason given in `message`."
+    message: str
+
+
+"""
+An object representing a successful or failed operation of type `T`.
+"""
+Result: TypeAlias = Success[T] | Failure

typechat/_internal/translator.py

@@ -0,0 +1,125 @@
+from typing_extensions import Generic, TypeVar
+
+import pydantic_core
+
+from typechat._internal.model import PromptSection, TypeChatLanguageModel
+from typechat._internal.result import Failure, Result, Success
+from typechat._internal.ts_conversion import python_type_to_typescript_schema
+from typechat._internal.validator import TypeChatValidator
+
+T = TypeVar("T", covariant=True)
+
+class TypeChatJsonTranslator(Generic[T]):
+    """
+    Represents an object that can translate natural language requests in JSON objects of the given type.
+    """
+
+    model: TypeChatLanguageModel
+    validator: TypeChatValidator[T]
+    target_type: type[T]
+    type_name: str
+    schema_str: str
+    _max_repair_attempts = 1
+
+    def __init__(
+        self,
+        model: TypeChatLanguageModel,
+        validator: TypeChatValidator[T],
+        target_type: type[T],
+        *, # keyword-only parameters follow
+        _raise_on_schema_errors: bool = True,
+    ):
+        """
+        Args:
+            model: The associated `TypeChatLanguageModel`.
+            validator: The associated `TypeChatValidator[T]`.
+            target_type: A runtime type object describing `T` - the expected shape of JSON data.
+        """
+        super().__init__()
+        self.model = model
+        self.validator = validator
+        self.target_type = target_type
+
+        conversion_result = python_type_to_typescript_schema(target_type)
+
+        if _raise_on_schema_errors and conversion_result.errors:
+            error_text = "".join(f"\n- {error}" for error in conversion_result.errors)
+            raise ValueError(f"Could not convert Python type to TypeScript schema: \n{error_text}")
+
+        self.type_name = conversion_result.typescript_type_reference
+        self.schema_str = conversion_result.typescript_schema_str
+
+    async def translate(self, input: str, *, prompt_preamble: str | list[PromptSection] | None = None) -> Result[T]:
+        """
+        Translates a natural language request into an object of type `T`. If the JSON object returned by
+        the language model fails to validate, repair attempts will be made up until `_max_repair_attempts`.
+        The prompt for the subsequent attempts will include the diagnostics produced for the prior attempt.
+        This often helps produce a valid instance.
+
+        Args:
+            input: A natural language request.
+            prompt_preamble: An optional string or list of prompt sections to prepend to the generated prompt.\
+                             If a string is given, it is converted to a single "user" role prompt section.
+        """
+
+        messages: list[PromptSection] = []
+
+        if prompt_preamble:
+            if isinstance(prompt_preamble, str):
+                prompt_preamble = [{"role": "user", "content": prompt_preamble}]
+            messages.extend(prompt_preamble)
+
+        messages.append({"role": "user", "content": self._create_request_prompt(input)})
+
+        num_repairs_attempted = 0
+        while True:
+            completion_response = await self.model.complete(messages)
+            if isinstance(completion_response, Failure):
+                return completion_response
+
+            text_response = completion_response.value
+            first_curly = text_response.find("{")
+            last_curly = text_response.rfind("}") + 1
+            error_message: str
+            if 0 <= first_curly < last_curly:
+                trimmed_response = text_response[first_curly:last_curly]
+                try:
+                    parsed_response = pydantic_core.from_json(trimmed_response, allow_inf_nan=False, cache_strings=False)
+                except ValueError as e:
+                    error_message = f"Error: {e}\n\nAttempted to parse:\n\n{trimmed_response}"
+                else:
+                    result = self.validator.validate_object(parsed_response)
+                    if isinstance(result, Success):
+                        return result
+                    error_message = result.message
+            else:
+                error_message = f"Response did not contain any text resembling JSON.\nResponse was\n\n{text_response}"
+            if num_repairs_attempted >= self._max_repair_attempts:
+                return Failure(error_message)
+            num_repairs_attempted += 1
+            messages.append({"role": "assistant", "content": text_response})
+            messages.append({"role": "user", "content": self._create_repair_prompt(error_message)})
+
+    def _create_request_prompt(self, intent: str) -> str:
+        prompt = f"""
+You are a service that translates user requests into JSON objects of type "{self.type_name}" according to the following TypeScript definitions:
+```
+{self.schema_str}
+```
+The following is a user request:
+'''
+{intent}
+'''
+The following is the user request translated into a JSON object with 2 spaces of indentation and no properties with the value undefined:
+"""
+        return prompt
+
+    def _create_repair_prompt(self, validation_error: str) -> str:
+        prompt = f"""
+The above JSON object is invalid for the following reason:
+'''
+{validation_error}
+'''
+The following is a revised JSON object:
+"""
+        return prompt

typechat/_internal/ts_conversion/__init__.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from typing_extensions import TypeAliasType
+
+from typechat._internal.ts_conversion.python_type_to_ts_nodes import python_type_to_typescript_nodes
+from typechat._internal.ts_conversion.ts_node_to_string import ts_declaration_to_str
+
+__all__ = [
+    "python_type_to_typescript_schema",
+    "TypeScriptSchemaConversionResult",
+]
+
+@dataclass
+class TypeScriptSchemaConversionResult:
+    typescript_schema_str: str
+    """The TypeScript declarations generated from the Python declarations."""
+
+    typescript_type_reference: str
+    """The TypeScript string representation of a given Python type."""
+
+    errors: list[str]
+    """Any errors that occurred during conversion."""
+
+def python_type_to_typescript_schema(py_type: type | TypeAliasType) -> TypeScriptSchemaConversionResult:
+    """Converts a Python type to a TypeScript schema."""
+
+    node_conversion_result = python_type_to_typescript_nodes(py_type)
+
+    decl_strs = map(ts_declaration_to_str, node_conversion_result.type_declarations)
+    decl_strs = reversed(list(decl_strs))
+
+    schema_str = "\n".join(decl_strs)
+
+    return TypeScriptSchemaConversionResult(
+        typescript_schema_str=schema_str,
+        typescript_type_reference=py_type.__name__,
+        errors=node_conversion_result.errors,
+    )

typechat/_internal/ts_conversion/python_type_to_ts_nodes.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+import inspect
+import sys
+import typing
+import typing_extensions
+from dataclasses import MISSING, Field, dataclass
+from types import NoneType, UnionType
+from typing_extensions import (
+    Annotated,
+    Any,
+    ClassVar,
+    Doc,
+    Final,
+    Generic,
+    Literal,
+    LiteralString,
+    Never,
+    NoReturn,
+    NotRequired,
+    Protocol,
+    Required,
+    TypeAlias,
+    TypeAliasType,    
+    TypeGuard,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    get_original_bases,
+    get_type_hints,
+    is_typeddict,
+)
+
+from typechat._internal.ts_conversion.ts_type_nodes import (
+    AnyTypeReferenceNode,
+    ArrayTypeNode,
+    BooleanTypeReferenceNode,
+    IdentifierNode,
+    IndexSignatureDeclarationNode,
+    InterfaceDeclarationNode,
+    LiteralTypeNode,
+    NeverTypeReferenceNode,
+    NullTypeReferenceNode,
+    NumberTypeReferenceNode,
+    PropertyDeclarationNode,
+    StringTypeReferenceNode,
+    ThisTypeReferenceNode,
+    TopLevelDeclarationNode,
+    TupleTypeNode,
+    TypeAliasDeclarationNode,
+    TypeNode,
+    TypeParameterDeclarationNode,
+    TypeReferenceNode,
+    UnionTypeNode,
+)
+
+class GenericDeclarationish(Protocol):
+    __parameters__: list[TypeVar]
+    __type_params__: list[TypeVar] # NOTE: may not be present unless running in 3.12
+
+class GenericAliasish(Protocol):
+    __origin__: object
+    __args__: tuple[object, ...]
+    __name__: str
+
+
+class Annotatedish(Protocol):
+    # NOTE: `__origin__` here refers to `SomeType` in `Annnotated[SomeType, ...]`
+    __origin__: object
+    __metadata__: tuple[object, ...]
+
+class Dataclassish(Protocol):
+    __dataclass_fields__: dict[str, Field[Any]]
+
+# type[TypedDict]
+# https://github.com/microsoft/pyright/pull/6505#issuecomment-1834431725
+class TypeOfTypedDict(Protocol):
+    __total__: bool
+
+if sys.version_info >= (3, 12) and typing.TypeAliasType is not typing_extensions.TypeAliasType:
+    # Sometimes typing_extensions aliases TypeAliasType,
+    # sometimes it's its own declaration.
+    def is_type_alias_type(py_type: object) -> TypeGuard[TypeAliasType]:
+        return isinstance(py_type, typing.TypeAliasType | typing_extensions.TypeAliasType)
+else:
+    def is_type_alias_type(py_type: object) -> TypeGuard[TypeAliasType]:
+        return isinstance(py_type, typing_extensions.TypeAliasType)
+
+
+def is_generic(py_type: object) -> TypeGuard[GenericAliasish]:
+    return hasattr(py_type, "__origin__") and hasattr(py_type, "__args__")
+
+def is_dataclass(py_type: object) -> TypeGuard[Dataclassish]:
+    return hasattr(py_type, "__dataclass_fields__") and isinstance(cast(Any, py_type).__dataclass_fields__, dict)
+
+TypeReferenceTarget: TypeAlias = type | TypeAliasType | TypeVar | GenericAliasish
+
+def is_python_type_or_alias(origin: object) -> TypeGuard[type | TypeAliasType]:
+    return isinstance(origin, type) or is_type_alias_type(origin)
+
+
+_KNOWN_GENERIC_SPECIAL_FORMS: frozenset[Any] = frozenset(
+    [
+        Required,
+        NotRequired,
+        ClassVar,
+        Final,
+        Annotated,
+        Generic,
+    ]
+)
+
+_KNOWN_SPECIAL_BASES: frozenset[Any] = frozenset([
+    typing.TypedDict,
+    typing_extensions.TypedDict,
+    Protocol,
+
+    # In older versions of Python, `__orig_bases__` will not be defined on `TypedDict`s
+    # derived from the built-in `typing` module (but they will from `typing_extensions`!).
+    # So `get_original_bases` will fetch `__bases__` which will map `TypedDict` to a plain `dict`.
+    dict,
+])
+
+
+@dataclass
+class TypeScriptNodeTranslationResult:
+    type_declarations: list[TopLevelDeclarationNode]
+    errors: list[str]
+
+
+# TODO: https://github.com/microsoft/pyright/issues/6587
+_SELF_TYPE = getattr(typing_extensions, "Self")
+
+_LIST_TYPES: set[object] = {
+    list,
+    set,
+    frozenset,
+    # TODO: https://github.com/microsoft/pyright/issues/6582
+    # collections.abc.MutableSequence,
+    # collections.abc.Sequence,
+    # collections.abc.Set
+}
+
+# TODO: https://github.com/microsoft/pyright/issues/6582
+# _DICT_TYPES: set[type] = {
+#     dict,
+#     collections.abc.MutableMapping,
+#     collections.abc.Mapping
+# }
+
+
+def python_type_to_typescript_nodes(root_py_type: object) -> TypeScriptNodeTranslationResult:
+    # TODO: handle conflicting names
+
+    declared_types: OrderedDict[object, TopLevelDeclarationNode | None] = OrderedDict()
+    undeclared_types: OrderedDict[object, object] = OrderedDict({root_py_type: root_py_type}) # just a set, really
+    used_names: dict[str, type | TypeAliasType] = {}
+    errors: list[str] = []
+
+    def skip_annotations(py_type: object) -> object:
+        origin = py_type
+        while (origin := get_origin(py_type)) and origin in _KNOWN_GENERIC_SPECIAL_FORMS:
+            type_arguments = get_args(py_type)
+            if not type_arguments:
+                errors.append(f"'{origin}' has been used without any type arguments.")
+                return Any
+            py_type = type_arguments[0]
+            continue
+        return py_type
+
+    def convert_to_type_reference_node(py_type: TypeReferenceTarget) -> TypeNode:
+        py_type_to_declare = py_type
+
+        if is_generic(py_type):
+            py_type_to_declare = get_origin(py_type)
+
+        if py_type_to_declare not in declared_types:
+            if is_python_type_or_alias(py_type_to_declare):
+                undeclared_types[py_type_to_declare] = py_type_to_declare
+            elif not isinstance(py_type, TypeVar):
+                errors.append(f"Invalid usage of '{py_type}' as a type annotation.")
+                return AnyTypeReferenceNode
+
+        if is_generic(py_type):
+            return generic_alias_to_type_reference(py_type)
+
+        return TypeReferenceNode(IdentifierNode(py_type.__name__))
+
+    def generic_alias_to_type_reference(py_type: GenericAliasish) -> TypeReferenceNode:
+        origin = get_origin(py_type)
+        assert origin is not None
+        name = origin.__name__
+        type_arguments = list(map(convert_to_type_node, get_args(py_type)))
+        return TypeReferenceNode(IdentifierNode(name), type_arguments)
+
+    def convert_literal_type_arg_to_type_node(py_type: object) -> TypeNode:
+        py_type = skip_annotations(py_type)
+        match py_type:
+            case str() | int() | float():  # no need to match bool, it's a subclass of int
+                return LiteralTypeNode(py_type)
+            case None:
+                return NullTypeReferenceNode
+            case _:
+                errors.append(f"'{py_type}' cannot be used as a literal type.")
+                return AnyTypeReferenceNode
+
+    def convert_to_type_node(py_type: object) -> TypeNode:
+        py_type = skip_annotations(py_type)
+
+        if py_type is str or py_type is LiteralString:
+            return StringTypeReferenceNode
+        if py_type is int or py_type is float:
+            return NumberTypeReferenceNode
+        if py_type is bool:
+            return BooleanTypeReferenceNode
+        if py_type is Any or py_type is object:
+            return AnyTypeReferenceNode
+        if py_type is None or py_type is NoneType:
+            return NullTypeReferenceNode
+        if py_type is Never or py_type is NoReturn:
+            return NeverTypeReferenceNode
+        if py_type is _SELF_TYPE:
+            return ThisTypeReferenceNode
+
+        # TODO: consider handling bare 'tuple' (and list, etc.)
+        # https://docs.python.org/3/library/typing.html#annotating-tuples
+        # Using plain tuple as an annotation is equivalent to using tuple[Any, ...]:
+
+        origin = get_origin(py_type)
+        if origin is not None:
+            if origin in _LIST_TYPES:
+                (type_arg,) = get_type_argument_nodes(py_type, 1, AnyTypeReferenceNode)
+                if isinstance(type_arg, UnionTypeNode):
+                    return TypeReferenceNode(IdentifierNode("Array"), [type_arg])
+                return ArrayTypeNode(type_arg)
+
+            if origin is dict:
+                # TODO
+                # Currently, we naively assume all dicts are string-keyed
+                # unless they're annotated with `int` or `float` (note: not `int | float`).
+                key_type_arg, value_type_arg = get_type_argument_nodes(py_type, 2, AnyTypeReferenceNode)
+                if key_type_arg is not NumberTypeReferenceNode:
+                    key_type_arg = StringTypeReferenceNode
+                return TypeReferenceNode(IdentifierNode("Record"), [key_type_arg, value_type_arg])
+
+            if origin is tuple:
+                # Note that when the type is `tuple[()]`,
+                # `type_args` will be an empty tuple.
+                # Which is nice, because we don't have to special-case anything!
+                type_args = get_args(py_type)
+
+                if Ellipsis in type_args:
+                    if len(type_args) != 2:
+                        errors.append(
+                            f"The tuple type '{py_type}' is ill-formed. Tuples with an ellipsis can only take the form 'tuple[SomeType, ...]'."
+                        )
+                        return ArrayTypeNode(AnyTypeReferenceNode)
+
+                    ellipsis_index = type_args.index(Ellipsis)
+                    if ellipsis_index != 1:
+                        errors.append(
+                            f"The tuple type '{py_type}' is ill-formed because the ellipsis (...) cannot be the first element."
+                        )
+                        return ArrayTypeNode(AnyTypeReferenceNode)
+
+                    return ArrayTypeNode(convert_to_type_node(type_args[0]))
+
+                return TupleTypeNode([convert_to_type_node(py_type_arg) for py_type_arg in type_args])
+
+            if origin is Union or origin is UnionType:
+                type_node = [convert_to_type_node(py_type_arg) for py_type_arg in get_args(py_type)]
+                assert len(type_node) > 1
+                return UnionTypeNode(type_node)
+
+            if origin is Literal:
+                type_node = [convert_literal_type_arg_to_type_node(py_type_arg) for py_type_arg in get_args(py_type)]
+                assert len(type_node) >= 1
+                return UnionTypeNode(type_node)
+
+            assert is_generic(py_type)
+            return convert_to_type_reference_node(py_type)
+
+        if is_python_type_or_alias(py_type):
+            return convert_to_type_reference_node(py_type)
+
+        if isinstance(py_type, TypeVar):
+            return convert_to_type_reference_node(py_type)
+
+        errors.append(f"'{py_type}' cannot be used as a type annotation.")
+        return AnyTypeReferenceNode
+
+    def declare_property(name: str, py_annotation: type | TypeAliasType, is_typeddict_attribute: bool, optionality_default: bool):
+        """
+        Declare a property for a given type.
+        If 'optionality_default' is 
+        """
+        current_annotation: object = py_annotation
+        origin: object
+        optional: bool | None = None
+        comment: str | None = None
+        while origin := get_origin(current_annotation):
+            if origin is Annotated and comment is None:
+                current_annotation = cast(Annotatedish, current_annotation)
+
+                for metadata in current_annotation.__metadata__:
+                    if isinstance(metadata, Doc):
+                        comment = metadata.documentation
+                        break
+                    if isinstance(metadata, str):
+                        comment = metadata
+                        break
+
+                current_annotation = current_annotation.__origin__
+
+            elif origin is Required or origin is NotRequired:
+                if not is_typeddict_attribute:
+                    errors.append(f"Optionality cannot be specified with {origin} outside of TypedDicts.")
+
+                if optional is None:
+                    optional = origin is NotRequired
+                else:
+                    errors.append(f"{origin} cannot be used within another optionality annotation.")
+
+                current_annotation = get_args(current_annotation)[0]
+            else:
+                break
+
+        if optional is None:
+            optional = optionality_default
+
+        type_annotation = convert_to_type_node(skip_annotations(current_annotation))
+        return PropertyDeclarationNode(name, optional, comment or "", type_annotation)
+
+    def reserve_name(val: type | TypeAliasType):
+        type_name = val.__name__
+        if type_name in used_names:
+            errors.append(f"Cannot create a schema using two types with the same name. {type_name} conflicts between {val} and {used_names[type_name]}")
+        else:
+            used_names[type_name] = val
+
+    def declare_type(py_type: object):
+        if (is_typeddict(py_type) or is_dataclass(py_type)) and isinstance(py_type, type):
+            comment = py_type.__doc__ or ""
+
+            if hasattr(py_type, "__type_params__") and cast(GenericDeclarationish, py_type).__type_params__:
+                type_params = [
+                    TypeParameterDeclarationNode(type_param.__name__)
+                    for type_param in cast(GenericDeclarationish, py_type).__type_params__
+                ]
+            elif hasattr(py_type, "__parameters__") and cast(GenericDeclarationish, py_type).__parameters__:
+                type_params = [
+                    TypeParameterDeclarationNode(type_param.__name__)
+                    for type_param in cast(GenericDeclarationish, py_type).__parameters__
+                ]
+            else:
+                type_params = None
+
+            annotated_members = get_type_hints(py_type, include_extras=True)
+
+            raw_but_filtered_bases: list[type] = [
+                base
+                for base in get_original_bases(py_type)
+                if not(base is object or base in _KNOWN_SPECIAL_BASES or get_origin(base) in _KNOWN_GENERIC_SPECIAL_FORMS)
+            ]
+            base_attributes: OrderedDict[str, set[object]] = OrderedDict()
+            for base in raw_but_filtered_bases:
+                for prop, type_hint in get_type_hints(get_origin(base) or base, include_extras=True).items():
+                    base_attributes.setdefault(prop, set()).add(type_hint)
+            bases = [convert_to_type_node(base) for base in raw_but_filtered_bases]
+
+            properties: list[PropertyDeclarationNode | IndexSignatureDeclarationNode] = []
+            if is_typeddict(py_type):
+                for attr_name, type_hint in annotated_members.items():
+                    if attribute_identical_in_all_bases(attr_name, type_hint, base_attributes):
+                        continue
+
+                    assume_optional = cast(TypeOfTypedDict, py_type).__total__ is False
+                    prop = declare_property(attr_name, type_hint, is_typeddict_attribute=True, optionality_default=assume_optional)
+                    properties.append(prop)
+            else:
+                # When a dataclass is created with no explicit docstring, @dataclass will
+                # generate one for us; however, we don't want these in the default output.
+                cleaned_signature = str(inspect.signature(py_type)).replace(" -> None", "")
+                dataclass_doc = f"{py_type.__name__}{cleaned_signature}"
+                if comment == dataclass_doc:
+                    comment = ""
+
+                for attr_name, field in cast(Dataclassish, py_type).__dataclass_fields__.items():
+                    type_hint = annotated_members[attr_name]
+                    optional = not(field.default is MISSING and field.default_factory is MISSING)
+                    prop = declare_property(attr_name, type_hint, is_typeddict_attribute=False, optionality_default=optional)
+                    properties.append(prop)
+
+            reserve_name(py_type)
+            return InterfaceDeclarationNode(py_type.__name__, type_params, comment, bases, properties)
+        if isinstance(py_type, type):
+            errors.append(f"{py_type.__name__} was not a TypedDict, dataclass, or type alias, and cannot be translated.")
+
+            reserve_name(py_type)
+
+            return InterfaceDeclarationNode(py_type.__name__, None, "", None, [])
+        if is_type_alias_type(py_type):
+            type_params = [TypeParameterDeclarationNode(type_param.__name__) for type_param in py_type.__type_params__]
+
+            reserve_name(py_type)
+
+            return TypeAliasDeclarationNode(
+                py_type.__name__,
+                type_params,
+                f"Comment for {py_type.__name__}.",
+                convert_to_type_node(py_type.__value__),
+            )
+
+        raise RuntimeError(f"Cannot declare type {py_type}.")
+
+    def attribute_identical_in_all_bases(attr_name: str, type_hint: object, base_attributes: dict[str, set[object]]) -> bool:
+        """
+        We typically want to omit attributes with type hints that are
+        identical to those declared in all base types.
+        """
+        return attr_name in base_attributes and len(base_attributes[attr_name]) == 1 and type_hint in base_attributes[attr_name]
+
+    def get_type_argument_nodes(py_type: object, count: int, default: TypeNode) -> list[TypeNode]:
+        py_type_args = get_args(py_type)
+        result: list[TypeNode] = []
+        if len(py_type_args) != count:
+            errors.append(f"Expected '{count}' type arguments for '{py_type}'.")
+        for i in range(count):
+            if i < len(py_type_args):
+                type_node = convert_to_type_node(py_type_args[i])
+            else:
+                type_node = default
+            result.append(type_node)
+        return result
+
+    while undeclared_types:
+        py_type = undeclared_types.popitem()[0]
+        declared_types[py_type] = None
+        declared_types[py_type] = declare_type(py_type)
+
+    type_declarations = cast(list[TopLevelDeclarationNode], list(declared_types.values()))
+    assert None not in type_declarations
+
+    return TypeScriptNodeTranslationResult(type_declarations, errors)

typechat/_internal/ts_conversion/ts_node_to_string.py

@@ -0,0 +1,96 @@
+import json
+from typing_extensions import assert_never
+
+from typechat._internal.ts_conversion.ts_type_nodes import (
+    ArrayTypeNode,
+    IdentifierNode,
+    IndexSignatureDeclarationNode,
+    InterfaceDeclarationNode,
+    LiteralTypeNode,
+    NullTypeReferenceNode,
+    PropertyDeclarationNode,
+    TopLevelDeclarationNode,
+    TupleTypeNode,
+    TypeAliasDeclarationNode,
+    TypeNode,
+    TypeReferenceNode,
+    UnionTypeNode,
+)
+
+
+def comment_to_str(comment_text: str, indentation: str) -> str:
+    comment_text = comment_text.strip()
+    if not comment_text:
+        return ""
+    lines = [line.strip() for line in comment_text.splitlines()]
+
+    return "\n".join([f"{indentation}// {line}" for line in lines]) + "\n"
+
+
+def ts_type_to_str(type_node: TypeNode) -> str:
+    match type_node:
+        case TypeReferenceNode(name, type_arguments):
+            assert isinstance(name, IdentifierNode)
+            if type_arguments is None:
+                return name.text
+            return f"{name.text}<{', '.join([ts_type_to_str(arg) for arg in type_arguments])}>"
+        case ArrayTypeNode(element_type):
+            assert type(element_type) is not UnionTypeNode
+            # if type(element_type) is UnionTypeNode:
+            #     return f"Array<{ts_type_to_str(element_type)}>"
+            return f"{ts_type_to_str(element_type)}[]"
+        case TupleTypeNode(element_types):
+            return f"[{', '.join([ts_type_to_str(element_type) for element_type in element_types])}]"
+        case UnionTypeNode(types):
+            # Remove duplicates, but try to preserve order of types,
+            # and put null at the end if it's present.
+            str_set: set[str] = set()
+            type_strs: list[str] = []
+            nullable = False
+            for type_node in types:
+                if type_node is NullTypeReferenceNode:
+                    nullable = True
+                    continue
+                type_str = ts_type_to_str(type_node)
+                if type_str not in str_set:
+                    str_set.add(type_str)
+                    type_strs.append(type_str)
+            if nullable:
+                type_strs.append("null")
+            return " | ".join(type_strs)
+        case LiteralTypeNode(value):
+            return json.dumps(value)
+        # case _:
+        #     raise NotImplementedError(f"Unhandled type {type(type_node)}")
+    assert_never(type_node)
+
+def object_member_to_str(member: PropertyDeclarationNode | IndexSignatureDeclarationNode) -> str:
+    match member:
+        case PropertyDeclarationNode(name, is_optional, comment, annotation):
+            comment = comment_to_str(comment, "    ")
+            if not name.isidentifier():
+                name = json.dumps(name)
+            return f"{comment}    {name}{'?' if is_optional else ''}: {ts_type_to_str(annotation)};"
+        case IndexSignatureDeclarationNode(key_type, value_type):
+            return f"[key: {ts_type_to_str(key_type)}]: {ts_type_to_str(value_type)};"
+        # case _:
+        #     raise NotImplementedError(f"Unhandled member type {type(member)}")
+    assert_never(member)
+
+
+def ts_declaration_to_str(declaration: TopLevelDeclarationNode) -> str:
+    match declaration:
+        case InterfaceDeclarationNode(name, type_parameters, comment, base_types, members):
+            comment = comment_to_str(comment, "")
+            type_param_str = f"<{', '.join([param.name for param in type_parameters])}>" if type_parameters else ""
+            base_type_str = (
+                f" extends {', '.join([ts_type_to_str(base_type) for base_type in base_types])}" if base_types else ""
+            )
+            members_str = "\n".join([f"{object_member_to_str(member)}" for member in members]) + "\n" if members else ""
+            return f"{comment}interface {name}{type_param_str}{base_type_str} {{\n{members_str}}}\n"
+        case TypeAliasDeclarationNode(name, type_parameters, comment, target):
+            type_param_str = f"<{', '.join([param.name for param in type_parameters])}>" if type_parameters else ""
+            return f"type {name}{type_param_str} = {ts_type_to_str(target)}\n"
+        # case _:
+        #     raise NotImplementedError(f"Unhandled declaration type {type(declaration)}")
+    assert_never(declaration)

typechat/_internal/ts_conversion/ts_type_nodes.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing_extensions import TypeAlias
+
+TypeNode: TypeAlias = "TypeReferenceNode | UnionTypeNode | LiteralTypeNode | ArrayTypeNode | TupleTypeNode"
+
+@dataclass
+class IdentifierNode:
+    text: str
+
+@dataclass
+class QualifiedNameNode:
+    left: QualifiedNameNode | IdentifierNode
+    right: IdentifierNode
+
+@dataclass
+class TypeReferenceNode:
+    name: QualifiedNameNode | IdentifierNode
+    type_arguments: list[TypeNode] | None = None
+
+@dataclass
+class UnionTypeNode:
+    types: list[TypeNode]
+
+@dataclass
+class LiteralTypeNode:
+    value: str | int | float | bool
+
+@dataclass
+class ArrayTypeNode:
+    element_type: TypeNode
+
+@dataclass
+class TupleTypeNode:
+    element_types: list[TypeNode]
+
+@dataclass
+class InterfaceDeclarationNode:
+    name: str
+    type_parameters: list[TypeParameterDeclarationNode] | None
+    comment: str
+    base_types: list[TypeNode] | None
+    members: list[PropertyDeclarationNode | IndexSignatureDeclarationNode]
+
+@dataclass
+class TypeParameterDeclarationNode:
+    name: str
+    constraint: TypeNode | None = None
+
+@dataclass
+class PropertyDeclarationNode:
+    name: str
+    is_optional: bool
+    comment: str
+    type: TypeNode
+
+@dataclass
+class IndexSignatureDeclarationNode:
+    key_type: TypeNode
+    value_type: TypeNode
+
+@dataclass
+class TypeAliasDeclarationNode:
+    name: str
+    type_parameters: list[TypeParameterDeclarationNode] | None
+    comment: str
+    type: TypeNode
+
+TopLevelDeclarationNode: TypeAlias = "InterfaceDeclarationNode | TypeAliasDeclarationNode"
+
+StringTypeReferenceNode = TypeReferenceNode(IdentifierNode("string"))
+NumberTypeReferenceNode = TypeReferenceNode(IdentifierNode("number"))
+BooleanTypeReferenceNode = TypeReferenceNode(IdentifierNode("boolean"))
+AnyTypeReferenceNode = TypeReferenceNode(IdentifierNode("any"))
+NullTypeReferenceNode = TypeReferenceNode(IdentifierNode("null"))
+NeverTypeReferenceNode = TypeReferenceNode(IdentifierNode("never"))
+ThisTypeReferenceNode = TypeReferenceNode(IdentifierNode("this"))

typechat/_internal/validator.py

@@ -0,0 +1,67 @@
+import json
+from typing_extensions import Generic, TypeVar
+
+import pydantic
+import pydantic_core
+
+from typechat._internal.result import Failure, Result, Success
+
+T = TypeVar("T", covariant=True)
+
+class TypeChatValidator(Generic[T]):
+    """
+    Validates an object against a given Python type.
+    """
+
+    _adapted_type: pydantic.TypeAdapter[T]
+
+    def __init__(self, py_type: type[T]):
+        """
+        Args:
+
+            py_type: The schema type to validate against.
+        """
+        super().__init__()
+        self._adapted_type = pydantic.TypeAdapter(py_type)
+
+    def validate_object(self, obj: object) -> Result[T]:
+        """
+        Validates the given Python object according to the associated schema type.
+
+        Returns a `Success[T]` object containing the object if validation was successful.
+        Otherwise, returns a `Failure` object with a `message` property describing the error.
+        """
+        try:
+            # TODO: Switch to `validate_python` when validation modes are exposed.
+            # https://github.com/pydantic/pydantic-core/issues/712
+            # We'd prefer to keep `validate_object` as the core method and
+            # allow translators to concern themselves with the JSON instead.
+            # However, under Pydantic's `strict` mode, a `dict` isn't considered compatible
+            # with a dataclass. So for now, jump back to JSON and validate the string.
+            json_str = pydantic_core.to_json(obj)
+            typed_dict = self._adapted_type.validate_json(json_str, strict=True)
+            return Success(typed_dict)
+        except pydantic.ValidationError as validation_error:
+            return _handle_error(validation_error)
+
+
+def _handle_error(validation_error: pydantic.ValidationError) -> Failure:
+    error_strings: list[str] = []
+    for error in validation_error.errors(include_url=False):
+        error_string = ""
+        loc_path = error["loc"]
+        if loc_path:
+            error_string += f"Validation path `{'.'.join(map(str, loc_path))}` "
+        else:
+            error_string += "Root validation "
+        input = error["input"]
+        error_string += f"failed for value `{json.dumps(input)}` because:\n  {error['msg']}"
+        error_strings.append(error_string)
+
+    if len(error_strings) > 1:
+        failure_message = "Several possible issues may have occurred with the given data.\n\n"
+    else:
+        failure_message = ""
+    failure_message += "\n".join(error_strings)
+
+    return Failure(failure_message)