Distractor API

Noise injection for model robustness.

Factory Function

from src.distractor import create_distractor_model

def create_distractor_model(
    config: Dict[str, Any],
    use_semantic: bool = True,
    llm_client: Optional[LLMClient] = None
) -> Union[DistractorModel, SemanticDistractorModel]:
    """
    Create appropriate distractor model.

    Args:
        config: Configuration dictionary
        use_semantic: Use 3-layer semantic distractor (True) or legacy (False)
        llm_client: Optional LLM client

    Returns:
        DistractorModel or SemanticDistractorModel instance
    """

SemanticDistractorModel

from src.distractor import SemanticDistractorModel

Class Definition

class SemanticDistractorModel:
    """
    Semantic-aware distractor with three-layer noise injection.

    Layers:
    1. Surface Noise (50%): Intent/slots preserved
    2. Incomplete Info (30%): Intent clear, slots missing
    3. Semantic Ambiguity (20%): Intent uncertain
    """

Constructor

def __init__(
    self,
    config: Dict[str, Any],
    strategy_config: Optional[Dict[str, Any]] = None,
    llm_client: Optional[LLMClient] = None
):
    """
    Initialize semantic distractor.

    Args:
        config: Main configuration
        strategy_config: Strategy config (or loads from strategy_path)
        llm_client: LLM client for noise generation
    """

Methods

def apply_noise(
    self,
    text: str,
    force: bool = False,
    persona_features: Optional[Dict[str, Any]] = None
) -> NoiseResult:
    """
    Apply semantic noise to text.

    Args:
        text: Original text
        force: Ignore activation probability
        persona_features: Optional persona for personalized noise

    Returns:
        NoiseResult with noisy text and metadata
    """

def apply_noise_batch(
    self,
    texts: List[str],
    show_progress: bool = True,
    persona_features: Optional[Dict[str, Any]] = None
) -> List[NoiseResult]:
    """Apply noise to multiple texts."""

Attributes

Attribute

Type

Description

enabled

bool

Whether distractor is enabled

activation_probability

float

Probability of applying noise

layer_weights

Dict[str, float]

Weight per layer

extractor

IntentSlotExtractor

Semantic extractor

generator

LLMNoiseGenerator

Noise generator

DistractorModel

from src.distractor import DistractorModel

Class Definition

class DistractorModel:
    """
    Rule-based distractor (legacy).

    Strategies: typo, word_swap, word_deletion, word_insertion,
                synonym_replacement, paraphrase
    """

Methods

def apply_noise(self, text: str, force: bool = False) -> List[NoisyVersion]:
    """
    Apply noise strategies to text.

    Returns:
        List of NoisyVersion objects
    """

def apply_to_interaction(self, interaction: Dict) -> Dict:
    """Apply noise to an interaction."""

NoiseResult

from src.noise_generator import NoiseResult

Class Definition

@dataclass
class NoiseResult:
    """
    Result of semantic noise application.

    Attributes:
        original_text: Original clean text
        noisy_text: Text with noise applied
        layer: Layer name (surface_noise, incomplete_info, semantic_ambiguity)
        layer_index: Layer number (1, 2, 3)
        applied_strategies: List of strategy names
        metadata: Additional information
        semantics: Extracted intent/slots
    """

Methods

def to_dict(self) -> Dict[str, Any]:
    """Convert to dictionary."""

NoisyVersion

from src.distractor import NoisyVersion

Class Definition

@dataclass
class NoisyVersion:
    """
    Legacy noise result.

    Attributes:
        original_text: Original text
        noisy_text: Noisy text
        noise_type: Strategy name
        noise_intensity: Noise level (0-1)
        metadata: Strategy configuration
    """

IntentSlotExtractor

from src.intent_extractor import IntentSlotExtractor

Class Definition

class IntentSlotExtractor:
    """Extracts intent and slots from text using LLM."""

Methods

def extract(self, text: str) -> ExtractedSemantics:
    """
    Extract intent and slots.

    Returns:
        ExtractedSemantics with intent, slots, confidence
    """

LLMNoiseGenerator

from src.noise_generator import LLMNoiseGenerator

Class Definition

class LLMNoiseGenerator:
    """Generates noisy text using LLM based on strategies."""

Methods

def generate_with_result(
    self,
    semantics: ExtractedSemantics,
    layer: str,
    layer_index: int,
    strategies: List[str],
    persona_features: Optional[Dict] = None
) -> NoiseResult:
    """
    Generate noisy version.

    Args:
        semantics: Extracted intent/slots
        layer: Target layer
        layer_index: Layer number
        strategies: Strategies to apply
        persona_features: Optional persona context

    Returns:
        NoiseResult with generated noise
    """

Usage Examples

Semantic Distractor

from src.distractor import SemanticDistractorModel

distractor = SemanticDistractorModel(config)

result = distractor.apply_noise(
    text="Help me write a Python script for data processing",
    persona_features={'communication_style': 'casual'}
)

print(f"Original: {result.original_text}")
print(f"Noisy: {result.noisy_text}")
print(f"Layer: {result.layer}")
print(f"Strategies: {result.applied_strategies}")

Legacy Distractor

from src.distractor import DistractorModel

distractor = DistractorModel(config)

versions = distractor.apply_noise("Help me write code")

for v in versions:
    print(f"{v.noise_type}: {v.noisy_text}")

Intent Extraction

from src.intent_extractor import IntentSlotExtractor

extractor = IntentSlotExtractor(llm_client)

semantics = extractor.extract("Book a flight to Paris for Monday")

print(f"Intent: {semantics.intent}")
print(f"Slots: {semantics.slots}")

See Also