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

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.9-cp313-cp313-manylinux_2_31_x86_64.whl (568.4 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.9-cp313-cp313-macosx_13_0_arm64.whl (350.8 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.9-cp312-cp312-win_amd64.whl (333.4 kB view details)

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.9-cp312-cp312-manylinux_2_31_x86_64.whl (569.8 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.9-cp312-cp312-macosx_13_0_arm64.whl (350.0 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.9-cp311-cp311-win_amd64.whl (339.3 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.9-cp311-cp311-manylinux_2_31_x86_64.whl (524.9 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.9-cp311-cp311-macosx_13_0_arm64.whl (345.9 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 edb5e3a19ef7f7ae1a131da8cee48b35747d412878696876e150c14a561592ba
MD5 c4a22ffc8ff768f79e9d828f03b38907
BLAKE2b-256 b05ced60c7e5cb9777e3508bd7cb2c1186bb57870c993cc3a608d5bebdd966b1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 7c842e5df2677717d8c1dafad2ddad174b79160ad5dc92db04a7d09add00dcad
MD5 144d2133366995798b49b87c52cb20ed
BLAKE2b-256 66df78318de6acdc1cf507ebd67563b93a384d9b1db069246b3ec7fb3447457c

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 102d00911ef322e11c5f5d75dddfd7ad6fee14de28c0c5402bc076ca9fa990fd
MD5 4c4e75b122cec0edddbd98769bd4ce30
BLAKE2b-256 33cba3d64cb9465671ac3652b93fe507ac4bb15ad0da4c75a74a4f139ba75891

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 d87c7d57df700168ad21c444fa25418c721fb61291545bed2f69169e90bc2fef
MD5 1d3d011ee0d1cfb612b179cf78a39ace
BLAKE2b-256 a6e213c79ab52038f9e7b5aae48d70725a2a7dc5fbc31fe4e6fe842187a9c9bc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 81fe3454d9eafac8fc1357fa34f07e3e8594661c1a533978ebbff2c3715114c6
MD5 4f44a59e638207c44d9de8c7b2cbd828
BLAKE2b-256 c1c1336b01124fab0d24201de367a2b08238e26564963ff3684d5ec6cdc3dc96

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 a50285f29a38210bc963f11af075bebb883b2e16c7e014118eb2f4d358eeaab3
MD5 1a9479112489acfd18850e376ea05b3e
BLAKE2b-256 f710346cf09ae8216dad4c4846110047877f184f6d1a9d05cfc75c8e8526dea8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 bf4638e62cbe2f48011be9742da27b0ce75b124dd44bb54637e4a8b7cd881b25
MD5 ffd343add83806030bde396fdbc1afd6
BLAKE2b-256 80f06dff0c5c0a78052bb9c9e58d87bb48279cb750825ce1e09a90b4dfbc143c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 49095bd904c9f1cc9e6a32d812ba1a71a379e4c5aff4ad9522ca1c871ca3266b
MD5 b146f0a27010ca37676f1456393e5687
BLAKE2b-256 6c7cba33a7f484b401865a9a4ce94608ded9ea665306a6b5a69964ae93a555b6

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.9-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 dd1060c90ff13ef071c34f0feb20c8ba1f41e0b9d5fbdfef1e44d84216a5ed12
MD5 b88c994fee9f24dfc93144a4cdb27751
BLAKE2b-256 4a6904a4f584eb500049265c7ea2155e9feba7d32fc107b68e87f56429218cce

See more details on using hashes here.

Provenance

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