TypeScript Types

interface AgentMonitoringConfig {
  apiKey: string;                    // Required: Your governance API key
  organizationId: string;            // Required: Your organization ID
  endpoint?: string;                 // Optional: Custom API endpoint
  environment?: Environment;         // Optional: Deployment environment
  batchSize?: number;               // Optional: Events per batch (1-1000)
  flushInterval?: number;           // Optional: Flush interval in ms (min 100)
  enableComplianceChecks?: boolean; // Optional: Enable compliance monitoring
  enableLogging?: boolean;          // Optional: Enable SDK logging
  logLevel?: LogLevel;              // Optional: Minimum log level
  retryAttempts?: number;           // Optional: Retry attempts (0-10)
  retryDelay?: number;              // Optional: Delay between retries in ms
}

type Environment = 'production' | 'staging' | 'development';
type LogLevel = 'debug' | 'info' | 'warn' | 'error';

interface MonitoringOptions {
  requestId?: string;               // Custom request identifier
  userId?: string;                  // User identifier for the interaction
  sessionId?: string;               // Override session ID
  agentCategory?: AgentCategory;    // Agent category for this interaction
  agentSpecialty?: BankingSpecialty; // Agent specialty for this interaction
  trackConversationStart?: boolean; // Whether to track conversation start
  complianceChecks?: boolean;       // Override global compliance setting
}

interface AgentInfo {
  id: string;                       // Unique agent identifier
  name: string;                     // Human-readable agent name
  category: AgentCategory;          // Agent type classification
  specialty?: BankingSpecialty;     // Banking domain specialty
  version: string;                  // Agent version string
  llmProvider: string;              // LLM provider name
  model: string;                    // Model name/version
  description: string;              // Detailed agent description
  systemPrompt?: string;            // System prompt used
  availableTools?: ToolInfo[];      // Tools available to the agent
  complianceSettings?: ComplianceSettings; // Compliance configuration
}

type AgentCategory = 'persona' | 'tool_calling' | 'workflow' | 'autonomous';

type BankingSpecialty =
  | 'generalist'
  | 'personal_banking'
  | 'business_banking'
  | 'wealth_management'
  | 'mortgage_lending'
  | 'investment_services'
  | 'fraud_detection'
  | 'customer_service'
  | 'compliance';

interface ToolInfo {
  name: string;                     // Tool name
  description: string;              // Tool description
  category: string;                 // Tool category
  riskLevel: RiskLevel;            // Risk level for compliance
  version?: string;                 // Tool version
  parameters?: ToolParameters;      // Tool parameter schema
}

type RiskLevel = 'low' | 'medium' | 'high';

interface ToolParameters {
  type: 'object';
  properties: Record<string, {
    type: string;
    description: string;
    required?: boolean;
    default?: any;
  }>;
  required?: string[];
}

interface ComplianceSettings {
  sr11_7_enabled: boolean;          // SR 11-7 model validation compliance
  fair_lending_monitoring: boolean; // Fair lending compliance monitoring
  bsa_aml_checks: boolean;          // BSA/AML compliance checks
  custom_rules?: string[];          // IDs of custom rules to apply
  risk_threshold?: number;          // Custom risk threshold (0-100)
}

interface InteractionEvent {
  sessionId: string;                // Required: Session identifier
  conversationId?: string;          // Optional: Conversation identifier
  userId?: string;                  // Optional: User identifier
  interactionType: EventType;       // Required: Type of interaction
  content?: string;                 // Content for message/error events
  toolName?: string;                // Tool name for tool events
  toolParameters?: any;             // Parameters for tool calls
  toolResult?: any;                 // Results from tool execution
  metadata?: EventMetadata;         // Additional event metadata

  // Error-specific fields (convenience for error events)
  errorType?: string;               // Error type classification
  errorCode?: string;               // Specific error code
  severity?: ErrorSeverity;         // Error severity level
}

type EventType =
  | 'conversation_start'
  | 'user_message'
  | 'agent_response'
  | 'tool_call'
  | 'tool_result'
  | 'error'
  | 'conversation_end';

type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';

interface EventMetadata {
  // LLM Performance Metrics
  llmLatency?: number;              // LLM response time in ms
  tokensUsed?: TokenUsage;          // Token usage statistics
  cost?: number;                    // Calculated cost for the request
  temperature?: number;             // LLM temperature setting
  maxTokens?: number;               // Maximum tokens setting

  // Quality Metrics
  responseQuality?: number;         // Response quality score (0-100)
  relevanceScore?: number;          // Relevance score (0-100)
  coherenceScore?: number;          // Coherence score (0-100)
  helpfulnessScore?: number;        // Helpfulness score (0-100)

  // Tool Execution
  toolExecutionTime?: number;       // Tool execution time in ms
  toolVersion?: string;             // Version of tool used
  cacheHit?: boolean;               // Whether result was cached

  // Error Context
  errorStack?: string;              // Error stack trace
  recoverable?: boolean;            // Whether error is recoverable
  userImpact?: ImpactLevel;         // Impact on user experience
  systemImpact?: ImpactLevel;       // Impact on system functionality
  errorSource?: ErrorSource;        // Source of the error
  originalError?: any;              // Original error object

  // Conversation Context
  duration?: number;                // Conversation duration in ms
  messageCount?: number;            // Total message count
  userSatisfaction?: number;        // User satisfaction (1-10)
  resolutionStatus?: ResolutionStatus; // How conversation ended
  endReason?: EndReason;            // Reason for ending
  followUpRequired?: boolean;       // Whether follow-up is needed
  escalationReason?: string;        // Reason for escalation

  // Business Context
  customerTier?: string;            // Customer tier/segment
  channel?: string;                 // Communication channel
  deviceFingerprint?: string;       // Device identification
  geolocation?: string;             // Geographic location

  // Custom fields
  [key: string]: any;               // Allow additional custom metadata
}

interface TokenUsage {
  input: number;                    // Input tokens used
  output: number;                   // Output tokens used
  total: number;                    // Total tokens used
}

type ImpactLevel = 'none' | 'minimal' | 'moderate' | 'high';
type ErrorSource = 'client' | 'server' | 'external' | 'unknown';
type ResolutionStatus = 'resolved' | 'unresolved' | 'escalated' | 'abandoned';
type EndReason = 'user_initiated' | 'timeout' | 'error' | 'system_initiated';

interface ConversationStartEvent extends BaseEvent {
  interactionType: 'conversation_start';
  metadata?: {
    userAgent?: string;             // User's browser/client info
    ipAddress?: string;             // User's IP address
    referrer?: string;              // Referring page/application
    channel?: string;               // Communication channel
    customerType?: string;          // Type of customer
    [key: string]: any;
  };
}

interface UserMessageEvent extends BaseEvent {
  interactionType: 'user_message';
  content: string;                  // The user's message content
  contentHash?: string;             // Hash of the content
  contentLength: number;            // Length of the content
  metadata?: {
    messageId?: string;             // Unique message identifier
    threadId?: string;              // Thread identifier
    attachments?: AttachmentInfo[]; // File attachments
    sentiment?: string;             // Detected sentiment
    language?: string;              // Detected language
    [key: string]: any;
  };
}

interface AttachmentInfo {
  type: string;                     // MIME type
  size: number;                     // File size in bytes
  name: string;                     // Original filename
  hash?: string;                    // File hash for integrity
}

interface AgentResponseEvent extends BaseEvent {
  interactionType: 'agent_response';
  content: string;                  // The agent's response content
  contentHash?: string;             // Hash of the content
  contentLength: number;            // Length of the content
  llmMetadata?: LLMMetadata;        // LLM-specific metadata
  qualityMetrics?: QualityMetrics;  // Response quality metrics
  complianceFlags?: ComplianceFlag[]; // Compliance violations
  riskScore?: number;               // Calculated risk score
  requiresReview?: boolean;         // Whether human review is needed
}

interface LLMMetadata {
  model: string;                    // Model used
  provider: string;                 // LLM provider
  latency: number;                  // Response latency in ms
  tokensUsed: TokenUsage;           // Token usage
  cost?: number;                    // Calculated cost
  temperature?: number;             // Temperature setting
  maxTokens?: number;               // Max tokens setting
  topP?: number;                    // Top-p sampling parameter
  frequencyPenalty?: number;        // Frequency penalty
  presencePenalty?: number;         // Presence penalty
}

interface QualityMetrics {
  responseQuality: number;          // Overall quality score (0-100)
  relevanceScore: number;           // Relevance to user query (0-100)
  coherenceScore: number;           // Internal coherence (0-100)
  helpfulnessScore: number;         // Helpfulness rating (0-100)
  factualAccuracy?: number;         // Factual accuracy (0-100)
  completeness?: number;            // Response completeness (0-100)
}

interface ToolCallEvent extends BaseEvent {
  interactionType: 'tool_call';
  toolName: string;                 // Name of the tool called
  toolParameters: any;              // Parameters passed to tool
  toolCategory?: string;            // Category of the tool
  riskLevel?: RiskLevel;            // Risk level of the tool
  metadata?: {
    toolVersion?: string;           // Version of the tool
    executionContext?: string;      // Execution context
    timeout?: number;               // Tool timeout setting
    retryAttempts?: number;         // Number of retry attempts
    [key: string]: any;
  };
}

interface ToolResultEvent extends BaseEvent {
  interactionType: 'tool_result';
  toolName: string;                 // Name of the tool
  toolResult: any;                  // Result from tool execution
  toolError?: string;               // Error message if tool failed
  executionTime: number;            // Execution time in ms
  success: boolean;                 // Whether execution succeeded
  metadata?: {
    cacheHit?: boolean;             // Whether result was cached
    dataSource?: string;            // Source of the data
    resultSize?: number;            // Size of result in bytes
    retryCount?: number;            // Number of retries needed
    [key: string]: any;
  };
}

interface ErrorEvent extends BaseEvent {
  interactionType: 'error';
  errorType: string;                // Classification of error type
  errorMessage: string;             // Human-readable error message
  errorStack?: string;              // Stack trace if available
  errorCode?: string;               // Specific error code
  severity: ErrorSeverity;          // Severity level
  recoverable: boolean;             // Whether error is recoverable
  metadata?: {
    userImpact: ImpactLevel;        // Impact on user experience
    systemImpact: ImpactLevel;      // Impact on system
    errorSource: ErrorSource;       // Source of the error
    originalError?: any;            // Original error object
    contextInfo?: any;              // Additional context
    [key: string]: any;
  };
}

interface ConversationEndEvent extends BaseEvent {
  interactionType: 'conversation_end';
  duration: number;                 // Total conversation duration in ms
  messageCount: number;             // Total messages exchanged
  userSatisfaction?: number;        // User satisfaction rating (1-10)
  resolutionStatus: ResolutionStatus; // How conversation was resolved
  metadata?: {
    endReason: EndReason;           // Reason for ending
    followUpRequired: boolean;       // Whether follow-up is needed
    escalationReason?: string;      // Reason for escalation if any
    avgResponseTime?: number;       // Average response time
    toolCallCount?: number;         // Number of tool calls made
    errorCount?: number;            // Number of errors encountered
    [key: string]: any;
  };
}

interface ComplianceRule {
  id: string;                       // Unique rule identifier
  name: string;                     // Human-readable rule name
  description: string;              // Detailed rule description
  category: ComplianceCategory;     // Compliance category
  severity: ComplianceSeverity;     // Severity of violations
  isActive: boolean;                // Whether rule is active
  ruleFunction: (context: InteractionContext) => ComplianceResult; // Rule logic
  version?: string;                 // Rule version
  createdAt?: string;               // Rule creation timestamp
  updatedAt?: string;               // Rule last update timestamp
  tags?: string[];                  // Tags for organization
}

type ComplianceCategory =
  | 'sr_11_7'                       // Model validation requirements
  | 'fair_lending'                  // Fair lending compliance
  | 'bsa_aml'                       // Bank Secrecy Act / Anti-Money Laundering
  | 'privacy'                       // Privacy and PII protection
  | 'consumer_protection'           // Consumer protection regulations
  | 'custom';                       // Organization-specific rules

type ComplianceSeverity = 'info' | 'warning' | 'violation';

interface InteractionContext {
  agentId: string;                  // Agent identifier
  agentCategory: AgentCategory;     // Agent category
  agentSpecialty?: BankingSpecialty; // Agent specialty
  userMessage?: string;             // User's message content
  agentResponse?: string;           // Agent's response content
  toolsUsed?: ToolUsageInfo[];      // Tools used in interaction
  userId?: string;                  // User identifier
  sessionId: string;                // Session identifier
  timestamp: number;                // Interaction timestamp
  metadata?: any;                   // Additional metadata

  // Extended context for banking compliance
  customerProfile?: CustomerProfile; // Customer information
  transactionContext?: TransactionContext; // Transaction details
  riskFactors?: string[];           // Identified risk factors
}

interface ToolUsageInfo {
  name: string;                     // Tool name
  parameters: any;                  // Parameters used
  result: any;                      // Result returned
  executionTime?: number;           // Execution time
  success: boolean;                 // Whether execution succeeded
}

interface CustomerProfile {
  customerId: string;               // Customer identifier
  customerTier?: string;            // Customer tier/segment
  riskRating?: string;              // Customer risk rating
  accountTypes?: string[];          // Types of accounts held
  relationshipLength?: number;      // Length of relationship in months
  previousViolations?: number;      // Number of previous violations
}

interface TransactionContext {
  transactionId?: string;           // Transaction identifier
  amount?: number;                  // Transaction amount
  transactionType?: string;         // Type of transaction
  frequency?: string;               // Transaction frequency
  location?: string;                // Transaction location
  merchantCategory?: string;        // Merchant category code
}

interface ComplianceResult {
  isCompliant: boolean;             // Overall compliance status
  violations: ComplianceViolation[]; // Array of violations found
  riskScore: number;                // Calculated risk score (0-100)
  requiresReview: boolean;          // Whether human review is needed
  metadata?: {
    evaluationTime?: number;        // Time taken to evaluate
    rulesEvaluated?: number;        // Number of rules checked
    confidence?: number;            // Confidence in result (0-1)
    [key: string]: any;
  };
}

interface ComplianceViolation {
  rule: string;                     // ID of rule that detected violation
  severity: ComplianceSeverity;     // Severity level
  description: string;              // Human-readable description
  context?: ViolationContext;       // Additional context
  recommendation?: string;          // Suggested remediation
  confidence?: number;              // Confidence in detection (0-1)
  timestamp?: number;               // When violation was detected
}

interface ViolationContext {
  detectedContent?: string;         // Content that triggered violation
  detectedPattern?: string;         // Pattern that was matched
  riskFactors?: string[];           // Contributing risk factors
  relatedViolations?: string[];     // Related violation IDs
  customerImpact?: ImpactLevel;     // Impact on customer
  businessImpact?: ImpactLevel;     // Impact on business
  regulatoryImpact?: string;        // Potential regulatory impact
  [key: string]: any;               // Additional context fields
}

interface EventBatch {
  batchId: string;                  // Unique batch identifier
  organizationId: string;           // Organization identifier
  timestamp: number;                // Batch creation timestamp
  events: DetailedEvent[];          // Array of events in batch
  eventCount: number;               // Number of events
  totalSize: number;                // Total size in bytes
  checksum?: string;                // Batch integrity checksum
  metadata?: {
    batchVersion?: string;          // Batch format version
    compressionType?: string;       // Compression algorithm used
    encryptionInfo?: string;        // Encryption information
    [key: string]: any;
  };
}

type DetailedEvent =
  | ConversationStartEvent
  | UserMessageEvent
  | AgentResponseEvent
  | ToolCallEvent
  | ToolResultEvent
  | ErrorEvent
  | ConversationEndEvent;

interface EventBatcherConfig {
  batchSize: number;                // Events per batch
  flushInterval: number;            // Flush interval in ms
  onFlush: (events: DetailedEvent[]) => Promise<void>; // Flush callback
  logger: Logger;                   // Logger instance
  maxRetries?: number;              // Maximum retry attempts
  retryDelay?: number;              // Delay between retries
  compression?: boolean;            // Enable compression
  encryption?: EncryptionConfig;    // Encryption configuration
}

interface EncryptionConfig {
  enabled: boolean;                 // Whether encryption is enabled
  algorithm?: string;               // Encryption algorithm
  keyId?: string;                   // Key identifier
}

interface BaseEvent {
  eventId: string;                  // Unique event identifier
  timestamp: number;                // Event timestamp
  sessionId: string;                // Session identifier
  agentId: string;                  // Agent identifier
  userId?: string;                  // User identifier
  conversationId?: string;          // Conversation identifier
  environment: Environment;         // Environment designation
  requestId: string;                // Request identifier
  version?: string;                 // Event schema version
}

interface Logger {
  debug(message: string, data?: any): void;
  info(message: string, data?: any): void;
  warn(message: string, data?: any): void;
  error(message: string, data?: any): void;
}

interface HttpOptions {
  method: string;                   // HTTP method
  headers?: Record<string, string>; // Request headers
  body?: string;                    // Request body
  timeout?: number;                 // Request timeout in ms
  retries?: number;                 // Number of retry attempts
  retryDelay?: number;              // Delay between retries
}

interface ValidationError extends Error {
  name: 'ValidationError';
  details: ValidationDetail[];      // Detailed validation errors
  field?: string;                   // Field that failed validation
  value?: any;                      // Value that failed validation
}

interface ValidationDetail {
  field: string;                    // Field path
  message: string;                  // Error message
  code: string;                     // Error code
  value?: any;                      // Invalid value
}

// Core configuration
export type {
  AgentMonitoringConfig,
  MonitoringOptions,
  Environment,
  LogLevel
};

// Agent types
export type {
  AgentInfo,
  AgentCategory,
  BankingSpecialty,
  ToolInfo,
  RiskLevel,
  ComplianceSettings
};

// Event types
export type {
  InteractionEvent,
  EventType,
  EventMetadata,
  TokenUsage,
  ErrorSeverity,
  ImpactLevel,
  ErrorSource,
  ResolutionStatus,
  EndReason
};

// Detailed event types
export type {
  ConversationStartEvent,
  UserMessageEvent,
  AgentResponseEvent,
  ToolCallEvent,
  ToolResultEvent,
  ErrorEvent,
  ConversationEndEvent,
  LLMMetadata,
  QualityMetrics
};

// Compliance types
export type {
  ComplianceRule,
  ComplianceCategory,
  ComplianceSeverity,
  InteractionContext,
  ComplianceResult,
  ComplianceViolation,
  ViolationContext,
  ToolUsageInfo,
  CustomerProfile,
  TransactionContext
};

// Utility types
export type {
  BaseEvent,
  EventBatch,
  EventBatcherConfig,
  Logger,
  HttpOptions,
  ValidationError,
  ValidationDetail
};

import type { ComplianceRule, InteractionContext, ComplianceResult } from '@agent-governance/node';

const customRule: ComplianceRule = {
  id: 'banking-hours-compliance',
  name: 'Banking Hours Compliance',
  description: 'Ensures banking hours are mentioned correctly',
  category: 'consumer_protection',
  severity: 'warning',
  isActive: true,
  ruleFunction: (context: InteractionContext): ComplianceResult => {
    const violations = [];
    const response = context.agentResponse || '';

    if (response.includes('banking hours') && !response.includes('Monday through Friday')) {
      violations.push({
        rule: 'banking-hours-compliance',
        severity: 'warning' as const,
        description: 'Banking hours mentioned without complete schedule',
        context: {
          detectedContent: response,
          missingInfo: 'complete_schedule'
        },
        recommendation: 'Include full banking hours (Monday through Friday, 9 AM to 5 PM)'
      });
    }

    return {
      isCompliant: violations.length === 0,
      violations,
      riskScore: violations.length * 10,
      requiresReview: violations.length > 0
    };
  }
};

import type { InteractionEvent, EventMetadata, TokenUsage } from '@agent-governance/node';

const trackAgentResponse = (
  monitor: AgentMonitor,
  agentId: string,
  sessionId: string,
  content: string,
  metadata: EventMetadata
) => {
  const event: InteractionEvent = {
    sessionId,
    interactionType: 'agent_response',
    content,
    metadata: {
      llmLatency: metadata.llmLatency,
      tokensUsed: metadata.tokensUsed,
      responseQuality: metadata.responseQuality,
      cost: metadata.cost
    }
  };

  monitor.track(agentId, event);
};

import type { AgentMonitoringConfig, AgentInfo } from '@agent-governance/node';

const config: AgentMonitoringConfig = {
  apiKey: process.env.AGENT_GOVERNANCE_API_KEY!,
  organizationId: process.env.AGENT_GOVERNANCE_ORG_ID!,
  environment: 'production',
  batchSize: 100,
  flushInterval: 5000,
  enableComplianceChecks: true,
  enableLogging: false,
  logLevel: 'error',
  retryAttempts: 3,
  retryDelay: 1000
};

const agentInfo: AgentInfo = {
  id: 'banking-assistant',
  name: 'Personal Banking Assistant',
  category: 'tool_calling',
  specialty: 'personal_banking',
  version: '2.1.0',
  llmProvider: 'anthropic',
  model: 'claude-3-5-sonnet-20241022',
  description: 'AI assistant for personal banking services',
  complianceSettings: {
    sr11_7_enabled: true,
    fair_lending_monitoring: false,
    bsa_aml_checks: true
  }
};