@ai-pip/csl 0.1.1 → 0.1.3

package/layers/csl/domain/exceptions/index.ts

@@ -1,2 +0,0 @@
-export * from './ClassificationError';
-export * from './SegmentationError';

package/layers/csl/domain/index.ts

@@ -1,4 +0,0 @@
-export * from './entities'
-export * from './services'
-export * from './value-objects'
-export * from './exceptions'

package/layers/csl/domain/services/AnomalyService.ts

@@ -1,255 +0,0 @@
-import type { Segment } from '../entities'
-import { AnomalyScore } from '../value-objects'
-import type { AnomalyAction, RiskScore } from '../../types'
-import { TrustLevelType } from '../../types'
-
-/**
- * Configuration for AnomalyService
- * 
- * @property highRiskThreshold - Score threshold for BLOCK action (default: 0.7)
- * @property mediumRiskThreshold - Score threshold for WARN action (default: 0.3)
- * @property trustLevelWeight - Weight multiplier for trust level in score calculation (default: 0.3)
- * @property piDetectionWeight - Weight multiplier for PI detection in score calculation (default: 0.5)
- * @property contentLengthWeight - Weight multiplier for content length anomaly (default: 0.1)
- * @property originWeight - Weight multiplier for origin risk in score calculation (default: 0.1)
- */
-export interface AnomalyServiceConfig {
-  readonly highRiskThreshold?: RiskScore
-  readonly mediumRiskThreshold?: RiskScore
-  readonly trustLevelWeight?: number
-  readonly piDetectionWeight?: number
-  readonly contentLengthWeight?: number
-  readonly originWeight?: number
-}
-
-/**
- * AnomalyService calculates anomaly scores for content segments based on multiple risk factors.
- * 
- * @remarks
- * This service performs complex risk analysis by combining multiple factors:
- * - Trust level of the segment
- * - Prompt injection detection results
- * - Content length anomalies
- * - Origin risk assessment
- * 
- * **Key Features:**
- * - Configurable thresholds and weights
- * - Multi-factor risk analysis
- * - Deterministic scoring algorithm
- * - Returns AnomalyScore with recommended action
- * 
- * **Scoring Algorithm:**
- * The final score is a weighted combination of:
- * 1. Trust Level Risk (0-1): Lower trust = higher risk
- * 2. PI Detection Risk (0-1): Based on detection score
- * 3. Content Length Anomaly (0-1): Very short or very long content
- * 4. Origin Risk (0-1): Based on origin type
- * 
- * Final score = (trustLevelRisk * trustLevelWeight) +
- *               (piDetectionRisk * piDetectionWeight) +
- *               (contentLengthRisk * contentLengthWeight) +
- *               (originRisk * originWeight)
- * 
- * @example
- * ```typescript
- * // Default configuration
- * const anomalyService = new AnomalyService()
- * 
- * // Custom configuration
- * const customService = new AnomalyService({
- *   highRiskThreshold: 0.8,
- *   mediumRiskThreshold: 0.4,
- *   piDetectionWeight: 0.7
- * })
- * 
- * // Calculate anomaly score
- * const anomalyScore = anomalyService.calculateScore(segment)
- * 
- * if (anomalyScore.isHighRisk()) {
- *   console.log('High risk detected!')
- * }
- * ```
- */
-export class AnomalyService {
-  private readonly config: Required<AnomalyServiceConfig>
-
-  constructor(config?: AnomalyServiceConfig) {
-    this.config = {
-      highRiskThreshold: config?.highRiskThreshold ?? 0.7,
-      mediumRiskThreshold: config?.mediumRiskThreshold ?? 0.3,
-      trustLevelWeight: config?.trustLevelWeight ?? 0.3,
-      piDetectionWeight: config?.piDetectionWeight ?? 0.5,
-      contentLengthWeight: config?.contentLengthWeight ?? 0.1,
-      originWeight: config?.originWeight ?? 0.1,
-    }
-
-    // Validate thresholds
-    if (this.config.highRiskThreshold < this.config.mediumRiskThreshold) {
-      throw new Error(
-        `AnomalyService: highRiskThreshold (${this.config.highRiskThreshold}) ` +
-        `must be >= mediumRiskThreshold (${this.config.mediumRiskThreshold})`
-      )
-    }
-
-    // Validate weights sum to approximately 1.0 (allow small floating point differences)
-    const totalWeight = this.config.trustLevelWeight +
-                       this.config.piDetectionWeight +
-                       this.config.contentLengthWeight +
-                       this.config.originWeight
-
-    if (Math.abs(totalWeight - 1) > 0.01) {
-      throw new Error(
-        `AnomalyService: weights must sum to 1.0, got ${totalWeight}`
-      )
-    }
-  }
-
-  /**
-   * Calculates the anomaly score for a segment based on multiple risk factors
-   * 
-   * @param segment - The segment to analyze
-   * @returns AnomalyScore with calculated score and recommended action
-   * 
-   * @throws {TypeError} If segment is not a Segment instance
-   * 
-   * @example
-   * ```typescript
-   * const anomalyScore = anomalyService.calculateScore(segment)
-   * console.log(`Anomaly score: ${anomalyScore.score}, Action: ${anomalyScore.action}`)
-   * ```
-   */
-  calculateScore(segment: Segment): AnomalyScore {
-    if (!segment || typeof segment !== 'object' || !('id' in segment)) {
-      throw new TypeError('AnomalyService.calculateScore: segment must be a Segment instance')
-    }
-
-    // Calculate individual risk components
-    const trustLevelRisk = this.calculateTrustLevelRisk(segment)
-    const piDetectionRisk = this.calculatePiDetectionRisk(segment)
-    const contentLengthRisk = this.calculateContentLengthRisk(segment)
-    const originRisk = this.calculateOriginRisk(segment)
-
-    // Weighted combination
-    const finalScore = Math.min(1,
-      (trustLevelRisk * this.config.trustLevelWeight) +
-      (piDetectionRisk * this.config.piDetectionWeight) +
-      (contentLengthRisk * this.config.contentLengthWeight) +
-      (originRisk * this.config.originWeight)
-    )
-
-    // Determine action based on thresholds
-    const action = this.determineAction(finalScore)
-
-    return new AnomalyScore(finalScore, action)
-  }
-
-  /**
-   * Calculates risk based on trust level
-   * TC = 0.0 (no risk), STC = 0.5 (medium risk), UC = 1.0 (high risk)
-   */
-  private calculateTrustLevelRisk(segment: Segment): RiskScore {
-    const trustLevel = segment.trustLevel
-    if (!trustLevel) {
-      return 1 as RiskScore // Unknown trust level = maximum risk
-    }
-
-    switch (trustLevel.value) {
-      case TrustLevelType.TC:
-        return 0 as RiskScore
-      case TrustLevelType.STC:
-        return 0.5 as RiskScore
-      case TrustLevelType.UC:
-        return 1 as RiskScore
-      default:
-        return 1 as RiskScore
-    }
-  }
-
-  /**
-   * Calculates risk based on prompt injection detection results
-   */
-  private calculatePiDetectionRisk(segment: Segment): RiskScore {
-    const piDetection = segment.piDetection
-    if (!piDetection) {
-      return 0 as RiskScore // No detection = no risk from this factor
-    }
-
-    // Use the detection score directly
-    return piDetection.score
-  }
-
-  /**
-   * Calculates risk based on content length anomalies
-   * Very short (< 10 chars) or very long (> 10000 chars) content is suspicious
-   */
-  private calculateContentLengthRisk(segment: Segment): RiskScore {
-    const contentLength = segment.content.length
-
-    // Very short content (potential injection fragments)
-    if (contentLength < 10) {
-      return 0.8 as RiskScore
-    }
-
-    // Very long content (potential obfuscation)
-    if (contentLength > 10000) {
-      return 0.6 as RiskScore
-    }
-
-    // Normal length range
-    if (contentLength >= 10 && contentLength <= 1000) {
-      return 0 as RiskScore
-    }
-
-    // Medium length (1000-10000) - slight risk
-    return 0.2 as RiskScore
-  }
-
-  /**
-   * Calculates risk based on origin type
-   */
-  private calculateOriginRisk(segment: Segment): RiskScore {
-    const origin = segment.origin
-
-    // User input is always high risk
-    if (origin.isUser()) {
-      return 1 as RiskScore
-    }
-
-    // External content (network, injected) is high risk
-    if (origin.isExternal()) {
-      return 0.9 as RiskScore
-    }
-
-    // System content is low risk
-    if (origin.isSystem()) {
-      return 0 as RiskScore
-    }
-
-    // DOM content risk depends on visibility
-    if (origin.isDom()) {
-      // Hidden DOM content is more risky
-      return origin.type === 'DOM_HIDDEN' ? 0.7 as RiskScore : 0.3 as RiskScore
-    }
-
-    // Unknown origin is high risk
-    if (origin.isUnknown()) {
-      return 1 as RiskScore
-    }
-
-    // Default: medium risk
-    return 0.5 as RiskScore
-  }
-
-  /**
-   * Determines the action based on the calculated score
-   */
-  private determineAction(score: RiskScore): AnomalyAction {
-    if (score >= this.config.highRiskThreshold) {
-      return 'BLOCK'
-    } else if (score >= this.config.mediumRiskThreshold) {
-      return 'WARN'
-    } else {
-      return 'ALLOW'
-    }
-  }
-}

package/layers/csl/domain/services/LineageService.ts

@@ -1,224 +0,0 @@
-import { LineageEntry } from '../value-objects'
-
-/**
- * LineageService manages the lineage (audit trail) of content segments.
- * 
- * @remarks
- * This service maintains a stateful map of segment IDs to their lineage entries,
- * allowing complete traceability of how each segment was processed through the pipeline.
- * 
- * **Key Features:**
- * - Maintains internal state (Map) for lineage tracking
- * - Supports multiple entries per segment (chronological order)
- * - Provides query methods for lineage retrieval
- * - Thread-safe operations (immutable entries)
- * 
- * **Usage:**
- * LineageService is instantiated once and reused across the processing pipeline.
- * Each processing step should add an entry to track what happened to the segment.
- * 
- * @example
- * ```typescript
- * const lineageService = new LineageService()
- * 
- * // Add entries during processing
- * lineageService.addEntry('seg-123', new LineageEntry('normalization', Date.now(), 'Unicode normalized'))
- * lineageService.addEntry('seg-123', new LineageEntry('classification', Date.now(), 'Classified as TC'))
- * 
- * // Retrieve lineage
- * const lineage = lineageService.getLineage('seg-123')
- * console.log(`Segment has ${lineage.length} processing steps`)
- * 
- * // Clear lineage when done
- * lineageService.clearLineage('seg-123')
- * ```
- */
-export class LineageService {
-  private readonly lineageMap: Map<string, LineageEntry[]>
-
-  constructor() {
-    this.lineageMap = new Map()
-  }
-
-  /**
-   * Adds a lineage entry for a specific segment
-   * 
-   * @param segmentId - The unique identifier of the segment
-   * @param entry - The lineage entry to add
-   * 
-   * @throws {TypeError} If segmentId is not a valid string
-   * @throws {TypeError} If entry is not a LineageEntry instance
-   * 
-   * @example
-   * ```typescript
-   * lineageService.addEntry('seg-123', new LineageEntry('normalization', Date.now(), 'Applied'))
-   * ```
-   */
-  addEntry(segmentId: string, entry: LineageEntry): void {
-    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
-      throw new TypeError('LineageService.addEntry: segmentId must be a non-empty string')
-    }
-
-    if (!(entry instanceof LineageEntry)) {
-      throw new TypeError('LineageService.addEntry: entry must be a LineageEntry instance')
-    }
-
-    const currentLineage = this.lineageMap.get(segmentId) ?? []
-    this.lineageMap.set(segmentId, [...currentLineage, entry])
-  }
-
-  /**
-   * Retrieves all lineage entries for a specific segment
-   * 
-   * @param segmentId - The unique identifier of the segment
-   * @returns Array of LineageEntry instances in chronological order (empty array if no entries)
-   * 
-   * @throws {TypeError} If segmentId is not a valid string
-   * 
-   * @example
-   * ```typescript
-   * const lineage = lineageService.getLineage('seg-123')
-   * lineage.forEach(entry => {
-   *   console.log(`${entry.step} at ${new Date(entry.timestamp).toISOString()}`)
-   * })
-   * ```
-   */
-  getLineage(segmentId: string): readonly LineageEntry[] {
-    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
-      throw new TypeError('LineageService.getLineage: segmentId must be a non-empty string')
-    }
-
-    const lineage = this.lineageMap.get(segmentId)
-    return lineage ? Object.freeze([...lineage]) : Object.freeze([])
-  }
-
-  /**
-   * Checks if a segment has any lineage entries
-   * 
-   * @param segmentId - The unique identifier of the segment
-   * @returns true if the segment has lineage entries, false otherwise
-   * 
-   * @throws {TypeError} If segmentId is not a valid string
-   * 
-   * @example
-   * ```typescript
-   * if (lineageService.hasLineage('seg-123')) {
-   *   const entries = lineageService.getLineage('seg-123')
-   * }
-   * ```
-   */
-  hasLineage(segmentId: string): boolean {
-    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
-      throw new TypeError('LineageService.hasLineage: segmentId must be a non-empty string')
-    }
-
-    const lineage = this.lineageMap.get(segmentId)
-    return lineage !== undefined && lineage.length > 0
-  }
-
-  /**
-   * Clears all lineage entries for a specific segment
-   * 
-   * @param segmentId - The unique identifier of the segment
-   * @returns true if lineage was cleared, false if segment had no lineage
-   * 
-   * @throws {TypeError} If segmentId is not a valid string
-   * 
-   * @example
-   * ```typescript
-   * const hadLineage = lineageService.clearLineage('seg-123')
-   * if (hadLineage) {
-   *   console.log('Lineage cleared')
-   * }
-   * ```
-   */
-  clearLineage(segmentId: string): boolean {
-    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
-      throw new TypeError('LineageService.clearLineage: segmentId must be a non-empty string')
-    }
-
-    const hadLineage = this.lineageMap.has(segmentId)
-    this.lineageMap.delete(segmentId)
-    return hadLineage
-  }
-
-  /**
-   * Retrieves all segment IDs that have lineage entries
-   * 
-   * @returns Array of segment IDs that have lineage entries
-   * 
-   * @example
-   * ```typescript
-   * const segmentIds = lineageService.getAllSegmentIds()
-   * console.log(`Tracking ${segmentIds.length} segments`)
-   * ```
-   */
-  getAllSegmentIds(): readonly string[] {
-    return Object.freeze([...this.lineageMap.keys()])
-  }
-
-  /**
-   * Retrieves the total count of lineage entries across all segments
-   * 
-   * @returns Total number of lineage entries
-   * 
-   * @example
-   * ```typescript
-   * const totalEntries = lineageService.getTotalEntryCount()
-   * console.log(`Total lineage entries: ${totalEntries}`)
-   * ```
-   */
-  getTotalEntryCount(): number {
-    let total = 0
-    for (const lineage of this.lineageMap.values()) {
-      total += lineage.length
-    }
-    return total
-  }
-
-  /**
-   * Clears all lineage entries for all segments
-   * 
-   * @returns Number of segments that had lineage entries
-   * 
-   * @example
-   * ```typescript
-   * const clearedCount = lineageService.clearAllLineage()
-   * console.log(`Cleared lineage for ${clearedCount} segments`)
-   * ```
-   */
-  clearAllLineage(): number {
-    const count = this.lineageMap.size
-    this.lineageMap.clear()
-    return count
-  }
-
-  /**
-   * Gets lineage entries for a specific step type
-   * 
-   * @param segmentId - The unique identifier of the segment
-   * @param stepType - The step type to filter by (e.g., 'normalization', 'classification')
-   * @returns Array of LineageEntry instances matching the step type
-   * 
-   * @throws {TypeError} If segmentId or stepType are not valid strings
-   * 
-   * @example
-   * ```typescript
-   * const normalizationEntries = lineageService.getLineageByStep('seg-123', 'normalization')
-   * ```
-   */
-  getLineageByStep(segmentId: string, stepType: string): readonly LineageEntry[] {
-    if (!segmentId || typeof segmentId !== 'string' || segmentId.trim().length === 0) {
-      throw new TypeError('LineageService.getLineageByStep: segmentId must be a non-empty string')
-    }
-
-    if (!stepType || typeof stepType !== 'string' || stepType.trim().length === 0) {
-      throw new TypeError('LineageService.getLineageByStep: stepType must be a non-empty string')
-    }
-
-    const lineage = this.getLineage(segmentId)
-    return Object.freeze(
-      lineage.filter(entry => entry.step === stepType.trim())
-    )
-  }
-}