expose messages to prompt helper and finish docs for it

Author: dtam

docs/how_to_guides/using_llms.md

@@ -306,24 +306,23 @@ guard = Guard().use(ProfanityFree())
 # Function that takes the prompt as a string and returns the LLM output as string
 def my_llm_api(
     *,
-    messages: Optional[list[dict]] = None,
     **kwargs
 ) -> str:
     """Custom LLM API wrapper.
 
     At least one of messages should be provided.
 
     Args:
-        messages (list[dict]): The message history to be passed to the LLM API
         **kwargs: Any additional arguments to be passed to the LLM API
 
     Returns:
         str: The output of the LLM API
     """
-
+    messages = kwargs.pop("messages", [])
+    updated_messages = some_message_processing(messages)
     # Call your LLM API here
     # What you pass to the llm will depend on what arguments it accepts.
-    llm_output = some_llm(messages, **kwargs)
+    llm_output = some_llm(updated_messages, **kwargs)
 
     return llm_output
 

docs/migration_guides/0-6-migration.md

@@ -90,4 +90,24 @@ guard(
 These callables are being removed in favor of support through passing no callable and setting the appropriate api key and model argument. See LINK TO DOCS for more info.
 
 ### Prompt no longer a required positional argument on custom callables
-Custom callables will no longer throw an error if the prompt arg is missing in their declaration and guardrails will no longer pass prompt as the first argument. They need to be updated to the messages kwarg to get text input. If a custom callables underlying llm only accepts a single string a helper exists that can compose messages into one otherwise some code to adapt them will be required. 
+Custom callables will no longer throw an error if the prompt arg is missing in their declaration and guardrails will no longer pass prompt as the first argument. They need to be updated to the messages kwarg to get text input. If a custom callables underlying llm only accepts a single string a helper exists that can compose messages into one otherwise some code to adapt them will be required. 
+
+```py
+from guardrails import messages_to_prompt_string
+
+class CustomCallableCallable(PromptCallableBase):
+    def llm_api(
+        self,
+        *args,
+        **kwargs,
+    ) -> str:
+        messages = kwargs.pop("messages", [])
+        prompt = messages_to_prompt_string(messages)
+
+        llm_string_output = some_llm_call_requiring_prompt(
+            prompt,
+            *args,
+            **kwargs,
+        )
+        return llm_string_output
+````

guardrails/__init__.py

@@ -4,13 +4,14 @@
 from guardrails.async_guard import AsyncGuard
 from guardrails.llm_providers import PromptCallableBase
 from guardrails.logging_utils import configure_logging
-from guardrails.prompt import Instructions, Prompt
+from guardrails.prompt import Instructions, Prompt, Messages
 from guardrails.utils import constants, docs_utils
 from guardrails.types.on_fail import OnFailAction
 from guardrails.validator_base import Validator, register_validator
 from guardrails.settings import settings
 from guardrails.hub.install import install
 from guardrails.classes.validation_outcome import ValidationOutcome
+from guardrails.utils.prompt_utils import messages_to_prompt_string
 
 __all__ = [
     "Guard",
@@ -22,8 +23,10 @@
     "constants",
     "docs_utils",
     "configure_logging",
+    "messages_to_prompt_string",
     "Prompt",
     "Instructions",
+    "Messages",
     "settings",
     "install",
     "ValidationOutcome",

guardrails/llm_providers.py

@@ -31,22 +31,7 @@
 from guardrails.utils.safe_get import safe_get
 from guardrails.telemetry import trace_llm_call, trace_operation
 
-
-# todo fix circular import
-def messages_string(
-    messages: Union[list[dict[str, Union[str, Prompt, Instructions]]], MessageHistory],
-) -> str:
-    messages_copy = ""
-    for msg in messages:
-        content = (
-            msg["content"].source  # type: ignore
-            if isinstance(msg["content"], Prompt)
-            or isinstance(msg["content"], Instructions)  # type: ignore
-            else msg["content"]  # type: ignore
-        )
-        messages_copy += content
-    return messages_copy
-
+from guardrails.utils.prompt_utils import messages_to_prompt_string
 
 ###
 # Synchronous wrappers
@@ -296,7 +281,7 @@ def _invoke_llm(
                 "The `torch` package is not installed. "
                 "Install with `pip install torch`"
             )
-        prompt = messages_string(messages)
+        prompt = messages_to_prompt_string(messages)
         tokenizer = kwargs.pop("tokenizer")
         if not tokenizer:
             raise UserFacingException(
@@ -408,7 +393,7 @@ def _invoke_llm(
         temperature = kwargs.pop("temperature", None)
         if temperature == 0:
             temperature = None
-        prompt = messages_string(messages)
+        prompt = messages_to_prompt_string(messages)
         trace_operation(
             input_mime_type="application/json",
             input_value={

guardrails/prompt/__init__.py

@@ -1,7 +1,9 @@
 from .instructions import Instructions
 from .prompt import Prompt
+from .messages import Messages
 
 __all__ = [
     "Prompt",
     "Instructions",
+    "Messages",
 ]

guardrails/run/__init__.py

@@ -2,13 +2,12 @@
 from guardrails.run.runner import Runner
 from guardrails.run.stream_runner import StreamRunner
 from guardrails.run.async_stream_runner import AsyncStreamRunner
-from guardrails.run.utils import messages_source, messages_string
+from guardrails.run.utils import messages_source
 
 __all__ = [
     "Runner",
     "AsyncRunner",
     "StreamRunner",
     "AsyncStreamRunner",
     "messages_source",
-    "messages_string",
 ]

guardrails/run/utils.py

@@ -28,18 +28,6 @@ def messages_source(messages: MessageHistory) -> MessageHistory:
     return messages_copy
 
 
-def messages_string(messages: MessageHistory) -> str:
-    messages_copy = ""
-    for msg in messages:
-        content = (
-            msg["content"].source
-            if isinstance(msg["content"], Prompt)
-            else msg["content"]
-        )
-        messages_copy += content
-    return messages_copy
-
-
 def preprocess_prompt_for_string_output(
     prompt_callable: PromptCallableBase,
     instructions: Optional[Instructions],

guardrails/utils/docs_utils.py

@@ -1,6 +1,8 @@
 import typing as t
 
-from guardrails.prompt import Prompt
+from guardrails.prompt import Prompt, Instructions
+
+from guardrails.types.inputs import MessageHistory
 
 try:
     import tiktoken
@@ -19,6 +21,23 @@
         nltk.download("punkt")
 
 
+def messages_to_prompt_string(
+    messages: t.Union[
+        list[dict[str, t.Union[str, Prompt, Instructions]]], MessageHistory
+    ],
+) -> str:
+    messages_copy = ""
+    for msg in messages:
+        content = (
+            msg["content"].source  # type: ignore
+            if isinstance(msg["content"], Prompt)
+            or isinstance(msg["content"], Instructions)  # type: ignore
+            else msg["content"]  # type: ignore
+        )
+        messages_copy += content
+    return messages_copy
+
+
 class TextSplitter:
     """Split the docs into chunks with token boundaries."""
 

guardrails/utils/prompt_utils.py

@@ -1,10 +1,13 @@
 import json
 import re
-from typing import Any, Dict
+from typing import Any, Dict, Union
 
 from guardrails.classes.output_type import OutputTypes
 
 from guardrails.types.validator import ValidatorMap
+from guardrails.prompt.prompt import Prompt
+from guardrails.prompt.instructions import Instructions
+from guardrails.types.inputs import MessageHistory
 
 
 def prompt_uses_xml(prompt: str) -> bool:
@@ -47,3 +50,18 @@ def prompt_content_for_schema(
     if output_type == OutputTypes.STRING:
         return prompt_content_for_string_schema(output_schema, validator_map, json_path)
     return json.dumps(output_schema)
+
+
+def messages_to_prompt_string(
+    messages: Union[list[dict[str, Union[str, Prompt, Instructions]]], MessageHistory],
+) -> str:
+    messages_copy = ""
+    for msg in messages:
+        content = (
+            msg["content"].source  # type: ignore
+            if isinstance(msg["content"], Prompt)
+            or isinstance(msg["content"], Instructions)  # type: ignore
+            else msg["content"]  # type: ignore
+        )
+        messages_copy += content
+    return messages_copy