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.13)

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.12-cp313-cp313-win_amd64.whl (335.2 kB view details)

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.12-cp313-cp313-manylinux_2_31_x86_64.whl (573.3 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.12-cp313-cp313-macosx_13_0_arm64.whl (355.2 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.12-cp312-cp312-win_amd64.whl (338.4 kB view details)

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.12-cp312-cp312-manylinux_2_31_x86_64.whl (574.5 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.12-cp312-cp312-macosx_13_0_arm64.whl (354.9 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.12-cp311-cp311-win_amd64.whl (344.2 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.12-cp311-cp311-manylinux_2_31_x86_64.whl (529.7 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.12-cp311-cp311-macosx_13_0_arm64.whl (350.9 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 7fabff890004bc59e164c7fea5e598c82eb0276995361ab5f210ae8802920f7c
MD5 ff13dcec4ea8bdc3afd695713d00073d
BLAKE2b-256 741165b329df852f2186d4097743c810f6ffed22ddd825450718dacd47da6084

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.12-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.12-cp313-cp313-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 eddf8ebd595550dabacc1b0ca1bf5e2ac251bbc8e10acab7cac086a6f1ba3a2a
MD5 908f0f9ad20811e6018799dd0a0ada26
BLAKE2b-256 3bb55deb188fc81b4eb51e18d62b3f818a774561a31937d08ffef14147b06aae

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 e8507e5a8efb1173550660e779caaaf092619d930aaeeae2d8f4dfb34eea979f
MD5 5d30e0227091191ccb150cfcffdaa706
BLAKE2b-256 d5b9992bfb6baf11b2314d963b5307257cfec423306bf9a851f81982c8a14199

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.12-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.12-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 aa2157ab23b17a0958ad3e047b7f9386a0ef68c1741c77c4154f7c4c4e4712bf
MD5 8c5ac86216dd93f7b9a0259ff3006e6e
BLAKE2b-256 dfa3d4320cc0a1444febd3b4d6507d83705915e168cf13240d4af8a8d45b953b

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.12-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.12-cp312-cp312-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 cb42556013cf08ad13404a4edf21cf728bf0e1245aeadc42d2ac175dcad7b648
MD5 61b70c1461de45b8f1cbf9ff9c2aca38
BLAKE2b-256 6d2dfcdc5fc25e908f8450a7752231e2168e06749fa49d348d56124f8653fa38

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 89b731913c331439446e02faec7d0976953e820538233c0b6ae4e6baaac409d3
MD5 4562b93029d7671f1faa862d19fdf61f
BLAKE2b-256 696b738342653c64d702d19c7635a9c61439bedcdc9cc3176e5739df1d6f163e

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.12-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.12-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 7a67a635a2e348b708946497dafced3405c46e023860b82faa254427518a401e
MD5 e1a1726f800d9292afd697b32e0fd7d6
BLAKE2b-256 fdafef3012ccf225cbf3e49e08d3e75ef78b95a05d6404ced1eb869437590de6

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.12-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.12-cp311-cp311-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 de68e0dcae04509c24b5208d8e2ff66c5b821a7abd4388d4803cc934e0036258
MD5 56fff1955a2efc4af0b52749cd0bfd76
BLAKE2b-256 48ba8e1cbcb6d6e602abc2ab8a156db4b1f316cff9369dd1a8b98f18892c1c20

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.12-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 fa80071a23bff9f0e6f76eb81847a38b02748ec35db236303d22cd91ca153038
MD5 3f44715ef45fd4ce90cfeaaf09cd976e
BLAKE2b-256 9c205b878d68e3359da7be8732585ae7989b6fa2b42b750bd83af24f5372d8a5

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.12-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 Sentry Error logging StatusPage Status page