additory 0.1.0a1__py3-none-any.whl

additory/common/__init__.py

@@ -0,0 +1,157 @@
+"""
+Common Utilities Module
+
+Shared functionality used by both augment and synthetic modules:
+- Distribution functions (normal, uniform, skewed, etc.)
+- List file management (.list format)
+- Pattern file management (.properties format)
+- Fallback resolution logic
+
+This module eliminates code duplication and provides consistent behavior
+across augment and synthetic data generation.
+"""
+
+from .distributions import (
+    generate_normal,
+    generate_uniform,
+    generate_skewed,
+    generate_beta,
+    generate_gamma,
+    generate_exponential_dist,
+    generate_kde,
+    generate_multivariate_normal,
+    generate_distribution_values,
+    estimate_distribution_params,
+    calculate_skewness,
+    detect_distribution_type,
+    DistributionType,
+)
+
+from .lists import (
+    load_list_file,
+    parse_list_file,
+    get_list_values,
+    list_all_lists,
+)
+
+from .patterns import (
+    load_properties_file,
+    parse_properties_file,
+    get_pattern,
+    list_all_patterns,
+)
+
+from .resolver import (
+    resolve_pattern,
+    resolve_with_logging,
+    PatternResolutionResult,
+    PreferMode,
+)
+
+from .backend import (
+    detect_backend,
+    is_dataframe,
+    to_polars,
+    from_polars,
+    BackendType,
+)
+
+from .validation import (
+    validate_dataframe,
+    validate_columns_exist,
+    validate_positive_number,
+    validate_non_negative_number,
+    validate_parameter_choice,
+    validate_ratio,
+    validate_string_not_empty,
+    validate_integer_in_range,
+    ValidationError,
+)
+
+from .exceptions import (
+    AdditoryError,
+    ValidationError,
+    BackendError,
+    ConversionError,
+    ExpressionError,
+    ConfigurationError,
+    UnitConversionError,
+    EncodingError,
+    LookupError,
+    SyntheticDataError,
+    AugmentError,
+)
+
+from .column_utils import (
+    sanitize_column_name,
+    generate_safe_column_name,
+    validate_column_name,
+    truncate_column_name,
+    generate_column_names_with_prefix_suffix,
+)
+
+__all__ = [
+    # Distribution functions
+    "generate_normal",
+    "generate_uniform",
+    "generate_skewed",
+    "generate_beta",
+    "generate_gamma",
+    "generate_exponential_dist",
+    "generate_kde",
+    "generate_multivariate_normal",
+    "generate_distribution_values",
+    "estimate_distribution_params",
+    "calculate_skewness",
+    "detect_distribution_type",
+    "DistributionType",
+    # List management
+    "load_list_file",
+    "parse_list_file",
+    "get_list_values",
+    "list_all_lists",
+    # Pattern management
+    "load_properties_file",
+    "parse_properties_file",
+    "get_pattern",
+    "list_all_patterns",
+    # Resolution
+    "resolve_pattern",
+    "resolve_with_logging",
+    "PatternResolutionResult",
+    "PreferMode",
+    # Backend detection
+    "detect_backend",
+    "is_dataframe",
+    "to_polars",
+    "from_polars",
+    "BackendType",
+    # Validation
+    "validate_dataframe",
+    "validate_columns_exist",
+    "validate_positive_number",
+    "validate_non_negative_number",
+    "validate_parameter_choice",
+    "validate_ratio",
+    "validate_string_not_empty",
+    "validate_integer_in_range",
+    "ValidationError",
+    # Exceptions
+    "AdditoryError",
+    "ValidationError",
+    "BackendError",
+    "ConversionError",
+    "ExpressionError",
+    "ConfigurationError",
+    "UnitConversionError",
+    "EncodingError",
+    "LookupError",
+    "SyntheticDataError",
+    "AugmentError",
+    # Column utilities
+    "sanitize_column_name",
+    "generate_safe_column_name",
+    "validate_column_name",
+    "truncate_column_name",
+    "generate_column_names_with_prefix_suffix",
+]

additory/common/backend.py

@@ -0,0 +1,355 @@
+"""
+Unified Backend Detection System
+
+Provides consistent backend detection across all additory modules.
+"""
+
+import pandas as pd
+from typing import Any, Literal, Dict
+
+# Optional imports
+try:
+    import polars as pl
+    HAS_POLARS = True
+except ImportError:
+    HAS_POLARS = False
+    pl = None
+
+try:
+    import cudf
+    HAS_CUDF = True
+except (ImportError, Exception):
+    HAS_CUDF = False
+    cudf = None
+
+
+BackendType = Literal['pandas', 'polars', 'cudf']
+ExecutionMode = Literal['cpu', 'gpu']
+
+
+def detect_backend(df: Any) -> BackendType:
+    """
+    Detect the specific backend type of a dataframe.
+    
+    Args:
+        df: Dataframe to detect
+        
+    Returns:
+        'pandas', 'polars', or 'cudf'
+        
+    Raises:
+        TypeError: If not a supported dataframe type
+        
+    Usage:
+        - Use this when you need to know the SPECIFIC backend
+        - For utilities that need native operations
+        - For type-specific conversions
+        
+    Examples:
+        >>> backend = detect_backend(df)
+        >>> if backend == 'polars':
+        ...     result = df.select(...)
+        >>> elif backend == 'pandas':
+        ...     result = df[...]
+    """
+    if isinstance(df, pd.DataFrame):
+        return 'pandas'
+    elif HAS_POLARS and isinstance(df, pl.DataFrame):
+        return 'polars'
+    elif HAS_CUDF and isinstance(df, cudf.DataFrame):
+        return 'cudf'
+    else:
+        raise TypeError(
+            f"Unsupported dataframe type: {type(df)}. "
+            f"Supported types: pandas.DataFrame"
+            f"{', polars.DataFrame' if HAS_POLARS else ''}"
+            f"{', cudf.DataFrame' if HAS_CUDF else ''}"
+        )
+
+
+def detect_execution_mode(df: Any, preference: str = None) -> ExecutionMode:
+    """
+    Detect execution mode (CPU vs GPU) for expression processing.
+    
+    Args:
+        df: Dataframe to detect
+        preference: User preference ('cpu', 'gpu', or None for auto)
+        
+    Returns:
+        'cpu' or 'gpu'
+        
+    Usage:
+        - Use this for expression execution routing
+        - Respects user preferences
+        - Falls back intelligently
+        
+    Examples:
+        >>> mode = detect_execution_mode(df, preference='gpu')
+        >>> if mode == 'gpu':
+        ...     # Use GPU-accelerated execution
+    """
+    backend = detect_backend(df)
+    
+    # User preference takes priority
+    if preference == 'gpu' and HAS_CUDF:
+        return 'gpu'
+    elif preference == 'cpu':
+        return 'cpu'
+    
+    # Auto-detect based on dataframe type
+    if backend == 'cudf':
+        return 'gpu'
+    else:
+        return 'cpu'
+
+
+def is_dataframe(obj: Any) -> bool:
+    """
+    Check if object is any supported dataframe type.
+    
+    Args:
+        obj: Object to check
+        
+    Returns:
+        True if supported dataframe type
+        
+    Usage:
+        - Use for simple boolean checks
+        - Fast validation without exceptions
+        
+    Examples:
+        >>> if is_dataframe(obj):
+        ...     process(obj)
+    """
+    return (
+        isinstance(obj, pd.DataFrame) or
+        (HAS_POLARS and isinstance(obj, pl.DataFrame)) or
+        (HAS_CUDF and isinstance(obj, cudf.DataFrame))
+    )
+
+
+def get_available_backends() -> Dict[str, bool]:
+    """
+    Get availability status of all backends.
+    
+    Returns:
+        Dictionary mapping backend name to availability
+        
+    Examples:
+        >>> backends = get_available_backends()
+        >>> if backends['polars']:
+        ...     # Use polars-specific features
+    """
+    return {
+        'pandas': True,  # Always available
+        'polars': HAS_POLARS,
+        'cudf': HAS_CUDF
+    }
+
+
+def check_backend_available(backend: BackendType) -> bool:
+    """
+    Check if a specific backend is available.
+    
+    Args:
+        backend: Backend to check ('pandas', 'polars', 'cudf')
+        
+    Returns:
+        True if backend is available
+        
+    Examples:
+        >>> if check_backend_available('polars'):
+        ...     # Safe to use polars
+    """
+    availability = get_available_backends()
+    return availability.get(backend, False)
+
+
+# ============================================================================
+# Arrow Bridge Helpers - Polars-Only Architecture
+# ============================================================================
+
+def get_arrow_bridge():
+    """
+    Get singleton instance of Arrow bridge.
+    
+    Returns:
+        EnhancedArrowBridge instance
+        
+    Usage:
+        - Use for all cross-backend conversions
+        - Handles pandas/polars/cuDF via Arrow
+    """
+    from additory.core.backends.arrow_bridge import EnhancedArrowBridge
+    
+    # Singleton pattern
+    if not hasattr(get_arrow_bridge, '_instance'):
+        get_arrow_bridge._instance = EnhancedArrowBridge()
+    
+    return get_arrow_bridge._instance
+
+
+def to_polars(df: Any, backend_type: BackendType = None) -> 'pl.DataFrame':
+    """
+    Convert any dataframe to Polars via Arrow bridge.
+    
+    This is the primary conversion function for the Polars-only architecture.
+    All operations (expressions, augment, etc.) use this to convert input
+    dataframes to Polars for processing.
+    
+    Args:
+        df: Input dataframe (pandas, polars, or cuDF)
+        backend_type: Source backend type (auto-detected if None)
+        
+    Returns:
+        Polars DataFrame
+        
+    Raises:
+        TypeError: If df is not a supported dataframe type
+        RuntimeError: If conversion fails
+        
+    Examples:
+        >>> # Convert pandas to polars
+        >>> pl_df = to_polars(pandas_df)
+        
+        >>> # Convert cuDF to polars
+        >>> pl_df = to_polars(cudf_df)
+        
+        >>> # Already polars (no-op)
+        >>> pl_df = to_polars(polars_df)
+    """
+    if not HAS_POLARS:
+        raise RuntimeError(
+            "Polars is not available. Install with: pip install polars"
+        )
+    
+    # Fast path: already Polars
+    if isinstance(df, pl.DataFrame):
+        return df
+    
+    # Validate input
+    if not is_dataframe(df):
+        raise TypeError(
+            f"Expected pandas, polars, or cuDF DataFrame, got {type(df)}"
+        )
+    
+    # Auto-detect backend if not provided
+    if backend_type is None:
+        backend_type = detect_backend(df)
+    
+    # Convert via Arrow bridge
+    try:
+        bridge = get_arrow_bridge()
+        arrow_table = bridge.to_arrow(df, backend_type)
+        pl_df = bridge.from_arrow(arrow_table, "polars")
+        return pl_df
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to convert {backend_type} DataFrame to Polars: {e}"
+        ) from e
+
+
+def from_polars(pl_df: 'pl.DataFrame', target_backend: BackendType) -> Any:
+    """
+    Convert Polars dataframe back to target backend via Arrow bridge.
+    
+    This is used to convert results back to the user's original format
+    after processing in Polars.
+    
+    Args:
+        pl_df: Polars DataFrame
+        target_backend: Target backend ('pandas', 'polars', or 'cudf')
+        
+    Returns:
+        DataFrame in target format
+        
+    Raises:
+        TypeError: If pl_df is not a Polars DataFrame
+        ValueError: If target_backend is not supported
+        RuntimeError: If conversion fails
+        
+    Examples:
+        >>> # Convert back to pandas
+        >>> pandas_df = from_polars(pl_df, 'pandas')
+        
+        >>> # Convert back to cuDF
+        >>> cudf_df = from_polars(pl_df, 'cudf')
+        
+        >>> # Keep as polars (no-op)
+        >>> pl_df = from_polars(pl_df, 'polars')
+    """
+    if not HAS_POLARS:
+        raise RuntimeError(
+            "Polars is not available. Install with: pip install polars"
+        )
+    
+    # Validate input
+    if not isinstance(pl_df, pl.DataFrame):
+        raise TypeError(
+            f"Expected Polars DataFrame, got {type(pl_df)}"
+        )
+    
+    # Validate target backend
+    if target_backend not in ('pandas', 'polars', 'cudf'):
+        raise ValueError(
+            f"Invalid target_backend: {target_backend}. "
+            f"Must be 'pandas', 'polars', or 'cudf'"
+        )
+    
+    # Fast path: already target format
+    if target_backend == 'polars':
+        return pl_df
+    
+    # Check target backend availability
+    if target_backend == 'cudf' and not HAS_CUDF:
+        raise RuntimeError(
+            "cuDF is not available. Install with: pip install cudf"
+        )
+    
+    # Convert via Arrow bridge
+    try:
+        bridge = get_arrow_bridge()
+        arrow_table = bridge.to_arrow(pl_df, "polars")
+        result_df = bridge.from_arrow(arrow_table, target_backend)
+        return result_df
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to convert Polars DataFrame to {target_backend}: {e}"
+        ) from e
+
+
+def convert_via_polars(df: Any, target_backend: BackendType = None) -> Any:
+    """
+    Convert dataframe to target backend via Polars (round-trip conversion).
+    
+    This is a convenience function that combines to_polars() and from_polars().
+    Useful for format conversions without processing.
+    
+    Args:
+        df: Input dataframe
+        target_backend: Target backend (defaults to input backend)
+        
+    Returns:
+        DataFrame in target format
+        
+    Examples:
+        >>> # Convert pandas to cuDF via Polars
+        >>> cudf_df = convert_via_polars(pandas_df, 'cudf')
+        
+        >>> # Round-trip (normalize via Polars)
+        >>> normalized_df = convert_via_polars(df)
+    """
+    # Detect input backend
+    input_backend = detect_backend(df)
+    
+    # Default to same backend
+    if target_backend is None:
+        target_backend = input_backend
+    
+    # Fast path: same backend
+    if input_backend == target_backend:
+        return df
+    
+    # Convert via Polars
+    pl_df = to_polars(df, input_backend)
+    return from_polars(pl_df, target_backend)

additory/common/column_utils.py

@@ -0,0 +1,191 @@
+"""
+Common Column Utilities
+
+Provides column name handling utilities shared across modules.
+"""
+
+import re
+from typing import List
+from .exceptions import ValidationError
+
+
+def sanitize_column_name(col_name: str) -> str:
+    """
+    Convert column name to Python-friendly identifier.
+    
+    Rules:
+    - Replace spaces and special chars with underscores
+    - Remove consecutive underscores  
+    - Remove leading/trailing underscores
+    - Ensure doesn't start with number
+    - Convert to lowercase for consistency
+    
+    Args:
+        col_name: Original column name
+        
+    Returns:
+        Sanitized column name safe for Python identifiers
+        
+    Examples:
+        >>> sanitize_column_name("height collected on site")
+        'height_collected_on_site'
+        >>> sanitize_column_name("Patient Height - Site A")
+        'patient_height_site_a'
+        >>> sanitize_column_name("Weight (kg)")
+        'weight_kg'
+        >>> sanitize_column_name("temp@location#1")
+        'temp_location_1'
+    """
+    # Convert to string and handle None/empty
+    if not col_name:
+        return "unnamed_column"
+    
+    col_str = str(col_name)
+    
+    # Replace non-alphanumeric chars with underscores
+    sanitized = re.sub(r'[^a-zA-Z0-9_]', '_', col_str)
+    
+    # Remove consecutive underscores
+    sanitized = re.sub(r'_+', '_', sanitized)
+    
+    # Remove leading/trailing underscores
+    sanitized = sanitized.strip('_')
+    
+    # Ensure doesn't start with number
+    if sanitized and sanitized[0].isdigit():
+        sanitized = f"col_{sanitized}"
+    
+    # Convert to lowercase for consistency
+    sanitized = sanitized.lower()
+    
+    return sanitized if sanitized else "unnamed_column"
+
+
+def generate_safe_column_name(base_name: str, existing_columns: List[str]) -> str:
+    """
+    Generate a safe column name that doesn't conflict with existing columns.
+    
+    Args:
+        base_name: Desired column name
+        existing_columns: List of existing column names
+        
+    Returns:
+        Safe column name with _1, _2, etc. suffix if needed
+        
+    Examples:
+        >>> generate_safe_column_name("value", ["value", "value_1"])
+        'value_2'
+        >>> generate_safe_column_name("new_col", ["col1", "col2"])
+        'new_col'
+    """
+    if base_name not in existing_columns:
+        return base_name
+    
+    counter = 1
+    while f"{base_name}_{counter}" in existing_columns:
+        counter += 1
+    
+    return f"{base_name}_{counter}"
+
+
+def validate_column_name(name: str) -> None:
+    """
+    Validate column name format.
+    
+    Args:
+        name: Column name to validate
+        
+    Raises:
+        ValidationError: If name is invalid
+        
+    Examples:
+        >>> validate_column_name("valid_column")
+        >>> validate_column_name("")  # Raises ValidationError
+    """
+    if not isinstance(name, str):
+        raise ValidationError(f"Column name must be a string, got {type(name)}")
+    
+    if not name.strip():
+        raise ValidationError("Column name cannot be empty")
+
+
+def truncate_column_name(name: str, max_length: int = 63, 
+                        preserve_end: bool = True) -> str:
+    """
+    Truncate column name to maximum length while preserving uniqueness.
+    
+    Args:
+        name: Column name to truncate
+        max_length: Maximum length (default 63 for SQL compatibility)
+        preserve_end: If True, preserve end of name (where differences often are)
+        
+    Returns:
+        Truncated column name
+        
+    Examples:
+        >>> truncate_column_name("very_long_column_name_with_suffix_01", max_length=20)
+        'very_lon_suffix_01'
+        >>> truncate_column_name("short", max_length=20)
+        'short'
+    """
+    if len(name) <= max_length:
+        return name
+    
+    if preserve_end:
+        # Keep start and end, truncate middle
+        keep_start = max_length // 2
+        keep_end = max_length - keep_start
+        return name[:keep_start] + name[-keep_end:]
+    else:
+        # Simple truncation from start
+        return name[:max_length]
+
+
+def generate_column_names_with_prefix_suffix(
+    base_name: str,
+    values: List[str],
+    prefix: str = None,
+    suffix: str = None,
+    max_length: int = 63
+) -> List[str]:
+    """
+    Generate column names with optional prefix/suffix.
+    
+    Args:
+        base_name: Base column name
+        values: List of values to create column names for
+        prefix: Optional prefix
+        suffix: Optional suffix
+        max_length: Maximum column name length
+        
+    Returns:
+        List of generated column names
+        
+    Examples:
+        >>> generate_column_names_with_prefix_suffix(
+        ...     "color", ["red", "blue"], prefix="ohe"
+        ... )
+        ['ohe_color_red', 'ohe_color_blue']
+    """
+    column_names = []
+    
+    for value in values:
+        # Build parts
+        parts = []
+        if prefix:
+            parts.append(prefix)
+        parts.append(base_name)
+        parts.append(str(value))
+        if suffix:
+            parts.append(suffix)
+        
+        # Join with underscores
+        full_name = "_".join(parts)
+        
+        # Truncate if needed
+        if len(full_name) > max_length:
+            full_name = truncate_column_name(full_name, max_length)
+        
+        column_names.append(full_name)
+    
+    return column_names