Interface: Guardrails
Defined in: internal/guardrails/Guardrails.ts:112
Guardrails -- every check around a model call, in one place
About
The gateway knows that rules exist, not what the app's rules check.
Two checks: checkInput on the prompt before the model call, checkOutput on the answer after it. Each runs the gateway's
built-in rules first (prompt not empty, not over maxPromptChars, no prompt-injection marker; answer not truncated, matches
the schema) and the app's inputRules / outputRules only when those passed, so a paid moderation call is never made for a
prompt that is already rejected. The app's rules run in parallel, each under its timeout; a rule that throws or times out is
the ERROR issue rule_error, so a broken rule never lets anything pass (D47). A rule that classifies asks a model through
the judge it receives: one completion on the profile's cheap or main model, checked with the usage adapter, reported to it
and traced like every other call (D57, D59). The severity of an issue is the only verdict: ERROR fails the call, WARNING
flags it (D49).
Sits between the orchestration (prepareCall, checkOutput, parseEditedAnswer), which calls it, and the LLMClient,
which the judge calls go through.
Who needs it
AIGateway, through the orchestration, on every ask, run and resume. Constructed once from
IAIGatewayConfig.guardrails; a host replaces it through IAIGatewayDeps.guardrails.
What needs
IGuardrailsConfig: the app's rules and the limits, fixed at construction. IGuardrailsDeps: the LLMClient and the
ModelRegistry the judge calls use, so the Guardrails are created after them.
Pitfalls
Rules are fixed at construction: there is no addRule, a gateway that needs other rules is constructed again. Rule names
are unique, the app's input rules also against the built-in names; a duplicate throws 5373891090405. The error a rule
threw never reaches the caller's issues, it goes to the server log and to onRuleError only (D107).
Implements
Methods
checkInput()
checkInput(
__namedParameters):Promise<IInputCheck>
Defined in: internal/guardrails/Guardrails.ts:156
checkInput -- screens the prompt before the model call
About
The built-in rules first, the app's only when those passed.
Sanitises the prompt (trims, normalises line endings), then runs the built-in input rules (not empty unless files come
with it, not over maxPromptChars, no prompt-injection marker) and, only when none of them returned an ERROR, the app's
inputRules in parallel. Returns the sanitised prompt, every issue stamped with its rule's name, ok and the trace ids
of the judge calls, which the gateway annotates with the issues (D73). The call's abortSignal reaches every rule and
its judge call; an aborted call rejects with the signal's reason, not with a rule_error (D90).
Who needs it
prepareCall, on the prompt of every ask and run; AIGateway.resume, on the free text a user typed into a question
of the model (D62), with no files.
Parameters
__namedParameters
abortSignal?
AbortSignal
The call's signal: merged into every rule's.
An aborted call rejects with the signal's reason, no rule_error; so does a judge call the usage adapter refused, with that error.
files
IFileRef[]
inlineFiles
The same files with their bytes; the rules' judge sends them to the model.
profile
prompt
string
threadId?
string
Undefined when the call creates a new thread.
userContext
Returns
Promise<IInputCheck>
Implementation of
IGuardrails.checkInput
checkOutput()
checkOutput<
TStructured>(__namedParameters):Promise<IOutputCheck<TStructured>>
Defined in: internal/guardrails/Guardrails.ts:256
checkOutput -- screens the answer after the model call
About
Truncation and schema first, the app's rules only when those passed.
Flags a finishReason LENGTH as the WARNING output_truncated and, with a schema, parses the output against it with
parseStructured. Only when no ERROR came out of that, the app's outputRules run in parallel on the parsed value (or
the text) with the evidence of the call: the question, the KB chunks, the tool results, the user context, the profile and
the thread. Returns the parsed value, every issue stamped with its rule's name, ok and the trace ids of the judge calls,
which the gateway annotates with the issues (D73). The call's abortSignal reaches every rule and its judge call; an
aborted call rejects with the signal's reason, not with a rule_error (D90).
Who needs it
checkOutput of the orchestration, on the answer of every ask and of every run that ended with text (settleRun).
Type Parameters
TStructured
TStructured = unknown
Parameters
__namedParameters
abortSignal?
AbortSignal
The call's signal: merged into every rule's.
An aborted call rejects with the signal's reason, no rule_error; so does a judge call the usage adapter refused, with that error.
chunks
IChunk[]
The knowledge-base chunks that were in the request.
profile
prompt
string
The user's question the answer is for.
result
schema?
ZodType<TStructured, unknown, $ZodTypeInternals<TStructured, unknown>>
Zod schema of the expected answer; omit for a free-text answer.
threadId
string
toolResults
userContext
Returns
Promise<IOutputCheck<TStructured>>
Implementation of
IGuardrails.checkOutput
parseStructured()
parseStructured<
TStructured>(__namedParameters):object
Defined in: internal/guardrails/Guardrails.ts:375
parseStructured -- the schema check of an answer, on its own
About
Text in, the typed value or the issue out; no rule runs.
The model's own structured value is taken when it gave one, else the text is parsed as JSON; the result is validated
against the schema. A text that is not JSON is output_invalid_json, a value the schema rejects is output_schema
(with the first failing field), both ERROR; structured is then absent.
Who needs it
checkOutput, before the output rules; AIGateway.resume, on the text a reviewer edited (D99), which must still match
the schema the run was started with but is not screened by the rules.
Type Parameters
TStructured
TStructured
Parameters
__namedParameters
schema
ZodType<TStructured>
structured?
unknown
The structured value the model returned itself, when any; it is validated instead of the text.
text
string
Returns
object
issues
issues:
IIssue[]
structured?
optionalstructured?:TStructured
Implementation of
IGuardrails.parseStructured