Merge pull request #635 from guardrails-ai/shreya/custom-callable-docs

Update docs for using a custom llm

Author: CalebCourier

docs/how_to_guides/llm_api_wrappers.md

@@ -1,133 +1,156 @@
-# Guard Custom LLMs
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Use Guardrails with any LLMs
 
 Guardrails' `Guard` wrappers provide a simple way to add Guardrails to your LLM API calls. The wrappers are designed to be used with any LLM API.
 
+There are three ways to use Guardrails with an LLM API:
+1. [**Natively-supported LLMs**](#natively-supported-llms): Guardrails provides out-of-the-box wrappers for OpenAI, Cohere, Anthropic and HuggingFace. If you're using any of these APIs, check out the documentation in [this](#natively-supported-llms) section.
+2. [**LLMs supported through LiteLLM**](#llms-supported-via-litellm): Guardrails provides an easy integration with [liteLLM](https://docs.litellm.ai/docs/), a lightweight abstraction over LLM APIs that supports over 100+ LLMs. If you're using an LLM that isn't natively supported by Guardrails, you can use LiteLLM to integrate it with Guardrails. Check out the documentation in [this](#llms-supported-via-litellm) section.
+3. [**Build a custom LLM wrapper**](#build-a-custom-llm-wrapper): If you're using an LLM that isn't natively supported by Guardrails and you don't want to use LiteLLM, you can build a custom LLM API wrapper. Check out the documentation in [this](#build-a-custom-llm-wrapper) section.
 
-Here are some examples of how to use the wrappers with different LLM providers and models:
 
-## OpenAI
+## Natively-supported LLMs
 
-### Completion Models (e.g. GPT-3)
+Guardrails provides native support for a select few LLMs and Manifest. If you're using any of these LLMs, you can use Guardrails' out-of-the-box wrappers to add Guardrails to your LLM API calls.
 
-```python
-import openai
-import guardrails as gd
+<Tabs>
+  <TabItem value="openai" label="OpenAI" default>
+    ```python
+    import openai
+    from guardrails import Guard
+    from guardrails.hub import ProfanityFree
 
+    # Create a Guard
+    guard = Guard().use(ProfanityFree())
 
-# Create a Guard class
-guard = gd.Guard.from_rail(...)
-
-# Wrap openai API call
-raw_llm_output, guardrail_output, *rest = guard(
-    openai.Completion.create,
-    prompt_params={"prompt_param_1": "value_1", "prompt_param_2": "value_2", ..},
-    engine="text-davinci-003",
-    max_tokens=100,
-    temperature=0.0,
-)
-```
+    # Wrap openai API call
+    validated_response = guard(
+        openai.chat.completions.create,
+        prompt="Can you generate a list of 10 things that are not food?",
+        model="gpt-3.5-turbo",
+        max_tokens=100,
+        temperature=0.0,
+    )
+    ```
+  </TabItem>
+  <TabItem value="cohere" label="Cohere">
+    ```python
+    import cohere
+    from guardrails import Guard
+    from guardrails.hub import ProfanityFree
 
-### ChatCompletion Models (e.g. ChatGPT)
+    # Create a Guard
+    guard = Guard().use(ProfanityFree())
 
-```python
-import openai
-import guardrails as gd
+    # Create a Cohere client
+    cohere_client = cohere.Client(api_key="my_api_key")
 
-# Create a Guard class
-guard = gd.Guard.from_rail(...)
-
-# Wrap openai API call
-raw_llm_output, guardrail_output, *rest = guard(
-    openai.ChatCompletion.create,
-    prompt_params={"prompt_param_1": "value_1", "prompt_param_2": "value_2", ..},
-    system_prompt="You are a helpful assistant...",
-    model="gpt-3.5-turbo",
-    max_tokens=100,
-    temperature=0.0,
-)
-```
+    # Wrap cohere API call
+    validated_response = guard(
+        cohere_client.chat,
+        prompt="Can you try to generate a list of 10 things that are not food?",
+        model="command",
+        max_tokens=100,
+        ...
+    )
+    ```
+  </TabItem>
+</Tabs>
 
-## Cohere
 
-### Generate (e.g. GPT-3)
+## LLMs supported via LiteLLM
 
-```python
-import cohere
-import guardrails as gd
+[LiteLLM](https://docs.litellm.ai/docs/) is a lightweight wrapper that unifies the interface for over 100+ LLMs. Guardrails only supports 4 LLMs natively, but you can use Guardrails with LiteLLM to support over 100+ LLMs. You can read more about the LLMs supported by LiteLLM [here](https://docs.litellm.ai/docs/providers).
 
-# Create a Guard class
-guard = gd.Guard.from_rail(...)
-
-# Create a Cohere client
-cohere_client = cohere.Client(api_key="my_api_key")
-
-# Wrap cohere API call
-raw_llm_output, guardrail_output, *rest = guard(
-    cohere_client.generate,
-    prompt_params={"prompt_param_1": "value_1", "prompt_param_2": "value_2", ..},
-    model="command-nightly",
-    max_tokens=100,
-    ...
-)
-```
+In order to use Guardrails with any of the LLMs supported through liteLLM, you need to do the following:
+1. Call the `Guard.__call__` method with `litellm.completion` as the first argument.
+2. Pass any additional litellm arguments as keyword arguments to the `Guard.__call` method.
+
+Some examples of using Guardrails with LiteLLM are shown below.
 
-## Using Manifest
-[Manifest](https://github.com/HazyResearch/manifest) is a wrapper around most model APIs and supports hosting local models. It can be used as a LLM API.
+### Use Guardrails with Ollama
 
 ```python
-import guardrails as gd
-import manifest
+import litellm
+from guardrails import Guard
+from guardrails.hub import ProfanityFree
 
 # Create a Guard class
-guard = gd.Guard.from_rail(...)
-
-# Create a Manifest client - this one points to GPT-4
-# and caches responses in SQLLite
-manifest = manifest.Manifest(
-    client_name="openai",
-    engine="gpt-4",
-    cache_name="sqlite",
-    cache_connection="my_manifest_cache.db"
+guard = Guard().use(ProfanityFree())
+
+# Call the Guard to wrap the LLM API call
+validated_response = guard(
+    litellm.completion,
+    model="ollama/llama2",
+    max_tokens=500,
+    api_base="http://localhost:11434",
+    msg_history=[{"role": "user", "content": "hello"}]
 )
+```
+
+### Use Guardrails with Azure's OpenAI endpoint
 
-# Wrap openai API call
-raw_llm_output, guardrail_output, *rest = guard(
-    manifest,
-    prompt_params={"prompt_param_1": "value_1", "prompt_param_2": "value_2", ..},
-    max_tokens=100,
-    temperature=0.0,
+```python
+import os
+
+import litellm
+from guardrails import Guard
+from guardrails.hub import ProfanityFree
+
+validated_response = guard(
+    litellm.completion,
+    model="azure/<your deployment name>",
+    max_tokens=500,
+    api_base=os.environ.get("AZURE_OPENAI_API_BASE"),
+    api_version="2023-05-15",
+    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
+    msg_history=[{"role": "user", "content": "hello"}]
 )
 ```
 
+## Build a custom LLM wrapper
 
-## Using a custom LLM API
+In case you're using an LLM that isn't natively supported by Guardrails and you don't want to use LiteLLM, you can build a custom LLM API wrapper. In order to use a custom LLM, create a function that takes accepts a prompt as a string and any other arguments that you want to pass to the LLM API as keyword args. The function should return the output of the LLM API as a string.
 
 ```python
-import guardrails as gd
+from guardrails import Guard
+from guardrails.hub import ProfanityFree
 
 # Create a Guard class
-guard = gd.Guard.from_rail(...)
+guard = Guard().use(ProfanityFree())
 
 # Function that takes the prompt as a string and returns the LLM output as string
-def my_llm_api(prompt: str, **kwargs) -> str:
+def my_llm_api(
+    prompt: Optional[str] = None,
+    instruction: Optional[str] = None,
+    msg_history: Optional[list[dict]] = None,
+    **kwargs
+) -> str:
     """Custom LLM API wrapper.
 
+    At least one of prompt, instruction or msg_history should be provided.
+
     Args:
         prompt (str): The prompt to be passed to the LLM API
+        instruction (str): The instruction to be passed to the LLM API
+        msg_history (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
     """
 
     # Call your LLM API here
-    return ...
+    llm_output = some_llm(prompt, instruction, msg_history, **kwargs)
 
+    return llm_output
 
 # Wrap your LLM API call
-raw_llm_output, guardrail_output, *rest = guard(
+validated_response = guard(
     my_llm_api,
-    prompt_params={"prompt_param_1": "value_1", "prompt_param_2": "value_2", ..},
+    prompt="Can you generate a list of 10 things that are not food?",
     **kwargs,
 )
 ```

settings.ini

@@ -7,4 +7,4 @@ doc_host = https://outerbounds.github.io
 doc_baseurl = /nbdoc-docusaurus
 module_baseurls = metaflow=https://github.com/Netflix/metaflow/tree/master/
 	fastcore=https://github.com/fastcore/tree/master
-host = github
+host = github