@artemiskit/sdk 0.3.1 → 0.4.0

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 (78) hide show
  1. package/CHANGELOG.md +229 -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 +352 -0
  6. package/dist/builders/index.d.ts.map +1 -0
  7. package/dist/builders/index.js +354 -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 +53 -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 +44918 -28644
  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/index.js +13 -59
  39. package/dist/matchers/jest.d.ts +46 -0
  40. package/dist/matchers/jest.d.ts.map +1 -0
  41. package/dist/matchers/jest.js +0 -46
  42. package/dist/matchers/vitest.d.ts +24 -0
  43. package/dist/matchers/vitest.d.ts.map +1 -0
  44. package/dist/matchers/vitest.js +0 -46
  45. package/dist/types-only.d.ts +31 -0
  46. package/dist/types-only.d.ts.map +1 -0
  47. package/dist/types-only.js +1 -0
  48. package/dist/types.d.ts +379 -0
  49. package/dist/types.d.ts.map +1 -0
  50. package/dist/utils/index.d.ts +112 -0
  51. package/dist/utils/index.d.ts.map +1 -0
  52. package/dist/utils/index.js +58 -0
  53. package/package.json +19 -4
  54. package/src/__tests__/builders.test.ts +450 -0
  55. package/src/__tests__/circuit-breaker.test.ts +704 -0
  56. package/src/__tests__/compare.test.ts +469 -0
  57. package/src/__tests__/contracts.test.ts +354 -0
  58. package/src/__tests__/guardian-modes.test.ts +215 -0
  59. package/src/__tests__/guardrails.test.ts +404 -0
  60. package/src/__tests__/semantic-validator.test.ts +421 -0
  61. package/src/__tests__/utils.test.ts +324 -0
  62. package/src/__tests__/validate.test.ts +310 -0
  63. package/src/artemiskit.ts +479 -5
  64. package/src/builders/index.ts +700 -0
  65. package/src/contracts/index.ts +357 -0
  66. package/src/guardian/circuit-breaker.ts +74 -28
  67. package/src/guardian/guardian.ts +307 -20
  68. package/src/guardian/guardrails.ts +143 -1
  69. package/src/guardian/index.ts +35 -1
  70. package/src/guardian/interceptor.ts +87 -11
  71. package/src/guardian/semantic-validator.ts +399 -0
  72. package/src/guardian/types.ts +413 -2
  73. package/src/index.ts +258 -14
  74. package/src/types-only.ts +276 -0
  75. package/src/types.ts +186 -0
  76. package/src/utils/index.ts +225 -0
  77. package/tsconfig.json +2 -1
  78. package/adapters/openai/dist/index.js +0 -5625
@@ -7,8 +7,18 @@
7
7
 
8
8
  /**
9
9
  * Guardian operating mode
10
+ *
11
+ * Canonical modes (recommended):
12
+ * - 'observe': Log only, never block
13
+ * - 'selective': Block high-confidence threats
14
+ * - 'strict': Block all detected violations
15
+ *
16
+ * Legacy modes (deprecated, still supported):
17
+ * - 'testing' → maps to 'observe'
18
+ * - 'guardian' → maps to 'strict'
19
+ * - 'hybrid' → maps to 'selective'
10
20
  */
11
- export type GuardianMode = 'testing' | 'guardian' | 'hybrid';
21
+ export type GuardianMode = 'testing' | 'guardian' | 'hybrid' | 'observe' | 'selective' | 'strict';
12
22
 
13
23
  /**
14
24
  * Severity levels for violations
@@ -33,7 +43,8 @@ export type GuardrailType =
33
43
  | 'content_filter'
34
44
  | 'hallucination_check'
35
45
  | 'rate_limit'
36
- | 'cost_limit';
46
+ | 'cost_limit'
47
+ | 'circuit_breaker';
37
48
 
38
49
  /**
39
50
  * Violation detected by guardrails
@@ -235,6 +246,8 @@ export interface PIILocation {
235
246
  export interface InjectionDetection {
236
247
  detected: boolean;
237
248
  type?: InjectionType;
249
+ /** Severity of the detected injection pattern */
250
+ severity?: ViolationSeverity;
238
251
  confidence: number;
239
252
  pattern?: string;
240
253
  location?: { start: number; end: number };
@@ -434,3 +447,401 @@ export interface InterceptedAgentStep {
434
447
  output?: unknown;
435
448
  timestamp: Date;
436
449
  }
450
+
451
+ // =============================================================================
452
+ // Guardian Mode Types (v0.3.2+)
453
+ // =============================================================================
454
+
455
+ /**
456
+ * Canonical Guardian operating modes (v0.3.2+)
457
+ *
458
+ * - observe: Log only, never block (for monitoring and testing)
459
+ * - selective: Block high-confidence threats only (threshold-based)
460
+ * - strict: Block all detected violations (maximum protection)
461
+ */
462
+ export type GuardianModeCanonical = 'observe' | 'selective' | 'strict';
463
+
464
+ /**
465
+ * Legacy Guardian modes (deprecated, use canonical modes)
466
+ * @deprecated Use GuardianModeCanonical instead
467
+ *
468
+ * Mapping:
469
+ * - 'testing' → 'observe'
470
+ * - 'guardian' → 'strict'
471
+ * - 'hybrid' → 'selective'
472
+ */
473
+ export type GuardianModeLegacy = 'testing' | 'guardian' | 'hybrid';
474
+
475
+ /**
476
+ * All supported Guardian modes (canonical + legacy for backwards compatibility)
477
+ */
478
+ export type GuardianModeAll = GuardianModeCanonical | GuardianModeLegacy;
479
+
480
+ // =============================================================================
481
+ // Content Validation Types (v0.3.2+)
482
+ // =============================================================================
483
+
484
+ /**
485
+ * Validation categories for content checking
486
+ * These define what types of threats/issues to validate for
487
+ */
488
+ export type ValidationCategory =
489
+ | 'prompt_injection'
490
+ | 'jailbreak'
491
+ | 'pii_disclosure'
492
+ | 'role_manipulation'
493
+ | 'data_extraction'
494
+ | 'content_safety';
495
+
496
+ /**
497
+ * Pattern matching categories for granular control
498
+ */
499
+ export type PatternCategory =
500
+ | 'injection'
501
+ | 'pii'
502
+ | 'role_hijack'
503
+ | 'extraction'
504
+ | 'tool_abuse'
505
+ | 'content_filter';
506
+
507
+ /**
508
+ * Pattern matching configuration
509
+ */
510
+ export interface PatternConfig {
511
+ /** Enable pattern matching (default: true when strategy is 'pattern' or 'hybrid') */
512
+ enabled?: boolean;
513
+
514
+ /** Case-insensitive matching (default: true) */
515
+ caseInsensitive?: boolean;
516
+
517
+ /** Custom patterns to add */
518
+ customPatterns?: string[];
519
+
520
+ /** Pattern categories to enable (default: all) */
521
+ categories?: PatternCategory[];
522
+ }
523
+
524
+ /**
525
+ * Content validation strategy configuration
526
+ */
527
+ export interface ContentValidationConfig {
528
+ /**
529
+ * Validation strategy
530
+ * - 'semantic': LLM-based validation (default, recommended)
531
+ * - 'pattern': Regex/pattern-based validation only
532
+ * - 'hybrid': Both semantic and pattern validation
533
+ * - 'off': Disable content validation
534
+ */
535
+ strategy: 'semantic' | 'pattern' | 'hybrid' | 'off';
536
+
537
+ /** Confidence threshold for semantic validation (0-1, default: 0.9) */
538
+ semanticThreshold?: number;
539
+
540
+ /** Categories to validate (default: all) */
541
+ categories?: ValidationCategory[];
542
+
543
+ /** Pattern matching configuration (supplementary when strategy != 'pattern') */
544
+ patterns?: PatternConfig;
545
+ }
546
+
547
+ /**
548
+ * Result from semantic validation
549
+ */
550
+ export interface SemanticValidationResult {
551
+ /** Whether content passed validation */
552
+ valid: boolean;
553
+
554
+ /** Confidence score (0-1) */
555
+ confidence: number;
556
+
557
+ /** Detected category if invalid */
558
+ category?: ValidationCategory;
559
+
560
+ /** Human-readable reason */
561
+ reason?: string;
562
+
563
+ /** Whether this should block based on threshold */
564
+ shouldBlock: boolean;
565
+
566
+ /** Raw LLM response for debugging */
567
+ rawResponse?: string;
568
+ }
569
+
570
+ // =============================================================================
571
+ // Multi-Turn Detection Types (v0.3.3+)
572
+ // =============================================================================
573
+
574
+ /**
575
+ * Storage type for sessions
576
+ */
577
+ export type SessionStorageType = 'memory' | 'local' | 'supabase';
578
+
579
+ /**
580
+ * Session storage configuration
581
+ */
582
+ export interface SessionStorageConfig {
583
+ /** Storage type */
584
+ type: SessionStorageType;
585
+
586
+ /** Base path for local storage (default: '.artemis/sessions') */
587
+ basePath?: string;
588
+
589
+ /** Supabase table name (default: 'guardian_sessions') */
590
+ tableName?: string;
591
+ }
592
+
593
+ /**
594
+ * Individual message in a conversation session
595
+ */
596
+ export interface SessionMessage {
597
+ /** Message role */
598
+ role: 'user' | 'assistant';
599
+
600
+ /** Message content */
601
+ content: string;
602
+
603
+ /** When message was sent */
604
+ timestamp: Date;
605
+
606
+ /** Risk score for this message (0-1) */
607
+ riskScore?: number;
608
+
609
+ /** Detection flags triggered */
610
+ flags?: string[];
611
+ }
612
+
613
+ /**
614
+ * Session metrics for tracking conversation patterns
615
+ */
616
+ export interface SessionMetrics {
617
+ /** Total messages in session */
618
+ messageCount: number;
619
+
620
+ /** Trust-building score accumulator (0-1) */
621
+ trustBuildingScore: number;
622
+
623
+ /** Number of risk score increases */
624
+ escalationCount: number;
625
+
626
+ /** Most recent message risk score */
627
+ lastRiskScore: number;
628
+
629
+ /** Risk trend direction */
630
+ riskTrend: 'stable' | 'increasing' | 'decreasing';
631
+ }
632
+
633
+ /**
634
+ * Conversation session for multi-turn tracking
635
+ */
636
+ export interface ConversationSession {
637
+ /** Unique session identifier */
638
+ sessionId: string;
639
+
640
+ /** When session was created */
641
+ createdAt: Date;
642
+
643
+ /** Last update timestamp */
644
+ updatedAt: Date;
645
+
646
+ /** Session expiration time */
647
+ expiresAt: Date;
648
+
649
+ /** Messages in the session */
650
+ messages: SessionMessage[];
651
+
652
+ /** Session metrics */
653
+ metrics: SessionMetrics;
654
+ }
655
+
656
+ /**
657
+ * Trust-building detection heuristic config
658
+ */
659
+ export interface TrustBuildingHeuristicConfig {
660
+ /** Enable this heuristic */
661
+ enabled: boolean;
662
+
663
+ /** Score threshold to flag (default: 0.7) */
664
+ threshold?: number;
665
+ }
666
+
667
+ /**
668
+ * Escalation detection heuristic config
669
+ */
670
+ export interface EscalationHeuristicConfig {
671
+ /** Enable this heuristic */
672
+ enabled: boolean;
673
+
674
+ /** Number of consecutive increases to flag (default: 3) */
675
+ consecutiveIncreases?: number;
676
+
677
+ /** Minimum risk increase per message to count (default: 0.15) */
678
+ minIncrement?: number;
679
+ }
680
+
681
+ /**
682
+ * Context manipulation detection heuristic config
683
+ */
684
+ export interface ContextManipulationHeuristicConfig {
685
+ /** Enable this heuristic */
686
+ enabled: boolean;
687
+
688
+ /** Patterns that indicate claimed prior agreement */
689
+ claimPatterns?: string[];
690
+ }
691
+
692
+ /**
693
+ * Split payload detection heuristic config
694
+ */
695
+ export interface SplitPayloadHeuristicConfig {
696
+ /** Enable this heuristic */
697
+ enabled: boolean;
698
+
699
+ /** How many recent messages to combine for detection (default: 5) */
700
+ combineWindow?: number;
701
+ }
702
+
703
+ /**
704
+ * Multi-turn detection heuristics configuration
705
+ */
706
+ export interface MultiTurnHeuristics {
707
+ /** Detect trust-building patterns before sensitive requests */
708
+ trustBuilding?: TrustBuildingHeuristicConfig;
709
+
710
+ /** Detect escalating risk across messages */
711
+ escalation?: EscalationHeuristicConfig;
712
+
713
+ /** Detect false claims about prior conversation */
714
+ contextManipulation?: ContextManipulationHeuristicConfig;
715
+
716
+ /** Detect attack payloads split across messages */
717
+ splitPayload?: SplitPayloadHeuristicConfig;
718
+ }
719
+
720
+ /**
721
+ * LLM-based semantic analysis for multi-turn detection
722
+ */
723
+ export interface MultiTurnSemanticConfig {
724
+ /** Enable semantic analysis */
725
+ enabled: boolean;
726
+
727
+ /** Use same LLM client as Guardian (default: true) */
728
+ useSameLLM?: boolean;
729
+
730
+ /** Confidence threshold for flagging (default: 0.85) */
731
+ threshold?: number;
732
+ }
733
+
734
+ /**
735
+ * Multi-turn detection configuration
736
+ */
737
+ export interface MultiTurnConfig {
738
+ /** Enable multi-turn detection */
739
+ enabled: boolean;
740
+
741
+ /** Number of messages to keep in sliding window (default: 10) */
742
+ windowSize?: number;
743
+
744
+ /** Session timeout in ms (default: 3600000 = 1 hour) */
745
+ timeout?: number;
746
+
747
+ /** Session storage configuration */
748
+ storage: SessionStorageConfig | 'memory';
749
+
750
+ /** Detection heuristics (all enabled by default) */
751
+ heuristics?: MultiTurnHeuristics;
752
+
753
+ /** LLM-based semantic analysis */
754
+ semanticAnalysis?: MultiTurnSemanticConfig;
755
+ }
756
+
757
+ /**
758
+ * Individual heuristic result
759
+ */
760
+ export interface HeuristicResult {
761
+ /** Name of the heuristic */
762
+ name: string;
763
+
764
+ /** Whether this heuristic was triggered */
765
+ triggered: boolean;
766
+
767
+ /** Confidence/score for this heuristic */
768
+ score: number;
769
+
770
+ /** Details about what triggered it */
771
+ details?: Record<string, unknown>;
772
+ }
773
+
774
+ /**
775
+ * Combined results from all heuristics
776
+ */
777
+ export interface HeuristicResults {
778
+ /** Trust-building detection result */
779
+ trustBuilding?: HeuristicResult;
780
+
781
+ /** Escalation detection result */
782
+ escalation?: HeuristicResult;
783
+
784
+ /** Context manipulation detection result */
785
+ contextManipulation?: HeuristicResult;
786
+
787
+ /** Split payload detection result */
788
+ splitPayload?: HeuristicResult;
789
+ }
790
+
791
+ /**
792
+ * Result from multi-turn validation
793
+ */
794
+ export interface MultiTurnValidationResult {
795
+ /** Whether validation passed */
796
+ valid: boolean;
797
+
798
+ /** Session identifier */
799
+ sessionId: string;
800
+
801
+ /** Index of this message in the session */
802
+ messageIndex: number;
803
+
804
+ /** Single-message risk score (0-1) */
805
+ messageRisk: number;
806
+
807
+ /** Conversation-level risk score (0-1) */
808
+ conversationRisk: number;
809
+
810
+ /** Individual heuristic flags */
811
+ flags: {
812
+ trustBuildingDetected: boolean;
813
+ escalationPattern: boolean;
814
+ contextManipulation: boolean;
815
+ splitPayloadScore: number;
816
+ };
817
+
818
+ /** Semantic analysis result (if enabled) */
819
+ semanticAnalysis?: {
820
+ confidence: number;
821
+ category?: string;
822
+ reason?: string;
823
+ };
824
+
825
+ /** Recommended action based on all signals */
826
+ recommendation: 'allow' | 'warn' | 'verify' | 'block';
827
+
828
+ /** Detailed violations if any */
829
+ violations: Violation[];
830
+ }
831
+
832
+ /**
833
+ * Options for validating a message with session context
834
+ */
835
+ export interface ValidateMessageOptions {
836
+ /** Session identifier */
837
+ sessionId: string;
838
+
839
+ /** Message to validate */
840
+ message: string;
841
+
842
+ /** Message role (default: 'user') */
843
+ role?: 'user' | 'assistant';
844
+
845
+ /** Optional: provide history instead of relying on storage */
846
+ history?: Array<{ role: 'user' | 'assistant'; content: string }>;
847
+ }