Skip to content

Commit c43a351

Browse files
RobGeadaRobGeada
authored
Merge pull request #30 from trustyai-explainability/MoreReadme
CHORE: Flesh out README
2 parents db210ad + 0871e90 commit c43a351

File tree

1 file changed

+121
-2
lines changed

1 file changed

+121
-2
lines changed

‎README.md

Lines changed: 121 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,135 @@
1-
# Detectors for the FMS Guardrails Orchestrator
1+
# Detector Algorithms for the FMS Guardrails Orchestrator
22

33
[FMS Guardrails Orchestrator](https://github.com/foundation-model-stack/fms-guardrails-orchestrator) is an open source project led by IBM which provides a server for invocation of detectors on text generation input and output, and standalone detections.
44

5-
This repository is intended to provide a collection of detectors that are supported by [the TrustyAI team](https://github.com/trustyai-explainability).
5+
This repository is intended to provide a collection of detector algorithms and microservices that are supported by [the TrustyAI team](https://github.com/trustyai-explainability).
66

77
## Detectors
88

99
At the moment, the following detectors are supported:
1010

1111
- `huggingface` -- a generic detector class that is intended to be compatible with any [AutoModelForSequenceClassification](https://huggingface.co/docs/transformers/en/model_doc/auto#transformers.AutoModelForSequenceClassification) or a specific kind of [AutoModelForCausalLM](https://huggingface.co/docs/transformers/en/model_doc/auto#transformers.AutoModelForCausalLM), namely [GraniteForCausalLM](https://github.com/ibm-granite/granite-guardian); this detector exposes `/api/v1/text/contents` and thus, could be configured to be a detector of type: `text_contents` within the FMS Guardrails Orchestrator framework. This detector is also intended to be deployed as a [KServe](https://github.com/kserve/kserve) inference service.
12+
- `llm_judge` -- Integrates the [vLLM Judge](https://github.com/trustyai-explainability/vllm_judge) library to use LLM-as-a-judge based guardrailing architecture
13+
- `builtIn` -- Small, lightweight detection functions that are deployed out-of-the-box alongside the [Guardrails Orchestrator](https://github.com/foundation-model-stack/fms-guardrails-orchestrator). The built-in detectors provide a number of heuristic or algorithmic detection functions, such as:
14+
- Regex-based detections, with pre-written regexes for flagging various Personally Identifiable Information items like emails or phone numbers, as well as the ability to provide custom regexes
15+
- File-type validations, for verifying if model input/output is valid JSON, XML, or YAML
1216

1317

18+
## Building
1419

20+
* `huggingface`: podman build -f detectors/Dockerfile.hf detectors
21+
* `llm_judge`: podman build -f detectors/Dockerfile.llm_judge detectors
22+
* `builtIn`: podman build -f detectors/Dockerfile.builtIn detectors
1523

24+
## Running locally
25+
* `builtIn`: podman run -p 8080:8080 $BUILT_IN_IMAGE
1626

27+
### File Type Validation Example
28+
```bash
29+
curl -X POST http://localhost:8080/api/v1/text/contents \
30+
-H "Content-Type: application/json" \
31+
-d '{
32+
"contents": [
33+
"{\"hello\": \"message\"}",
34+
"not valid json"
35+
],
36+
"detector_params": {
37+
"file_type": [
38+
"json"
39+
]
40+
}
41+
}'
42+
```
43+
Response:
44+
```json
45+
[
46+
[],
47+
[
48+
{
49+
"start": 0,
50+
"end": 14,
51+
"text": "not valid json",
52+
"detection": "invalid_json",
53+
"detection_type": "file_type",
54+
"score": 1.0,
55+
"evidences": null
56+
}
57+
]
58+
]
59+
```
60+
61+
### PII Validation Example
62+
```bash
63+
curl -X POST http://localhost:8080/api/v1/text/contents \
64+
-H "Content-Type: application/json" \
65+
-d '{
66+
"contents": [
67+
"Hi my email is [email protected]",
68+
"There is a party@my house and you can reach me at 123-456-7890"
69+
],
70+
"detector_params": {
71+
"regex": [
72+
"email", "us-phone-number"
73+
]
74+
}
75+
}' | jq
76+
```
77+
Response:
78+
```json
79+
[
80+
[
81+
{
82+
"start": 15,
83+
"end": 26,
84+
"text": "[email protected]",
85+
"detection": "email_address",
86+
"detection_type": "pii",
87+
"score": 1.0,
88+
"evidences": null
89+
}
90+
],
91+
[
92+
{
93+
"start": 50,
94+
"end": 62,
95+
"text": "123-456-7890",
96+
"detection": "us-phone-number",
97+
"detection_type": "pii",
98+
"score": 1.0,
99+
"evidences": null
100+
}
101+
]
102+
]
103+
```
104+
105+
### Get list of built-in detection algorithms:
106+
```bash
107+
curl http://localhost:8080/registry | jq
108+
```
109+
Response:
110+
```json
111+
{
112+
"regex": {
113+
"credit-card": "Detect credit cards in the text contents (Visa, MasterCard, Amex, Discover, Diners Club, JCB) with Luhn check",
114+
"email": "Detect email addresses in the text contents",
115+
"ipv4": "Detect IPv4 addresses in the text contents",
116+
"ipv6": "Detect IPv6 addresses in the text contents",
117+
"us-phone-number": "Detect US phone numbers in the text contents",
118+
"us-social-security-number": "Detect social security numbers in the text contents",
119+
"uk-post-code": "Detect UK post codes in the text contents",
120+
"$CUSTOM_REGEX": "Replace $CUSTOM_REGEX with a custom regex to define your own regex detector"
121+
},
122+
"file_type": {
123+
"json": "Detect if the text contents is not valid JSON",
124+
"xml": "Detect if the text contents is not valid XML",
125+
"yaml": "Detect if the text contents is not valid YAML",
126+
"json-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided JSON schema. To specify a schema, replace $SCHEMA with a JSON schema.",
127+
"xml-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided XML schema. To specify a schema, replace $SCHEMA with an XML Schema Definition (XSD)",
128+
"yaml-with-schema:$SCHEMA": "Detect if the text contents does not satisfy a provided schema. To specify a schema, replace $SCHEMA with a JSON schema. That's not a typo, you validate YAML with a JSON schema!"
129+
}
130+
}
131+
132+
```
133+
134+
## API
135+
See [IBM Detector API](https://foundation-model-stack.github.io/fms-guardrails-orchestrator/?urls.primaryName=Detector+API)

0 commit comments

Comments
 (0)