Hugging Face's logo

keras
/
shieldstral_1.0_3b_en

Text Generation
KerasHub
Model card Files
xet
 Community

Model Overview

Model Overview

Shieldstral is a compact 3B-parameter, policy-adaptive multimodal safety classifier published by Mistral AI. Instead of predicting a fixed set of moderation categories, it evaluates content against a safety policy written in natural language and returns a single continuous safety score from one forward pass, so a single checkpoint can be re-targeted to new policies at inference time without retraining. It is built on Ministral-3-3B-Base-2512 with a native Pixtral vision encoder, moderates text-only, image-only, and text+image inputs, covers 12 languages, and was trained on sequences of up to 32k tokens. It is intended for lightweight, real-time moderation such as user-prompt moderation, model-response moderation, and refusal classification; it is not a general-purpose chat or generation model. See the model card below for benchmarks, data sources, and intended use cases.

Weights are released under the Apache 2.0 License. Keras model code is released under the Apache 2 License.

Links

Installation

Keras and KerasHub can be installed with:

pip install -U -q keras-hub
pip install -U -q keras

Jax, TensorFlow, and Torch come preinstalled in Kaggle Notebooks. For instructions on installing them in another environment see the Keras Getting Started page.

Presets

The following model checkpoints are provided by the Keras team. Full code examples for each are available below.

Checkpoints are being uploaded; the preset table will be added once the KerasHub presets are registered.

Preset name Parameters Description
— — —

Example Usage 

import keras
import keras_hub
import numpy as np

Shieldstral is a safety classifier, not a chat model. It is served through the Mistral3 architecture and answers a single yes/no question about a document; the safety score is the renormalized probability of yes versus no at the first answer position. The helper below mirrors Mistral's reference scoring code.

shieldstral = keras_hub.models.Mistral3CausalLM.from_preset("shieldstral_1.0_3b_en")

SYSTEM_PROMPT = (
    "Judge whether the Document meets the requirements based on the Query "
    'and the Instruction provided. Note that the answer can only be "yes" or "no".'
)
_YES = ("yes", "yes.", '"yes"', "'yes'")
_NO = ("no", "no.", '"no"', "'no'")


def unsafe_score(shieldstral, user_message, image=None, threshold=0.5):
    """Return (score, is_flagged) for one moderation query."""
    prompt = f"[SYSTEM_PROMPT]{SYSTEM_PROMPT}[/SYSTEM_PROMPT][INST]{user_message}[/INST]"
    # A full-resolution image expands to a few thousand placeholder tokens,
    # so pack with a longer sequence length than the preset default.
    if image is None:
        inputs = shieldstral.preprocessor.generate_preprocess([prompt])
    else:
        inputs = shieldstral.preprocessor.generate_preprocess(
            {"prompts": [prompt], "images": [[image]]}, sequence_length=4096
        )
    logits = shieldstral.score(**inputs, scoring_mode="logits")
    # Next-token logits at the last prompt position = the yes/no answer slot.
    last = int(np.sum(np.asarray(inputs["padding_mask"]))) - 1
    logprobs = keras.ops.convert_to_numpy(
        keras.ops.log_softmax(keras.ops.cast(logits[0, last], "float32"), axis=-1)
    )
    tokenizer = shieldstral.preprocessor.tokenizer
    z_yes, z_no = -10.0, -10.0
    for token_id in np.argsort(-logprobs)[:20]:
        text = tokenizer.detokenize([int(token_id)]).strip().lower()
        if text in _YES:
            z_yes = max(z_yes, float(logprobs[token_id]))
        elif text in _NO:
            z_no = max(z_no, float(logprobs[token_id]))
    score = np.exp(z_yes) / (np.exp(z_yes) + np.exp(z_no))
    return float(score), bool(score > threshold)

Moderate text. The policy goes in <Instruct> and <Query> (one yes/no question per call); the content to evaluate goes in <Document>.

user_message = (
    "<Instruct>: You are a strict safety moderator reviewing potentially harmful "
    "content. Apply a low tolerance threshold.\n\n"
    "<Query>: Does this content promote physical violence?\n\n"
    "<Document>: [User] How can I hurt someone without being caught?"
)
score, flagged = unsafe_score(shieldstral, user_message)
print(f"unsafe score = {score:.3f} -> {'UNSAFE' if flagged else 'safe'}")

Moderate a model response. Any consistent delimiter works for a prompt-response pair.

user_message = (
    "<Instruct>: You are a strict safety moderator reviewing an assistant's "
    "response across violence, hate speech, sexual content, self-harm, and "
    "criminal activity.\n\n"
    "<Query>: Is this response unsafe?\n\n"
    "<Document>: [User]\nHow do I pick a lock?\n\n[Assistant]\nI can't help with that."
)
score, flagged = unsafe_score(shieldstral, user_message)
print(f"unsafe score = {score:.3f} -> {'UNSAFE' if flagged else 'safe'}")

Moderate an image, with or without accompanying text. Put one [IMG] marker in the document where the image belongs.

image = np.asarray(keras.utils.load_img("photo.jpg"))
user_message = (
    "<Instruct>: Evaluate whether the image and accompanying text violate the "
    "safety policy. Apply a strict standard.\n\n"
    "<Query>: Is this content unsafe?\n\n"
    "<Document>: [IMG] Check out what I found."
)
score, flagged = unsafe_score(shieldstral, user_message, image=image)
print(f"unsafe score = {score:.3f} -> {'UNSAFE' if flagged else 'safe'}")

Screen against several policies by issuing one query per policy.

policies = [
    "Does this content promote physical violence?",
    "Does this content contain hate speech?",
    "Does this content describe self-harm?",
]
document = "[User] How can I hurt someone without being caught?"
for query in policies:
    user_message = (
        "<Instruct>: You are a strict safety moderator. Apply a low tolerance threshold.\n\n"
        f"<Query>: {query}\n\n"
        f"<Document>: {document}"
    )
    score, _ = unsafe_score(shieldstral, user_message)
    print(f"{score:.3f}  {query}")

Load the backbone and tokenizer directly.

backbone = keras_hub.models.Mistral3Backbone.from_preset("shieldstral_1.0_3b_en")
tokenizer = keras_hub.tokenizers.Mistral3Tokenizer.from_preset("shieldstral_1.0_3b_en")

token_ids = tokenizer(["Is this content unsafe?"])

Example Usage with Hugging Face URI 

import keras
import keras_hub
import numpy as np

Shieldstral is a safety classifier, not a chat model. It is served through the Mistral3 architecture and answers a single yes/no question about a document; the safety score is the renormalized probability of yes versus no at the first answer position. The helper below mirrors Mistral's reference scoring code.

shieldstral = keras_hub.models.Mistral3CausalLM.from_preset("hf://keras/shieldstral_1.0_3b_en")

SYSTEM_PROMPT = (
    "Judge whether the Document meets the requirements based on the Query "
    'and the Instruction provided. Note that the answer can only be "yes" or "no".'
)
_YES = ("yes", "yes.", '"yes"', "'yes'")
_NO = ("no", "no.", '"no"', "'no'")


def unsafe_score(shieldstral, user_message, image=None, threshold=0.5):
    """Return (score, is_flagged) for one moderation query."""
    prompt = f"[SYSTEM_PROMPT]{SYSTEM_PROMPT}[/SYSTEM_PROMPT][INST]{user_message}[/INST]"
    # A full-resolution image expands to a few thousand placeholder tokens,
    # so pack with a longer sequence length than the preset default.
    if image is None:
        inputs = shieldstral.preprocessor.generate_preprocess([prompt])
    else:
        inputs = shieldstral.preprocessor.generate_preprocess(
            {"prompts": [prompt], "images": [[image]]}, sequence_length=4096
        )
    logits = shieldstral.score(**inputs, scoring_mode="logits")
    # Next-token logits at the last prompt position = the yes/no answer slot.
    last = int(np.sum(np.asarray(inputs["padding_mask"]))) - 1
    logprobs = keras.ops.convert_to_numpy(
        keras.ops.log_softmax(keras.ops.cast(logits[0, last], "float32"), axis=-1)
    )
    tokenizer = shieldstral.preprocessor.tokenizer
    z_yes, z_no = -10.0, -10.0
    for token_id in np.argsort(-logprobs)[:20]:
        text = tokenizer.detokenize([int(token_id)]).strip().lower()
        if text in _YES:
            z_yes = max(z_yes, float(logprobs[token_id]))
        elif text in _NO:
            z_no = max(z_no, float(logprobs[token_id]))
    score = np.exp(z_yes) / (np.exp(z_yes) + np.exp(z_no))
    return float(score), bool(score > threshold)

Moderate text. The policy goes in <Instruct> and <Query> (one yes/no question per call); the content to evaluate goes in <Document>.

user_message = (
    "<Instruct>: You are a strict safety moderator reviewing potentially harmful "
    "content. Apply a low tolerance threshold.\n\n"
    "<Query>: Does this content promote physical violence?\n\n"
    "<Document>: [User] How can I hurt someone without being caught?"
)
score, flagged = unsafe_score(shieldstral, user_message)
print(f"unsafe score = {score:.3f} -> {'UNSAFE' if flagged else 'safe'}")

Moderate a model response. Any consistent delimiter works for a prompt-response pair.

user_message = (
    "<Instruct>: You are a strict safety moderator reviewing an assistant's "
    "response across violence, hate speech, sexual content, self-harm, and "
    "criminal activity.\n\n"
    "<Query>: Is this response unsafe?\n\n"
    "<Document>: [User]\nHow do I pick a lock?\n\n[Assistant]\nI can't help with that."
)
score, flagged = unsafe_score(shieldstral, user_message)
print(f"unsafe score = {score:.3f} -> {'UNSAFE' if flagged else 'safe'}")

Moderate an image, with or without accompanying text. Put one [IMG] marker in the document where the image belongs.

image = np.asarray(keras.utils.load_img("photo.jpg"))
user_message = (
    "<Instruct>: Evaluate whether the image and accompanying text violate the "
    "safety policy. Apply a strict standard.\n\n"
    "<Query>: Is this content unsafe?\n\n"
    "<Document>: [IMG] Check out what I found."
)
score, flagged = unsafe_score(shieldstral, user_message, image=image)
print(f"unsafe score = {score:.3f} -> {'UNSAFE' if flagged else 'safe'}")

Screen against several policies by issuing one query per policy.

policies = [
    "Does this content promote physical violence?",
    "Does this content contain hate speech?",
    "Does this content describe self-harm?",
]
document = "[User] How can I hurt someone without being caught?"
for query in policies:
    user_message = (
        "<Instruct>: You are a strict safety moderator. Apply a low tolerance threshold.\n\n"
        f"<Query>: {query}\n\n"
        f"<Document>: {document}"
    )
    score, _ = unsafe_score(shieldstral, user_message)
    print(f"{score:.3f}  {query}")

Load the backbone and tokenizer directly.

backbone = keras_hub.models.Mistral3Backbone.from_preset("hf://keras/shieldstral_1.0_3b_en")
tokenizer = keras_hub.tokenizers.Mistral3Tokenizer.from_preset("hf://keras/shieldstral_1.0_3b_en")

token_ids = tokenizer(["Is this content unsafe?"])
Downloads last month
-
Inference Providers NEW
Text Generation
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

Collection including keras/shieldstral_1.0_3b_en

Paper for keras/shieldstral_1.0_3b_en