additory 0.1.0a1__py3-none-any.whl

additory/augment/strategies.py

@@ -0,0 +1,883 @@
+"""
+Strategy handlers for data augmentation
+
+Provides different strategies for generating synthetic data:
+- auto: Random sampling from existing values
+- increment: Increment numeric or pattern-based values
+- choice:[...]: Random selection from inline list
+- choice_list:name: Random selection from registered/built-in list
+"""
+
+import re
+import random
+from typing import Any, Dict, List, Optional, Tuple
+
+from additory.common.exceptions import ValidationError, AugmentError
+from additory.augment.list_registry import get_list
+
+
+def parse_strategy_params(strategy_spec: str) -> Tuple[str, Dict[str, Any]]:
+    """
+    Parse strategy specification with inline parameters.
+    
+    Supports two formats:
+    1. key=value format: "increment:start=100:pattern=EMP_[001]"
+    2. range format: "range:18-65"
+    
+    Args:
+        strategy_spec: Strategy string with optional parameters
+    
+    Returns:
+        Tuple of (strategy_name, params_dict)
+        - strategy_name: Base strategy name (e.g., "increment", "range")
+        - params_dict: Dictionary of parsed parameters
+    
+    Raises:
+        ValidationError: If parameter format is invalid
+    
+    Examples:
+        >>> parse_strategy_params("increment")
+        ("increment", {})
+        
+        >>> parse_strategy_params("increment:start=100")
+        ("increment", {"start": 100})
+        
+        >>> parse_strategy_params("increment:start=100:pattern=EMP_[001]")
+        ("increment", {"start": 100, "pattern": "EMP_[001]"})
+        
+        >>> parse_strategy_params("range:18-65")
+        ("range", {"min": 18, "max": 65})
+    """
+    if not strategy_spec or not strategy_spec.strip():
+        raise ValidationError("Empty strategy specification")
+    
+    parts = strategy_spec.split(":")
+    
+    strategy_name = parts[0].strip()
+    
+    if not strategy_name:
+        raise ValidationError("Empty strategy name")
+    
+    if len(parts) == 1:
+        # No parameters
+        return strategy_name, {}
+    
+    # Special case: range format "range:18-65"
+    if strategy_name == "range" and len(parts) == 2:
+        range_part = parts[1].strip()
+        
+        # Check if it's the min-max format (no = sign)
+        if "=" not in range_part:
+            if "-" not in range_part:
+                raise ValidationError(
+                    f"Invalid range format: {range_part}. "
+                    "Expected format: range:min-max (e.g., range:18-65)"
+                )
+            
+            # Split by dash, handling negative numbers
+            # Use regex to properly split on dash
+            match = re.match(r'^(-?\d+)-(-?\d+)$', range_part)
+            if match:
+                try:
+                    min_val = int(match.group(1))
+                    max_val = int(match.group(2))
+                    return strategy_name, {"min": min_val, "max": max_val}
+                except ValueError:
+                    raise ValidationError(
+                        f"Invalid range format: {range_part}. "
+                        "Expected format: range:min-max (e.g., range:18-65)"
+                    )
+            else:
+                raise ValidationError(
+                    f"Invalid range format: {range_part}. "
+                    "Expected format: range:min-max (e.g., range:18-65)"
+                )
+    
+    # Parse key=value parameters
+    params = {}
+    
+    for i in range(1, len(parts)):
+        param_part = parts[i].strip()
+        
+        if "=" not in param_part:
+            raise ValidationError(
+                f"Invalid parameter format: '{param_part}'. "
+                "Expected format: key=value (e.g., start=100)"
+            )
+        
+        key, value = param_part.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        
+        if not key:
+            raise ValidationError(
+                f"Empty parameter key in: '{param_part}'"
+            )
+        
+        if not value:
+            raise ValidationError(
+                f"Empty parameter value for key '{key}'"
+            )
+        
+        # Try to convert numeric strings to integers
+        try:
+            # Check if it's a valid integer
+            if value.lstrip('-').isdigit():
+                params[key] = int(value)
+            else:
+                # Keep as string
+                params[key] = value
+        except ValueError:
+            # Keep as string if conversion fails
+            params[key] = value
+    
+    return strategy_name, params
+
+
+def parse_increment_strategy(strategy_spec: str) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Parse increment strategy specification.
+    
+    Args:
+        strategy_spec: Strategy string like:
+            - "increment"
+            - "increment:EMP_[001]_ID"
+            - r"increment:A(\\d+)"
+    
+    Returns:
+        Tuple of (pattern, regex_pattern)
+        - pattern: Original pattern string (for bracket notation)
+        - regex_pattern: Compiled regex pattern (for extraction)
+    
+    Examples:
+        >>> parse_increment_strategy("increment")
+        (None, None)
+        
+        >>> parse_increment_strategy("increment:EMP_[001]_ID")
+        ("EMP_[001]_ID", r"EMP_(\\d{3})_ID")
+        
+        >>> parse_increment_strategy(r"increment:A(\\d+)")
+        (None, r"A(\\d+)")
+    """
+    parts = strategy_spec.split(":", 1)
+    
+    if len(parts) == 1:
+        # Simple "increment" with no pattern
+        return None, None
+    
+    pattern_str = parts[1].strip()
+    
+    # Check if it's bracket notation: EMP_[001]_ID
+    if "[" in pattern_str and "]" in pattern_str:
+        # Extract the bracketed part
+        bracket_match = re.search(r'\[(\d+)\]', pattern_str)
+        if not bracket_match:
+            raise ValidationError(
+                f"Invalid bracket pattern: {pattern_str}. "
+                "Brackets must contain digits, e.g., [001] or [123]"
+            )
+        
+        # Get the number inside brackets to determine padding
+        number_str = bracket_match.group(1)
+        padding = len(number_str)
+        
+        # Convert bracket notation to regex
+        # EMP_[001]_ID -> EMP_(\d{3})_ID
+        regex_pattern = pattern_str.replace(f"[{number_str}]", f"(\\d{{{padding}}})")
+        
+        return pattern_str, regex_pattern
+    
+    # Otherwise, assume it's already a regex pattern
+    # Validate that it has a capture group
+    if "(" not in pattern_str or ")" not in pattern_str:
+        raise ValidationError(
+            f"Invalid pattern: {pattern_str}. "
+            "Pattern must either use bracket notation [001] or regex with capture group (\\d+)"
+        )
+    
+    return None, pattern_str
+
+
+def validate_increment_column(
+    last_value: Any,
+    pattern: Optional[str],
+    regex_pattern: Optional[str]
+) -> Tuple[int, Optional[str], Optional[int]]:
+    """
+    Validate that a column can be incremented and extract current value.
+    
+    Args:
+        last_value: Last value in the column
+        pattern: Pattern string (if using bracket notation)
+        regex_pattern: Regex pattern (if provided)
+    
+    Returns:
+        Tuple of (current_number, prefix_suffix_template, padding)
+        - current_number: The numeric value to increment from
+        - prefix_suffix_template: Template for reconstruction (e.g., "EMP_{}_ID")
+        - padding: Number of digits for zero-padding (or None)
+    
+    Raises:
+        ValidationError: If column cannot be incremented
+    """
+    last_value_str = str(last_value)
+    
+    # Case 1: Pure numeric value
+    if regex_pattern is None and pattern is None:
+        try:
+            current_number = int(last_value)
+            return current_number, None, None
+        except (ValueError, TypeError):
+            raise ValidationError(
+                f"Column has non-numeric last value '{last_value}'. "
+                "For non-numeric columns, you must provide a pattern. "
+                "Examples: 'increment:EMP_[001]_ID' or 'increment:A(\\d+)'"
+            )
+    
+    # Case 2: Pattern-based value
+    if regex_pattern is None:
+        raise ValidationError("Pattern parsing failed - this should not happen")
+    
+    # Try to match the pattern
+    match = re.search(regex_pattern, last_value_str)
+    if not match:
+        raise ValidationError(
+            f"Pattern '{pattern or regex_pattern}' does not match last value '{last_value}'. "
+            "Please verify the pattern matches your data."
+        )
+    
+    # Extract the numeric part
+    try:
+        number_str = match.group(1)
+        current_number = int(number_str)
+        padding = len(number_str) if number_str.startswith('0') else None
+    except (ValueError, IndexError):
+        raise ValidationError(
+            f"Could not extract numeric value from '{last_value}' using pattern '{pattern or regex_pattern}'"
+        )
+    
+    # Create template for reconstruction
+    # Replace the captured group with {} placeholder
+    template = re.sub(r'\([^)]+\)', '{}', regex_pattern)
+    # Remove regex special characters for simple replacement
+    template = template.replace('\\d', '').replace('{', '').replace('}', '')
+    
+    # Better approach: use the actual matched string positions
+    start, end = match.span(1)
+    template = last_value_str[:start] + '{}' + last_value_str[end:]
+    
+    return current_number, template, padding
+
+
+def generate_increment_values(
+    start_number: int,
+    count: int,
+    template: Optional[str],
+    padding: Optional[int]
+) -> List[Any]:
+    """
+    Generate incremented values.
+    
+    Args:
+        start_number: Starting number (last value + 1)
+        count: Number of values to generate
+        template: Template for reconstruction (e.g., "EMP_{}_ID")
+        padding: Number of digits for zero-padding
+    
+    Returns:
+        List of generated values
+    """
+    values = []
+    
+    for i in range(count):
+        new_number = start_number + i
+        
+        if template is None:
+            # Pure numeric
+            values.append(new_number)
+        else:
+            # Pattern-based
+            if padding:
+                number_str = str(new_number).zfill(padding)
+            else:
+                number_str = str(new_number)
+            
+            new_value = template.format(number_str)
+            values.append(new_value)
+    
+    return values
+
+
+def apply_increment_strategy(
+    df_polars: Any,
+    column: str,
+    strategy_spec: str,
+    n_rows: int,
+    params: Optional[Dict[str, Any]] = None
+) -> List[Any]:
+    """
+    Apply increment strategy to a column (Polars-only).
+    
+    Supports two modes:
+    1. Augment mode: Increment from last value in df_polars
+    2. Create mode: Start from specified value (requires params with 'start')
+    
+    Args:
+        df_polars: Input Polars DataFrame (None in create mode)
+        column: Column name to increment
+        strategy_spec: Strategy specification (e.g., "increment:EMP_[001]_ID")
+        n_rows: Number of new values to generate
+        params: Optional parameters dict with 'start' and/or 'pattern' keys
+    
+    Returns:
+        List of new values for the column
+    
+    Raises:
+        ValidationError: If strategy cannot be applied
+    
+    Examples:
+        # Augment mode (with DataFrame)
+        >>> apply_increment_strategy(df, "id", "increment", 5)
+        [11, 12, 13, 14, 15]  # if last value was 10
+        
+        # Create mode (no DataFrame, with start parameter)
+        >>> apply_increment_strategy(None, "id", "increment", 5, {"start": 100})
+        [100, 101, 102, 103, 104]
+        
+        # Create mode with pattern
+        >>> apply_increment_strategy(None, "emp_id", "increment", 3, 
+        ...                          {"start": 1, "pattern": "EMP_[001]"})
+        ["EMP_001", "EMP_002", "EMP_003"]
+    """
+    # Determine mode: augment (has df) or create (no df)
+    is_create_mode = df_polars is None
+    
+    if is_create_mode:
+        # Create mode: use start parameter
+        if params is None or "start" not in params:
+            raise ValidationError(
+                f"Increment strategy in create mode requires 'start' parameter. "
+                f"Use format: 'increment:start=N' or 'increment:start=N:pattern=P'"
+            )
+        
+        start_number = params["start"]
+        
+        # Check if pattern is provided in params
+        if "pattern" in params:
+            pattern_str = params["pattern"]
+            
+            # Parse the pattern to get template and padding
+            if "[" in pattern_str and "]" in pattern_str:
+                # Bracket notation: EMP_[001]
+                bracket_match = re.search(r'\[(\d+)\]', pattern_str)
+                if not bracket_match:
+                    raise ValidationError(
+                        f"Invalid bracket pattern: {pattern_str}. "
+                        "Brackets must contain digits, e.g., [001] or [123]"
+                    )
+                
+                number_str = bracket_match.group(1)
+                padding = len(number_str)
+                
+                # Create template by replacing [NNN] with {}
+                template = pattern_str.replace(f"[{number_str}]", "{}")
+            else:
+                raise ValidationError(
+                    f"Invalid pattern: {pattern_str}. "
+                    "Pattern must use bracket notation [001]"
+                )
+        else:
+            # No pattern, pure numeric
+            template = None
+            padding = None
+        
+        # Generate values starting from start_number
+        new_values = generate_increment_values(
+            start_number=start_number,
+            count=n_rows,
+            template=template,
+            padding=padding
+        )
+        
+        return new_values
+    
+    else:
+        # Augment mode: use existing logic
+        # Parse the strategy
+        pattern, regex_pattern = parse_increment_strategy(strategy_spec)
+        
+        # Get last value from the Polars column
+        last_value = df_polars[column][-1]
+        
+        # Validate and extract current value
+        current_number, template, padding = validate_increment_column(
+            last_value, pattern, regex_pattern
+        )
+        
+        # Generate new values starting from current + 1
+        new_values = generate_increment_values(
+            start_number=current_number + 1,
+            count=n_rows,
+            template=template,
+            padding=padding
+        )
+        
+        return new_values
+
+
+def parse_strategy_dict(strategy: Any) -> Dict[str, str]:
+    """
+    Parse and validate strategy parameter.
+    
+    Args:
+        strategy: Strategy specification, can be:
+            - str: "auto" (default for all columns)
+            - dict: {"col1": "increment", "col2": "auto", ...}
+    
+    Returns:
+        Dictionary mapping column names to strategy specs
+    
+    Raises:
+        ValidationError: If strategy format is invalid
+    """
+    if isinstance(strategy, str):
+        # Simple string strategy applies to all columns
+        return {"__default__": strategy}
+    
+    if isinstance(strategy, dict):
+        # Validate all strategy values are strings
+        for col, strat in strategy.items():
+            if not isinstance(strat, str):
+                raise ValidationError(
+                    f"Strategy for column '{col}' must be a string, got {type(strat)}"
+                )
+        return strategy
+    
+    raise ValidationError(
+        f"Strategy must be str or dict, got {type(strategy)}"
+    )
+
+
+def get_column_strategy(column: str, strategy_dict: Dict[str, str]) -> str:
+    """
+    Get strategy for a specific column.
+    
+    Args:
+        column: Column name
+        strategy_dict: Parsed strategy dictionary
+    
+    Returns:
+        Strategy string for the column (defaults to "auto")
+    """
+    if column in strategy_dict:
+        return strategy_dict[column]
+    
+    # Return default strategy
+    return strategy_dict.get("__default__", "auto")
+
+
+def parse_choice_strategy(strategy_spec: str) -> Tuple[str, Optional[List[Any]]]:
+    """
+    Parse choice strategy specification.
+    
+    Args:
+        strategy_spec: Strategy string like:
+            - "choice:[value1,value2,value3]"
+            - "choice_list:banks"
+    
+    Returns:
+        Tuple of (strategy_type, values)
+        - strategy_type: "choice" or "choice_list"
+        - values: List of values (for choice) or None (for choice_list)
+    
+    Raises:
+        ValidationError: If strategy format is invalid
+    
+    Examples:
+        >>> parse_choice_strategy("choice:[Active,Inactive,Pending]")
+        ("choice", ["Active", "Inactive", "Pending"])
+        
+        >>> parse_choice_strategy("choice_list:banks")
+        ("choice_list", None)
+    """
+    if strategy_spec.startswith("choice:["):
+        # Inline list: choice:[value1,value2,value3]
+        if not strategy_spec.endswith("]"):
+            raise ValidationError(
+                f"Invalid choice strategy: {strategy_spec}. "
+                "Must be in format: choice:[value1,value2,value3]"
+            )
+        
+        # Extract values between [ and ]
+        values_str = strategy_spec[len("choice:["):-1]
+        
+        if not values_str.strip():
+            raise ValidationError(
+                f"Choice list cannot be empty: {strategy_spec}"
+            )
+        
+        # Split by comma and strip whitespace
+        values = [v.strip() for v in values_str.split(",")]
+        
+        if len(values) == 0:
+            raise ValidationError(
+                f"Choice list must contain at least one value: {strategy_spec}"
+            )
+        
+        return "choice", values
+    
+    elif strategy_spec.startswith("choice_list:"):
+        # Named list: choice_list:banks
+        list_name = strategy_spec[len("choice_list:"):].strip()
+        
+        if not list_name:
+            raise ValidationError(
+                f"Invalid choice_list strategy: {strategy_spec}. "
+                "Must be in format: choice_list:list_name"
+            )
+        
+        return "choice_list", list_name
+    
+    else:
+        raise ValidationError(
+            f"Invalid choice strategy: {strategy_spec}. "
+            "Must start with 'choice:[' or 'choice_list:'"
+        )
+
+
+def apply_range_strategy(
+    min_val: int,
+    max_val: int,
+    n_rows: int,
+    seed: Optional[int]
+) -> List[int]:
+    """
+    Apply range strategy to generate random integers within a range.
+    
+    Args:
+        min_val: Minimum value (inclusive)
+        max_val: Maximum value (inclusive)
+        n_rows: Number of values to generate
+        seed: Random seed for reproducibility
+    
+    Returns:
+        List of random integers within the specified range
+    
+    Raises:
+        ValidationError: If min_val >= max_val
+    
+    Examples:
+        >>> apply_range_strategy(18, 65, 5, seed=42)
+        [34, 52, 23, 61, 38]
+        
+        >>> apply_range_strategy(40000, 120000, 3, seed=42)
+        [75000, 110000, 45000]
+    """
+    # Validate range
+    if min_val >= max_val:
+        raise ValidationError(
+            f"Invalid range: min ({min_val}) must be less than max ({max_val})"
+        )
+    
+    # Set seed for reproducibility
+    if seed is not None:
+        random.seed(seed)
+    
+    # Generate random integers within range (inclusive)
+    values = [random.randint(min_val, max_val) for _ in range(n_rows)]
+    
+    return values
+
+
+def apply_choice_strategy(
+    strategy_spec: str,
+    n_rows: int,
+    seed: Optional[int]
+) -> List[Any]:
+    """
+    Apply choice strategy to generate values.
+    
+    Args:
+        strategy_spec: Strategy specification (e.g., "choice:[A,B,C]")
+        n_rows: Number of values to generate
+        seed: Random seed for reproducibility
+    
+    Returns:
+        List of randomly selected values
+    
+    Raises:
+        ValidationError: If strategy cannot be applied
+    """
+    # Parse the strategy
+    strategy_type, values_or_name = parse_choice_strategy(strategy_spec)
+    
+    # Get the actual values list
+    if strategy_type == "choice":
+        values = values_or_name
+    elif strategy_type == "choice_list":
+        # Resolve list name to actual list
+        list_name = values_or_name
+        try:
+            values = get_list(list_name)
+        except ValidationError as e:
+            raise ValidationError(
+                f"Cannot apply choice_list strategy: {e}"
+            )
+    else:
+        raise ValidationError(f"Unknown choice strategy type: {strategy_type}")
+    
+    # Generate random selections
+    if seed is not None:
+        # Use Python's random for consistency across backends
+        random.seed(seed)
+    
+    selected_values = random.choices(values, k=n_rows)
+    
+    return selected_values
+
+
+
+def apply_forecast_strategy(
+    df_polars: Any,
+    column: str,
+    strategy_spec: str,
+    n_rows: int,
+    seed: Optional[int] = None
+) -> List[Any]:
+    """
+    Apply forecast strategy to a column.
+    
+    Supports:
+    - forecast:linear
+    - forecast:polynomial
+    - forecast:exponential
+    - forecast:moving_average
+    - forecast:seasonal
+    - forecast:auto
+    
+    Args:
+        df_polars: Input Polars DataFrame
+        column: Column name to forecast
+        strategy_spec: Strategy specification (e.g., "forecast:seasonal:period=12")
+        n_rows: Number of values to forecast
+        seed: Random seed (not used for deterministic forecasts)
+    
+    Returns:
+        List of forecasted values
+    
+    Raises:
+        ValidationError: If strategy cannot be applied
+    
+    Examples:
+        >>> apply_forecast_strategy(df, "sales", "forecast:linear", 10)
+        [105.2, 110.4, 115.6, ...]
+        
+        >>> apply_forecast_strategy(df, "sales", "forecast:seasonal:period=12", 24)
+        [98.5, 102.3, 95.8, ...]
+    """
+    from additory.augment.forecast import forecast_values, ForecastMethod
+    
+    # Parse strategy: forecast:method:param1=val1:param2=val2
+    parts = strategy_spec.split(":")
+    
+    if len(parts) < 2:
+        raise ValidationError(
+            f"Invalid forecast strategy: {strategy_spec}. "
+            "Expected format: forecast:method or forecast:method:param=value"
+        )
+    
+    # parts[0] is "forecast", parts[1] is method
+    method = parts[1].strip()
+    
+    # Parse additional parameters
+    params = {}
+    for i in range(2, len(parts)):
+        param_part = parts[i].strip()
+        
+        if "=" in param_part:
+            key, value = param_part.split("=", 1)
+            key = key.strip()
+            value = value.strip()
+            
+            # Try to convert to int/float
+            try:
+                if "." in value:
+                    params[key] = float(value)
+                else:
+                    params[key] = int(value)
+            except ValueError:
+                params[key] = value
+    
+    # Call forecast function
+    try:
+        return forecast_values(
+            df_polars,
+            column,
+            n_rows,
+            method=method,
+            **params
+        )
+    except Exception as e:
+        raise ValidationError(f"Forecast strategy failed: {e}")
+
+
+def apply_distribution_strategy(
+    df_polars: Any,
+    column: str,
+    strategy_spec: str,
+    n_rows: int,
+    seed: Optional[int] = None
+) -> List[Any]:
+    """
+    Apply distribution strategy to a column.
+    
+    Supports:
+    - normal (or normal:auto)
+    - normal:mean=X:std=Y
+    - uniform:min=X:max=Y
+    - skewed_left:skewness=X
+    - skewed_right:skewness=X
+    
+    Args:
+        df_polars: Input Polars DataFrame (for parameter estimation)
+        column: Column name to generate from
+        strategy_spec: Strategy specification (e.g., "normal:auto")
+        n_rows: Number of values to generate
+        seed: Random seed for reproducibility
+    
+    Returns:
+        List of generated values
+    
+    Raises:
+        ValidationError: If strategy cannot be applied
+    
+    Examples:
+        >>> apply_distribution_strategy(df, "age", "normal:auto", 100, seed=42)
+        [34.5, 28.9, 41.2, ...]
+        
+        >>> apply_distribution_strategy(df, "score", "uniform:min=0:max=100", 50)
+        [45.2, 78.9, 12.3, ...]
+    """
+    from additory.common.distributions import generate_distribution_values
+    
+    # Parse strategy: distribution:param1=val1:param2=val2
+    parts = strategy_spec.split(":")
+    
+    if len(parts) < 1:
+        raise ValidationError(f"Invalid distribution strategy: {strategy_spec}")
+    
+    distribution = parts[0].strip()
+    
+    # Parse additional parameters
+    params = {}
+    auto_mode = False
+    
+    for i in range(1, len(parts)):
+        param_part = parts[i].strip()
+        
+        if param_part == "auto":
+            # Special case: normal:auto
+            auto_mode = True
+            continue
+        
+        if "=" in param_part:
+            key, value = param_part.split("=", 1)
+            key = key.strip()
+            value = value.strip()
+            
+            # Try to convert to int/float
+            try:
+                if "." in value:
+                    params[key] = float(value)
+                else:
+                    params[key] = int(value)
+            except ValueError:
+                params[key] = value
+    
+    # Get existing data for parameter estimation
+    data = df_polars[column].to_numpy()
+    
+    # Determine distribution type
+    if auto_mode:
+        dist_type = 'auto'
+    else:
+        dist_type = distribution
+    
+    # Call distribution function
+    try:
+        return generate_distribution_values(
+            n_rows,
+            distribution=dist_type,
+            data=data,
+            seed=seed,
+            **params
+        )
+    except Exception as e:
+        raise ValidationError(f"Distribution strategy failed: {e}")
+
+
+def apply_smote_strategy(
+    df_polars: Any,
+    columns: List[str],
+    strategy_spec: str,
+    n_rows: int,
+    seed: Optional[int] = None
+) -> Dict[str, List[Any]]:
+    """
+    Apply SMOTE strategy to multiple columns.
+    
+    SMOTE generates synthetic samples using k-nearest neighbors.
+    
+    Args:
+        df_polars: Input Polars DataFrame
+        columns: List of column names to use for SMOTE
+        strategy_spec: Strategy specification (e.g., "smote:k=5")
+        n_rows: Number of synthetic samples to generate
+        seed: Random seed for reproducibility
+    
+    Returns:
+        Dictionary mapping column names to generated values
+    
+    Raises:
+        ValidationError: If strategy cannot be applied
+    
+    Examples:
+        >>> apply_smote_strategy(df, ["feature1", "feature2"], "smote:k=5", 100)
+        {"feature1": [1.2, 3.4, ...], "feature2": [5.6, 7.8, ...]}
+    """
+    from additory.augment.smote import generate_smote_values
+    
+    # Parse strategy: smote:k=5
+    parts = strategy_spec.split(":")
+    
+    # Parse parameters
+    params = {}
+    for i in range(1, len(parts)):
+        param_part = parts[i].strip()
+        
+        if "=" in param_part:
+            key, value = param_part.split("=", 1)
+            key = key.strip()
+            value = value.strip()
+            
+            # Convert k to k_neighbors
+            if key == "k":
+                key = "k_neighbors"
+            
+            # Try to convert to int
+            try:
+                params[key] = int(value)
+            except ValueError:
+                params[key] = value
+    
+    # Call SMOTE function
+    try:
+        return generate_smote_values(
+            df_polars,
+            columns,
+            n_rows,
+            seed=seed,
+            **params
+        )
+    except Exception as e:
+        raise ValidationError(f"SMOTE strategy failed: {e}")