# Shield Decorators

Use `Shield` decorators when you want guardrails to run automatically around your application code.

```python
from highflame import Highflame
from highflame.shield import Shield

client = Highflame(api_key="hf_sk_...")
shield = Shield(client)
```

## `@shield.prompt`

Guards the prompt content before the function runs. If denied, the function is never called.

```python
# Bare decorator — defaults apply
@shield.prompt
def chat(message: str) -> str:
    return llm.complete(message)


# With options
@shield.prompt(mode="monitor", content_arg="user_input", session_id="sess_abc")
def chat(context: str, user_input: str) -> str:
    return llm.complete(user_input)
```

| Option        | Type                                    | Default           | Description                    |
| ------------- | --------------------------------------- | ----------------- | ------------------------------ |
| `mode`        | `"enforce"` \| `"monitor"` \| `"alert"` | `"enforce"`       | Enforcement mode               |
| `content_arg` | `str`                                   | first `str` param | Name of the parameter to guard |
| `session_id`  | `str \| None`                           | `None`            | Session ID for tracking        |

## `@shield.tool`

Guards tool arguments before the tool executes. If denied, the function is never called. All bound arguments are forwarded as tool-call context.

```python
@shield.tool
def shell(cmd: str) -> str:
    return subprocess.check_output(cmd, shell=True).decode()


@shield.tool(tool_name="bash_executor", mode="alert")
def run_bash(cmd: str, timeout: int = 30) -> str:
    ...
```

| Option       | Type                                    | Default       | Description                   |
| ------------ | --------------------------------------- | ------------- | ----------------------------- |
| `mode`       | `"enforce"` \| `"monitor"` \| `"alert"` | `"enforce"`   | Enforcement mode              |
| `tool_name`  | `str \| None`                           | function name | Tool name sent to the service |
| `session_id` | `str \| None`                           | `None`        | Session ID                    |

## `@shield.toolresponse`

Guards the tool's return value after the function runs. The function always executes; its return value is blocked if denied.

```python
@shield.toolresponse
def fetch_page(url: str) -> str:
    return requests.get(url).text


@shield.toolresponse(mode="alert", tool_name="web_fetch")
async def afetch(url: str) -> str:
    async with httpx.AsyncClient() as c:
        resp = await c.get(url)
    return resp.text
```

| Option       | Type                                    | Default       | Description                   |
| ------------ | --------------------------------------- | ------------- | ----------------------------- |
| `mode`       | `"enforce"` \| `"monitor"` \| `"alert"` | `"enforce"`   | Enforcement mode              |
| `tool_name`  | `str \| None`                           | function name | Tool name sent to the service |
| `session_id` | `str \| None`                           | `None`        | Session ID                    |

## `@shield.modelresponse`

Guards the LLM's output before returning it to the caller. The function always executes; its return value is blocked if denied.

```python
@shield.modelresponse
def generate(prompt: str) -> str:
    return openai_client.complete(prompt)


@shield.modelresponse(mode="alert", session_id="sess_xyz")
async def agenerate(prompt: str) -> str:
    return await anthropic_client.acomplete(prompt)
```

| Option       | Type                                    | Default     | Description      |
| ------------ | --------------------------------------- | ----------- | ---------------- |
| `mode`       | `"enforce"` \| `"monitor"` \| `"alert"` | `"enforce"` | Enforcement mode |
| `session_id` | `str \| None`                           | `None`      | Session ID       |

## `@shield()` Generic Decorator

Use the generic decorator when you need a content type or action not covered by the named decorators.

```python
@shield(content_type="file", action="write_file", content_arg="content")
def write_config(path: str, content: str) -> None:
    with open(path, "w") as f:
        f.write(content)


@shield(content_type="file", action="read_file", content_arg="path")
async def read_secret(path: str) -> str:
    async with aiofiles.open(path) as f:
        return await f.read()
```

| Option         | Type                                    | Default           | Description                                 |
| -------------- | --------------------------------------- | ----------------- | ------------------------------------------- |
| `content_type` | `str`                                   | required          | Content type such as `"file"` or `"prompt"` |
| `action`       | `str`                                   | required          | Action such as `"write_file"`               |
| `content_arg`  | `str \| None`                           | first `str` param | Parameter to guard                          |
| `mode`         | `"enforce"` \| `"monitor"` \| `"alert"` | `"enforce"`       | Enforcement mode                            |
| `session_id`   | `str \| None`                           | `None`            | Session ID                                  |

## Related Topics

* [Low-Level Client](/api-reference/sdk/shield/python-sdk/client-api.md) if you need full request and response control
* [Advanced Topics](/api-reference/sdk/shield/python-sdk/advanced-topics.md) for enforcement modes, sessions, debugging, and streaming


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/api-reference/sdk/shield/python-sdk/decorators.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.