Guardrails: валидация и исправление выходов LLM

Title:

URL Source: https://raw.githubusercontent.com/guardrails-ai/guardrails/main/docs/api_reference/guards.md

Markdown Content: # 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.