Ctrlk

Python SDK

Highflame Python SDK overview with a guided path for setup, decorators, low-level client usage, and advanced Shield topics.

Python client for the Highflame guardrails service. The Python SDK gives you two main integration styles:

  • Shield decorators for the fastest path to guarding prompts, tools, and model outputs

  • the Highflame client when you want full control over requests, responses, and debugging

Read This Section in Order

  1. Getting Started: install the SDK, authenticate, and wire up your first guarded function

  2. Shield Decorators: choose the right decorator and configure it correctly

  3. Low-Level Client: use client.guard.*, client.detect.*, client.detectors.*, and client.debug.*

  4. Advanced Topics: debugging, optimization, streaming, agentic context, sessions, and client configuration

Choosing the Right API

I want to...
Use

Guard a prompt before my LLM runs

@shield.prompt

Guard a tool call before it executes

@shield.tool

Guard a tool's return value before it's used

@shield.toolresponse

Guard the LLM's output before returning to the caller

@shield.modelresponse

Guard a file read or write

@shield(content_type="file", action="read_file")

Evaluate with full control and inspect the full response

client.guard.evaluate()

Evaluate a prompt with minimal code

client.guard.evaluate_prompt()

Evaluate a tool call with minimal code

client.guard.evaluate_tool_call()

Run detectors without Cedar policy evaluation

client.detect.run()

Observe traffic without blocking

pass mode="monitor"

Understand why a decision was made

pass explain=True to GuardRequest

See per-detector breakdowns

pass debug=True to GuardRequest

Only run detectors referenced by active policies

pass optimize=True to GuardRequest

BlockedError is only raised by Shield decorators. Direct client.guard.evaluate() calls always return a GuardResponse, even when the decision is deny.

Create one Highflame client per process, not per request. The client maintains an internal token cache and connection pool.

Framework Integrations

Both Python and TypeScript ship packaged framework adapters:

If you are starting fresh, begin with Getting Started, then come back here when you need a different integration style.

PreviousShieldNextGetting Started

Last updated