coco-framework 0.1.0__py3-none-any.whl

coco_core/prompts/chat.py

@@ -0,0 +1,1495 @@
+"""Chat prompt template."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+from typing import (
+    Annotated,
+    Any,
+    TypedDict,
+    TypeVar,
+    cast,
+    overload,
+)
+
+from pydantic import (
+    Field,
+    PositiveInt,
+    SkipValidation,
+    model_validator,
+)
+from typing_extensions import Self, override
+
+from coco_core._api import deprecated
+from coco_core.messages import (
+    AIMessage,
+    AnyMessage,
+    BaseMessage,
+    ChatMessage,
+    HumanMessage,
+    SystemMessage,
+    convert_to_messages,
+)
+from coco_core.messages.base import get_msg_title_repr
+from coco_core.prompt_values import ChatPromptValue
+from coco_core.prompts.base import BasePromptTemplate
+from coco_core.prompts.dict import DictPromptTemplate
+from coco_core.prompts.image import ImagePromptTemplate
+from coco_core.prompts.message import (
+    BaseMessagePromptTemplate,
+)
+from coco_core.prompts.prompt import PromptTemplate
+from coco_core.prompts.string import (
+    PromptTemplateFormat,
+    StringPromptTemplate,
+    get_template_variables,
+)
+from coco_core.utils import get_colored_text
+from coco_core.utils.interactive_env import is_interactive_env
+
+
+class MessagesPlaceholder(BaseMessagePromptTemplate):
+    """Prompt template that assumes variable is already list of messages.
+
+    A placeholder which can be used to pass in a list of messages.
+
+    !!! example "Direct usage"
+
+        ```python
+        from coco_core.prompts import MessagesPlaceholder
+
+        prompt = MessagesPlaceholder("history")
+        prompt.format_messages()  # raises KeyError
+
+        prompt = MessagesPlaceholder("history", optional=True)
+        prompt.format_messages()  # returns empty list []
+
+        prompt.format_messages(
+            history=[
+                ("system", "You are an AI assistant."),
+                ("human", "Hello!"),
+            ]
+        )
+        # -> [
+        #     SystemMessage(content="You are an AI assistant."),
+        #     HumanMessage(content="Hello!"),
+        # ]
+        ```
+
+    !!! example "Building a prompt with chat history"
+
+        ```python
+        from coco_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+
+        prompt = ChatPromptTemplate.from_messages(
+            [
+                ("system", "You are a helpful assistant."),
+                MessagesPlaceholder("history"),
+                ("human", "{question}"),
+            ]
+        )
+        prompt.invoke(
+            {
+                "history": [("human", "what's 5 + 2"), ("ai", "5 + 2 is 7")],
+                "question": "now multiply that by 4",
+            }
+        )
+        # -> ChatPromptValue(messages=[
+        #     SystemMessage(content="You are a helpful assistant."),
+        #     HumanMessage(content="what's 5 + 2"),
+        #     AIMessage(content="5 + 2 is 7"),
+        #     HumanMessage(content="now multiply that by 4"),
+        # ])
+        ```
+
+    !!! example "Limiting the number of messages"
+
+        ```python
+        from coco_core.prompts import MessagesPlaceholder
+
+        prompt = MessagesPlaceholder("history", n_messages=1)
+
+        prompt.format_messages(
+            history=[
+                ("system", "You are an AI assistant."),
+                ("human", "Hello!"),
+            ]
+        )
+        # -> [
+        #     HumanMessage(content="Hello!"),
+        # ]
+        ```
+    """
+
+    variable_name: str
+    """Name of variable to use as messages."""
+
+    optional: bool = False
+    """Whether `format_messages` must be provided.
+
+    If `True` `format_messages` can be called with no arguments and will return an empty
+    list.
+
+    If `False` then a named argument with name `variable_name` must be passed in, even
+    if the value is an empty list.
+    """
+
+    n_messages: PositiveInt | None = None
+    """Maximum number of messages to include.
+
+    If `None`, then will include all.
+    """
+
+    def __init__(
+        self, variable_name: str, *, optional: bool = False, **kwargs: Any
+    ) -> None:
+        """Create a messages placeholder.
+
+        Args:
+            variable_name: Name of variable to use as messages.
+            optional: Whether `format_messages` must be provided.
+
+                If `True` format_messages can be called with no arguments and will
+                return an empty list.
+
+                If `False` then a named argument with name `variable_name` must be
+                passed in, even if the value is an empty list.
+        """
+        # mypy can't detect the init which is defined in the parent class
+        # b/c these are BaseModel classes.
+        super().__init__(variable_name=variable_name, optional=optional, **kwargs)  # type: ignore[call-arg,unused-ignore]
+
+    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Format messages from kwargs.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            List of `BaseMessage` objects.
+
+        Raises:
+            ValueError: If variable is not a list of messages.
+        """
+        value = (
+            kwargs.get(self.variable_name, [])
+            if self.optional
+            else kwargs[self.variable_name]
+        )
+        if not isinstance(value, list):
+            msg = (
+                f"variable {self.variable_name} should be a list of base messages, "
+                f"got {value} of type {type(value)}"
+            )
+            raise ValueError(msg)  # noqa: TRY004
+        value = convert_to_messages(value)
+        if self.n_messages:
+            value = value[-self.n_messages :]
+        return value
+
+    @property
+    def input_variables(self) -> list[str]:
+        """Input variables for this prompt template.
+
+        Returns:
+            List of input variable names.
+        """
+        return [self.variable_name] if not self.optional else []
+
+    @override
+    def pretty_repr(self, html: bool = False) -> str:
+        """Human-readable representation.
+
+        Args:
+            html: Whether to format as HTML.
+
+        Returns:
+            Human-readable representation.
+        """
+        var = "{" + self.variable_name + "}"
+        if html:
+            title = get_msg_title_repr("Messages Placeholder", bold=True)
+            var = get_colored_text(var, "yellow")
+        else:
+            title = get_msg_title_repr("Messages Placeholder")
+        return f"{title}\n\n{var}"
+
+
+MessagePromptTemplateT = TypeVar(
+    "MessagePromptTemplateT", bound="BaseStringMessagePromptTemplate"
+)
+"""Type variable for message prompt templates."""
+
+
+class BaseStringMessagePromptTemplate(BaseMessagePromptTemplate, ABC):
+    """Base class for message prompt templates that use a string prompt template."""
+
+    prompt: StringPromptTemplate
+    """String prompt template."""
+
+    additional_kwargs: dict[str, Any] = Field(default_factory=dict)
+    """Additional keyword arguments to pass to the prompt template."""
+
+    @classmethod
+    def from_template(
+        cls,
+        template: str,
+        template_format: PromptTemplateFormat = "f-string",
+        partial_variables: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Self:
+        """Create a class from a string template.
+
+        Args:
+            template: a template.
+            template_format: format of the template.
+            partial_variables: A dictionary of variables that can be used to partially
+                fill in the template.
+
+                For example, if the template is `"{variable1} {variable2}"`, and
+                `partial_variables` is `{"variable1": "foo"}`, then the final prompt
+                will be `"foo {variable2}"`.
+
+            **kwargs: Keyword arguments to pass to the constructor.
+
+        Returns:
+            A new instance of this class.
+        """
+        prompt = PromptTemplate.from_template(
+            template,
+            template_format=template_format,
+            partial_variables=partial_variables,
+        )
+        return cls(prompt=prompt, **kwargs)
+
+    @classmethod
+    def from_template_file(
+        cls,
+        template_file: str | Path,
+        **kwargs: Any,
+    ) -> Self:
+        """Create a class from a template file.
+
+        Args:
+            template_file: path to a template file.
+            **kwargs: Keyword arguments to pass to the constructor.
+
+        Returns:
+            A new instance of this class.
+        """
+        prompt = PromptTemplate.from_file(template_file)
+        return cls(prompt=prompt, **kwargs)
+
+    @abstractmethod
+    def format(self, **kwargs: Any) -> BaseMessage:
+        """Format the prompt template.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            Formatted message.
+        """
+
+    async def aformat(self, **kwargs: Any) -> BaseMessage:
+        """Async format the prompt template.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            Formatted message.
+        """
+        return self.format(**kwargs)
+
+    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Format messages from kwargs.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            List of `BaseMessage` objects.
+        """
+        return [self.format(**kwargs)]
+
+    async def aformat_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Async format messages from kwargs.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            List of `BaseMessage` objects.
+        """
+        return [await self.aformat(**kwargs)]
+
+    @property
+    def input_variables(self) -> list[str]:
+        """Input variables for this prompt template.
+
+        Returns:
+            List of input variable names.
+        """
+        return self.prompt.input_variables
+
+    @override
+    def pretty_repr(self, html: bool = False) -> str:
+        """Human-readable representation.
+
+        Args:
+            html: Whether to format as HTML.
+
+        Returns:
+            Human-readable representation.
+        """
+        # TODO: Handle partials
+        title = self.__class__.__name__.replace("MessagePromptTemplate", " Message")
+        title = get_msg_title_repr(title, bold=html)
+        return f"{title}\n\n{self.prompt.pretty_repr(html=html)}"
+
+
+class ChatMessagePromptTemplate(BaseStringMessagePromptTemplate):
+    """Chat message prompt template."""
+
+    role: str
+    """Role of the message."""
+
+    def format(self, **kwargs: Any) -> BaseMessage:
+        """Format the prompt template.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            Formatted message.
+        """
+        text = self.prompt.format(**kwargs)
+        return ChatMessage(
+            content=text, role=self.role, additional_kwargs=self.additional_kwargs
+        )
+
+    async def aformat(self, **kwargs: Any) -> BaseMessage:
+        """Async format the prompt template.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            Formatted message.
+        """
+        text = await self.prompt.aformat(**kwargs)
+        return ChatMessage(
+            content=text, role=self.role, additional_kwargs=self.additional_kwargs
+        )
+
+
+class _TextTemplateParam(TypedDict, total=False):
+    text: str | dict[str, Any]
+
+
+class _ImageTemplateParam(TypedDict, total=False):
+    image_url: str | dict[str, Any]
+
+
+class _StringImageMessagePromptTemplate(BaseMessagePromptTemplate):
+    """Human message prompt template. This is a message sent from the user."""
+
+    prompt: (
+        StringPromptTemplate
+        | list[StringPromptTemplate | ImagePromptTemplate | DictPromptTemplate]
+    )
+    """Prompt template."""
+    additional_kwargs: dict[str, Any] = Field(default_factory=dict)
+    """Additional keyword arguments to pass to the prompt template."""
+
+    _msg_class: type[BaseMessage]
+
+    @classmethod
+    def from_template(
+        cls: type[Self],
+        template: str
+        | Sequence[str | _TextTemplateParam | _ImageTemplateParam | dict[str, Any]],
+        template_format: PromptTemplateFormat = "f-string",
+        *,
+        partial_variables: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Self:
+        """Create a class from a string template.
+
+        Args:
+            template: a template.
+            template_format: format of the template.
+
+                Options are: `'f-string'`, `'mustache'`, `'jinja2'`.
+            partial_variables: A dictionary of variables that can be used too partially.
+
+            **kwargs: Keyword arguments to pass to the constructor.
+
+        Returns:
+            A new instance of this class.
+
+        Raises:
+            ValueError: If the template is not a string or list of strings.
+        """
+        prompt: (
+            StringPromptTemplate
+            | list[StringPromptTemplate | ImagePromptTemplate | DictPromptTemplate]
+        )
+        if isinstance(template, str):
+            prompt = PromptTemplate.from_template(
+                template,
+                template_format=template_format,
+                partial_variables=partial_variables,
+            )
+            return cls(prompt=prompt, **kwargs)
+        if isinstance(template, Sequence):
+            if (partial_variables is not None) and len(partial_variables) > 0:
+                msg = "Partial variables are not supported for list of templates."
+                raise ValueError(msg)
+            prompt = []
+            for tmpl in template:
+                if isinstance(tmpl, str) or (
+                    isinstance(tmpl, dict)
+                    and "text" in tmpl
+                    and set(tmpl.keys()) <= {"type", "text"}
+                ):
+                    if isinstance(tmpl, str):
+                        text: str = tmpl
+                    else:
+                        text = cast("_TextTemplateParam", tmpl)["text"]  # type: ignore[assignment]
+                    prompt.append(
+                        PromptTemplate.from_template(
+                            text, template_format=template_format
+                        )
+                    )
+                elif (
+                    isinstance(tmpl, dict)
+                    and "image_url" in tmpl
+                    and set(tmpl.keys())
+                    <= {
+                        "type",
+                        "image_url",
+                    }
+                ):
+                    img_template = cast("_ImageTemplateParam", tmpl)["image_url"]
+                    input_variables = []
+                    if isinstance(img_template, str):
+                        variables = get_template_variables(
+                            img_template, template_format
+                        )
+                        if variables:
+                            if len(variables) > 1:
+                                msg = (
+                                    "Only one format variable allowed per image"
+                                    f" template.\nGot: {variables}"
+                                    f"\nFrom: {tmpl}"
+                                )
+                                raise ValueError(msg)
+                            input_variables = [variables[0]]
+                        img_template = {"url": img_template}
+                        img_template_obj = ImagePromptTemplate(
+                            input_variables=input_variables,
+                            template=img_template,
+                            template_format=template_format,
+                        )
+                    elif isinstance(img_template, dict):
+                        img_template = dict(img_template)
+                        for key in ["url", "path", "detail"]:
+                            if key in img_template:
+                                input_variables.extend(
+                                    get_template_variables(
+                                        img_template[key], template_format
+                                    )
+                                )
+                        img_template_obj = ImagePromptTemplate(
+                            input_variables=input_variables,
+                            template=img_template,
+                            template_format=template_format,
+                        )
+                    else:
+                        msg = f"Invalid image template: {tmpl}"  # type: ignore[unreachable]
+                        raise ValueError(msg)
+                    prompt.append(img_template_obj)
+                elif isinstance(tmpl, dict):
+                    if template_format == "jinja2":
+                        msg = (
+                            "jinja2 is unsafe and is not supported for templates "
+                            "expressed as dicts. Please use 'f-string' or 'mustache' "
+                            "format."
+                        )
+                        raise ValueError(msg)
+                    data_template_obj = DictPromptTemplate(
+                        template=cast("dict[str, Any]", tmpl),
+                        template_format=template_format,
+                    )
+                    prompt.append(data_template_obj)
+                else:
+                    msg = f"Invalid template: {tmpl}"  # type: ignore[unreachable]
+                    raise ValueError(msg)
+            return cls(prompt=prompt, **kwargs)
+        msg = f"Invalid template: {template}"  # type: ignore[unreachable]
+        raise ValueError(msg)
+
+    @classmethod
+    def from_template_file(
+        cls: type[Self],
+        template_file: str | Path,
+        input_variables: list[str],
+        **kwargs: Any,
+    ) -> Self:
+        """Create a class from a template file.
+
+        Args:
+            template_file: path to a template file.
+            input_variables: list of input variables.
+            **kwargs: Keyword arguments to pass to the constructor.
+
+        Returns:
+            A new instance of this class.
+        """
+        template = Path(template_file).read_text(encoding="utf-8")
+        return cls.from_template(template, input_variables=input_variables, **kwargs)
+
+    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Format messages from kwargs.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            List of `BaseMessage` objects.
+        """
+        return [self.format(**kwargs)]
+
+    async def aformat_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Async format messages from kwargs.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            List of `BaseMessage` objects.
+        """
+        return [await self.aformat(**kwargs)]
+
+    @property
+    def input_variables(self) -> list[str]:
+        """Input variables for this prompt template.
+
+        Returns:
+            List of input variable names.
+        """
+        prompts = self.prompt if isinstance(self.prompt, list) else [self.prompt]
+        return [iv for prompt in prompts for iv in prompt.input_variables]
+
+    def format(self, **kwargs: Any) -> BaseMessage:
+        """Format the prompt template.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            Formatted message.
+        """
+        if isinstance(self.prompt, StringPromptTemplate):
+            text = self.prompt.format(**kwargs)
+            return self._msg_class(
+                content=text, additional_kwargs=self.additional_kwargs
+            )
+        content: list[str | dict[str, Any]] = []
+        for prompt in self.prompt:
+            inputs = {var: kwargs[var] for var in prompt.input_variables}
+            if isinstance(prompt, StringPromptTemplate):
+                formatted_text = prompt.format(**inputs)
+                if formatted_text != "":
+                    content.append({"type": "text", "text": formatted_text})
+            elif isinstance(prompt, ImagePromptTemplate):
+                formatted_image = prompt.format(**inputs)
+                content.append({"type": "image_url", "image_url": formatted_image})
+            elif isinstance(prompt, DictPromptTemplate):
+                formatted_dict = prompt.format(**inputs)
+                content.append(formatted_dict)
+        return self._msg_class(
+            content=content, additional_kwargs=self.additional_kwargs
+        )
+
+    async def aformat(self, **kwargs: Any) -> BaseMessage:
+        """Async format the prompt template.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+
+        Returns:
+            Formatted message.
+        """
+        if isinstance(self.prompt, StringPromptTemplate):
+            text = await self.prompt.aformat(**kwargs)
+            return self._msg_class(
+                content=text, additional_kwargs=self.additional_kwargs
+            )
+        content: list[str | dict[str, Any]] = []
+        for prompt in self.prompt:
+            inputs = {var: kwargs[var] for var in prompt.input_variables}
+            if isinstance(prompt, StringPromptTemplate):
+                formatted_text = await prompt.aformat(**inputs)
+                if formatted_text != "":
+                    content.append({"type": "text", "text": formatted_text})
+            elif isinstance(prompt, ImagePromptTemplate):
+                formatted_image = await prompt.aformat(**inputs)
+                content.append({"type": "image_url", "image_url": formatted_image})
+            elif isinstance(prompt, DictPromptTemplate):
+                formatted_dict = prompt.format(**inputs)
+                content.append(formatted_dict)
+        return self._msg_class(
+            content=content, additional_kwargs=self.additional_kwargs
+        )
+
+    @override
+    def pretty_repr(self, html: bool = False) -> str:
+        """Human-readable representation.
+
+        Args:
+            html: Whether to format as HTML.
+
+        Returns:
+            Human-readable representation.
+        """
+        # TODO: Handle partials
+        title = self.__class__.__name__.replace("MessagePromptTemplate", " Message")
+        title = get_msg_title_repr(title, bold=html)
+        prompts = self.prompt if isinstance(self.prompt, list) else [self.prompt]
+        prompt_reprs = "\n\n".join(prompt.pretty_repr(html=html) for prompt in prompts)
+        return f"{title}\n\n{prompt_reprs}"
+
+
+class HumanMessagePromptTemplate(_StringImageMessagePromptTemplate):
+    """Human message prompt template.
+
+    This is a message sent from the user.
+    """
+
+    _msg_class: type[BaseMessage] = HumanMessage
+
+
+class AIMessagePromptTemplate(_StringImageMessagePromptTemplate):
+    """AI message prompt template.
+
+    This is a message sent from the AI.
+    """
+
+    _msg_class: type[BaseMessage] = AIMessage
+
+
+class SystemMessagePromptTemplate(_StringImageMessagePromptTemplate):
+    """System message prompt template.
+
+    This is a message that is not sent to the user.
+    """
+
+    _msg_class: type[BaseMessage] = SystemMessage
+
+
+class BaseChatPromptTemplate(BasePromptTemplate[str], ABC):
+    """Base class for chat prompt templates."""
+
+    @property
+    @override
+    def lc_attributes(self) -> dict[str, Any]:
+        return {"input_variables": self.input_variables}
+
+    def format(self, **kwargs: Any) -> str:
+        """Format the chat template into a string.
+
+        Args:
+            **kwargs: Keyword arguments to use for filling in template variables in all
+                the template messages in this chat template.
+
+        Returns:
+            Formatted string.
+        """
+        return self.format_prompt(**kwargs).to_string()
+
+    async def aformat(self, **kwargs: Any) -> str:
+        """Async format the chat template into a string.
+
+        Args:
+            **kwargs: Keyword arguments to use for filling in template variables in all
+                the template messages in this chat template.
+
+        Returns:
+            Formatted string.
+        """
+        return (await self.aformat_prompt(**kwargs)).to_string()
+
+    def format_prompt(self, **kwargs: Any) -> ChatPromptValue:
+        """Format prompt.
+
+        Should return a `ChatPromptValue`.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+        """
+        messages = self.format_messages(**kwargs)
+        return ChatPromptValue(messages=messages)
+
+    async def aformat_prompt(self, **kwargs: Any) -> ChatPromptValue:
+        """Async format prompt.
+
+        Should return a `ChatPromptValue`.
+
+        Args:
+            **kwargs: Keyword arguments to use for formatting.
+        """
+        messages = await self.aformat_messages(**kwargs)
+        return ChatPromptValue(messages=messages)
+
+    @abstractmethod
+    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Format kwargs into a list of messages.
+
+        Returns:
+            List of `BaseMessage` objects.
+        """
+
+    async def aformat_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Async format kwargs into a list of messages.
+
+        Returns:
+            List of `BaseMessage` objects.
+        """
+        return self.format_messages(**kwargs)
+
+    def pretty_repr(
+        self,
+        html: bool = False,  # noqa: FBT001,FBT002
+    ) -> str:
+        """Human-readable representation.
+
+        Args:
+            html: Whether to format as HTML.
+
+        Returns:
+            Human-readable representation.
+        """
+        raise NotImplementedError
+
+    def pretty_print(self) -> None:
+        """Print a human-readable representation."""
+        print(self.pretty_repr(html=is_interactive_env()))  # noqa: T201
+
+
+MessageLike = BaseMessagePromptTemplate | BaseMessage | BaseChatPromptTemplate
+
+MessageLikeRepresentation = (
+    MessageLike
+    | tuple[str | type, str | Sequence[dict[str, Any]] | Sequence[object]]
+    | str
+    | dict[str, Any]
+)
+
+
+class ChatPromptTemplate(BaseChatPromptTemplate):
+    """Prompt template for chat models.
+
+    Use to create flexible templated prompts for chat models.
+
+    !!! example
+
+        ```python
+        from coco_core.prompts import ChatPromptTemplate
+
+        template = ChatPromptTemplate(
+            [
+                ("system", "You are a helpful AI bot. Your name is {name}."),
+                ("human", "Hello, how are you doing?"),
+                ("ai", "I'm doing well, thanks!"),
+                ("human", "{user_input}"),
+            ]
+        )
+
+        prompt_value = template.invoke(
+            {
+                "name": "Bob",
+                "user_input": "What is your name?",
+            }
+        )
+        # Output:
+        # ChatPromptValue(
+        #    messages=[
+        #        SystemMessage(content='You are a helpful AI bot. Your name is Bob.'),
+        #        HumanMessage(content='Hello, how are you doing?'),
+        #        AIMessage(content="I'm doing well, thanks!"),
+        #        HumanMessage(content='What is your name?')
+        #    ]
+        # )
+        ```
+
+    !!! note "Messages Placeholder"
+
+        ```python
+        # In addition to Human/AI/Tool/Function messages,
+        # you can initialize the template with a MessagesPlaceholder
+        # either using the class directly or with the shorthand tuple syntax:
+
+        template = ChatPromptTemplate(
+            [
+                ("system", "You are a helpful AI bot."),
+                # Means the template will receive an optional list of messages under
+                # the "conversation" key
+                ("placeholder", "{conversation}"),
+                # Equivalently:
+                # MessagesPlaceholder(variable_name="conversation", optional=True)
+            ]
+        )
+
+        prompt_value = template.invoke(
+            {
+                "conversation": [
+                    ("human", "Hi!"),
+                    ("ai", "How can I assist you today?"),
+                    ("human", "Can you make me an ice cream sundae?"),
+                    ("ai", "No."),
+                ]
+            }
+        )
+
+        # Output:
+        # ChatPromptValue(
+        #    messages=[
+        #        SystemMessage(content='You are a helpful AI bot.'),
+        #        HumanMessage(content='Hi!'),
+        #        AIMessage(content='How can I assist you today?'),
+        #        HumanMessage(content='Can you make me an ice cream sundae?'),
+        #        AIMessage(content='No.'),
+        #    ]
+        # )
+        ```
+
+    !!! note "Single-variable template"
+
+        If your prompt has only a single input variable (i.e., one instance of
+        `'{variable_nams}'`), and you invoke the template with a non-dict object, the
+        prompt template will inject the provided argument into that variable location.
+
+        ```python
+        from coco_core.prompts import ChatPromptTemplate
+
+        template = ChatPromptTemplate(
+            [
+                ("system", "You are a helpful AI bot. Your name is Carl."),
+                ("human", "{user_input}"),
+            ]
+        )
+
+        prompt_value = template.invoke("Hello, there!")
+        # Equivalent to
+        # prompt_value = template.invoke({"user_input": "Hello, there!"})
+
+        # Output:
+        #  ChatPromptValue(
+        #     messages=[
+        #         SystemMessage(content='You are a helpful AI bot. Your name is Carl.'),
+        #         HumanMessage(content='Hello, there!'),
+        #     ]
+        # )
+        ```
+    """
+
+    messages: Annotated[list[MessageLike], SkipValidation()]
+    """List of messages consisting of either message prompt templates or messages."""
+
+    validate_template: bool = False
+    """Whether or not to try validating the template."""
+
+    def __init__(
+        self,
+        messages: Sequence[MessageLikeRepresentation],
+        *,
+        template_format: PromptTemplateFormat = "f-string",
+        **kwargs: Any,
+    ) -> None:
+        """Create a chat prompt template from a variety of message formats.
+
+        Args:
+            messages: Sequence of message representations.
+
+                A message can be represented using the following formats:
+
+                1. `BaseMessagePromptTemplate`
+                2. `BaseMessage`
+                3. 2-tuple of `(message type, template)`; e.g.,
+                    `('human', '{user_input}')`
+                4. 2-tuple of `(message class, template)`
+                5. A string which is shorthand for `('human', template)`; e.g.,
+                    `'{user_input}'`
+            template_format: Format of the template.
+            **kwargs: Additional keyword arguments passed to `BasePromptTemplate`,
+                including (but not limited to):
+
+                - `input_variables`: A list of the names of the variables whose values
+                    are required as inputs to the prompt.
+                - `optional_variables`: A list of the names of the variables for
+                    placeholder or `MessagePlaceholder` that are optional.
+
+                    These variables are auto inferred from the prompt and user need not
+                    provide them.
+
+                - `partial_variables`: A dictionary of the partial variables the prompt
+                    template carries.
+
+                    Partial variables populate the template so that you don't need to
+                    pass them in every time you call the prompt.
+
+                - `validate_template`: Whether to validate the template.
+                - `input_types`: A dictionary of the types of the variables the prompt
+                    template expects.
+
+                    If not provided, all variables are assumed to be strings.
+
+        Examples:
+            Instantiation from a list of message templates:
+
+            ```python
+            template = ChatPromptTemplate(
+                [
+                    ("human", "Hello, how are you?"),
+                    ("ai", "I'm doing well, thanks!"),
+                    ("human", "That's good to hear."),
+                ]
+            )
+            ```
+
+            Instantiation from mixed message formats:
+
+            ```python
+            template = ChatPromptTemplate(
+                [
+                    SystemMessage(content="hello"),
+                    ("human", "Hello, how are you?"),
+                ]
+            )
+            ```
+        """
+        messages_ = [
+            _convert_to_message_template(message, template_format)
+            for message in messages
+        ]
+
+        # Automatically infer input variables from messages
+        input_vars: set[str] = set()
+        optional_variables: set[str] = set()
+        partial_vars: dict[str, Any] = {}
+        for message in messages_:
+            if isinstance(message, MessagesPlaceholder) and message.optional:
+                partial_vars[message.variable_name] = []
+                optional_variables.add(message.variable_name)
+            elif isinstance(
+                message, (BaseChatPromptTemplate, BaseMessagePromptTemplate)
+            ):
+                input_vars.update(message.input_variables)
+
+        kwargs = {
+            "input_variables": sorted(input_vars),
+            "optional_variables": sorted(optional_variables),
+            "partial_variables": partial_vars,
+            **kwargs,
+        }
+        cast("type[ChatPromptTemplate]", super()).__init__(messages=messages_, **kwargs)
+
+    @classmethod
+    def get_lc_namespace(cls) -> list[str]:
+        """Get the namespace of the Coco object.
+
+        Returns:
+            `["coco", "prompts", "chat"]`
+        """
+        return ["coco", "prompts", "chat"]
+
+    def __add__(self, other: Any) -> ChatPromptTemplate:
+        """Combine two prompt templates.
+
+        Args:
+            other: Another prompt template.
+
+        Returns:
+            Combined prompt template.
+        """
+        partials = {**self.partial_variables}
+
+        # Need to check that other has partial variables since it may not be
+        # a ChatPromptTemplate.
+        if hasattr(other, "partial_variables") and other.partial_variables:
+            partials.update(other.partial_variables)
+
+        # Allow for easy combining
+        if isinstance(other, ChatPromptTemplate):
+            return ChatPromptTemplate(messages=self.messages + other.messages).partial(
+                **partials
+            )
+        if isinstance(
+            other, (BaseMessagePromptTemplate, BaseMessage, BaseChatPromptTemplate)
+        ):
+            return ChatPromptTemplate(messages=[*self.messages, other]).partial(
+                **partials
+            )
+        if isinstance(other, (list, tuple)):
+            other_ = ChatPromptTemplate.from_messages(other)
+            return ChatPromptTemplate(messages=self.messages + other_.messages).partial(
+                **partials
+            )
+        if isinstance(other, str):
+            prompt = HumanMessagePromptTemplate.from_template(other)
+            return ChatPromptTemplate(messages=[*self.messages, prompt]).partial(
+                **partials
+            )
+        msg = f"Unsupported operand type for +: {type(other)}"
+        raise NotImplementedError(msg)
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_input_variables(cls, values: dict[str, Any]) -> Any:
+        """Validate input variables.
+
+        If `input_variables` is not set, it will be set to the union of all input
+        variables in the messages.
+
+        Args:
+            values: values to validate.
+
+        Returns:
+            Validated values.
+
+        Raises:
+            ValueError: If input variables do not match.
+        """
+        messages = values["messages"]
+        input_vars: set[str] = set()
+        optional_variables = set()
+        input_types: dict[str, Any] = values.get("input_types", {})
+        for message in messages:
+            if isinstance(message, (BaseMessagePromptTemplate, BaseChatPromptTemplate)):
+                input_vars.update(message.input_variables)
+            if isinstance(message, MessagesPlaceholder):
+                if "partial_variables" not in values:
+                    values["partial_variables"] = {}
+                if (
+                    message.optional
+                    and message.variable_name not in values["partial_variables"]
+                ):
+                    values["partial_variables"][message.variable_name] = []
+                    optional_variables.add(message.variable_name)
+                if message.variable_name not in input_types:
+                    input_types[message.variable_name] = list[AnyMessage]
+        if "partial_variables" in values:
+            input_vars -= set(values["partial_variables"])
+        if optional_variables:
+            input_vars -= optional_variables
+        if "input_variables" in values and values.get("validate_template"):
+            if input_vars != set(values["input_variables"]):
+                msg = (
+                    "Got mismatched input_variables. "
+                    f"Expected: {input_vars}. "
+                    f"Got: {values['input_variables']}"
+                )
+                raise ValueError(msg)
+        else:
+            values["input_variables"] = sorted(input_vars)
+        if optional_variables:
+            values["optional_variables"] = sorted(optional_variables)
+        values["input_types"] = input_types
+        return values
+
+    @classmethod
+    def from_template(cls, template: str, **kwargs: Any) -> ChatPromptTemplate:
+        """Create a chat prompt template from a template string.
+
+        Creates a chat template consisting of a single message assumed to be from the
+        human.
+
+        Args:
+            template: Template string
+            **kwargs: Keyword arguments to pass to the constructor.
+
+        Returns:
+            A new instance of this class.
+        """
+        prompt_template = PromptTemplate.from_template(template, **kwargs)
+        message = HumanMessagePromptTemplate(prompt=prompt_template)
+        return cls.from_messages([message])
+
+    @classmethod
+    def from_messages(
+        cls,
+        messages: Sequence[MessageLikeRepresentation],
+        template_format: PromptTemplateFormat = "f-string",
+    ) -> ChatPromptTemplate:
+        """Create a chat prompt template from a variety of message formats.
+
+        Examples:
+            Instantiation from a list of message templates:
+
+            ```python
+            template = ChatPromptTemplate.from_messages(
+                [
+                    ("human", "Hello, how are you?"),
+                    ("ai", "I'm doing well, thanks!"),
+                    ("human", "That's good to hear."),
+                ]
+            )
+            ```
+
+            Instantiation from mixed message formats:
+
+            ```python
+            template = ChatPromptTemplate.from_messages(
+                [
+                    SystemMessage(content="hello"),
+                    ("human", "Hello, how are you?"),
+                ]
+            )
+            ```
+        Args:
+            messages: Sequence of message representations.
+
+                A message can be represented using the following formats:
+
+                1. `BaseMessagePromptTemplate`
+                2. `BaseMessage`
+                3. 2-tuple of `(message type, template)`; e.g.,
+                    `('human', '{user_input}')`
+                4. 2-tuple of `(message class, template)`
+                5. A string which is shorthand for `('human', template)`; e.g.,
+                    `'{user_input}'`
+            template_format: Format of the template.
+
+        Returns:
+            A chat prompt template.
+
+        """
+        return cls(messages, template_format=template_format)
+
+    def format_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Format the chat template into a list of finalized messages.
+
+        Args:
+            **kwargs: Keyword arguments to use for filling in template variables
+                in all the template messages in this chat template.
+
+        Raises:
+            ValueError: If messages are of unexpected types.
+
+        Returns:
+            List of formatted messages.
+        """
+        kwargs = self._merge_partial_and_user_variables(**kwargs)
+        result = []
+        for message_template in self.messages:
+            if isinstance(message_template, BaseMessage):
+                result.extend([message_template])
+            elif isinstance(
+                message_template, (BaseMessagePromptTemplate, BaseChatPromptTemplate)
+            ):
+                message = message_template.format_messages(**kwargs)
+                result.extend(message)
+            else:
+                msg = f"Unexpected input: {message_template}"  # type: ignore[unreachable]
+                raise ValueError(msg)  # noqa: TRY004
+        return result
+
+    async def aformat_messages(self, **kwargs: Any) -> list[BaseMessage]:
+        """Async format the chat template into a list of finalized messages.
+
+        Args:
+            **kwargs: Keyword arguments to use for filling in template variables
+                in all the template messages in this chat template.
+
+        Returns:
+            List of formatted messages.
+
+        Raises:
+            ValueError: If unexpected input.
+        """
+        kwargs = self._merge_partial_and_user_variables(**kwargs)
+        result = []
+        for message_template in self.messages:
+            if isinstance(message_template, BaseMessage):
+                result.extend([message_template])
+            elif isinstance(
+                message_template, (BaseMessagePromptTemplate, BaseChatPromptTemplate)
+            ):
+                message = await message_template.aformat_messages(**kwargs)
+                result.extend(message)
+            else:
+                msg = f"Unexpected input: {message_template}"  # type: ignore[unreachable]
+                raise ValueError(msg)  # noqa:TRY004
+        return result
+
+    def partial(self, **kwargs: Any) -> ChatPromptTemplate:
+        """Get a new `ChatPromptTemplate` with some input variables already filled in.
+
+        Args:
+            **kwargs: Keyword arguments to use for filling in template variables.
+
+                Ought to be a subset of the input variables.
+
+        Returns:
+            A new `ChatPromptTemplate`.
+
+        Example:
+            ```python
+            from coco_core.prompts import ChatPromptTemplate
+
+            template = ChatPromptTemplate.from_messages(
+                [
+                    ("system", "You are an AI assistant named {name}."),
+                    ("human", "Hi I'm {user}"),
+                    ("ai", "Hi there, {user}, I'm {name}."),
+                    ("human", "{input}"),
+                ]
+            )
+            template2 = template.partial(user="Lucy", name="R2D2")
+
+            template2.format_messages(input="hello")
+            ```
+        """
+        prompt_dict = self.__dict__.copy()
+        prompt_dict["input_variables"] = list(
+            set(self.input_variables).difference(kwargs)
+        )
+        prompt_dict["partial_variables"] = {**self.partial_variables, **kwargs}
+        return type(self)(**prompt_dict)
+
+    def append(self, message: MessageLikeRepresentation) -> None:
+        """Append a message to the end of the chat template.
+
+        Args:
+            message: representation of a message to append.
+        """
+        self.messages.append(_convert_to_message_template(message))
+
+    def extend(self, messages: Sequence[MessageLikeRepresentation]) -> None:
+        """Extend the chat template with a sequence of messages.
+
+        Args:
+            messages: Sequence of message representations to append.
+        """
+        self.messages.extend(
+            [_convert_to_message_template(message) for message in messages]
+        )
+
+    @overload
+    def __getitem__(self, index: int) -> MessageLike: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> ChatPromptTemplate: ...
+
+    def __getitem__(self, index: int | slice) -> MessageLike | ChatPromptTemplate:
+        """Use to index into the chat template.
+
+        Returns:
+            If index is an int, returns the message at that index.
+
+            If index is a slice, returns a new `ChatPromptTemplate` containing the
+                messages in that slice.
+        """
+        if isinstance(index, slice):
+            start, stop, step = index.indices(len(self.messages))
+            messages = self.messages[start:stop:step]
+            return ChatPromptTemplate.from_messages(messages)
+        return self.messages[index]
+
+    def __len__(self) -> int:
+        """Return the length of the chat template."""
+        return len(self.messages)
+
+    @property
+    def _prompt_type(self) -> str:
+        """Name of prompt type. Used for serialization."""
+        return "chat"
+
+    @deprecated(
+        since="1.2.21",
+        removal="2.0.0",
+        alternative="Use `dumpd`/`dumps` from `coco_core.load` to serialize "
+        "prompts and `load`/`loads` to deserialize them.",
+    )
+    def save(self, file_path: Path | str) -> None:
+        """Save prompt to file.
+
+        Args:
+            file_path: path to file.
+        """
+        raise NotImplementedError
+
+    @override
+    def pretty_repr(self, html: bool = False) -> str:
+        """Human-readable representation.
+
+        Args:
+            html: Whether to format as HTML.
+
+        Returns:
+            Human-readable representation.
+        """
+        # TODO: handle partials
+        return "\n\n".join(msg.pretty_repr(html=html) for msg in self.messages)
+
+
+def _create_template_from_message_type(
+    message_type: str,
+    template: str | list[str | dict[str, Any] | bool],
+    template_format: PromptTemplateFormat = "f-string",
+) -> BaseMessagePromptTemplate:
+    """Create a message prompt template from a message type and template string.
+
+    Args:
+        message_type: The type of the message template (e.g., `'human'`, `'ai'`, etc.)
+        template: The template string.
+        template_format: Format of the template.
+
+    Returns:
+        A message prompt template of the appropriate type.
+
+    Raises:
+        ValueError: If unexpected message type.
+    """
+    if message_type in {"human", "user"}:
+        message: BaseMessagePromptTemplate = HumanMessagePromptTemplate.from_template(
+            cast("str", template), template_format=template_format
+        )
+    elif message_type in {"ai", "assistant"}:
+        message = AIMessagePromptTemplate.from_template(
+            cast("str", template), template_format=template_format
+        )
+    elif message_type == "system":
+        message = SystemMessagePromptTemplate.from_template(
+            cast("str", template), template_format=template_format
+        )
+    elif message_type == "placeholder":
+        if isinstance(template, str):
+            if template[0] != "{" or template[-1] != "}":
+                msg = (
+                    f"Invalid placeholder template: {template}."
+                    " Expected a variable name surrounded by curly braces."
+                )
+                raise ValueError(msg)
+            var_name = template[1:-1]
+            message = MessagesPlaceholder(variable_name=var_name, optional=True)
+        else:
+            try:
+                var_name_wrapped, is_optional = template
+            except ValueError as e:
+                msg = (
+                    "Unexpected arguments for placeholder message type."
+                    " Expected either a single string variable name"
+                    " or a list of [variable_name: str, is_optional: bool]."
+                    f" Got: {template}"
+                )
+                raise ValueError(msg) from e
+
+            if not isinstance(is_optional, bool):
+                msg = f"Expected is_optional to be a boolean. Got: {is_optional}"
+                raise ValueError(msg)  # noqa: TRY004
+
+            if not isinstance(var_name_wrapped, str):
+                msg = f"Expected variable name to be a string. Got: {var_name_wrapped}"
+                raise ValueError(msg)  # noqa: TRY004
+            if var_name_wrapped[0] != "{" or var_name_wrapped[-1] != "}":
+                msg = (
+                    f"Invalid placeholder template: {var_name_wrapped}."
+                    " Expected a variable name surrounded by curly braces."
+                )
+                raise ValueError(msg)
+            var_name = var_name_wrapped[1:-1]
+
+            message = MessagesPlaceholder(variable_name=var_name, optional=is_optional)
+    else:
+        msg = (
+            f"Unexpected message type: {message_type}. Use one of 'human',"
+            f" 'user', 'ai', 'assistant', or 'system'."
+        )
+        raise ValueError(msg)
+    return message
+
+
+def _convert_to_message_template(
+    message: MessageLikeRepresentation,
+    template_format: PromptTemplateFormat = "f-string",
+) -> BaseMessage | BaseMessagePromptTemplate | BaseChatPromptTemplate:
+    """Instantiate a message from a variety of message formats.
+
+    A message can be represented using the following formats:
+
+    1. `BaseMessagePromptTemplate`
+    2. `BaseMessage`
+    3. 2-tuple of `(message type, template)`; e.g., `('human', '{user_input}')`
+    4. 2-tuple of `(message class, template)`
+    5. A string which is shorthand for `('human', template)`; e.g., `'{user_input}'`
+
+    Args:
+        message: A representation of a message in one of the supported formats.
+        template_format: Format of the template.
+
+    Returns:
+        An instance of a message or a message template.
+
+    Raises:
+        ValueError: If unexpected message type.
+        ValueError: If 2-tuple does not have 2 elements.
+    """
+    if isinstance(message, (BaseMessagePromptTemplate, BaseChatPromptTemplate)):
+        message_: BaseMessage | BaseMessagePromptTemplate | BaseChatPromptTemplate = (
+            message
+        )
+    elif isinstance(message, BaseMessage):
+        message_ = message
+    elif isinstance(message, str):
+        message_ = _create_template_from_message_type(
+            "human", message, template_format=template_format
+        )
+    elif isinstance(message, (tuple, dict)):
+        if isinstance(message, dict):
+            if set(message.keys()) != {"content", "role"}:
+                msg = (
+                    "Expected dict to have exact keys 'role' and 'content'."
+                    f" Got: {message}"
+                )
+                raise ValueError(msg)
+            message_type_str = message["role"]
+            template = message["content"]
+        else:
+            if len(message) != 2:  # noqa: PLR2004
+                msg = f"Expected 2-tuple of (role, template), got {message}"  # type: ignore[unreachable]
+                raise ValueError(msg)
+            message_type_str, template = message
+
+        if isinstance(message_type_str, str):
+            message_ = _create_template_from_message_type(
+                message_type_str, template, template_format=template_format
+            )
+        elif (
+            hasattr(message_type_str, "model_fields")
+            and "type" in message_type_str.model_fields
+        ):
+            message_type = message_type_str.model_fields["type"].default
+            message_ = _create_template_from_message_type(
+                message_type, template, template_format=template_format
+            )
+        else:
+            message_ = message_type_str(
+                prompt=PromptTemplate.from_template(
+                    cast("str", template), template_format=template_format
+                )
+            )
+    else:
+        msg = f"Unsupported message type: {type(message)}"  # type: ignore[unreachable]
+        raise NotImplementedError(msg)
+
+    return message_
+
+
+# For backwards compat:
+_convert_to_message = _convert_to_message_template