Metadata-Version: 2.4
Name: crocotiger-engine
Version: 0.3.0
Summary: Sentence-level prompt guardrail engine — build and validate against a SentenceValidator. Framework adapters (LangChain/LlamaIndex) live in the separate `crocotiger` package.
License-Expression: LicenseRef-TekDatum-Commercial
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: EULA.md
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: sentence-transformers==5.1.2
Requires-Dist: torch==2.13.0
Requires-Dist: pandas==2.3.3
Requires-Dist: numpy==2.0.1
Requires-Dist: pyarrow==23.0.1
Requires-Dist: sqlmodel==0.0.24
Requires-Dist: pydantic==2.11.7
Requires-Dist: dspy==3.0.3
Requires-Dist: litellm==1.87.0
Requires-Dist: openai>=2.24.0
Requires-Dist: google-genai==1.48.0
Requires-Dist: logfire>=3.0.0
Requires-Dist: tqdm==4.67.3
Requires-Dist: rich==13.9.4
Requires-Dist: pypdf2==3.0.1
Requires-Dist: unstructured==0.24.0
Requires-Dist: scrapy==2.17.0
Requires-Dist: regex==2024.11.6
Requires-Dist: scikit-learn==1.6.1
Requires-Dist: sqlalchemy
Requires-Dist: typing_extensions
Requires-Dist: python-dotenv
Requires-Dist: boto3==1.39.10
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Dynamic: license-file

# crocotiger-engine

Sentence-level prompt guardrail — a compiled binary engine.

`crocotiger-engine` is the engine that powers the [`crocotiger`](https://pypi.org/project/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

```bash
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:

```python
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

```python
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

| Field | Type | Meaning |
|---|---|---|
| `valid` | `bool` | `False` means the prompt was blocked |
| `reason_code` | `str` | Why it was accepted/rejected |
| `duration` | `float` | Validation time in milliseconds |

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

```python
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`](https://pypi.org/project/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.
