@kindgi/guardrails 0.0.0-bootstrap.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +78 -1
- package/dist/action-handler.d.ts +82 -0
- package/dist/action-handler.d.ts.map +1 -0
- package/dist/action-handler.js +120 -0
- package/dist/action-handler.js.map +1 -0
- package/dist/checks.d.ts +9 -0
- package/dist/checks.d.ts.map +1 -0
- package/dist/checks.js +235 -0
- package/dist/checks.js.map +1 -0
- package/dist/define-check.d.ts +93 -0
- package/dist/define-check.d.ts.map +1 -0
- package/dist/define-check.js +110 -0
- package/dist/define-check.js.map +1 -0
- package/dist/define.d.ts +27 -0
- package/dist/define.d.ts.map +1 -0
- package/dist/define.js +126 -0
- package/dist/define.js.map +1 -0
- package/dist/engine.d.ts +49 -0
- package/dist/engine.d.ts.map +1 -0
- package/dist/engine.js +198 -0
- package/dist/engine.js.map +1 -0
- package/dist/errors.d.ts +91 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +4 -0
- package/dist/errors.js.map +1 -0
- package/dist/execution-strategy.d.ts +80 -0
- package/dist/execution-strategy.d.ts.map +1 -0
- package/dist/execution-strategy.js +96 -0
- package/dist/execution-strategy.js.map +1 -0
- package/dist/guardrail.schema.json +261 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/judge.d.ts +31 -0
- package/dist/judge.d.ts.map +1 -0
- package/dist/judge.js +171 -0
- package/dist/judge.js.map +1 -0
- package/dist/types.d.ts +407 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +11 -0
- package/dist/types.js.map +1 -0
- package/package.json +64 -4
- package/src/action-handler.ts +179 -0
- package/src/checks.ts +236 -0
- package/src/define-check.ts +207 -0
- package/src/define.ts +146 -0
- package/src/engine.ts +271 -0
- package/src/errors.ts +107 -0
- package/src/execution-strategy.ts +184 -0
- package/src/guardrail.schema.json +261 -0
- package/src/index.ts +79 -0
- package/src/judge.ts +221 -0
- package/src/types.ts +455 -0
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { GuardrailError, JudgeMissingError, ScopeMismatchError } from './errors.js';
|
|
2
|
+
import { type ExecutionStrategy } from './execution-strategy.js';
|
|
3
|
+
import type { CheckRegistry, EvaluationBindings, EvaluationResult, Guardrail, RunTrace } from './types.js';
|
|
4
|
+
/** Expose the built-in registry so callers can extend it with adapter strategies. */
|
|
5
|
+
export declare function builtInStrategies(): readonly ExecutionStrategy[];
|
|
6
|
+
/**
|
|
7
|
+
* Evaluate one guardrail against a run trace. Handles:
|
|
8
|
+
* - Scope check (mode + agent + flow + tenant filters).
|
|
9
|
+
* - Dispatch by `kind` through `bindings.strategies` (or the built-ins):
|
|
10
|
+
* zero-llm → check.evaluate; llm-judge → invokeJudge; external → an
|
|
11
|
+
* `invalid-guardrail` error unless the caller registered its own
|
|
12
|
+
* `external` strategy.
|
|
13
|
+
* - Action derivation from `guardrail.action.on-violation`.
|
|
14
|
+
* - Compliance evidence emission on violation (if bindings.compliance
|
|
15
|
+
* is set and the trace carries a `projectId`).
|
|
16
|
+
* - Action-handler invocation on violation (if bindings.actions is set);
|
|
17
|
+
* an action with no registered handler returns `unknown-action`.
|
|
18
|
+
*
|
|
19
|
+
* Returns:
|
|
20
|
+
* - `{ kind: 'ok', value: EvaluationResult }` — guardrail applied + evaluated.
|
|
21
|
+
* - `{ kind: 'skip', reason }` — guardrail didn't apply (scope mismatch).
|
|
22
|
+
* - `{ kind: 'err', error }` — evaluation failed (unknown kind or check,
|
|
23
|
+
* judge missing or unroutable), or the violation's action has no
|
|
24
|
+
* handler in `bindings.actions` (`unknown-action`, after the violation
|
|
25
|
+
* was recorded).
|
|
26
|
+
*/
|
|
27
|
+
export type EvaluationOutcome = {
|
|
28
|
+
readonly kind: 'ok';
|
|
29
|
+
readonly value: EvaluationResult;
|
|
30
|
+
} | {
|
|
31
|
+
readonly kind: 'skip';
|
|
32
|
+
readonly reason: ScopeMismatchError;
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: 'err';
|
|
35
|
+
readonly error: GuardrailError | JudgeMissingError;
|
|
36
|
+
};
|
|
37
|
+
export declare function evaluateGuardrail(guardrail: Guardrail, checks: CheckRegistry, trace: RunTrace, bindings?: EvaluationBindings): Promise<EvaluationOutcome>;
|
|
38
|
+
/**
|
|
39
|
+
* Evaluate every guardrail in the list against a trace. Order-independent —
|
|
40
|
+
* each check is a pure function over the trace. Returns one outcome per
|
|
41
|
+
* guardrail.
|
|
42
|
+
*/
|
|
43
|
+
export declare function evaluateAll(guardrails: readonly Guardrail[], checks: CheckRegistry, trace: RunTrace, bindings?: EvaluationBindings): Promise<readonly EvaluationOutcome[]>;
|
|
44
|
+
/**
|
|
45
|
+
* Extract only the violations from a batch of outcomes — convenience for
|
|
46
|
+
* callers that want to apply enforcement actions.
|
|
47
|
+
*/
|
|
48
|
+
export declare function violations(outcomes: readonly EvaluationOutcome[]): readonly EvaluationResult[];
|
|
49
|
+
//# sourceMappingURL=engine.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,EACL,KAAK,iBAAiB,EAMvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,QAAQ,EAET,MAAM,YAAY,CAAC;AAqBpB,qFAAqF;AACrF,wBAAgB,iBAAiB,IAAI,SAAS,iBAAiB,EAAE,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEjF,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,QAAQ,EACf,QAAQ,GAAE,kBAAuB,GAChC,OAAO,CAAC,iBAAiB,CAAC,CA0G5B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,QAAQ,EACf,QAAQ,GAAE,kBAAuB,GAChC,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAEvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,gBAAgB,EAAE,CAM9F"}
|
package/dist/engine.js
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
// Copyright (C) 2026 Kindgi Inc.
|
|
3
|
+
import { createExecutionStrategyRegistry, externalStrategy, makeLlmJudgeStrategy, zeroLlmStrategy, } from './execution-strategy.js';
|
|
4
|
+
import { invokeJudge } from './judge.js';
|
|
5
|
+
/**
|
|
6
|
+
* Default strategy registry seeded with the built-ins (`zero-llm`,
|
|
7
|
+
* `llm-judge`, `external`). Cached so repeated `evaluateGuardrail`
|
|
8
|
+
* calls don't reinstantiate the registry.
|
|
9
|
+
*/
|
|
10
|
+
let defaultRegistry;
|
|
11
|
+
function getDefaultStrategyRegistry() {
|
|
12
|
+
if (defaultRegistry === undefined) {
|
|
13
|
+
defaultRegistry = createExecutionStrategyRegistry([
|
|
14
|
+
zeroLlmStrategy,
|
|
15
|
+
makeLlmJudgeStrategy((config, capability, trace, bindings) => invokeJudge(config, capability, trace, bindings)),
|
|
16
|
+
externalStrategy,
|
|
17
|
+
]);
|
|
18
|
+
}
|
|
19
|
+
return defaultRegistry;
|
|
20
|
+
}
|
|
21
|
+
/** Expose the built-in registry so callers can extend it with adapter strategies. */
|
|
22
|
+
export function builtInStrategies() {
|
|
23
|
+
return getDefaultStrategyRegistry().list();
|
|
24
|
+
}
|
|
25
|
+
export async function evaluateGuardrail(guardrail, checks, trace, bindings = {}) {
|
|
26
|
+
const scope = checkScope(guardrail, trace);
|
|
27
|
+
if (scope !== null)
|
|
28
|
+
return { kind: 'skip', reason: scope };
|
|
29
|
+
// Check-registry lookup is delegated to each strategy — `zero-llm`
|
|
30
|
+
// resolves the check inside its evaluate; strategies like
|
|
31
|
+
// `sandbox-code` or `external` don't consult the CheckRegistry at
|
|
32
|
+
// all. Keeps the engine strategy-agnostic.
|
|
33
|
+
const strategies = bindings.strategies ?? getDefaultStrategyRegistry();
|
|
34
|
+
const strategy = strategies.get(guardrail.kind);
|
|
35
|
+
if (strategy === undefined) {
|
|
36
|
+
return {
|
|
37
|
+
kind: 'err',
|
|
38
|
+
error: {
|
|
39
|
+
code: 'invalid-guardrail',
|
|
40
|
+
message: `Guardrail "${guardrail.id}" declares unknown kind "${guardrail.kind}" — no execution strategy registered`,
|
|
41
|
+
issues: [{ path: '/kind', message: `unknown kind: ${guardrail.kind}` }],
|
|
42
|
+
},
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
const strategyOutcome = await strategy.evaluate(guardrail, checks, trace, bindings);
|
|
46
|
+
if (strategyOutcome.kind === 'err') {
|
|
47
|
+
const err = strategyOutcome.error;
|
|
48
|
+
return {
|
|
49
|
+
kind: 'err',
|
|
50
|
+
error: {
|
|
51
|
+
code: err.code,
|
|
52
|
+
message: err.message,
|
|
53
|
+
...(err.issues !== undefined && { issues: err.issues }),
|
|
54
|
+
guardrailId: guardrail.id,
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
const result = strategyOutcome.value;
|
|
59
|
+
const action = result.passed
|
|
60
|
+
? 'noop'
|
|
61
|
+
: guardrail.action['on-violation'];
|
|
62
|
+
const severity = guardrail.severity ?? 'error';
|
|
63
|
+
const evaluation = {
|
|
64
|
+
guardrailId: guardrail.id,
|
|
65
|
+
result,
|
|
66
|
+
action,
|
|
67
|
+
severity,
|
|
68
|
+
at: new Date().toISOString(),
|
|
69
|
+
};
|
|
70
|
+
if (!result.passed && bindings.compliance !== undefined && trace.projectId !== undefined) {
|
|
71
|
+
// Compliance emit needs `projectId` (every evidence record is
|
|
72
|
+
// project-scoped). Skip emit when the trace carries no project
|
|
73
|
+
// scope.
|
|
74
|
+
await bindings.compliance.emit({
|
|
75
|
+
tenantId: trace.tenantId,
|
|
76
|
+
projectId: trace.projectId,
|
|
77
|
+
kind: 'guardrail-violation',
|
|
78
|
+
outcome: 'failed',
|
|
79
|
+
payload: {
|
|
80
|
+
version: 1,
|
|
81
|
+
guardrailId: guardrail.id,
|
|
82
|
+
guardrailName: guardrail.name,
|
|
83
|
+
checkId: guardrail.check,
|
|
84
|
+
checkKind: guardrail.kind,
|
|
85
|
+
severity,
|
|
86
|
+
action: guardrail.action['on-violation'],
|
|
87
|
+
reason: result.reason,
|
|
88
|
+
judgeResponse: result.judgeResponse,
|
|
89
|
+
attributes: result.attributes,
|
|
90
|
+
},
|
|
91
|
+
...(trace.runId !== undefined && {
|
|
92
|
+
provenanceRef: { runId: trace.runId },
|
|
93
|
+
}),
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
// Invoke the registered action handler. Handler errors are logged into
|
|
97
|
+
// the evaluation attributes but don't roll back the evaluation itself —
|
|
98
|
+
// the violation is still recorded. `on-violation` is an open string, so
|
|
99
|
+
// an action nobody registered a handler for fails here, by name.
|
|
100
|
+
if (bindings.actions !== undefined && !result.passed) {
|
|
101
|
+
const handler = bindings.actions.get(action);
|
|
102
|
+
if (handler === undefined) {
|
|
103
|
+
return {
|
|
104
|
+
kind: 'err',
|
|
105
|
+
error: {
|
|
106
|
+
code: 'unknown-action',
|
|
107
|
+
message: `Guardrail "${guardrail.id}" fired action "${action}", but no action handler is registered for it`,
|
|
108
|
+
guardrailId: guardrail.id,
|
|
109
|
+
action,
|
|
110
|
+
},
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
const applied = await handler.apply({ guardrail, evaluation, trace });
|
|
114
|
+
if (applied.kind === 'err') {
|
|
115
|
+
// Attach handler error to the evaluation attributes; don't fail.
|
|
116
|
+
evaluation.result = {
|
|
117
|
+
...evaluation.result,
|
|
118
|
+
attributes: {
|
|
119
|
+
...(evaluation.result.attributes ?? {}),
|
|
120
|
+
actionHandlerError: applied.error,
|
|
121
|
+
},
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
return { kind: 'ok', value: evaluation };
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Evaluate every guardrail in the list against a trace. Order-independent —
|
|
129
|
+
* each check is a pure function over the trace. Returns one outcome per
|
|
130
|
+
* guardrail.
|
|
131
|
+
*/
|
|
132
|
+
export async function evaluateAll(guardrails, checks, trace, bindings = {}) {
|
|
133
|
+
return Promise.all(guardrails.map((inv) => evaluateGuardrail(inv, checks, trace, bindings)));
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Extract only the violations from a batch of outcomes — convenience for
|
|
137
|
+
* callers that want to apply enforcement actions.
|
|
138
|
+
*/
|
|
139
|
+
export function violations(outcomes) {
|
|
140
|
+
const out = [];
|
|
141
|
+
for (const o of outcomes) {
|
|
142
|
+
if (o.kind === 'ok' && !o.value.result.passed)
|
|
143
|
+
out.push(o.value);
|
|
144
|
+
}
|
|
145
|
+
return out;
|
|
146
|
+
}
|
|
147
|
+
function checkScope(guardrail, trace) {
|
|
148
|
+
const scope = guardrail.scope ?? {};
|
|
149
|
+
const when = scope.when ?? 'always';
|
|
150
|
+
if (when === 'ci-only' && trace.mode !== 'ci') {
|
|
151
|
+
return {
|
|
152
|
+
code: 'scope-mismatch',
|
|
153
|
+
message: `guardrail "${guardrail.id}" is ci-only`,
|
|
154
|
+
guardrailId: guardrail.id,
|
|
155
|
+
reason: 'wrong-mode',
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
if (when === 'runtime-only' && trace.mode !== 'runtime') {
|
|
159
|
+
return {
|
|
160
|
+
code: 'scope-mismatch',
|
|
161
|
+
message: `guardrail "${guardrail.id}" is runtime-only`,
|
|
162
|
+
guardrailId: guardrail.id,
|
|
163
|
+
reason: 'wrong-mode',
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
if (scope.agents !== undefined &&
|
|
167
|
+
scope.agents.length > 0 &&
|
|
168
|
+
(trace.agentId === undefined || !scope.agents.includes(trace.agentId))) {
|
|
169
|
+
return {
|
|
170
|
+
code: 'scope-mismatch',
|
|
171
|
+
message: `guardrail "${guardrail.id}" does not apply to agent ${String(trace.agentId)}`,
|
|
172
|
+
guardrailId: guardrail.id,
|
|
173
|
+
reason: 'wrong-agent',
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
if (scope.flows !== undefined &&
|
|
177
|
+
scope.flows.length > 0 &&
|
|
178
|
+
(trace.flowId === undefined || !scope.flows.includes(trace.flowId))) {
|
|
179
|
+
return {
|
|
180
|
+
code: 'scope-mismatch',
|
|
181
|
+
message: `guardrail "${guardrail.id}" does not apply to flow ${String(trace.flowId)}`,
|
|
182
|
+
guardrailId: guardrail.id,
|
|
183
|
+
reason: 'wrong-flow',
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
if (scope.tenants !== undefined &&
|
|
187
|
+
scope.tenants.length > 0 &&
|
|
188
|
+
!scope.tenants.includes(trace.tenantId)) {
|
|
189
|
+
return {
|
|
190
|
+
code: 'scope-mismatch',
|
|
191
|
+
message: `guardrail "${guardrail.id}" does not apply to tenant ${trace.tenantId}`,
|
|
192
|
+
guardrailId: guardrail.id,
|
|
193
|
+
reason: 'wrong-tenant',
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
return null;
|
|
197
|
+
}
|
|
198
|
+
//# sourceMappingURL=engine.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { GuardrailId } from '@kindgi/types';
|
|
2
|
+
/**
|
|
3
|
+
* Errors emitted by @kindgi/guardrails. Every variant carries a `code`
|
|
4
|
+
* for pattern matching; messages are human-readable, not API contract.
|
|
5
|
+
*/
|
|
6
|
+
export type GuardrailError = InvalidGuardrailError | InvalidCheckDefinitionError | UnknownCheckError | InvalidCheckConfigError | JudgeMissingError | JudgeRoutingError | ScopeMismatchError | UnknownActionError;
|
|
7
|
+
/**
|
|
8
|
+
* The judge model couldn't be routed via `@kindgi/capabilities`. Wraps
|
|
9
|
+
* the underlying capability error (usually `capability-unsatisfiable` —
|
|
10
|
+
* no registered provider matches the judge's declared capability).
|
|
11
|
+
*/
|
|
12
|
+
export interface JudgeRoutingError {
|
|
13
|
+
readonly code: 'judge-routing-failed';
|
|
14
|
+
readonly message: string;
|
|
15
|
+
readonly guardrailId: GuardrailId;
|
|
16
|
+
readonly cause: unknown;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* The declaration is invalid. From `defineGuardrail` /
|
|
20
|
+
* `validateGuardrailSpec`: it fails the schema, or (`defineGuardrail`)
|
|
21
|
+
* its registered check has another kind. From the engine: its kind has
|
|
22
|
+
* no registered strategy, it is `llm-judge` without `judgeCapabilities`,
|
|
23
|
+
* or it is `external` and only the built-in `external` strategy is
|
|
24
|
+
* registered.
|
|
25
|
+
*/
|
|
26
|
+
export interface InvalidGuardrailError {
|
|
27
|
+
readonly code: 'invalid-guardrail';
|
|
28
|
+
readonly message: string;
|
|
29
|
+
readonly issues: readonly {
|
|
30
|
+
readonly path: string;
|
|
31
|
+
readonly message: string;
|
|
32
|
+
}[];
|
|
33
|
+
}
|
|
34
|
+
/** The guardrail references a check id that isn't registered. */
|
|
35
|
+
export interface UnknownCheckError {
|
|
36
|
+
readonly code: 'unknown-check';
|
|
37
|
+
readonly message: string;
|
|
38
|
+
readonly guardrailId: GuardrailId;
|
|
39
|
+
readonly checkId: string;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* The guardrail fired an action that no handler in
|
|
43
|
+
* `EvaluationBindings.actions` handles. `on-violation` is an open
|
|
44
|
+
* string, so an unknown name is accepted at define time and surfaces
|
|
45
|
+
* here, when the guardrail fires. The violation itself was already
|
|
46
|
+
* recorded (and compliance evidence emitted) before the lookup.
|
|
47
|
+
*/
|
|
48
|
+
export interface UnknownActionError {
|
|
49
|
+
readonly code: 'unknown-action';
|
|
50
|
+
readonly message: string;
|
|
51
|
+
readonly guardrailId: GuardrailId;
|
|
52
|
+
readonly action: string;
|
|
53
|
+
}
|
|
54
|
+
/** The guardrail's `config` failed the check's own validator. */
|
|
55
|
+
export interface InvalidCheckConfigError {
|
|
56
|
+
readonly code: 'invalid-check-config';
|
|
57
|
+
readonly message: string;
|
|
58
|
+
readonly guardrailId: GuardrailId;
|
|
59
|
+
readonly reason: string;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* `defineCheck` couldn't build the check — either the supplied Zod
|
|
63
|
+
* schema failed to convert via `z.toJSONSchema()`, or the resulting
|
|
64
|
+
* JSON Schema failed to compile as Draft 2020-12.
|
|
65
|
+
*/
|
|
66
|
+
export interface InvalidCheckDefinitionError {
|
|
67
|
+
readonly code: 'invalid-check-definition';
|
|
68
|
+
readonly message: string;
|
|
69
|
+
readonly checkId: string;
|
|
70
|
+
readonly cause: unknown;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* An `llm-judge` guardrail was evaluated without the required bindings
|
|
74
|
+
* (providerRegistry or judgeProvider). Runtime-only error.
|
|
75
|
+
*/
|
|
76
|
+
export interface JudgeMissingError {
|
|
77
|
+
readonly code: 'judge-missing';
|
|
78
|
+
readonly message: string;
|
|
79
|
+
readonly guardrailId: GuardrailId;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Not really an error — surfaced so callers can distinguish "guardrail
|
|
83
|
+
* didn't apply to this trace" from "guardrail applied and passed."
|
|
84
|
+
*/
|
|
85
|
+
export interface ScopeMismatchError {
|
|
86
|
+
readonly code: 'scope-mismatch';
|
|
87
|
+
readonly message: string;
|
|
88
|
+
readonly guardrailId: GuardrailId;
|
|
89
|
+
readonly reason: 'wrong-mode' | 'wrong-agent' | 'wrong-flow' | 'wrong-tenant';
|
|
90
|
+
}
|
|
91
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,qBAAqB,GACrB,2BAA2B,GAC3B,iBAAiB,GACjB,uBAAuB,GACvB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjF;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC;CAC/E"}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { Capability } from '@kindgi/capabilities';
|
|
2
|
+
import type { CheckRegistry, CheckResult, EvaluationBindings, Guardrail, RunTrace } from './types.js';
|
|
3
|
+
/**
|
|
4
|
+
* A strategy that knows how to evaluate one `Guardrail.kind`. Registered
|
|
5
|
+
* once at boot; the engine dispatches by looking up `guardrail.kind`
|
|
6
|
+
* against the strategy registry.
|
|
7
|
+
*
|
|
8
|
+
* Built-in strategies: `zero-llm` (delegates to `CheckRegistry`),
|
|
9
|
+
* `llm-judge` (routes through capabilities + `invokeJudge`), and
|
|
10
|
+
* `external` (returns an "evaluated elsewhere" error).
|
|
11
|
+
*
|
|
12
|
+
* Adapter packages register their own strategies without touching the
|
|
13
|
+
* engine — e.g. a strategy that runs check code in a sandbox, or one
|
|
14
|
+
* that delegates to an external policy engine.
|
|
15
|
+
*/
|
|
16
|
+
export interface ExecutionStrategy {
|
|
17
|
+
readonly kind: string;
|
|
18
|
+
/** Human-friendly name for diagnostics. */
|
|
19
|
+
readonly name?: string;
|
|
20
|
+
/**
|
|
21
|
+
* Evaluate one guardrail against a trace. Returns the CheckResult the
|
|
22
|
+
* engine finalizes into an EvaluationResult; or an error object shaped
|
|
23
|
+
* to be surfaced directly.
|
|
24
|
+
*/
|
|
25
|
+
evaluate(guardrail: Guardrail, checks: CheckRegistry, trace: RunTrace, bindings: EvaluationBindings): Promise<StrategyResult>;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Discriminated result a strategy returns. `ok` produces a CheckResult;
|
|
29
|
+
* `err` surfaces a structured error with a JSON-Pointer-style path so
|
|
30
|
+
* the engine can attach it to the guardrail id it came from.
|
|
31
|
+
*/
|
|
32
|
+
export type StrategyResult = {
|
|
33
|
+
readonly kind: 'ok';
|
|
34
|
+
readonly value: CheckResult;
|
|
35
|
+
} | {
|
|
36
|
+
readonly kind: 'err';
|
|
37
|
+
readonly error: StrategyError;
|
|
38
|
+
};
|
|
39
|
+
export interface StrategyError {
|
|
40
|
+
/** Discriminant matching the engine's GuardrailError union or a sub-code. */
|
|
41
|
+
readonly code: string;
|
|
42
|
+
readonly message: string;
|
|
43
|
+
readonly issues?: readonly {
|
|
44
|
+
readonly path: string;
|
|
45
|
+
readonly message: string;
|
|
46
|
+
}[];
|
|
47
|
+
/** Filled in by the engine — the guardrail id currently evaluating. */
|
|
48
|
+
readonly guardrailId?: string;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Registry the engine consults at dispatch time. Register once; every
|
|
52
|
+
* subsequent `evaluateGuardrail` call sees the additional strategy.
|
|
53
|
+
*/
|
|
54
|
+
export interface ExecutionStrategyRegistry {
|
|
55
|
+
register(strategy: ExecutionStrategy): void;
|
|
56
|
+
get(kind: string): ExecutionStrategy | undefined;
|
|
57
|
+
list(): readonly ExecutionStrategy[];
|
|
58
|
+
}
|
|
59
|
+
export declare function createExecutionStrategyRegistry(seed?: readonly ExecutionStrategy[]): ExecutionStrategyRegistry;
|
|
60
|
+
/** `zero-llm` — delegate to the registered `Check` via CheckRegistry. */
|
|
61
|
+
export declare const zeroLlmStrategy: ExecutionStrategy;
|
|
62
|
+
/**
|
|
63
|
+
* `external` — placeholder for guardrails evaluated by an external
|
|
64
|
+
* service: it always returns an `invalid-guardrail` error. Callers that
|
|
65
|
+
* want external evaluation register their own `external` strategy that
|
|
66
|
+
* routes to their service.
|
|
67
|
+
*/
|
|
68
|
+
export declare const externalStrategy: ExecutionStrategy;
|
|
69
|
+
/**
|
|
70
|
+
* Factory for the built-in `llm-judge` strategy. Takes the judge
|
|
71
|
+
* function as a parameter so this module does not import judge.ts; the
|
|
72
|
+
* engine passes `invokeJudge`.
|
|
73
|
+
*/
|
|
74
|
+
export declare function makeLlmJudgeStrategy(invokeJudge: (config: unknown, capability: Capability, trace: RunTrace, bindings: EvaluationBindings) => Promise<CheckResult | {
|
|
75
|
+
readonly error: {
|
|
76
|
+
readonly code: string;
|
|
77
|
+
readonly message: string;
|
|
78
|
+
};
|
|
79
|
+
}>): ExecutionStrategy;
|
|
80
|
+
//# sourceMappingURL=execution-strategy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"execution-strategy.d.ts","sourceRoot":"","sources":["../src/execution-strategy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CACN,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjF,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACjD,IAAI,IAAI,SAAS,iBAAiB,EAAE,CAAC;CACtC;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,GAAE,SAAS,iBAAiB,EAAO,GACtC,yBAAyB,CAc3B;AAID,yEAAyE;AACzE,eAAO,MAAM,eAAe,EAAE,iBAkB7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAmB9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,CACX,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,kBAAkB,KACzB,OAAO,CACV,WAAW,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CACtF,GACA,iBAAiB,CA8BnB"}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
// Copyright (C) 2026 Kindgi Inc.
|
|
3
|
+
export function createExecutionStrategyRegistry(seed = []) {
|
|
4
|
+
const strategies = new Map();
|
|
5
|
+
for (const s of seed)
|
|
6
|
+
strategies.set(s.kind, s);
|
|
7
|
+
return {
|
|
8
|
+
register(strategy) {
|
|
9
|
+
strategies.set(strategy.kind, strategy);
|
|
10
|
+
},
|
|
11
|
+
get(kind) {
|
|
12
|
+
return strategies.get(kind);
|
|
13
|
+
},
|
|
14
|
+
list() {
|
|
15
|
+
return [...strategies.values()];
|
|
16
|
+
},
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
// ============ built-in strategies ============
|
|
20
|
+
/** `zero-llm` — delegate to the registered `Check` via CheckRegistry. */
|
|
21
|
+
export const zeroLlmStrategy = {
|
|
22
|
+
kind: 'zero-llm',
|
|
23
|
+
name: 'Zero-LLM check',
|
|
24
|
+
async evaluate(guardrail, checks, trace, bindings) {
|
|
25
|
+
const check = checks.get(guardrail.check);
|
|
26
|
+
if (check === undefined) {
|
|
27
|
+
return {
|
|
28
|
+
kind: 'err',
|
|
29
|
+
error: {
|
|
30
|
+
code: 'unknown-check',
|
|
31
|
+
message: `Guardrail "${guardrail.id}" references unregistered check "${guardrail.check}"`,
|
|
32
|
+
},
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
const config = (guardrail.config ?? {});
|
|
36
|
+
const result = await check.evaluate(config, trace, bindings);
|
|
37
|
+
return { kind: 'ok', value: result };
|
|
38
|
+
},
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* `external` — placeholder for guardrails evaluated by an external
|
|
42
|
+
* service: it always returns an `invalid-guardrail` error. Callers that
|
|
43
|
+
* want external evaluation register their own `external` strategy that
|
|
44
|
+
* routes to their service.
|
|
45
|
+
*/
|
|
46
|
+
export const externalStrategy = {
|
|
47
|
+
kind: 'external',
|
|
48
|
+
name: 'External (not implemented at engine layer)',
|
|
49
|
+
async evaluate() {
|
|
50
|
+
return {
|
|
51
|
+
kind: 'err',
|
|
52
|
+
error: {
|
|
53
|
+
code: 'invalid-guardrail',
|
|
54
|
+
message: 'external-kind guardrails are evaluated outside the engine — register an execution strategy for kind `external`',
|
|
55
|
+
issues: [
|
|
56
|
+
{
|
|
57
|
+
path: '/kind',
|
|
58
|
+
message: 'external kind requires a caller-registered execution strategy',
|
|
59
|
+
},
|
|
60
|
+
],
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
},
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* Factory for the built-in `llm-judge` strategy. Takes the judge
|
|
67
|
+
* function as a parameter so this module does not import judge.ts; the
|
|
68
|
+
* engine passes `invokeJudge`.
|
|
69
|
+
*/
|
|
70
|
+
export function makeLlmJudgeStrategy(invokeJudge) {
|
|
71
|
+
return {
|
|
72
|
+
kind: 'llm-judge',
|
|
73
|
+
name: 'LLM judge',
|
|
74
|
+
async evaluate(guardrail, _checks, trace, bindings) {
|
|
75
|
+
if (guardrail.judgeCapabilities === undefined) {
|
|
76
|
+
return {
|
|
77
|
+
kind: 'err',
|
|
78
|
+
error: {
|
|
79
|
+
code: 'invalid-guardrail',
|
|
80
|
+
message: `llm-judge guardrail "${guardrail.id}" missing judgeCapabilities`,
|
|
81
|
+
issues: [{ path: '/judgeCapabilities', message: 'required for kind=llm-judge' }],
|
|
82
|
+
},
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
const judged = await invokeJudge(guardrail.config ?? {}, guardrail.judgeCapabilities, trace, bindings);
|
|
86
|
+
if ('error' in judged) {
|
|
87
|
+
return {
|
|
88
|
+
kind: 'err',
|
|
89
|
+
error: { code: judged.error.code, message: judged.error.message },
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
return { kind: 'ok', value: judged };
|
|
93
|
+
},
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
//# sourceMappingURL=execution-strategy.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"execution-strategy.js","sourceRoot":"","sources":["../src/execution-strategy.ts"],"names":[],"mappings":"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"}
|