crocotiger-engine

Sentence-level prompt guardrail — a compiled binary engine.

crocotiger-engine is the engine that powers the crocotiger guardrail SDK.

Features

• Build a SentenceValidator from a topic description — LLM-driven accept/reject corpus generation, embedding, and threshold auto-tuning
• Validate a prompt against the fitted validator, with a clear accept/reject decision
• Framework-agnostic — LangChain/LlamaIndex adapters live in the separate crocotiger package

Installation

pip install crocotiger-engine

Prebuilt wheels are provided for CPython 3.11–3.13 on Linux, macOS, and Windows.

Quick start

Build or load a validator

Building is the slow, costly part (LLM calls to generate attack/topic datasets) — check for an existing artifact first and reuse it:

from pathlib import Path
from crocotiger_engine import build_sentence_validator, SentenceValidator

VALIDATOR_PATH = Path("./my-guardrail-build/sentence_validator")

if VALIDATOR_PATH.exists():
    sentence_validator = SentenceValidator.load_from(str(VALIDATOR_PATH))
else:
    sentence_validator = build_sentence_validator(
        output_dir=VALIDATOR_PATH.parent,
        topic="customer support for an online banking product",
        context="a banking customer support assistant",
        restricted_topics=["hacking or unauthorized system access"],
        datasets_path="/path/to/your/dataset/corpus",
    )

Validating a prompt directly

import asyncio

result = asyncio.run(sentence_validator.validate("How do I hack into a database?"))
result.valid          # False means the prompt was blocked
result.reason_code    # why it was accepted/rejected

SentenceValidatorResult at a glance

It's a plain object, not a dict. This is a deliberately trimmed view — the internal engine's result also carries per-call diagnostic detail (nearest matching list entries, internal classification), which isn't exposed here since it isn't meaningful outside the internal guardrail-builder product this engine is derived from.

get_options() at a glance

options = sentence_validator.get_options()

Returns a SentenceValidatorOptions with name, model_name, accept_threshold, reject_threshold, review_criteria, use_density — config/tuning values only. It does not include the raw accept/reject list content the validator was built from.

Credentials and data

• At least one of OPENAI_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY — only needed the first time you build a validator (dataset generation). Loading a previously-built validator needs none of these.
• A local dataset corpus — required only when building from scratch, not when loading an existing validator. build_sentence_validator downloads it automatically from S3 on first use (bundled read-only-scoped credential).

Usage

Most users should install crocotiger, which provides SentenceValidatorMiddleware/SentenceValidatorLLMGuard adapters that call the same sentence_validator.validate() under the hood — wiring this into a LangChain agent or a LlamaIndex query engine without calling .validate() yourself.

License

Commercial / proprietary. Use is governed by the TekDatum End User License Agreement. See the accompanying EULA. All rights reserved.