typeagent-py 0.1.0__tar.gz → 0.1.2__tar.gz

{typeagent_py-0.1.0/typeagent_py.egg-info → typeagent_py-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typeagent-py
-Version: 0.1.0
+Version: 0.1.2
 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 → typeagent_py-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typeagent-py"
-version = "0.1.0"
+version = "0.1.2"
 description = "TypeAgent implements an agentic memory framework."
 authors = [
   { name = "Guido van Rossum", email = "gvanrossum@microsoft.com" },
@@ -48,6 +48,9 @@ packages = [
     "typeagent.storage",
     "typeagent.storage.memory",
     "typeagent.storage.sqlite",
+    "typechat",
+    "typechat._internal",
+    "typechat._internal.ts_conversion",
 ]
 
 [tool.pytest.ini_options]

{typeagent_py-0.1.0 → typeagent_py-0.1.2/typeagent_py.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typeagent-py
-Version: 0.1.0
+Version: 0.1.2
 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 → typeagent_py-0.1.2}/typeagent_py.egg-info/SOURCES.txt

@@ -84,4 +84,17 @@ typeagent_py.egg-info/PKG-INFO
 typeagent_py.egg-info/SOURCES.txt
 typeagent_py.egg-info/dependency_links.txt
 typeagent_py.egg-info/requires.txt
-typeagent_py.egg-info/top_level.txt
+typeagent_py.egg-info/top_level.txt
+typechat/__about__.py
+typechat/__init__.py
+typechat/py.typed
+typechat/_internal/__init__.py
+typechat/_internal/interactive.py
+typechat/_internal/model.py
+typechat/_internal/result.py
+typechat/_internal/translator.py
+typechat/_internal/validator.py
+typechat/_internal/ts_conversion/__init__.py
+typechat/_internal/ts_conversion/python_type_to_ts_nodes.py
+typechat/_internal/ts_conversion/ts_node_to_string.py
+typechat/_internal/ts_conversion/ts_type_nodes.py

{typeagent_py-0.1.0 → typeagent_py-0.1.2}/typeagent_py.egg-info/top_level.txt

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

typeagent_py-0.1.2/typechat/__about__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# SPDX-FileCopyrightText: Microsoft Corporation
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.2"

typeagent_py-0.1.2/typechat/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# 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",
+]

typeagent_py-0.1.2/typechat/_internal/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.

typeagent_py-0.1.2/typechat/_internal/interactive.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+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)

typeagent_py-0.1.2/typechat/_internal/model.py

@@ -0,0 +1,187 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+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={})

typeagent_py-0.1.2/typechat/_internal/result.py

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+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

typeagent_py-0.1.2/typechat/_internal/translator.py

@@ -0,0 +1,128 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+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

typeagent_py-0.1.2/typechat/_internal/ts_conversion/__init__.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+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,
+    )