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:
Latest release

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

Uploaded CPython 3.13Windows x86-64

gllm_guardrail_binary-0.0.14-cp313-cp313-manylinux_2_31_x86_64.whl (582.2 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.14-cp313-cp313-macosx_13_0_arm64.whl (362.4 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.14-cp312-cp312-win_amd64.whl (343.2 kB view details)

Uploaded CPython 3.12Windows x86-64

gllm_guardrail_binary-0.0.14-cp312-cp312-manylinux_2_31_x86_64.whl (581.7 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.14-cp312-cp312-macosx_13_0_arm64.whl (353.0 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gllm_guardrail_binary-0.0.14-cp311-cp311-win_amd64.whl (346.6 kB view details)

Uploaded CPython 3.11Windows x86-64

gllm_guardrail_binary-0.0.14-cp311-cp311-manylinux_2_31_x86_64.whl (532.6 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gllm_guardrail_binary-0.0.14-cp311-cp311-macosx_13_0_arm64.whl (352.5 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 69b98ac3042997d58c7d3e29b3dddfad1f3a5e97bce364d3a62979f48980e3ef
MD5 e22e5e4ea22a6e414c7ea564e9327e28
BLAKE2b-256 b2eb96a0415f0d44cecaa16f17148c53ee3e1b0006d254651d89fb3cff696cfd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 f4c513cc9f6dfa4b1ec7835a8d354c2b49ce8a7333d431998a99ed5e2cbfd770
MD5 9ab71ffd6e62b3436248a0a46d9ed166
BLAKE2b-256 128e3ebd026fa6b228a4d78c89b7dda1c982206bb31375c26470c2305a140e36

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 ce3bacbba95375039d9a1954214b1581bb0fee2749349f06edd614ace10aa43f
MD5 ebe7869d59eae12fa796f8ef62080323
BLAKE2b-256 e0e7ed89cb48956ddc8411a74ddfce7bce53c7e85374ed70c23442eb1c0e6cc9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 31dc96820041aa37e270568c6b55a35a2ba136ea14b574b6902ef4752db22ce6
MD5 e88561e7df69d185e6f9ed019e5b8d96
BLAKE2b-256 c8640c7422e0dd962080b89ae00d11291cfc90621b3012411501b65a16e685f7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 d6869d4f8bc0a6d2300da2935d12b5410c2c64e82aef949c83eee626bfcbb1b2
MD5 84cdc26039ca88d84435dab52b1783b9
BLAKE2b-256 b71ee15450f4dd49a87ecb113bf7405bfed8e4f0ebee9901fb0c6a77dbe25386

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 84deba24aa09dab6fee1ab56b01757c584144bdf03b6bd0bdc427c322805bdbd
MD5 48d311c85140d204dd31d6cd23ac4d79
BLAKE2b-256 48de407484c5c52fad0017d1c50e9259d2f970cab37039bc82b5543ff19ea6c3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 017138bcded469105e1b20aecda7b58188e07169a0fe7766443925b36b86cb66
MD5 d9fa3ead1e72dd3d533ba3a1c043e283
BLAKE2b-256 890606498a834528a3d1d49b8af4d09fc555d55389c983fdf2ec7096589300fd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 caaef8f61c783deec095da364e77254eb5f98e3d2c921c4ea86006f13101dec4
MD5 3ce5c7d21250ddd9b9e3289b0cdb26d1
BLAKE2b-256 b220db97b043f7633501984f3446b4ce19f3616c6f1250bf166323e393b9674c

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for gllm_guardrail_binary-0.0.14-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 d386c0acef9af26b2a4d1cc326bdb7ba92d06d971a31586401b446846f3f6838
MD5 a4ab5caa9e904a89efd95b5ba4243327
BLAKE2b-256 7c0c8e445444be833045bac02c59f0880412a16605c8db7497dbf7e46052cdc0

See more details on using hashes here.

Provenance

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

Release history Release notifications | RSS feed

This release

0.0.14 This release

9 files

0.0.13

9 files

0.0.12

9 files

0.0.11

9 files

0.0.10

9 files

0.0.9

9 files

0.0.8

9 files

0.0.7.post4

9 files

0.0.7.post3

9 files

0.0.7.post2

9 files

0.0.7.post1

9 files

0.0.7

9 files

0.0.6

8 files

0.0.5

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page