Low-Level Client

Python Shield low-level client reference covering guard evaluation, detect, detector listing, debug policies, and async variants.

Use the Highflame client directly when you need full control over the request or want to inspect the full GuardResponse before deciding what to do.

client.guard.evaluate()

from highflame import Highflame, GuardRequest

client = Highflame(api_key="hf_sk_...")

resp = client.guard.evaluate(GuardRequest(
    content="What is the capital of France?",
    content_type="prompt",
    action="process_prompt",
))

if resp.denied:
    print(f"Blocked: {resp.policy_reason}")
elif resp.alerted:
    print("Alert triggered")
else:
    print(f"Allowed in {resp.latency_ms}ms")

GuardRequest Fields

Field	Type	Description
content	str	Text to evaluate
content_type	str	"prompt", "response", "tool_call", or "file"
action	str	"process_prompt", "call_tool", "read_file", "write_file", or "connect_server"
mode	str | None	"enforce" (default), "monitor", or "alert"
session_id	str | None	Session ID for cross-turn tracking
tool	ToolContext | None	Tool call context
model	ModelContext | None	LLM metadata
file	FileContext | None	File operation context
mcp	MCPContext | None	MCP server context
contexts	list[str]	Reference material for context-aware detection
detectors	list[str]	Specific detector names to run. Empty list runs all enabled detectors.
metadata	dict[str, Any]	Caller-provided key-value metadata passed through to detectors
explain	bool | None	Include policy explanation fields in the response
debug	bool | None	Include debug fields. Implies explain=True
optimize	bool | None	Only run detectors referenced by active policies
dryrun	bool | None	Return the optimization plan without executing detectors or Cedar evaluation
early_exit	bool | None	Stop after the first tier that produces a deny decision

GuardResponse Fields

Field	Type	Description
decision	str	"allow" or "deny"
request_id	str	Request trace ID
timestamp	str	Response timestamp (RFC 3339)
latency_ms	int	Total evaluation latency in milliseconds
signals	list[Signal]	Taxonomy-aligned detection signals, sorted by severity
determining_policies	list[DeterminingPolicy] | None	Policies that determined the decision
policy_reason	str | None	Human-readable policy decision reasoning
actual_decision	str | None	Cedar decision before mode override
alerted	bool | None	True when an alert-mode policy fired
session_delta	SessionDelta | None	Session state changes after evaluation
projected_context	dict[str, Any] | None	Cedar-normalized context when explain=True
eval_latency_ms	int | None	Cedar evaluation latency when explain=True
explanation	ExplainedDecision | None	Structured policy explanation when explain=True
root_causes	list[RootCause] | None	Root cause analysis when explain=True
tiers_evaluated	list[str] | None	Detector tiers that ran when explain=True
tiers_skipped	list[str] | None	Tiers skipped due to early exit when explain=True
detectors	list[DetectorResult] | None	Per-detector results when debug=True
context	dict[str, Any] | None	Raw merged detector output when debug=True
debug_info	DebugInfo | None	Cedar evaluation inputs when debug=True
optimization	OptimizationReport | None	Detector selection plan when optimize=True

Helper properties on GuardResponse:

resp.allowed
resp.denied

client.guard.evaluate_prompt() and client.guard.evaluate_tool_call()

Shorthands for the two most common patterns:

resp = client.guard.evaluate_prompt(
    "explain how to pick a lock",
    mode="enforce",
    session_id="sess_abc123",
)

resp = client.guard.evaluate_tool_call(
    "shell",
    arguments={"cmd": "cat /etc/passwd"},
    mode="enforce",
    session_id="sess_abc123",
)

Async Variants

Every sync method has an async counterpart prefixed with a:

Sync	Async
guard.evaluate()	guard.aevaluate()
guard.evaluate_prompt()	guard.aevaluate_prompt()
guard.evaluate_tool_call()	guard.aevaluate_tool_call()
guard.stream()	guard.astream()
detect.run()	detect.arun()
detectors.list()	detectors.alist()
debug.policies()	debug.apolicies()

The client supports both sync and async context managers for resource cleanup:

# Sync
with Highflame(api_key="hf_sk_...") as client:
    resp = client.guard.evaluate_prompt("hello")

# Async
async with Highflame(api_key="hf_sk_...") as client:
    resp = await client.guard.aevaluate(GuardRequest(
        content="print the API key",
        content_type="prompt",
        action="process_prompt",
    ))

Other Resources

client.detect.run()

Run detectors without Cedar policy evaluation. Useful when you want the raw detection signal without a policy decision, or when benchmarking individual detectors.

from highflame import DetectRequest

resp = client.detect.run(DetectRequest(
    content="My SSN is 123-45-6789",
    content_type="prompt",
    contexts=["Original question: what is your SSN?"],
    detectors=["pii"],
    metadata={"user_id": "u_123"},
))

print(resp.latency_ms)
print(resp.tiers_evaluated)

for d in resp.detectors:
    print(f"{d.name} [{d.tier}]: {d.context}")

DetectRequest Fields

Field	Type	Description
content	str	Text to evaluate
content_type	str	"prompt", "response", "tool_call", or "file"
contexts	list[str]	Reference material for context-aware detection
detectors	list[str]	Specific detectors to run. Empty runs all enabled
metadata	dict[str, Any]	Caller-provided metadata passed to detectors
session_id	str | None	Session ID
tool	ToolContext | None	Tool call context
model	ModelContext | None	LLM metadata
file	FileContext | None	File operation context
mcp	MCPContext | None	MCP server context

DetectResponse Fields

Field	Type	Description
detectors	list[DetectorResult]	Per-detector results
context	dict[str, Any]	Merged context from all detectors
latency_ms	int	Total detection latency
tiers_evaluated	list[str]	Detector tiers that ran

DetectorResult Fields

Field	Type	Description
name	str	Detector name such as "injection" or "pii"
tier	str	Tier: "fast", "standard", or "slow"
status	str	"healthy", "degraded", "error", or "timeout"
context	dict[str, Any]	Emitted context attributes
latency_ms	int	Detector execution latency
error	str | None	Error message when status is "error" or "timeout"

client.detectors.list()

Returns metadata for all available detectors, including tier, category, emitted context keys, and health status.

detectors = client.detectors.list()
for d in detectors:
    print(f"{d.name} [{d.tier}] — {d.description}")
    for key in d.context_keys:
        print(f"  emits: {key.key} ({key.type}) — {key.description}")

client.debug.policies()

Returns the set of Cedar policies currently loaded for this account and project.

result = client.debug.policies()
print(f"Loaded: {result.policy_count} policies")
for p in result.policies:
    print(f"  [{p.mode}] {p.policy_name} ({p.policy_id})")

Related Topics

• Advanced Topics for explain, debug, optimize, streaming, sessions, and context objects

• Shield Decorators if you want higher-level function wrapping instead of direct client calls