SDK Quick Reference

All common Highflame SDK patterns side by side — Python and TypeScript. Installation, client setup, guard evaluation, Shield wrappers, ZeroID, error handling, streaming.

Common patterns at a glance. Both Python and TypeScript side by side.

Installation

SDK

Command

Python

pip install highflame

TypeScript

npm install @highflame/sdk

Rust

cargo add highflame

Framework extras:

pip install 'highflame[langgraph]'
pip install 'highflame[crewai]'
pip install 'highflame[strands]'

Client Initialization

from highflame import Highflame

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

Evaluate a Prompt

resp = client.guard.evaluate_prompt("user message")
if resp.denied:
    raise PermissionError(resp.policy_reason)

Evaluate a Tool Call

resp = client.guard.evaluate_tool_call(
    "shell",
    arguments={"cmd": "ls /etc"},
)

Full GuardRequest

from highflame import GuardRequest

resp = client.guard.evaluate(GuardRequest(
    content="text to evaluate",
    content_type="prompt",          # "prompt" | "response" | "tool_call" | "file"
    action="process_prompt",        # "process_prompt" | "call_tool" | "read_file" | "write_file" | "connect_server"
    mode="enforce",                 # "enforce" | "monitor" | "alert"
    session_id="sess_abc123",
))

Shield Decorators / Wrappers

from highflame.shield import Shield

shield = Shield(client)

@shield.prompt
def chat(message: str) -> str: ...

@shield.tool
def shell(cmd: str) -> str: ...

@shield.toolresponse
def fetch(url: str) -> str: ...

@shield.modelresponse
def generate(prompt: str) -> str: ...

import { Shield } from "@highflame/sdk";

const shield = new Shield(client);

const chat = shield.prompt(async (msg: string) => llm.complete(msg));
const shell = shield.tool(async function shell(cmd: string) { ... });
const fetch = shield.toolResponse(async (url: string) => http.get(url));
const gen = shield.modelResponse(async (prompt: string) => llm.complete(prompt));

Async Evaluation

resp = await client.guard.aevaluate_prompt("message")
resp = await client.guard.aevaluate(request)

Error Handling

from highflame import BlockedError, AuthenticationError, RateLimitError, APIError, APIConnectionError

try:
    resp = client.guard.evaluate(request)
except BlockedError as e:       # from Shield decorators only
    print(e.response.policy_reason)
except AuthenticationError as e:
    print(f"401: {e.detail}")
except RateLimitError as e:
    print(f"429: {e.detail}")
except APIError as e:
    print(f"{e.status}: {e.detail}")
except APIConnectionError as e:
    print(f"Network error: {e}")

import { BlockedError, AuthenticationError, RateLimitError, APIError, APIConnectionError } from "@highflame/sdk";

try {
  const resp = await client.guard.evaluate(request);
} catch (err) {
  if (err instanceof BlockedError) console.error(err.response.policy_reason);
  else if (err instanceof AuthenticationError) console.error(`401: ${err.detail}`);
  else if (err instanceof RateLimitError) console.error(`429: ${err.detail}`);
  else if (err instanceof APIError) console.error(`${err.status}: ${err.detail}`);
  else if (err instanceof APIConnectionError) console.error(`Network: ${err.message}`);
}

Enforcement Modes

Mode

resp.denied / decision

resp.alerted

Use for

"enforce"

True / "deny" on violation

False

Production enforcement

"monitor"

Always False / "allow"

False

Shadow testing, rollout staging

"alert"

Always False / "allow"

True if violated

Alerting without blocking

ZeroID — Issue and Verify Tokens

from highflame.zeroid import ZeroIDClient

client = ZeroIDClient(base_url="https://auth.zeroid.dev", account_id="acct-demo", project_id="proj-prod")

# Register agent
reg = client.agents.register(name="My Agent", external_id="my-agent", sub_type="tool_agent", trust_level="first_party", created_by="[email protected]")

# Issue token
token = client.tokens.issue(grant_type="api_key", api_key=reg.api_key)

# Verify locally (fast, no revocation check)
identity = client.tokens.verify(token.access_token)

# Verify with revocation check (online)
session = client.tokens.session(token.access_token)

import { ZeroIDClient } from "@highflame/sdk";

const client = new ZeroIDClient({ baseUrl: "https://auth.zeroid.dev", accountId: "acct-demo", projectId: "proj-prod" });

// Register agent
const reg = await client.agents.register({ name: "My Agent", external_id: "my-agent", sub_type: "tool_agent", trust_level: "first_party", created_by: "[email protected]" });

// Issue token
const token = await client.tokens.issue({ grant_type: "api_key", api_key: reg.api_key });

// Verify locally (fast)
const identity = await client.tokens.verify(token.access_token);

// Verify with revocation check (online)
const session = await client.tokens.session(token.access_token);

ZeroID Identity Helper Methods

identity.has_scope("data:read")    # bool
identity.has_tool("bash")          # bool
identity.is_delegated()            # bool
identity.delegated_by()            # str | None

ZeroID + Shield — Two-Layer Pattern

identity = zeroid.tokens.verify_bearer(request.headers["Authorization"])

resp = shield_client.guard.evaluate(GuardRequest(
    content=prompt,
    content_type="prompt",
    action="process_prompt",
    session_id=session_id,
    context={
        "trust_level": identity.trust_level,
        "sub_type": identity.sub_type,
        "delegation_depth": identity.delegation_depth,
        "delegated_by": identity.delegated_by(),
        "scopes": identity.scopes,
    },
))

const identity = await zeroid.tokens.verifyBearer(request.headers.authorization);

const resp = await shieldClient.guard.evaluate({
  content: prompt,
  content_type: "prompt",
  action: "process_prompt",
  session_id: sessionId,
  context: {
    trust_level: identity.trust_level,
    sub_type: identity.sub_type,
    delegation_depth: identity.delegation_depth,
    delegated_by: identity.delegatedBy(),
    scopes: identity.scopes,
  },
});

Streaming

for event in client.guard.stream(request):
    if event.type == "decision":
        print(event.data.get("decision"))

# Async
async for event in client.guard.astream(request):
    if event.type == "decision":
        print(event.data.get("decision"))

Client Options Reference

Option (Python)

Option (TypeScript)

Default

Description

api_key

apiKey

required

Service key or raw JWT

base_url

baseUrl

Highflame SaaS

Guard service URL

token_url

tokenUrl

Highflame SaaS

Token exchange URL

timeout

30.0 / 30000

Per-request timeout (s / ms)

max_retries

maxRetries

2

Retries on 429/5xx

account_id

accountId

—

Account scope

project_id

projectId

—

Project scope

default_headers

defaultHeaders

—

Extra headers on every request

PreviousHighflame Services NextProduction Patterns

Last updated 1 month ago