Shield Decorators

Reference for Python Shield decorators, including prompt, tool, tool response, model response, and generic wrappers.

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

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.

# 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.

@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.

@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.

@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.

@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 if you need full request and response control

• Advanced Topics for enforcement modes, sessions, debugging, and streaming