@artemiskit/sdk 0.3.1 → 0.3.3

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.
Files changed (74) hide show
  1. package/CHANGELOG.md +213 -0
  2. package/README.md +44 -1
  3. package/dist/artemiskit.d.ts +149 -0
  4. package/dist/artemiskit.d.ts.map +1 -0
  5. package/dist/builders/index.d.ts +350 -0
  6. package/dist/builders/index.d.ts.map +1 -0
  7. package/dist/builders/index.js +398 -0
  8. package/dist/contracts/index.d.ts +253 -0
  9. package/dist/contracts/index.d.ts.map +1 -0
  10. package/dist/contracts/index.js +99 -0
  11. package/dist/guardian/action-validator.d.ts +92 -0
  12. package/dist/guardian/action-validator.d.ts.map +1 -0
  13. package/dist/guardian/circuit-breaker.d.ts +211 -0
  14. package/dist/guardian/circuit-breaker.d.ts.map +1 -0
  15. package/dist/guardian/guardian.d.ts +213 -0
  16. package/dist/guardian/guardian.d.ts.map +1 -0
  17. package/dist/guardian/guardrails.d.ts +107 -0
  18. package/dist/guardian/guardrails.d.ts.map +1 -0
  19. package/dist/guardian/index.d.ts +35 -0
  20. package/dist/guardian/index.d.ts.map +1 -0
  21. package/dist/guardian/intent-classifier.d.ts +81 -0
  22. package/dist/guardian/intent-classifier.d.ts.map +1 -0
  23. package/dist/guardian/interceptor.d.ts +141 -0
  24. package/dist/guardian/interceptor.d.ts.map +1 -0
  25. package/dist/guardian/policy.d.ts +52 -0
  26. package/dist/guardian/policy.d.ts.map +1 -0
  27. package/dist/guardian/semantic-validator.d.ts +61 -0
  28. package/dist/guardian/semantic-validator.d.ts.map +1 -0
  29. package/dist/guardian/types.d.ts +653 -0
  30. package/dist/guardian/types.d.ts.map +1 -0
  31. package/dist/index.d.ts +23 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +24847 -13653
  34. package/dist/matchers/core.d.ts +81 -0
  35. package/dist/matchers/core.d.ts.map +1 -0
  36. package/dist/matchers/index.d.ts +6 -0
  37. package/dist/matchers/index.d.ts.map +1 -0
  38. package/dist/matchers/jest.d.ts +46 -0
  39. package/dist/matchers/jest.d.ts.map +1 -0
  40. package/dist/matchers/vitest.d.ts +24 -0
  41. package/dist/matchers/vitest.d.ts.map +1 -0
  42. package/dist/types-only.d.ts +31 -0
  43. package/dist/types-only.d.ts.map +1 -0
  44. package/dist/types-only.js +1 -0
  45. package/dist/types.d.ts +377 -0
  46. package/dist/types.d.ts.map +1 -0
  47. package/dist/utils/index.d.ts +112 -0
  48. package/dist/utils/index.d.ts.map +1 -0
  49. package/dist/utils/index.js +104 -0
  50. package/package.json +17 -2
  51. package/src/__tests__/builders.test.ts +445 -0
  52. package/src/__tests__/circuit-breaker.test.ts +704 -0
  53. package/src/__tests__/compare.test.ts +469 -0
  54. package/src/__tests__/contracts.test.ts +354 -0
  55. package/src/__tests__/guardian-modes.test.ts +215 -0
  56. package/src/__tests__/guardrails.test.ts +404 -0
  57. package/src/__tests__/semantic-validator.test.ts +421 -0
  58. package/src/__tests__/utils.test.ts +324 -0
  59. package/src/__tests__/validate.test.ts +307 -0
  60. package/src/artemiskit.ts +478 -5
  61. package/src/builders/index.ts +698 -0
  62. package/src/contracts/index.ts +357 -0
  63. package/src/guardian/circuit-breaker.ts +74 -28
  64. package/src/guardian/guardian.ts +307 -20
  65. package/src/guardian/guardrails.ts +143 -1
  66. package/src/guardian/index.ts +35 -1
  67. package/src/guardian/interceptor.ts +87 -11
  68. package/src/guardian/semantic-validator.ts +399 -0
  69. package/src/guardian/types.ts +413 -2
  70. package/src/index.ts +258 -14
  71. package/src/types-only.ts +276 -0
  72. package/src/types.ts +183 -0
  73. package/src/utils/index.ts +225 -0
  74. package/tsconfig.json +2 -1
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Guardrails Module
3
+ *
4
+ * Provides input/output validation including:
5
+ * - Injection detection (prompt injection, jailbreaks)
6
+ * - PII detection and redaction
7
+ * - Content filtering
8
+ * - Custom validation rules
9
+ */
10
+ import type { ContentCategory, ContentFilterResult, GuardrailResult, InjectionDetection, PIIDetection, PIIType, PatternCategory, PatternConfig, ViolationSeverity } from './types';
11
+ /**
12
+ * Options for custom pattern matching
13
+ */
14
+ export interface CustomPatternOptions {
15
+ /** Case-insensitive matching (default: true) */
16
+ caseInsensitive?: boolean;
17
+ /** Pattern category for categorization */
18
+ category?: PatternCategory;
19
+ /** Severity level for matches */
20
+ severity?: ViolationSeverity;
21
+ }
22
+ /**
23
+ * Match a pattern against content with options
24
+ */
25
+ export declare function matchPattern(content: string, pattern: string | RegExp, options?: CustomPatternOptions): {
26
+ matched: boolean;
27
+ match?: RegExpMatchArray;
28
+ };
29
+ /**
30
+ * Create a custom pattern guardrail
31
+ */
32
+ export declare function createCustomPatternGuardrail(patterns: Array<string | RegExp>, options?: CustomPatternOptions): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
33
+ /**
34
+ * Detect injection attempts in text
35
+ */
36
+ export declare function detectInjection(text: string): InjectionDetection;
37
+ /**
38
+ * Create an injection detection guardrail
39
+ */
40
+ export declare function createInjectionGuardrail(): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
41
+ /**
42
+ * Detect PII in text
43
+ */
44
+ export declare function detectPII(text: string): PIIDetection;
45
+ /**
46
+ * Create a PII detection guardrail
47
+ */
48
+ export declare function createPIIGuardrail(options?: {
49
+ redact?: boolean;
50
+ block?: boolean;
51
+ allowedTypes?: PIIType[];
52
+ }): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
53
+ /**
54
+ * Filter content for harmful categories
55
+ */
56
+ export declare function filterContent(text: string): ContentFilterResult;
57
+ /**
58
+ * Create a content filter guardrail
59
+ */
60
+ export declare function createContentFilterGuardrail(options?: {
61
+ blockedCategories?: ContentCategory[];
62
+ warnCategories?: ContentCategory[];
63
+ }): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
64
+ /**
65
+ * Guardrail configuration options
66
+ */
67
+ export interface GuardrailsConfig {
68
+ /** Enable injection detection */
69
+ injectionDetection?: boolean;
70
+ /** Enable PII detection */
71
+ piiDetection?: boolean;
72
+ /** PII detection options */
73
+ piiOptions?: {
74
+ redact?: boolean;
75
+ block?: boolean;
76
+ allowedTypes?: PIIType[];
77
+ };
78
+ /** Enable content filtering */
79
+ contentFilter?: boolean;
80
+ /** Content filter options */
81
+ contentFilterOptions?: {
82
+ blockedCategories?: ContentCategory[];
83
+ warnCategories?: ContentCategory[];
84
+ };
85
+ /**
86
+ * Pattern matching configuration
87
+ * Controls how custom patterns are matched
88
+ */
89
+ patternConfig?: PatternConfig;
90
+ /**
91
+ * Custom patterns to add to injection detection
92
+ * These are checked in addition to built-in patterns
93
+ */
94
+ customPatterns?: Array<string | RegExp>;
95
+ /**
96
+ * Pattern categories to enable (default: all)
97
+ * Use this to selectively enable pattern categories
98
+ */
99
+ enabledPatternCategories?: PatternCategory[];
100
+ /** Custom guardrails */
101
+ custom?: Array<(content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>>;
102
+ }
103
+ /**
104
+ * Create a composite guardrail from configuration
105
+ */
106
+ export declare function createGuardrails(config?: GuardrailsConfig): Array<(content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>>;
107
+ //# sourceMappingURL=guardrails.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/guardian/guardrails.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EAEnB,eAAe,EACf,kBAAkB,EAElB,YAAY,EAEZ,OAAO,EACP,eAAe,EACf,aAAa,EAEb,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAMjB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,oBAAyB,GACjC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAqBhD;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAChC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAkClF;AA6GD;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAwBhE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,CAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,eAAe,CAAC,CA6B5B;AAwDD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA8BpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB,GACL,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAmClF;AA0ED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CA2B/D;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE;IACP,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC;IACtC,cAAc,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B,GACL,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAkClF;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,4BAA4B;IAC5B,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;KAC1B,CAAC;IAEF,+BAA+B;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE;QACrB,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC;QACtC,cAAc,CAAC,EAAE,eAAe,EAAE,CAAC;KACpC,CAAC;IAEF;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAExC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,eAAe,EAAE,CAAC;IAE7C,wBAAwB;IACxB,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;CAClG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,GAAE,gBAAqB,GAC5B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAiDzF"}
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Guardian Module - Runtime protection for AI/LLM applications
3
+ *
4
+ * Provides comprehensive guardrails to prevent AI agents from performing
5
+ * harmful or unauthorized actions.
6
+ *
7
+ * @example
8
+ * ```typescript
9
+ * import { Guardian, createGuardian } from '@artemiskit/sdk/guardian';
10
+ *
11
+ * const guardian = createGuardian({
12
+ * mode: 'guardian',
13
+ * blockOnFailure: true,
14
+ * });
15
+ *
16
+ * // Wrap your LLM client
17
+ * const protectedClient = guardian.protect(myLLMClient);
18
+ *
19
+ * // Validate tool calls
20
+ * const result = await guardian.validateAction('delete_file', { path: '/etc/passwd' });
21
+ * if (!result.valid) {
22
+ * console.log('Blocked:', result.violations);
23
+ * }
24
+ * ```
25
+ */
26
+ export { Guardian, createGuardian, normalizeGuardianMode, type GuardianConfig } from './guardian';
27
+ export { SemanticValidator, createSemanticValidator } from './semantic-validator';
28
+ export { GuardianInterceptor, GuardianBlockedError, createInterceptor, type InterceptorConfig, type InterceptorStats, type GuardrailFn, } from './interceptor';
29
+ export { ActionValidator, createDefaultActionValidator, type ActionValidatorConfig, type ActionValidationResult, } from './action-validator';
30
+ export { IntentClassifier, createIntentClassifier, type IntentClassifierConfig, type IntentCategory, } from './intent-classifier';
31
+ export { detectInjection, createInjectionGuardrail, detectPII, createPIIGuardrail, filterContent, createContentFilterGuardrail, createGuardrails, matchPattern, createCustomPatternGuardrail, type GuardrailsConfig, type CustomPatternOptions, } from './guardrails';
32
+ export { loadPolicy, parsePolicy, validatePolicy, createDefaultPolicy, mergePolicies, getRulesByType, isRuleEnabled, generatePolicyTemplate, PolicyLoadError, PolicyValidationError, } from './policy';
33
+ export { CircuitBreaker, MetricsCollector, RateLimiter, type CircuitBreakerEvent, type CircuitBreakerEventHandler, type RateLimiterConfig, } from './circuit-breaker';
34
+ export type { GuardianMode, ViolationSeverity, ViolationAction, GuardrailType, Violation, GuardrailResult, PolicyRule, PolicyCondition, GuardianPolicy, CircuitBreakerConfig, RateLimitConfig, CostLimitConfig, ActionDefinition, ActionParameter, ParameterValidation, IntentClassification, PIIDetection, PIIType, PIILocation, InjectionDetection, InjectionType, ContentFilterResult, ContentFlag, ContentCategory, HallucinationCheckResult, Citation, UnsupportedClaim, GuardianMetrics, CircuitBreakerState, CostTracking, GuardianEventType, GuardianEvent, GuardianEventHandler, InterceptedRequest, InterceptedResponse, InterceptedToolCall, InterceptedAgentStep, FrameworkType, FrameworkIntegrationConfig, GuardianModeCanonical, GuardianModeLegacy, GuardianModeAll, ContentValidationConfig, PatternConfig, ValidationCategory, PatternCategory, SemanticValidationResult, SessionStorageType, SessionStorageConfig, SessionMessage, SessionMetrics, ConversationSession, TrustBuildingHeuristicConfig, EscalationHeuristicConfig, ContextManipulationHeuristicConfig, SplitPayloadHeuristicConfig, MultiTurnHeuristics, MultiTurnSemanticConfig, MultiTurnConfig, HeuristicResult, HeuristicResults, MultiTurnValidationResult, ValidateMessageOptions, } from './types';
35
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guardian/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAGlG,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGlF,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,SAAS,EACT,kBAAkB,EAClB,aAAa,EACb,4BAA4B,EAC5B,gBAAgB,EAEhB,YAAY,EACZ,4BAA4B,EAC5B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAEV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,SAAS,EACT,eAAe,EAEf,UAAU,EACV,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,eAAe,EAEf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EAEnB,oBAAoB,EAEpB,YAAY,EACZ,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,QAAQ,EACR,gBAAgB,EAEhB,eAAe,EACf,mBAAmB,EACnB,YAAY,EAEZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EAEpB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EAEpB,aAAa,EACb,0BAA0B,EAE1B,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EAEf,uBAAuB,EACvB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,wBAAwB,EAExB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,4BAA4B,EAC5B,yBAAyB,EACzB,kCAAkC,EAClC,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,SAAS,CAAC"}
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Intent Classifier
3
+ *
4
+ * Analyzes AI/agent intent to determine what it's trying to accomplish,
5
+ * not just the literal action. Uses pattern matching and optionally LLM-based
6
+ * classification to detect potentially risky intents.
7
+ */
8
+ import type { ModelClient } from '@artemiskit/core';
9
+ import type { GuardrailResult, IntentClassification, ViolationSeverity } from './types';
10
+ /**
11
+ * Intent category definition
12
+ */
13
+ export interface IntentCategory {
14
+ name: string;
15
+ description: string;
16
+ riskLevel: ViolationSeverity;
17
+ patterns?: RegExp[];
18
+ keywords?: string[];
19
+ examples?: string[];
20
+ action?: 'allow' | 'warn' | 'block';
21
+ }
22
+ /**
23
+ * Intent classifier configuration
24
+ */
25
+ export interface IntentClassifierConfig {
26
+ /** Pre-defined intent categories */
27
+ categories?: IntentCategory[];
28
+ /** Use LLM for classification */
29
+ useLLM?: boolean;
30
+ /** LLM client for classification */
31
+ llmClient?: ModelClient;
32
+ /** Minimum confidence threshold */
33
+ confidenceThreshold?: number;
34
+ /** Block unknown intents */
35
+ blockUnknown?: boolean;
36
+ /** Block high-risk intents */
37
+ blockHighRisk?: boolean;
38
+ }
39
+ /**
40
+ * Intent Classifier
41
+ *
42
+ * Analyzes text to determine the underlying intent and assess risk.
43
+ */
44
+ export declare class IntentClassifier {
45
+ private config;
46
+ private categories;
47
+ constructor(config?: IntentClassifierConfig);
48
+ /**
49
+ * Classify the intent of a given text
50
+ */
51
+ classify(text: string): Promise<IntentClassification[]>;
52
+ /**
53
+ * Create a guardrail function from this classifier
54
+ */
55
+ asGuardrail(): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
56
+ /**
57
+ * Validate content and return guardrail result
58
+ */
59
+ validate(text: string): Promise<GuardrailResult>;
60
+ /**
61
+ * Add a custom intent category
62
+ */
63
+ addCategory(category: IntentCategory): void;
64
+ /**
65
+ * Remove an intent category
66
+ */
67
+ removeCategory(name: string): void;
68
+ /**
69
+ * Get all categories
70
+ */
71
+ getCategories(): IntentCategory[];
72
+ /**
73
+ * Classify using LLM (for more nuanced understanding)
74
+ */
75
+ private classifyWithLLM;
76
+ }
77
+ /**
78
+ * Create a default intent classifier
79
+ */
80
+ export declare function createIntentClassifier(config?: IntentClassifierConfig): IntentClassifier;
81
+ //# sourceMappingURL=intent-classifier.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"intent-classifier.d.ts","sourceRoot":"","sources":["../../src/guardian/intent-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAa,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,iCAAiC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,mCAAmC;IACnC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4BAA4B;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA0ID;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAAmB;gBAEzB,MAAM,GAAE,sBAA2B;IAU/C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAuD7D;;OAEG;IACH,WAAW,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC;IAO/F;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAyCtD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAI3C;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIlC;;OAEG;IACH,aAAa,IAAI,cAAc,EAAE;IAIjC;;OAEG;YACW,eAAe;CAoC9B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,sBAA2B,GAAG,gBAAgB,CAE5F"}
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Guardian Interceptor
3
+ *
4
+ * Wraps LLM clients to intercept and validate all inputs/outputs.
5
+ * Acts as middleware between the agent and the LLM.
6
+ */
7
+ import type { GenerateOptions, GenerateResult, ModelClient } from '@artemiskit/core';
8
+ import type { GuardianEventHandler, GuardrailResult, InterceptedRequest, Violation } from './types';
9
+ /**
10
+ * Guardrail function signature
11
+ */
12
+ export type GuardrailFn = (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
13
+ /**
14
+ * Interceptor configuration
15
+ */
16
+ export interface InterceptorConfig {
17
+ /** Enable input validation */
18
+ validateInput?: boolean;
19
+ /** Enable output validation */
20
+ validateOutput?: boolean;
21
+ /** Input guardrails to run */
22
+ inputGuardrails?: GuardrailFn[];
23
+ /** Output guardrails to run */
24
+ outputGuardrails?: GuardrailFn[];
25
+ /** Whether to block on validation failure (flat boolean, see shouldBlockViolation for finer control) */
26
+ blockOnFailure?: boolean;
27
+ /**
28
+ * Callback to determine if a specific violation should cause blocking.
29
+ * Use this for mode-aware blocking (e.g., selective mode blocks only high-severity).
30
+ * If provided, this callback is used instead of flat blockOnFailure for per-violation decisions.
31
+ * The callback receives a violation and should return true if it should block.
32
+ */
33
+ shouldBlockViolation?: (violation: Violation) => boolean;
34
+ /** Event handlers */
35
+ onEvent?: GuardianEventHandler;
36
+ /** Log violations */
37
+ logViolations?: boolean;
38
+ /**
39
+ * Callback to check if requests should be allowed (e.g., circuit breaker check).
40
+ * Called before each LLM request. Return false to block the request.
41
+ */
42
+ shouldAllow?: () => {
43
+ allowed: boolean;
44
+ reason?: string;
45
+ };
46
+ }
47
+ /**
48
+ * Interceptor statistics
49
+ */
50
+ export interface InterceptorStats {
51
+ totalRequests: number;
52
+ blockedRequests: number;
53
+ totalViolations: number;
54
+ averageLatencyMs: number;
55
+ inputViolations: number;
56
+ outputViolations: number;
57
+ }
58
+ /**
59
+ * Guardian Interceptor wraps a ModelClient to add validation
60
+ */
61
+ export declare class GuardianInterceptor implements ModelClient {
62
+ readonly provider: string;
63
+ private client;
64
+ private config;
65
+ private stats;
66
+ private requestHistory;
67
+ constructor(client: ModelClient, config?: InterceptorConfig);
68
+ /**
69
+ * Generate with guardrail validation
70
+ */
71
+ generate(options: GenerateOptions): Promise<GenerateResult>;
72
+ /**
73
+ * Get model capabilities (pass-through)
74
+ */
75
+ capabilities(): Promise<import("@artemiskit/core").ModelCapabilities>;
76
+ /**
77
+ * Stream generation with guardrail validation
78
+ *
79
+ * IMPORTANT: Streaming is currently not supported by GuardianInterceptor.
80
+ * This method throws an error to prevent bypassing Guardian protections.
81
+ *
82
+ * Streaming validation is complex because:
83
+ * 1. Input validation must complete before streaming starts
84
+ * 2. Output validation requires the complete response
85
+ * 3. Circuit breaker must be checked per-request
86
+ *
87
+ * For protected LLM access, use the non-streaming `generate()` method.
88
+ * If you need streaming, use the underlying client directly (unprotected).
89
+ *
90
+ * @throws {Error} Always throws - streaming not supported in Guardian
91
+ */
92
+ stream?(_options: GenerateOptions, _onChunk: (chunk: string) => void): AsyncIterable<string>;
93
+ /**
94
+ * Embed text (pass-through)
95
+ */
96
+ embed?(text: string, model?: string): Promise<number[]>;
97
+ /**
98
+ * Close the client
99
+ */
100
+ close?(): Promise<void>;
101
+ /**
102
+ * Get interceptor statistics
103
+ */
104
+ getStats(): InterceptorStats;
105
+ /**
106
+ * Reset statistics
107
+ */
108
+ resetStats(): void;
109
+ /**
110
+ * Get request history
111
+ */
112
+ getRequestHistory(): InterceptedRequest[];
113
+ /**
114
+ * Clear request history
115
+ */
116
+ clearHistory(): void;
117
+ /**
118
+ * Run guardrails and aggregate results
119
+ */
120
+ private runGuardrails;
121
+ /**
122
+ * Extract text from prompt (string or messages array)
123
+ */
124
+ private extractPromptText;
125
+ /**
126
+ * Emit an event to the handler
127
+ */
128
+ private emitEvent;
129
+ }
130
+ /**
131
+ * Error thrown when a request is blocked by guardrails
132
+ */
133
+ export declare class GuardianBlockedError extends Error {
134
+ readonly violations: Violation[];
135
+ constructor(message: string, violations: Violation[]);
136
+ }
137
+ /**
138
+ * Create an interceptor wrapping a model client
139
+ */
140
+ export declare function createInterceptor(client: ModelClient, config?: InterceptorConfig): GuardianInterceptor;
141
+ //# sourceMappingURL=interceptor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../../src/guardian/interceptor.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Policy Loader
3
+ *
4
+ * Loads and validates guardian policies from YAML files.
5
+ * Policies define the guardrails, rules, and configurations for the guardian.
6
+ */
7
+ import type { GuardianPolicy, GuardrailType, PolicyRule } from './types';
8
+ /**
9
+ * Load a guardian policy from a YAML file
10
+ */
11
+ export declare function loadPolicy(filePath: string): GuardianPolicy;
12
+ /**
13
+ * Parse a guardian policy from YAML string
14
+ */
15
+ export declare function parsePolicy(yamlContent: string): GuardianPolicy;
16
+ /**
17
+ * Validate a guardian policy object
18
+ */
19
+ export declare function validatePolicy(policy: unknown): GuardianPolicy;
20
+ /**
21
+ * Create a default guardian policy
22
+ */
23
+ export declare function createDefaultPolicy(): GuardianPolicy;
24
+ /**
25
+ * Merge two policies (second overrides first)
26
+ */
27
+ export declare function mergePolicies(base: GuardianPolicy, override: Partial<GuardianPolicy>): GuardianPolicy;
28
+ /**
29
+ * Get rules by type from a policy
30
+ */
31
+ export declare function getRulesByType(policy: GuardianPolicy, type: GuardrailType): PolicyRule[];
32
+ /**
33
+ * Check if a rule is enabled in the policy
34
+ */
35
+ export declare function isRuleEnabled(policy: GuardianPolicy, ruleId: string): boolean;
36
+ /**
37
+ * Error thrown when policy loading fails
38
+ */
39
+ export declare class PolicyLoadError extends Error {
40
+ constructor(message: string);
41
+ }
42
+ /**
43
+ * Error thrown when policy validation fails
44
+ */
45
+ export declare class PolicyValidationError extends Error {
46
+ constructor(message: string);
47
+ }
48
+ /**
49
+ * Generate a YAML policy template
50
+ */
51
+ export declare function generatePolicyTemplate(): string;
52
+ //# sourceMappingURL=policy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/guardian/policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAIV,cAAc,EACd,aAAa,EACb,UAAU,EAIX,MAAM,SAAS,CAAC;AA8FjB;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAgB3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAiB/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAS9D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CA2FpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,GAChC,cAAc,CAkBhB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,UAAU,EAAE,CAExF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG7E;AAMD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAyG/C"}
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Semantic Validator
3
+ *
4
+ * Provides LLM-based content validation using the "LLM-as-judge" pattern.
5
+ * This complements pattern-based detection by using semantic understanding
6
+ * to identify threats that regex patterns might miss.
7
+ */
8
+ import type { ModelClient } from '@artemiskit/core';
9
+ import type { ContentValidationConfig, GuardrailResult, SemanticValidationResult } from './types';
10
+ /**
11
+ * SemanticValidator - LLM-based content validation
12
+ */
13
+ export declare class SemanticValidator {
14
+ private llmClient;
15
+ private config;
16
+ constructor(llmClient: ModelClient, config: ContentValidationConfig);
17
+ /**
18
+ * Validate input content using LLM
19
+ */
20
+ validateInput(content: string): Promise<SemanticValidationResult>;
21
+ /**
22
+ * Validate output content using LLM
23
+ * @param content - The output to validate
24
+ * @param inputContext - Optional input that generated this output (for context)
25
+ */
26
+ validateOutput(content: string, inputContext?: string): Promise<SemanticValidationResult>;
27
+ /**
28
+ * Create a guardrail function from this validator
29
+ *
30
+ * For output validation, the context parameter should include `inputContext`
31
+ * containing the original user input, which improves detection of manipulation
32
+ * success patterns where an attacker's prompt injection affected the output.
33
+ */
34
+ asGuardrail(direction?: 'input' | 'output'): (content: string, context?: Record<string, unknown>) => Promise<GuardrailResult>;
35
+ /**
36
+ * Internal validation logic
37
+ */
38
+ private validate;
39
+ /**
40
+ * Parse LLM response into SemanticValidationResult
41
+ *
42
+ * SECURITY: This method detects multiple valid JSON candidates in the response.
43
+ * Multiple candidates could indicate a prompt injection attack where the attacker
44
+ * prepended their own benign JSON object. When detected, we treat this as suspicious.
45
+ */
46
+ private parseResponse;
47
+ /**
48
+ * Extract a complete JSON object from a string starting at the given index
49
+ * Uses brace counting to handle nested objects correctly
50
+ */
51
+ private extractJsonObject;
52
+ /**
53
+ * Map validation category to severity
54
+ */
55
+ private categoryToSeverity;
56
+ }
57
+ /**
58
+ * Create a semantic validator instance
59
+ */
60
+ export declare function createSemanticValidator(llmClient: ModelClient, config?: Partial<ContentValidationConfig>): SemanticValidator;
61
+ //# sourceMappingURL=semantic-validator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"semantic-validator.d.ts","sourceRoot":"","sources":["../../src/guardian/semantic-validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EACf,wBAAwB,EAIzB,MAAM,SAAS,CAAC;AAwDjB;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,MAAM,CAA0B;gBAE5B,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,uBAAuB;IAKnE;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAIvE;;;;OAIG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAI/F;;;;;;OAMG;IACH,WAAW,CACT,SAAS,GAAE,OAAO,GAAG,QAAkB,GACtC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC;IAsCnF;;OAEG;YACW,QAAQ;IA0CtB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAyHrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAc3B;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,WAAW,EACtB,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GACxC,iBAAiB,CASnB"}