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

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.11-cp313-cp313-manylinux_2_31_x86_64.whl (574.5 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.11-cp313-cp313-macosx_13_0_arm64.whl (356.0 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.11-cp312-cp312-win_amd64.whl (339.1 kB view details)

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.11-cp312-cp312-manylinux_2_31_x86_64.whl (575.8 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.11-cp312-cp312-macosx_13_0_arm64.whl (355.6 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.11-cp311-cp311-win_amd64.whl (345.0 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.11-cp311-cp311-manylinux_2_31_x86_64.whl (530.8 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.11-cp311-cp311-macosx_13_0_arm64.whl (351.7 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 7ad98e15662180580cad67f14e98669ee6d8b68c9c5a2e67af3c38e136f6fea3
MD5 fc9f3c90798053377d4862f10a7cdd07
BLAKE2b-256 472b6124574f64ed9edbecf1a3f6ff3559c37202ea6d060d96ebe496d16762cb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 d6a590423408f7d17431e91f5bedfadb676dcae47223eba2a47c3770ffde3faa
MD5 7d436c0fc946522fa3490c16df22effd
BLAKE2b-256 244315dc7e1d7c831a1b6aaf3a5a218e156a7c9091a24efcc3363ec48c6dfefc

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 8431fd3b5860f893803db22266bf99a0ca9328d4324e62252422dc045f58d6fc
MD5 e0d0934f0edaeb700a39252ab7ecaedd
BLAKE2b-256 a70f129cafaeec704b84877c4e6196742bc2aa12575dab8bd549d0d1e1733ae4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 5bf0921b312a1f5fc3b5c46b57889f16675b790dc77c93dff4fa9199b1bfa866
MD5 331748f689e23ece25655ee119287016
BLAKE2b-256 9af4a35f5187cf55ea1491820b977937282e4c767ae930023e9ebd80b8aab62b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 461d53c7075e1d8ff1dc368bf2b1ea78941295c7039e525a848da128776be1e2
MD5 82b10fc15df623c1932ceda50cccb88e
BLAKE2b-256 bd18b8795156fe822827b0e0ce1cfc9f0c4605b8069831c9372c69c4792cdfd2

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 4e7ce4fff043a1c7e9332602e996deb72a5fed7f17fa79e68158b076aeae0bb4
MD5 aa08470c58139a4cb4f3158bd2378ddd
BLAKE2b-256 754047c6d055ad9fb85ea241bc223c4e7c067d1c3a8a31a0c0efcc5b61f24dd5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 bf76cf99a9b492e3758725e16e8e2d87b43b6baeeff1e6475693000836ddd787
MD5 327eed59496d9dfe86f385bc02b995f5
BLAKE2b-256 b2ac41f46b0ca363a3df7559e6cadff1e976abc9856b61bfea32536640cc94bb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 9d31d663fb41dab5262d39f6c5946e11f047fec4e8352d3622d45d81f041352c
MD5 79088e4947eab6f47849648f6bc1fd70
BLAKE2b-256 f3762239d8c5fc83c53517caac0523af43073632d3a321aa3bb56dfdbb8db421

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.11-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 98936bf79964c193a82e8ea9ba54005a5658215e23da084edf5fc6d96ee0f128
MD5 e3428d45b91774d11f5567d4f4eca819
BLAKE2b-256 33e4782c2b03cc239033e69d9e2e9aca5e0eecc3b68a5f1208bd19adff276618

See more details on using hashes here.

Provenance

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