community: adding langchain-predictionguard partner package documentation (#28832)

- *[x] **PR title**: "community: adding langchain-predictionguard
partner package documentation"

- *[x] **PR message**:
- **Description:** This PR adds documentation for the
langchain-predictionguard package to main langchain repo, along with
deprecating current Prediction Guard LLMs package. The LLMs package was
previously broken, so I also updated it one final time to allow it to
continue working from this point onward. . This enables users to chat
with LLMs through the Prediction Guard ecosystem.
    - **Package Links**: 
        -  [PyPI](https://pypi.org/project/langchain-predictionguard/)
- [Github
Repo](https://www.github.com/predictionguard/langchain-predictionguard)
    - **Issue:** None
    - **Dependencies:** None
- **Twitter handle:** [@predictionguard](https://x.com/predictionguard)

- *[x] **Add tests and docs**: All docs have been added for the partner
package, and the current LLMs package test was updated to reflect
changes.


- *[x] **Lint and test**: Linting tests are all passing.

---------

Co-authored-by: ccurme <chester.curme@gmail.com>

libs/community/langchain_community/llms/predictionguard.py

@@ -1,90 +1,123 @@
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
+from langchain_core._api.deprecation import deprecated
 from langchain_core.callbacks import CallbackManagerForLLMRun
 from langchain_core.language_models.llms import LLM
-from langchain_core.utils import get_from_dict_or_env, pre_init
-from pydantic import ConfigDict
+from langchain_core.utils import get_from_dict_or_env
+from pydantic import BaseModel, ConfigDict, model_validator
 
 from langchain_community.llms.utils import enforce_stop_tokens
 
 logger = logging.getLogger(__name__)
 
 
+@deprecated(
+    since="0.3.28",
+    removal="1.0",
+    alternative_import="langchain_predictionguard.PredictionGuard",
+)
 class PredictionGuard(LLM):
     """Prediction Guard large language models.
 
     To use, you should have the ``predictionguard`` python package installed, and the
-    environment variable ``PREDICTIONGUARD_TOKEN`` set with your access token, or pass
-    it as a named parameter to the constructor. To use Prediction Guard's API along
-    with OpenAI models, set the environment variable ``OPENAI_API_KEY`` with your
-    OpenAI API key as well.
+    environment variable ``PREDICTIONGUARD_API_KEY`` set with your API key, or pass
+    it as a named parameter to the constructor.
 
     Example:
         .. code-block:: python
 
-            pgllm = PredictionGuard(model="MPT-7B-Instruct",
-                                    token="my-access-token",
-                                    output={
-                                        "type": "boolean"
-                                    })
+            llm = PredictionGuard(
+                model="Hermes-3-Llama-3.1-8B",
+                predictionguard_api_key="your Prediction Guard API key",
+            )
     """
 
     client: Any = None  #: :meta private:
-    model: Optional[str] = "MPT-7B-Instruct"
+
+    model: Optional[str] = "Hermes-3-Llama-3.1-8B"
     """Model name to use."""
 
-    output: Optional[Dict[str, Any]] = None
-    """The output type or structure for controlling the LLM output."""
-
-    max_tokens: int = 256
+    max_tokens: Optional[int] = 256
     """Denotes the number of tokens to predict per generation."""
 
-    temperature: float = 0.75
+    temperature: Optional[float] = 0.75
     """A non-negative float that tunes the degree of randomness in generation."""
 
-    token: Optional[str] = None
-    """Your Prediction Guard access token."""
+    top_p: Optional[float] = 0.1
+    """A non-negative float that controls the diversity of the generated tokens."""
+
+    top_k: Optional[int] = None
+    """The diversity of the generated text based on top-k sampling."""
 
     stop: Optional[List[str]] = None
 
-    model_config = ConfigDict(
-        extra="forbid",
-    )
+    predictionguard_input: Optional[Dict[str, Union[str, bool]]] = None
+    """The input check to run over the prompt before sending to the LLM."""
 
-    @pre_init
+    predictionguard_output: Optional[Dict[str, bool]] = None
+    """The output check to run the LLM output against."""
+
+    predictionguard_api_key: Optional[str] = None
+    """Prediction Guard API key."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
     def validate_environment(cls, values: Dict) -> Dict:
-        """Validate that the access token and python package exists in environment."""
-        token = get_from_dict_or_env(values, "token", "PREDICTIONGUARD_TOKEN")
-        try:
-            import predictionguard as pg
+        """Validate that the api_key and python package exists in environment."""
+        pg_api_key = get_from_dict_or_env(
+            values, "predictionguard_api_key", "PREDICTIONGUARD_API_KEY"
+        )
+
+        try:
+            from predictionguard import PredictionGuard
+
+            values["client"] = PredictionGuard(
+                api_key=pg_api_key,
+            )
 
-            values["client"] = pg.Client(token=token)
         except ImportError:
             raise ImportError(
                 "Could not import predictionguard python package. "
                 "Please install it with `pip install predictionguard`."
             )
-        return values
 
-    @property
-    def _default_params(self) -> Dict[str, Any]:
-        """Get the default parameters for calling the Prediction Guard API."""
-        return {
-            "max_tokens": self.max_tokens,
-            "temperature": self.temperature,
-        }
+        return values
 
     @property
     def _identifying_params(self) -> Dict[str, Any]:
         """Get the identifying parameters."""
-        return {**{"model": self.model}, **self._default_params}
+        return {"model": self.model}
 
     @property
     def _llm_type(self) -> str:
         """Return type of llm."""
         return "predictionguard"
 
+    def _get_parameters(self, **kwargs: Any) -> Dict[str, Any]:
+        # input kwarg conflicts with LanguageModelInput on BaseChatModel
+        input = kwargs.pop("predictionguard_input", self.predictionguard_input)
+        output = kwargs.pop("predictionguard_output", self.predictionguard_output)
+
+        params = {
+            **{
+                "max_tokens": self.max_tokens,
+                "temperature": self.temperature,
+                "top_p": self.top_p,
+                "top_k": self.top_k,
+                "input": (
+                    input.model_dump() if isinstance(input, BaseModel) else input
+                ),
+                "output": (
+                    output.model_dump() if isinstance(output, BaseModel) else output
+                ),
+            },
+            **kwargs,
+        }
+
+        return params
+
     def _call(
         self,
         prompt: str,
@@ -99,31 +132,35 @@ class PredictionGuard(LLM):
             The string generated by the model.
         Example:
             .. code-block:: python
-                response = pgllm.invoke("Tell me a joke.")
+                response = llm.invoke("Tell me a joke.")
         """
-        import predictionguard as pg
 
-        params = self._default_params
+        params = self._get_parameters(**kwargs)
+
+        stops = None
         if self.stop is not None and stop is not None:
             raise ValueError("`stop` found in both the input and default params.")
         elif self.stop is not None:
-            params["stop_sequences"] = self.stop
+            stops = self.stop
         else:
-            params["stop_sequences"] = stop
+            stops = stop
 
-        response = pg.Completion.create(
+        response = self.client.completions.create(
             model=self.model,
             prompt=prompt,
-            output=self.output,
-            temperature=params["temperature"],
-            max_tokens=params["max_tokens"],
-            **kwargs,
+            **params,
         )
+
+        for res in response["choices"]:
+            if res.get("status", "").startswith("error: "):
+                err_msg = res["status"].removeprefix("error: ")
+                raise ValueError(f"Error from PredictionGuard API: {err_msg}")
+
         text = response["choices"][0]["text"]
 
         # If stop tokens are provided, Prediction Guard's endpoint returns them.
         # In order to make this consistent with other endpoints, we strip them.
-        if stop is not None or self.stop is not None:
-            text = enforce_stop_tokens(text, params["stop_sequences"])
+        if stops:
+            text = enforce_stop_tokens(text, stops)
 
         return text

libs/community/scripts/check_pydantic.sh

@@ -20,7 +20,7 @@ count=$(git grep -E '(@root_validator)|(@validator)|(@field_validator)|(@pre_ini
 # PRs that increase the current count will not be accepted.
 # PRs that decrease update the code in the repository
 # and allow decreasing the count of are welcome!
-current_count=124
+current_count=123
 
 if [ "$count" -gt "$current_count" ]; then
   echo "The PR seems to be introducing new usage of @root_validator and/or @field_validator."

libs/community/tests/integration_tests/llms/test_predictionguard.py

@@ -1,10 +1,28 @@
 """Test Prediction Guard API wrapper."""
 
+import pytest
+
 from langchain_community.llms.predictionguard import PredictionGuard
 
 
-def test_predictionguard_call() -> None:
+def test_predictionguard_invoke() -> None:
     """Test valid call to prediction guard."""
-    llm = PredictionGuard(model="OpenAI-text-davinci-003")  # type: ignore[call-arg]
-    output = llm.invoke("Say foo:")
+    llm = PredictionGuard(model="Hermes-3-Llama-3.1-8B")  # type: ignore[call-arg]
+    output = llm.invoke("Tell a joke.")
     assert isinstance(output, str)
+
+
+def test_predictionguard_pii() -> None:
+    llm = PredictionGuard(
+        model="Hermes-3-Llama-3.1-8B",
+        predictionguard_input={"pii": "block"},
+        max_tokens=100,
+        temperature=1.0,
+    )
+
+    messages = [
+        "Hello, my name is John Doe and my SSN is 111-22-3333",
+    ]
+
+    with pytest.raises(ValueError, match=r"Could not make prediction. pii detected"):
+        llm.invoke(messages)

libs/packages.yml

@@ -163,4 +163,7 @@ packages:
     path: .
   - name: langchain-oceanbase
     repo: oceanbase/langchain-oceanbase
+    path: .
+  - name: langchain-predictionguard
+    repo: predictionguard/langchain-predictionguard
     path: .