> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murnitur.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Murnitur Shield is designed to protect your system from bad inputs and safeguard your users from harmful outputs. Think of it as a firewall for your data, ensuring that only appropriate content gets through.

<iframe width="700" height="400" src="https://www.loom.com/embed/761e138a9dae49ae8086361d57f9bb14?sid=89414bf7-7d26-4ed4-a10e-b09f9b400f14" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

## Generate API Key

* Visit [murnitur.ai](https://murnitur.ai) and sign in to your account.
* Navigate to the API key section and generate a new API key.

## Install Murnitur

Install the Murnitur package using pip:

<CodeGroup>
  ```bash python theme={null}
  pip install murnitur
  ```

  ```bash typescript theme={null}
  npm install murnitur
  ```
</CodeGroup>

## Define Rulesets

Rulesets are the core of Murnitur Shield, containing specific rules your application must comply with. They help determine what gets flagged or filtered based on predefined criteria.

Example ruleset:

<CodeGroup>
  ```python python theme={null}
  from murnitur.guard import RuleSet

  rulesets: list[RuleSet] = [
      {
          "rules": [
              {
                  "metric": "pii",
                  "operator": "contains",
                  "value": ["email", "ssn", "address", "phone_number"],
              },
          ],
          "action": {
              "type": "OVERRIDE",
              "fallback": "Sorry, I can't provide personal identifiable information.",
          },
      },
  ]
  ```

  ```typescript typescript theme={null}
  import { RuleSet } from "murnitur"

  const rulesets: RuleSet[] = [
      {
          rules: [
              {
                  metric: "pii",
                  operator: "contains",
                  value: ["email", "ssn", "address", "phone_number"],
              },
          ],
          action": {
              type: "OVERRIDE",
              fallback: "Sorry, I can't provide personal identifiable information.",
          },
      },
  ]
  ```
</CodeGroup>

Each ruleset includes:

* **Metric**: The type of content to check (e.g., PII).
* **Operator**: The condition to evaluate (e.g., "contains").
* **Value**: Specific values to look for (e.g., "email", "ssn").
* **Action**: What to do if a rule is triggered, such as overriding the response with a fallback message.

## Start the Firewall

Initialize Murnitur Shield to start filtering content:

<CodeGroup>
  ```python python theme={null}
  from murnitur import Guard

  payload = {
      "output": "James lives at 567 X. Elm St., Chicago, IL 60614.",
      "input": "Give me James' home address",
  }

  response = Guard.shield(
      payload=payload,
      rulesets=rulesets,
      config={
          "group": "development",
          "murnitur_key": "<YOUR_API_KEY>"
      }
  )
  ```

  ```typescript typescript theme={null}
  import { Guard } from "murnitur"

  const payload = {
      output: "James lives at 567 X. Elm St., Chicago, IL 60614.",
      input: "Give me James' home address",
  }

  const response = await Guard.shield(
      payload,
      rulesets,
      {
          "group": "development",
          "murnitur_key": "<YOUR_API_KEY>"
      }
  )
  ```
</CodeGroup>

## Quick Wiki

### `payload`

The `payload` parameter is a dictionary containing the data you want to inspect and filter. It typically includes:

* `input`: The original input data from the user.
* `output`: The generated output data from your system.

Example:

```python python theme={null}
payload = {
    "input": "User input data here",
    "output": "Generated output data here"
}
```

### `rulesets`

The `rulesets` parameter is a list of `RuleSet` objects defining the rules your application must comply with. Each `RuleSet` contains:

* `rules`: A list of individual rules to check against the `payload`.
  * `metric`: The type of content to evaluate (e.g., "pii" for Personally Identifiable Information).
  * `operator`: The condition to apply (e.g., "contains").
  * `value`: Specific values to look for (e.g., \["email", "ssn"]).
* `action`: The action to take if a rule is triggered.
  * `type`: The type of action (e.g., "OVERRIDE").
  * `fallback`: The fallback response if the action type is "OVERRIDE".

Example:

```python python theme={null}
rulesets = [
    {
        "rules": [
            {
                "metric": "pii",
                "operator": "contains",
                "value": ["email", "ssn", "address", "phone_number"]
            }
        ],
        "action": {
            "type": "OVERRIDE",
            "fallback": "Sorry, I can't provide personal identifiable information."
        }
    }
]
```

### `config`

The config parameter is a dictionary containing various configuration options for Murnitur Shield. It includes keys such as `murnitur_key`, `provider`, `model`, `group`, `api_key`, `base_url`, and `headers`.

Example:

```python python theme={null}
from murnitur.main import GuardConfig

config: GuardConfig
```

#### `murnitur_key`

The `murnitur_key` is a required string containing your Murnitur API key. This key authenticates your requests, captures interceptions, and links them to your account. If not passed, murnitur picks it up from the environment variables.

```python python theme={null}
config["murnitur_key"] = "your_murnitur_api_key_here"
```

#### `provider`

The `provider` parameter specifies the service provider you are using, such as "openai", "groq", "anthropic", or "custom".

Example:

```python theme={null}
config["provider"] = "openai"
```

#### `model`

By default, Murnitur uses `gpt-3.5-turbo`, but you can change it to any supported model from your chosen provider.

Example:

```python theme={null}
config["model"] = "gpt-4-turbo"
```

#### `group`

The `group` parameter is an optional string that categorizes the set of rules being applied. It helps in organizing and managing different rule sets for various environments or projects.

Example:

```python theme={null}
config["group"] = "development"
```

#### `api_key`

The `api_key` is an optional string containing your API key for the chosen provider. This key is required if you use any provider-specific metrics in your rule sets.

Example:

```python theme={null}
config["api_key"] = "your_provider_api_key_here"
```

#### `base_url`

The `base_url` is an optional string specifying the base URL for API requests. This is useful if you need to point to a different endpoint. It must be an OpenAI compatible API endpoint.

Example:

```python theme={null}
config["base_url"] = "https://api.openai.com/v1"
```

#### `headers`

The `headers` parameter is an optional dictionary containing any additional headers you need to include in your API requests.

Example:

```python theme={null}
config["headers"] = {"Custom-Header": "value"}
```

### Complete Example

Here is a complete example of using Murnitur Shield with all the parameters:

<CodeGroup>
  ```python python theme={null}
  from murnitur import Guard

  response = Guard.shield(
      payload={
          "input": "User input data here",
          "output": "Generated output data here"
      },
      rulesets=[
          {
              "rules": [
                  {
                      "metric": "pii",
                      "operator": "contains",
                      "value": ["email", "ssn", "address", "phone_number"]
                  }
              ],
              "action": {
                  "type": "OVERRIDE",
                  "fallback": "Sorry, I can't provide personal identifiable information."
              }
          }
      ],
      config={
          "group": "development",
          "murnitur_key": "your_api_key_here",
          "provider": "openai",
          "model": "gpt-4o-mini",
          "api_key": "provider_api_key"
      }
  )
  ```

  ```typescript typescript theme={null}
  import { Guard } from "murnitur"

  const response = await Guard.shield(
      {
          input: "User input data here",
          output: "Generated output data here"
      },
      [
          {
              rules: [
                  {
                      metric: "pii",
                      operator: "contains",
                      value: ["email", "ssn", "address", "phone_number"]
                  }
              ],
              action: {
                  type: "OVERRIDE",
                  fallback: "Sorry, I can't provide personal identifiable information."
              }
          }
      ],
      {
          group: "development",
          murnitur_key: "your_api_key_here",
          provider: "openai",
          model: "gpt-4o-mini",
          api_key: "provider_api_key"
      }
  )
  ```
</CodeGroup>