Skip to main content

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

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

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.13-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.13-cp313-cp313-macosx_13_0_arm64.whl (355.1 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.13-cp312-cp312-manylinux_2_31_x86_64.whl (574.6 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.13-cp312-cp312-macosx_13_0_arm64.whl (354.8 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.13-cp311-cp311-win_amd64.whl (344.3 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.13-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.13-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.13-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ffb04d3a36274bed7bf7cb230e09789c521f670f7cc11c3b4fef3e76d512195a
MD5 fa45b429740e79ffdb67485b05889ff7
BLAKE2b-256 d5fbff25e492b5fa85120a58848ac1bd77c77a7f7e11d1447ca16cce1af99f86

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 6b4c354612259a31628211ddb9ca606a3f2315e791a19b522c95432c6c3310d7
MD5 7fadacdd67fb0e28a6f87112ec60f1dd
BLAKE2b-256 e8565ddd7c5d048eeb5732c9f23fadc2613cf755eda11a37bea02751fcfae900

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 4d9f227e67092d9c3c29a9961ed68dc877e165ce75fd2d5b031c55736fc391fa
MD5 41fe5e9a9dcea54b5f0467e27103ddde
BLAKE2b-256 e2b9ace48089e870212a774d1d0efc637a57197f09973c26789529ed57ada12b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 0c311963b52143333ef24a968c895ccd660b4d212233a0f01e17960b80ee2c5c
MD5 0a14b7dcf6d148b2345463e5220cc441
BLAKE2b-256 42ec2e64dc3ff3ea162b8a1d18744a025d7dc987ef5b9615675e54b59a57b8b6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 e47de63fe9caa4e9d6230dae0a0df5c727a510b9456206e5269233ea7dd08ebd
MD5 0a22f0704027ff36e2bcf7ee3ee51e5e
BLAKE2b-256 0078448a2bfa804a68852797e5bcde2f887d8a4f643812932355b341daec8495

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 966bbdb606f9feb32aa30849e6c4ff07c6e3d28618b4ba7a89529ead90fc649b
MD5 a95c36018054016f76d9fc7a5bcc603c
BLAKE2b-256 51c2126ff587e3012d8cfa10b5903285b68846cbb8634b814ec92e033e132e53

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 7701e2bd2d3180aeea6dd01b5f2c9650cf6166fa621d8926f3b5e875b7ca0304
MD5 3c4881616af88026aa5bcacdc596baf3
BLAKE2b-256 7828639027eea21555ea774b41d0952d180d5c2dd50d53d4dbbe1bb0da834007

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 4aa83f66dd419e73a1d300d68bca54db77047e271647e14d8c02dae7dd7e8948
MD5 ed6cd46635754f29dda3381fb7f3e722
BLAKE2b-256 44d9fca6b5fcc3dc2aa8d10244898edf6fce93db87fda3141e404787f59415ce

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.13-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 98c778c28f4e94cc0e5dc2df78c74071883662abbcd65a569b2311157d33f3f2
MD5 a3b26df7ca00078995031be89214ae9e
BLAKE2b-256 d5d3278932d7b466c0afea7173fcc648b265b69cc27b1a3f73af4e034213c2dc

See more details on using hashes here.

Provenance

The following attestation bundles were made for gllm_guardrail_binary-0.0.13-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