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

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.8-cp313-cp313-manylinux_2_31_x86_64.whl (566.4 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.8-cp313-cp313-macosx_13_0_arm64.whl (349.4 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.8-cp312-cp312-win_amd64.whl (333.1 kB view details)

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.8-cp312-cp312-manylinux_2_31_x86_64.whl (568.1 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.8-cp312-cp312-macosx_13_0_arm64.whl (348.2 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.8-cp311-cp311-win_amd64.whl (339.1 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.8-cp311-cp311-manylinux_2_31_x86_64.whl (523.5 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.8-cp311-cp311-macosx_13_0_arm64.whl (344.9 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 8c1960b9162a3c84b4d49a0af9dd2798dd761d95591da8a3c2c36a57ace5f75a
MD5 ff764bd20e83f0be1f1f98c111a36dff
BLAKE2b-256 19717c0c07041b758d4fc3f17a35af303bd85810561f6f000927484bcbf86ae4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 6dfe09f3de66e4157c8d8f013a78d18a99ae39ff34ff32bbdac561c3401becf0
MD5 7ee9622327730c73293df934ec9b5e32
BLAKE2b-256 3582d284e50ca36c2fae0357b257259f10e569eb963448bc5cd9a516134ec367

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 05a7a959f7cedef017915631a411da1f34c17561cfbad17697dfcb53f6e047be
MD5 1c1eee55126105ba49be66629da9ba67
BLAKE2b-256 abf32522cdc19912ba4fbfb7fb2314553117064559465e27522d7b6b6197e74c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 06a0fe2f77da2ab052a9ae3d1573174d0e84f997ff6c842c00668fd086930cfb
MD5 7c82917c144f14fc013cd2e13adefd7f
BLAKE2b-256 2d8b24e08a4be0881513eaa4a9a266c02379cf9c8eaf89ecc99c3d47cd32b76e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 d7c3a6a476da1178a778caa83962047449f88757e68d9dd5be169b3cecc6fa17
MD5 7c460ddef1de36519b42d03d988687f4
BLAKE2b-256 7e686b969700bb249aa990bada6dd1d3c3a055e6489684cca1dd431292573867

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 133999b69be9c7c60d8e40240b6ea50c9c3df5cccd273a7cf490cdff4f2d2ffb
MD5 783d2b22b3ccf7cab2ffc13479fcf427
BLAKE2b-256 a7da463dd428043f50089ba9c5e624fb6b531db662df757d5c6cdb3c46122ca2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 960d8ff57d2aa2e818cfab5c6e139365f2a0a27d3efc44796bfae60e16632ab7
MD5 a803141975b2d5849cbf62f03fffc1de
BLAKE2b-256 d22f1f1338c81624d19dd94f718a6bd51bec73d82b22ad15ffa9581cd5a5498b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 56138efc4abc188c64ed00dd6942702182577ab9431e33c7c523e2a8377c25f1
MD5 2adc460289abb5ef078a5d6965961ed1
BLAKE2b-256 5238fd5084fdd7735667a29ba83185737c1b694c3e3078c362473cf880eeb30d

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.8-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 4062c162cdc3109758d6a054a6b6a802724963b004fd3e180bf0949ae2a34409
MD5 8ef934d018544cbc6c4d7536066dbfd0
BLAKE2b-256 2b049808ce54e40e460e600016c6b4c1a9dbc5c65bddfcdec6ec0a4f8996a7a2

See more details on using hashes here.

Provenance

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