# Python SDK

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](/api-reference/sdk/shield/python-sdk/getting-started.md): install the SDK, authenticate, and wire up your first guarded function
2. [Shield Decorators](/api-reference/sdk/shield/python-sdk/decorators.md): choose the right decorator and configure it correctly
3. [Low-Level Client](/api-reference/sdk/shield/python-sdk/client-api.md): use `client.guard.*`, `client.detect.*`, `client.detectors.*`, and `client.debug.*`
4. [Advanced Topics](/api-reference/sdk/shield/python-sdk/advanced-topics.md): 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`             |

{% hint style="warning" %}
**`BlockedError` is only raised by `Shield` decorators.** Direct `client.guard.evaluate()` calls always return a `GuardResponse`, even when the decision is deny.
{% endhint %}

{% hint style="warning" %}
**Create one `Highflame` client per process, not per request.** The client maintains an internal token cache and connection pool.
{% endhint %}

## Framework Integrations

Both Python and TypeScript ship packaged framework adapters:

* [LangGraph](/api-reference/sdk/shield/integrations/langgraph.md): `HighflameMiddleware`
* [CrewAI](/api-reference/sdk/shield/integrations/crewai.md): `HighflameCrewHooks`
* [AWS Strands](/api-reference/sdk/shield/integrations/strands.md): `HighflameStrandsHooks`
* [Azure AI Foundry](https://github.com/highflame-ai/highflame-docs/blob/main/api-reference/sdk/shield/integrations/foundry.md): `HighflameFoundryMiddleware`

If you are starting fresh, begin with [Getting Started](/api-reference/sdk/shield/python-sdk/getting-started.md), then come back here when you need a different integration style.


---

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