# Low-Level Client

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()`

```python
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`:

```python
resp.allowed
resp.denied
```

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

Shorthands for the two most common patterns:

```python
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:

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

```python
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.

```python
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.

```python
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](/api-reference/sdk/shield/python-sdk/advanced-topics.md) for `explain`, `debug`, `optimize`, streaming, sessions, and context objects
* [Shield Decorators](/api-reference/sdk/shield/python-sdk/decorators.md) if you want higher-level function wrapping instead of direct client calls


---

# 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/client-api.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.