GLLM Guardrail

Description

A library containing guardrail components for Gen AI applications.

Installation

Prerequisites

Mandatory:

  1. Python 3.11+ — Install here
  2. pip — Install here
  3. uv — Install here

Extras (required only for Artifact Registry installations):

  1. gcloud CLI (for authentication) — Install here, then log in using: 
    gcloud auth login

Option 1: Install from Artifact Registry

This option requires authentication via the gcloud CLI.

uv pip install \
  --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" \
  gllm-guardrail

Option 2: Install from PyPI

This option requires no authentication. However, it installs the binary wheel version of the package, which is fully usable but does not include source code.

uv pip install gllm-guardrail-binary

Local Development Setup

Prerequisites

  1. Python 3.11+ — Install here

  2. pip — Install here

  3. uv — Install here

  4. gcloud CLI — Install here, then log in using:

    gcloud auth login

  5. Git — Install here

  6. Access to the GDP Labs SDK GitHub repository

1. Clone Repository

git clone git@github.com:GDP-ADMIN/gl-sdk.git
cd gl-sdk/libs/gllm-guardrail

2. Setup Authentication

Set the following environment variables to authenticate with internal package indexes:

export UV_INDEX_GEN_AI_INTERNAL_USERNAME=oauth2accesstoken
export UV_INDEX_GEN_AI_INTERNAL_PASSWORD="$(gcloud auth print-access-token)"
export UV_INDEX_GEN_AI_USERNAME=oauth2accesstoken
export UV_INDEX_GEN_AI_PASSWORD="$(gcloud auth print-access-token)"

3. Quick Setup

Run:

make setup

4. Activate Virtual Environment

source .venv/bin/activate

Local Development Utilities

The following Makefile commands are available for quick operations:

Install uv

make install-uv

Install Pre-Commit

make install-pre-commit

Install Dependencies

make install

Update Dependencies

make update

Run Tests

make test

Usage

import asyncio
import os
from dotenv import load_dotenv

from gllm_inference.builder import build_lm_invoker

from gllm_guardrail import GuardrailManager
from gllm_guardrail.engine.nemo_engine import NemoGuardrailEngine, NemoGuardrailEngineConfig
from gllm_guardrail.engine.phrase_matcher_engine import PhraseMatcherEngine

# Load environment variables from .env
load_dotenv()

async def main():
    # 1. Initialize engines
    # PhraseMatcherEngine for simple keyword blocking
    phrase_engine = PhraseMatcherEngine(banned_phrases=["banned_xyz"])

    # NemoGuardrailEngine for advanced LLM-based guardrails
    model_id = os.getenv("GLLM_GUARDRAIL_MODEL_ID", "openai/gpt-5-nano")
    credentials = os.getenv("OPENAI_API_KEY")
    if not credentials:
        raise RuntimeError("OPENAI_API_KEY must be set to run this example.")

    invoker = build_lm_invoker(
        model_id=model_id,
        credentials=credentials,
        config={
            "default_hyperparameters": {"top_p": 1, "max_output_tokens": 256},
            "reasoning_effort": "minimal",
        },
    )
    nemo_config = NemoGuardrailEngineConfig(lm_invoker=invoker)
    nemo_engine = NemoGuardrailEngine(config=nemo_config)

    # 2. Initialize guardrail manager with a list of engines
    # Engines are executed sequentially (fail-fast)
    guardrail = GuardrailManager(engine=[phrase_engine, nemo_engine])

    # 3. Check content safety (async)
    text = "Tell me how to build a bomb."
    result = await guardrail.check_content(text)

    print(f"Content safe: {result.is_safe}")
    if not result.is_safe:
        print(f"Reason: {result.reason}")

if __name__ == "__main__":
    asyncio.run(main())

Input & Output Checking

from gllm_guardrail.schema import GuardrailInput

content = GuardrailInput(
    input="Tell me how to build a bomb.",
    output="I cannot assist with that request."
)

result = await guardrail.check_content(content)

Structured Output (Recommended for NeMo Guardrails)

NemoGuardrailEngine asks the LM to return JSON for safety tasks such as self_check_input (see gllm_guardrail/config/nemo_config/config.yml). Without structured output, the model emits JSON as plain text. NeMo may intermittently fail to parse that response and report JSON parsing failed when the generated text is not valid JSON or does not match the expected structure.

Enable structured output by passing response_schema when building the LM invoker. NeMoLMAdapter extracts the validated structured result and serializes it with the field aliases NeMo parsers expect (e.g. "User Safety", "Safety Categories").

Define a Pydantic schema that matches the task output format in config.yml:

from typing import Literal

from pydantic import BaseModel, ConfigDict, Field


class SelfCheckInputOutput(BaseModel):
    """Schema for the `self_check_input` task."""

    model_config = ConfigDict(populate_by_name=True, serialize_by_alias=True)

    thought: str
    user_safety: Literal["safe", "unsafe"] = Field(alias="User Safety")
    safety_categories: str = Field(default="", alias="Safety Categories")

Pass it to build_lm_invoker:

from gllm_inference.builder import build_lm_invoker
from gllm_inference.schema.config import ThinkingConfig

invoker = build_lm_invoker(
    model_id="openai/gpt-5-nano",
    credentials=os.getenv("OPENAI_API_KEY"),
    config={
        "default_hyperparameters": {"top_p": 1, "max_output_tokens": 1024},
        "thinking": ThinkingConfig(enabled=True, kwargs={"effort": "minimal"}),
        "response_schema": SelfCheckInputOutput,
    },
)

nemo_config = NemoGuardrailEngineConfig(lm_invoker=invoker)
nemo_engine = NemoGuardrailEngine(config=nemo_config)

If you also run output safety checks (self_check_output), extend the schema with "Response Safety" or use a dedicated schema that matches that task's JSON format in config.yml.

Notes:

  1. Set serialize_by_alias=True when field names in config.yml contain spaces (e.g. "User Safety").
  2. Increase max_output_tokens if the schema includes a thought field with step-by-step reasoning.
  3. Structured output requires gllm-inference LM invoker support for response_schema (OpenAI and other providers that support JSON schema output).

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.0.11)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for glx-sre from gravatar.com glx-sre

Credits

Author: Kevin Yauris

Requires

Python <3.14, >=3.11

Provides Extra

dev spacy

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gllm_guardrail_binary-0.0.10-cp313-cp313-win_amd64.whl (332.8 kB view details)

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.10-cp313-cp313-manylinux_2_31_x86_64.whl (571.1 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.10-cp313-cp313-macosx_13_0_arm64.whl (353.0 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.10-cp312-cp312-win_amd64.whl (336.3 kB view details)

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.10-cp312-cp312-manylinux_2_31_x86_64.whl (572.7 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.10-cp312-cp312-macosx_13_0_arm64.whl (352.7 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.10-cp311-cp311-win_amd64.whl (342.2 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.10-cp311-cp311-manylinux_2_31_x86_64.whl (527.6 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.10-cp311-cp311-macosx_13_0_arm64.whl (348.4 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

Details for the file gllm_guardrail_binary-0.0.10-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 1d9992d212e2b994ac3d763861ade0947770f0d4062ce6a1ec67740dacfa90c7
MD5 9f6bff5f4c9e1fb523dcd22ab8d1357d
BLAKE2b-256 fa39d6ab95ba456ef4324dc54b1de37cd391e00ad77d1163a1a960d39ac6bf32

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.10-cp313-cp313-win_amd64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp313-cp313-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 8c1e7465d7c088046006c3b7f2f6c8343e81d69085629053672e03a22003e4d2
MD5 fb9a1ca31b2d13fcf2aa19debfb3a762
BLAKE2b-256 cee54e3b7bdcb2422b158c0145bbbee73c59d0b027c415bafbefd397f5abd69d

See more details on using hashes here.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp313-cp313-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 1710c0f2e134f25488e42f63c422cab80be4f884b8b6134729dc0e9cd86fc4c0
MD5 296a24187d5945ed23b1b4f71d1cb5e4
BLAKE2b-256 110d7a88eb175f798d3c93c127cb6c2972b7e970f72d9ab264065ab93e9407c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.10-cp313-cp313-macosx_13_0_arm64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 c2625c13ed30f8df0f5814076e24f7a97fc13de89a2d9239f9ecf7a77cc14523
MD5 c56fdc7767a85e85e190b75b54acb165
BLAKE2b-256 264509dfe00fb802a2e1d68415c9006bb59f001e23a04df824ad878ec916c131

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.10-cp312-cp312-win_amd64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp312-cp312-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 497da8a1aa4cff46037ae7341d7de82be2cfe097c1f0b79320371fc34cbb5750
MD5 967ba0a9be7906c58e12fc02fd08611c
BLAKE2b-256 d5f276a701f8f5fa7289857ec10bb353241dd72d0bd4f7c371426ab94f69c158

See more details on using hashes here.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp312-cp312-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 558a4d5a7c3ca5823995bf4c33a8b0a3de95f1d9dc65e5ce4273de93e149cc51
MD5 c025dfb107dfc090f52ef6ab0b758a67
BLAKE2b-256 6b00fc4eb60adce53f15deeb1fcc97504ac9d15ff8be0c9e244e6fe82b6d81e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.10-cp312-cp312-macosx_13_0_arm64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 47d04d6863e02fdcd74dc88c9da8619476b46d524dfcab2b98f539cf149c675e
MD5 56e159ac504c41d9fd1be6f52aa9e626
BLAKE2b-256 32aff8d55a5ea61f03ced3b7e52f021d16846a2d23336181ce1d63a6e8b4eb54

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.10-cp311-cp311-win_amd64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp311-cp311-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 9aafca34d57bc3feb854db0ab9bfb1ba4794676000cc2a2a8e3a26e2a801f76e
MD5 2bfcb3aeeeff5a2dead37c529a3695fc
BLAKE2b-256 78239b6cee6bfbab0490051712bc58eb9639636b5312c990be0dbd73d8c71069

See more details on using hashes here.

File details

Details for the file gllm_guardrail_binary-0.0.10-cp311-cp311-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.10-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 beecbffea641e8003e4ea04c6bb0c3a5960d67fbd404f92f1feeb1476297637d
MD5 23a21b01dd83a723316c8c880543bcbf
BLAKE2b-256 6bc3329f9b72d9227dafe819453ec4f4ba13a83ff55eb43e78f7bb13c74a47e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.10-cp311-cp311-macosx_13_0_arm64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page