Guards

A guard is one check, configured. This page covers the five guard types Opik offers: what each one detects, what you configure on it, and what it needs in order to run.

You put guards into a policy in the Opik UI, and your application runs that policy by name. Configuration lives in Opik; your code only calls validate.

Quickstart

Create a policy in the UI with the guards you want, then build a guardrail from it and validate your text. A failing check raises, so the protected path only continues when validate returns.

1
from opik.guardrails import Guardrail
2
from opik import exceptions
3
4
guardrail = Guardrail.from_stored_policies(names=["no-financial-advice"])
5
6
llm_response = "You should buy some NVIDIA stocks!"
7
8
try:
9
    guardrail.validate(llm_response)
10
except exceptions.GuardrailValidationFailed as e:
11
    print(e)

The call is blocking, since the whole point is to stop your application before it returns a response you would not want a user to see.

The five guard types

Providers like OpenAI or Anthropic already block the most universal risks, such as harmful or malicious content. Opik’s guards cover the residual risks, which tend to be specific to your product and need configuring in more detail.

Each guard picks the method that gives the best balance of accuracy, latency, and cost for its problem — traditional NLP for personal data, small language models for topic and injection detection, a full LLM for nuanced judgement.

All five are configured the same way: switch the guard on in a policy and fill in its fields.

PII

Detects sensitive personal information such as names, addresses, email addresses, phone numbers, and credit card details.

What you configure

• Personal data to block — which categories to look for. The UI offers the categories that come up most often; the underlying detector supports a much longer list.
• Threshold — the confidence at or above which a detection counts. Lower is stricter.

The method used here leverages traditional NLP models for tokenization and named entity recognition.

Topic

Keeps inputs and outputs on topic.

What you configure

• Restricted topics — text must not match any of these.
• Allowed topics — text must match at least one of these.
• Threshold — the score at or above which a topic counts as detected.

You can set either list or both. Restricted topics are the common case: name what your application must stay away from.

This guardrail relies on a small language model, specifically a zero-shot classifier.

Prompt injection

Detects attempts to make your LLM ignore, override, or reveal its instructions, along with other malicious queries. Use it on user inputs to block jailbreaks and injection attacks before they reach your model.

What you configure

• Threshold — the injection probability at or above which the guard fails. Lower is stricter.

The model is fixed: this guard runs Opik Guard, a classifier we trained for this job. On a self-hosted deployment the server needs a Hugging Face token to fetch it — see the server configuration.

This guardrail relies on a small language model fine-tuned for prompt-injection detection.

LLM judge

Checks text against a rule you describe in plain language. Because a full LLM does the judging, it catches nuanced issues that heuristics and classifiers miss — giving regulated advice, drifting from your brand voice.

What you configure

• Instructions — the rule, in your own words. For example: “The text must not provide medical advice, diagnoses, or dosage recommendations.”
• Model — which model judges. It must be available through an LLM provider configured under AI Providers.

This is the one guard that does not use the guardrails server. Its model call is recorded as a nested LLM span under the guardrail span, so you can inspect the exact prompt, response, and token usage in the trace.

This guardrail relies on a large language model, and is best suited to complex checks where accuracy matters more than latency.

Custom classifier

Runs a model you fine-tuned yourself — a check that answers one yes-or-no question specific to your product, such as whether a reply is off-brand. Opik trains it on your labeled examples and serves it, so there is nothing to deploy.

What you configure

• Model — which of your models to run. Only models that are ready can be selected.
• Threshold — the score at or above which the guard fails.

See Custom models for how to fine-tune one.

This guardrail relies on a small language model fine-tuned on your own labeled examples.

Handling a failure

A failing guardrail raises an exception, and your application code needs to handle it — retry, fall back to a safe default, or return an error, whichever suits the situation.

Streaming responses and long inputs

Call guardrail.validate repeatedly to check a response chunk by chunk, or to check parts of a long input separately. The results are added as additional spans on the same trace.

1
for chunk in response:
2
    try:
3
        guardrail.validate(chunk)
4
    except exceptions.GuardrailValidationFailed as e:
5
        print(e)

Working with the results

When a guardrail fails on an LLM call, Opik adds the information to the trace automatically. You can filter the traces in your project down to those that failed a guardrail.

To see how often each guardrail is failing over time, open the Metrics section of the project.

Performance and limits

The guardrails backend uses a GPU automatically if one is available. For production use, running it on a GPU node is strongly recommended.

Current limits:

• Topic guardrail: the maximum input size is 1024 tokens
• Both Topic and PII guardrails support English language

Defining guards in code

Guards can also be listed inline instead of stored in a policy. This is handy for a quick experiment or a check that only one script cares about.

1
from opik.guardrails import Guardrail, PII, Topic
2
from opik import exceptions
3
4
guardrail = Guardrail(
5
    guards=[
6
        Topic(restricted_topics=["finance", "health"], threshold=0.9),
7
        PII(blocked_entities=["CREDIT_CARD", "PERSON"]),
8
    ]
9
)
10
11
try:
12
    guardrail.validate("You should buy some NVIDIA stocks!")
13
except exceptions.GuardrailValidationFailed as e:
14
    print(e)

Each guard type has a matching class, taking the same settings the UI exposes:

Manual guardrails

For a check that fits none of the five guard types — a one-off heuristic, or a business rule that is genuinely just code — you can run it yourself and log the result to Opik directly. No guard class and no guardrails server are involved.

1
import opik
2
import opik.opik_context
3
import traceback
4
5
# Brand mention detection
6
competitor_brands = [
7
    "OpenAI",
8
    "Anthropic",
9
    "Google AI",
10
    "Microsoft Copilot",
11
    "Amazon Bedrock",
12
    "Hugging Face",
13
    "Mistral AI",
14
    "Meta AI",
15
]
16
17
opik_client = opik.Opik()
18
19
20
def check_competitor_mentions(generation: str, trace_id: str) -> str:
21
    # Start the guardrail span first so the duration is accurately captured
22
    guardrail_span = opik_client.span(name="Guardrail", input={"generation": generation}, type="guardrail", trace_id=trace_id)
23
24
    # Manual guardrail logic - detect competitor brand mentions
25
    found_brands = []
26
    for brand in competitor_brands:
27
        if brand.lower() in generation.lower():
28
            found_brands.append(brand)
29
30
    # The key `guardrail_result` is required by Opik guardrails and must be either "passed" or "failed"
31
    if found_brands:
32
        guardrail_result = "failed"
33
        output = {"guardrail_result": guardrail_result, "found_brands": found_brands}
34
    else:
35
        guardrail_result = "passed"
36
        output = {"guardrail_result": guardrail_result}
37
38
    # Log the spans
39
    guardrail_span.end(output=output)
40
41
    # Upload the guardrail data for project-level metrics
42
    guardrail_data = {
43
        "project_name": opik_client._project_name,
44
        "entity_id": trace_id,
45
        "secondary_id": guardrail_span.id,
46
        "name": "TOPIC", # Supports either "TOPIC" or "PII"
47
        "result": guardrail_result,
48
        "config": {"blocked_brands": competitor_brands},
49
        "details": output,
50
    }
51
    try:
52
        opik_client.rest_client.guardrails.create_guardrails(guardrails=[guardrail_data])
53
    except Exception as e:
54
        traceback.print_exc()
55
56
    return generation
57
58
59
@opik.track
60
def main():
61
    good_generation = "You should use our AI platform for your machine learning projects!"
62
    check_competitor_mentions(good_generation, opik.opik_context.get_current_trace_data().id)
63
64
    bad_generation = "You might want to try OpenAI or Google AI for your project instead."
65
    check_competitor_mentions(bad_generation, opik.opik_context.get_current_trace_data().id)
66
67
68
if __name__ == "__main__":
69
    main()

The guardrail spans appear alongside your traces just like the built-in guards, showing what was detected and whether the check passed or failed.

Next steps