# Guards

## Guard

```python
class Guard(IGuard, Generic[OT])
```

The Guard class.

This class is the main entry point for using Guardrails. It can be
initialized by one of the following patterns:

- `Guard().use(...)`
- `Guard.for_string(...)`
- `Guard.for_pydantic(...)`
- `Guard.for_rail(...)`
- `Guard.for_rail_string(...)`

The `__call__`
method functions as a wrapper around LLM APIs. It takes in an LLM
API, and optional prompt parameters, and returns a ValidationOutcome
class that contains the raw output from
the LLM, the validated output, as well as other helpful information.

#### \_\_init\_\_

```python
def __init__(*,
             id: Optional[str] = None,
             name: Optional[str] = None,
             description: Optional[str] = None,
             validators: Optional[List[ValidatorReference]] = None,
             output_schema: Optional[Dict[str, Any]] = None,
             base_url: Optional[str] = None,
             api_key: Optional[str] = None,
             history_max_length: Optional[int] = None,
             use_server: Optional[bool] = None)
```

Initialize the Guard with serialized validator references and an
output schema.

Output schema must be a valid JSON Schema.

#### configure

```python
def configure(*,
              num_reasks: Optional[int] = None,
              allow_metrics_collection: Optional[bool] = None)
```

Configure the Guard.

**Arguments**:

- `num_reasks` _int, optional_ - The max times to re-ask the LLM
  if validation fails. Defaults to None.
- `allow_metrics_collection` _bool, optional_ - Whether to allow
  Guardrails to collect anonymous metrics.
  Defaults to None, and falls back to waht is
  set via the `guardrails configure` command.

#### for\_rail

```python
@classmethod
def for_rail(cls,
             rail_file: str,
             *,
             name: Optional[str] = None,
             description: Optional[str] = None)
```

Create a Guard using a `.rail` file to specify the output schema,
prompt, etc.

**Arguments**:

- `rail_file` - The path to the `.rail` file.
- `name` _str, optional_ - A unique name for this Guard. Defaults to `gr-` + the object id.
- `description` _str, optional_ - A description for this Guard. Defaults to None.
  

**Returns**:

  An instance of the `Guard` class.

#### for\_rail\_string

```python
@classmethod
def for_rail_string(cls,
                    rail_string: str,
                    *,
                    name: Optional[str] = None,
                    description: Optional[str] = None)
```

Create a Guard using a `.rail` string to specify the output schema,
prompt, etc..

**Arguments**:

- `rail_string` - The `.rail` string.
- `name` _str, optional_ - A unique name for this Guard. Defaults to `gr-` + the object id.
- `description` _str, optional_ - A description for this Guard. Defaults to None.
  

**Returns**:

  An instance of the `Guard` class.

#### for\_pydantic

```python
@classmethod
def for_pydantic(cls,
                 output_class: ModelOrListOfModels,
                 *,
                 reask_messages: Optional[List[Dict]] = None,
                 messages: Optional[List[Dict]] = None,
                 name: Optional[str] = None,
                 description: Optional[str] = None,
                 output_formatter: Optional[Union[str, BaseFormatter]] = None)
```

Create a Guard instance using a Pydantic model to specify the output
schema.

**Arguments**:

- `output_class` - (Union[Type[BaseModel], List[Type[BaseModel]]]): The pydantic model that describes
  the desired structure of the output.
- `messages` _List[Dict], optional_ - A list of messages to give to the llm. Defaults to None.
- `reask_messages` _List[Dict], optional_ - A list of messages to use during reasks. Defaults to None.
- `name` _str, optional_ - A unique name for this Guard. Defaults to `gr-` + the object id.
- `description` _str, optional_ - A description for this Guard. Defaults to None.
- `output_formatter` _str | Formatter, optional_ - 'none' (default), 'jsonformer', or a Guardrails Formatter.

#### for\_string

```python
@classmethod
def for_string(cls,
               validators: Sequence[Validator],
               *,
               string_description: Optional[str] = None,
               reask_messages: Optional[List[Dict]] = None,
               messages: Optional[List[Dict]] = None,
               name: Optional[str] = None,
               description: Optional[str] = None)
```

Create a Guard instance for a string response.

**Arguments**:

- `validators` - (List[Validator]): The list of validators to apply to the string output.
- `string_description` _str, optional_ - A description for the string to be generated. Defaults to None.
- `messages` _List[Dict], optional_ - A list of messages to pass to llm. Defaults to None.
- `reask_messages` _List[Dict], optional_ - A list of messages to use during reasks. Defaults to None.
- `name` _str, optional_ - A unique name for this Guard. Defaults to `gr-` + the object id.
- `description` _str, optional_ - A description for this Guard. Defaults to None.

#### \_\_call\_\_

```python
@trace(name="/guard_call", origin="Guard.__call__")
def __call__(
        llm_api: Optional[Callable] = None,
        *args,
        prompt_params: Optional[Dict] = None,
        num_reasks: Optional[int] = 1,
        messages: Optional[List[Dict]] = None,
        metadata: Optional[Dict] = None,
        full_schema_reask: Optional[bool] = None,
        **kwargs
) -> Union[ValidationOutcome[OT], Iterator[ValidationOutcome[OT]]]
```

Call the LLM and validate the output.

**Arguments**:

- `llm_api` - The LLM API to call
  (e.g. openai.completions.create or openai.Completion.acreate)
- `prompt_params` - The parameters to pass to the prompt.format() method.
- `num_reasks` - The max times to re-ask the LLM for invalid output.
- `messages` - The message history to pass to the LLM.
- `metadata` - Metadata to pass to the validators.
- `full_schema_reask` - When reasking, whether to regenerate the full schema
  or just the incorrect values.
  Defaults to `True` if a base model is provided,
  `False` otherwise.
  

**Returns**:

  ValidationOutcome

#### parse

```python
@trace(name="/guard_call", origin="Guard.parse")
def parse(llm_output: str,
          *args,
          metadata: Optional[Dict] = None,
          llm_api: Optional[Callable] = None,
          num_reasks: Optional[int] = None,
          prompt_params: Optional[Dict] = None,
          full_schema_reask: Optional[bool] = None,
          **kwargs) -> ValidationOutcome[OT]
```

Alternate flow to using Guard where the llm_output is known.

**Arguments**:

- `llm_output` - The output being parsed and validated.
- `metadata` - Metadata to pass to the validators.
- `llm_api` - The LLM API to call
  (e.g. openai.completions.create or openai.Completion.acreate)
- `num_reasks` - The max times to re-ask the LLM for invalid output.
- `prompt_params` - The parameters to pass to the prompt.format() method.
- `full_schema_reask` - When reasking, whether to regenerate the full schema
  or just the incorrect values.
  

**Returns**:

  ValidationOutcome

#### error\_spans\_in\_output

```python
def error_spans_in_output() -> List[ErrorSpan]
```

Get the error spans in the last output.

#### use

```python
def use(*validator_spread: Validator,
        validators: List[Validator] = [],
        on: str = "output") -> "Guard"
```

Applies validators to the property specified in the `on` argument.
Calling `Guard.use` with the same `on` value multiple times will
overwrite previously configured validators on the specified property.

**Arguments**:

  *validator_spread:
  One or more validators passed as positional arguments to use.
  validators:
  Keyword argument that allows explicitly setting a list of
  validators to use.
  on:
  The property to validate. Valid options include "output", "messages",
  or a JSON path starting with "$.". Defaults to "output".

#### get\_validators

```python
def get_validators(on: str) -> List[Validator]
```

The read-only counterpart to `Guard.use`. Retrieves the validators
applied to the specified property.

**Arguments**:

- `on` - The property for which to return configured validators.
  Valid options include "output", "messages",
  or a JSON path starting with "$.".

#### validate

```python
@trace(name="/guard_call", origin="Guard.validate")
def validate(llm_output: str, *args, **kwargs) -> ValidationOutcome[OT]
```

#### to\_runnable

```python
def to_runnable() -> Runnable
```

Convert a Guard to a LangChain Runnable.

#### to\_dict

```python
def to_dict() -> Dict[str, Any]
```

#### json\_function\_calling\_tool

```python
def json_function_calling_tool(
        tools: Optional[list] = None) -> List[Dict[str, Any]]
```

Appends an OpenAI tool that specifies the output structure using
JSON Schema for chat models.

#### from\_dict

```python
@classmethod
def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional["Guard"]
```

## AsyncGuard

```python
class AsyncGuard(Guard, Generic[OT])
```

The AsyncGuard class.

This class one of the main entry point for using Guardrails. It is
initialized from one of the following class methods:

- `for_rail`
- `for_rail_string`
- `for_pydantic`
- `for_string`

The `__call__`
method functions as a wrapper around LLM APIs. It takes in an Async LLM
API, and optional prompt parameters, and returns the raw output stream from
the LLM and the validated output stream.

#### \_\_init\_\_

```python
def __init__(*args, **kwargs)
```

#### for\_pydantic

```python
@classmethod
def for_pydantic(cls,
                 output_class: ModelOrListOfModels,
                 *,
                 messages: Optional[List[Dict]] = None,
                 reask_messages: Optional[List[Dict]] = None,
                 name: Optional[str] = None,
                 description: Optional[str] = None,
                 output_formatter: Optional[Union[str, BaseFormatter]] = None)
```

#### for\_string

```python
@classmethod
def for_string(cls,
               validators: Sequence[Validator],
               *,
               string_description: Optional[str] = None,
               messages: Optional[List[Dict]] = None,
               reask_messages: Optional[List[Dict]] = None,
               name: Optional[str] = None,
               description: Optional[str] = None)
```

#### from\_dict

```python
@classmethod
def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional["AsyncGuard"]
```

#### use

```python
def use(*validator_spread: Validator,
        validators: List[Validator] = [],
        on: str = "output") -> "AsyncGuard"
```

#### \_\_call\_\_

```python
@async_trace(name="/guard_call", origin="AsyncGuard.__call__")
async def __call__(
    llm_api: Optional[Callable[..., Awaitable[Any]]] = None,
    *args,
    prompt_params: Optional[Dict] = None,
    num_reasks: Optional[int] = 1,
    messages: Optional[List[Dict]] = None,
    metadata: Optional[Dict] = None,
    full_schema_reask: Optional[bool] = None,
    **kwargs
) -> Union[
        ValidationOutcome[OT],
        Awaitable[ValidationOutcome[OT]],
        AsyncIterator[ValidationOutcome[OT]],
]
```

Call the LLM and validate the output. Pass an async LLM API to
return a coroutine.

**Arguments**:

- `llm_api` - The LLM API to call
  (e.g. openai.completions.create or openai.chat.completions.create)
- `prompt_params` - The parameters to pass to the prompt.format() method.
- `num_reasks` - The max times to re-ask the LLM for invalid output.
- `messages` - The message history to pass to the LLM.
- `metadata` - Metadata to pass to the validators.
- `full_schema_reask` - When reasking, whether to regenerate the full schema
  or just the incorrect values.
  Defaults to `True` if a base model is provided,
  `False` otherwise.
  

**Returns**:

  The raw text output from the LLM and the validated output.

#### parse

```python
@async_trace(name="/guard_call", origin="AsyncGuard.parse")
async def parse(llm_output: str,
                *args,
                metadata: Optional[Dict] = None,
                llm_api: Optional[Callable[..., Awaitable[Any]]] = None,
                num_reasks: Optional[int] = None,
                prompt_params: Optional[Dict] = None,
                full_schema_reask: Optional[bool] = None,
                **kwargs) -> Awaitable[ValidationOutcome[OT]]
```

Alternate flow to using AsyncGuard where the llm_output is known.

**Arguments**:

- `llm_output` - The output being parsed and validated.
- `metadata` - Metadata to pass to the validators.
- `llm_api` - The LLM API to call
  (e.g. openai.completions.create or openai.Completion.acreate)
- `num_reasks` - The max times to re-ask the LLM for invalid output.
- `prompt_params` - The parameters to pass to the prompt.format() method.
- `full_schema_reask` - When reasking, whether to regenerate the full schema
  or just the incorrect values.
  

**Returns**:

  The validated response. This is either a string or a dictionary,
  determined by the object schema defined in the RAILspec.

#### validate

```python
@async_trace(name="/guard_call", origin="AsyncGuard.validate")
async def validate(llm_output: str, *args,
                   **kwargs) -> Awaitable[ValidationOutcome[OT]]
```

## ValidationOutcome

```python
class ValidationOutcome(IValidationOutcome, ArbitraryModel, Generic[OT])
```

The final output from a Guard execution.

**Attributes**:

- `call_id` - The id of the Call that produced this ValidationOutcome.
- `raw_llm_output` - The raw, unchanged output from the LLM call.
- `validated_output` - The validated, and potentially fixed, output from the LLM call
  after passing through validation.
- `reask` - If validation continuously fails and all allocated reasks are used,
  this field will contain the final reask that would have been sent
  to the LLM if additional reasks were available.
- `validation_passed` - A boolean to indicate whether or not the LLM output
  passed validation. If this is False, the validated_output may be invalid.
- `error` - If the validation failed, this field will contain the error message

#### from\_guard\_history

```python
@classmethod
def from_guard_history(cls, call: Call)
```

Create a ValidationOutcome from a history Call object.