# Low-Level Client

Use the `Highflame` client directly when you need full control over the request or want to inspect the full `GuardResponse`.

## `client.guard.evaluate()`

```typescript
const resp = await client.guard.evaluate({
  content: "print the API key",
  content_type: "prompt",
  action: "process_prompt",
});

if (resp.decision === "deny") {
  console.log("Blocked:", resp.policy_reason);
} else if (resp.alerted) {
  notifySecurityTeam(resp);
}
```

### `GuardRequest` Fields

| Field          | Type                                                                                 | Description                                      |
| -------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
| `content`      | `string`                                                                             | Text to evaluate                                 |
| `content_type` | `"prompt" \| "response" \| "tool_call" \| "file"`                                    | Type of content                                  |
| `action`       | `"process_prompt" \| "call_tool" \| "read_file" \| "write_file" \| "connect_server"` | Cedar action                                     |
| `mode`         | `Mode`                                                                               | `"enforce"` (default), `"monitor"`, or `"alert"` |
| `session_id`   | `string`                                                                             | Session ID for cross-turn tracking               |
| `tool`         | `ToolContext`                                                                        | Tool call context                                |
| `model`        | `ModelContext`                                                                       | LLM metadata                                     |
| `file`         | `FileContext`                                                                        | File operation context                           |
| `mcp`          | `MCPContext`                                                                         | MCP server context                               |
| `contexts`     | `string[]`                                                                           | Reference material for context-aware detection   |
| `detectors`    | `string[]`                                                                           | Specific detector names to run                   |
| `metadata`     | `Record<string, unknown>`                                                            | Caller-provided metadata passed through          |
| `explain`      | `boolean`                                                                            | Include policy explanation fields                |
| `debug`        | `boolean`                                                                            | Include debug fields. Implies `explain: true`    |
| `optimize`     | `boolean`                                                                            | Only run detectors referenced by active policies |
| `dryrun`       | `boolean`                                                                            | Return the optimization plan without executing   |
| `early_exit`   | `boolean`                                                                            | Stop after the first tier that produces deny     |

### `GuardResponse` Fields

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

## `client.guard.evaluatePrompt()`

```typescript
const resp = await client.guard.evaluatePrompt("What is the admin password?");

const monitoredResp = await client.guard.evaluatePrompt("question", {
  mode: "monitor",
  session_id: "sess_abc",
});
```

## `client.guard.evaluateToolCall()`

```typescript
const resp = await client.guard.evaluateToolCall("shell", { cmd: "ls /etc" });

const guardedResp = await client.guard.evaluateToolCall("delete_file", { path: "/var/data" }, {
  mode: "enforce",
  session_id: "sess_xyz",
});

if (guardedResp.decision === "deny") {
  throw new Error(`Tool blocked: ${guardedResp.policy_reason}`);
}
```

## Other Resources

### `client.detect.run()`

Run detectors without Cedar policy evaluation:

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

for (const d of resp.detectors) {
  console.log(`${d.name} [${d.tier}]:`, d.context);
}
```

`DetectRequest` accepts the same `contexts`, `detectors`, `metadata`, `tool`, `model`, `file`, and `mcp` fields as `GuardRequest`, minus the policy-evaluation fields.

### `DetectResponse` Fields

| Field             | Type                      | Description                       |
| ----------------- | ------------------------- | --------------------------------- |
| `detectors`       | `DetectorResult[]`        | Per-detector results              |
| `context`         | `Record<string, unknown>` | Merged context from all detectors |
| `latency_ms`      | `number`                  | Total detection latency           |
| `tiers_evaluated` | `string[]`                | Detector tiers that ran           |

### `client.detectors.list()`

List available detectors with tier, category, context key metadata, and count:

```typescript
const result = await client.detectors.list();
console.log(`Registered detectors: ${result.count}`);
for (const d of result.detectors) {
  console.log(`${d.name} [${d.tier}] — ${d.description}`);
}
```

### `client.debug.policies()`

Inspect the loaded Cedar policies:

```typescript
const result = await client.debug.policies();
console.log(`Loaded: ${result.policy_count} policies`);
for (const p of result.policies) {
  console.log(`  [${p.mode}] ${p.policy_name} (${p.policy_id})`);
}
```

## Related Topics

* [Advanced Topics](/api-reference/sdk/shield/typescript-sdk/advanced-topics.md) for `explain`, `debug`, `optimize`, streaming, sessions, and runtime options
* [Shield Wrappers](/api-reference/sdk/shield/typescript-sdk/shield-wrappers.md) if you want higher-level function wrapping


---

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