additory 0.1.0a3__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

additory/functions/snapshot/__init__.py

@@ -0,0 +1,82 @@
+"""
+Snapshot function - Filter and select data.
+
+This module provides the main snapshot function for filtering and selecting data.
+"""
+
+import polars as pl
+from typing import List, Optional
+
+from additory.common.validation import validate_dataframe, validate_not_empty
+from additory.common.result import wrap_result
+from additory.core.backend import detect_backend, to_polars, from_polars
+from additory.core.logging import Logger
+from additory.functions.snapshot.filter import apply_filter, select_columns
+
+
+def snapshot(
+    df,
+    where: Optional[str] = None,
+    columns: Optional[List[str]] = None
+):
+    """
+    Filter and select data from DataFrame.
+    
+    Args:
+        df: Input DataFrame (Polars, pandas, or cuDF)
+        where: Optional filter expression (SQL-like WHERE clause)
+        columns: Optional list of columns to select
+        
+    Returns:
+        DataFrameResult with filtered/selected data
+        
+    Examples:
+        >>> # Simple filter
+        >>> result = snapshot(df, where='age > 18')
+        
+        >>> # Filter + select
+        >>> result = snapshot(df, 
+        ...     where='age > 18 AND status == "active"',
+        ...     columns=['name', 'email', 'age'])
+        
+        >>> # Complex conditions
+        >>> result = snapshot(df,
+        ...     where='(age >= 18 AND status == "active") OR country == "USA"')
+    """
+    logger = Logger()
+    logger.info("[snapshot] Starting snapshot() function")
+    
+    try:
+        # Validate and convert
+        validate_dataframe(df)
+        validate_not_empty(df)
+        backend = detect_backend(df)
+        polars_df = to_polars(df)
+        
+        logger.info(f"Input: {polars_df.shape[0]} rows × {polars_df.shape[1]} columns")
+        
+        # Apply filter
+        if where:
+            polars_df = apply_filter(polars_df, where)
+        
+        # Select columns
+        if columns:
+            polars_df = select_columns(polars_df, columns)
+        
+        # Convert back
+        result = from_polars(polars_df, backend)
+        
+        logger.info(f"Output: {polars_df.shape[0]} rows × {polars_df.shape[1]} columns")
+        logger.info("[snapshot] snapshot() function complete")
+        
+        # Wrap result
+        return wrap_result(result, 'snapshot', metadata={
+            'where': where,
+            'columns': columns,
+            'rows_filtered': len(polars_df)
+        })
+        
+    except Exception as e:
+        logger.error(f"Error in snapshot() function: {e}", error_location="snapshot")
+        raise
+

additory/functions/snapshot/filter.py

@@ -0,0 +1,119 @@
+"""
+Filter and select data.
+
+This module provides filtering functionality for the snapshot function.
+"""
+
+import polars as pl
+from typing import List, Optional
+
+from additory.common.validation import validate_dataframe
+from additory.common.column_selector import select_columns as select_cols
+from additory.core.logging import Logger
+
+
+def apply_filter(df: pl.DataFrame, where: str) -> pl.DataFrame:
+    """
+    Apply WHERE clause filter to DataFrame.
+    
+    Args:
+        df: Input DataFrame
+        where: Filter expression (SQL-like WHERE clause)
+        
+    Returns:
+        Filtered DataFrame
+        
+    Example:
+        >>> result = apply_filter(df, 'age > 18 AND status == "active"')
+    """
+    logger = Logger()
+    
+    # Validate
+    validate_dataframe(df)
+    
+    if not where:
+        return df
+    
+    logger.info(f"Applying filter: {where}")
+    
+    # Parse and evaluate WHERE clause
+    where_expr = parse_where_clause(df, where)
+    result = df.filter(where_expr)
+    
+    logger.info(f"Filter applied: {len(result)} rows remaining")
+    
+    return result
+
+
+def parse_where_clause(df: pl.DataFrame, where: str) -> pl.Expr:
+    """
+    Parse WHERE clause into Polars expression.
+    
+    Args:
+        df: Input DataFrame (for column validation)
+        where: Filter expression
+        
+    Returns:
+        Polars expression
+        
+    Supports:
+        - Comparison: >, <, >=, <=, ==, !=
+        - Logical: AND, OR, NOT
+        - Parentheses for grouping
+        
+    Example:
+        >>> expr = parse_where_clause(df, 'age > 18 AND status == "active"')
+    """
+    # Simple implementation - convert to Polars expression
+    # This is a simplified parser - full implementation would use expressions.parser
+    
+    # Replace SQL-style logical operators with Python/Polars operators
+    expr_str = where
+    expr_str = expr_str.replace(' AND ', ' & ')
+    expr_str = expr_str.replace(' OR ', ' | ')
+    expr_str = expr_str.replace(' NOT ', ' ~ ')
+    
+    # For now, use Polars' SQL context for parsing
+    # Create a temporary SQL query and extract the filter
+    try:
+        # Build namespace with column references
+        namespace = {col: pl.col(col) for col in df.columns}
+        namespace['pl'] = pl
+        
+        # Evaluate the expression
+        result = eval(expr_str, namespace)
+        return result
+    except Exception as e:
+        raise ValueError(f"Invalid WHERE clause: {where}. Error: {e}")
+
+
+def select_columns(df: pl.DataFrame, columns: List[str]) -> pl.DataFrame:
+    """
+    Select specified columns from DataFrame.
+    
+    Args:
+        df: Input DataFrame
+        columns: List of column names to select
+        
+    Returns:
+        DataFrame with selected columns
+        
+    Example:
+        >>> result = select_columns(df, ['name', 'age', 'email'])
+    """
+    logger = Logger()
+    
+    # Validate
+    validate_dataframe(df)
+    
+    if not columns:
+        return df
+    
+    logger.info(f"Selecting {len(columns)} columns")
+    
+    # Use Polars select directly
+    result = df.select(columns)
+    
+    logger.info(f"Column selection complete")
+    
+    return result

additory/functions/synthetic/__init__.py

@@ -0,0 +1,113 @@
+"""
+Synthetic function - Generate synthetic data.
+
+This module provides the main synthetic function for generating synthetic data
+in three modes: augment, create, and preset.
+"""
+
+import polars as pl
+from typing import Dict, Optional, Union
+
+from additory.common.validation import validate_dataframe, validate_not_empty
+from additory.common.result import wrap_result
+from additory.core.backend import detect_backend, to_polars, from_polars
+from additory.core.logging import Logger
+from additory.functions.synthetic.mode_detector import detect_mode
+from additory.functions.synthetic.strategies.generative import generate_data
+from additory.functions.synthetic.strategies.augmentative import augment_data
+from additory.functions.synthetic.strategies.presets import apply_preset
+
+
+def synthetic(
+    df_or_mode,
+    n_rows: Optional[Union[int, str]] = None,
+    strategy: Optional[Dict] = None,
+    preset: Optional[str] = None,
+    **kwargs
+):
+    """
+    Generate synthetic data.
+    
+    Args:
+        df_or_mode: DataFrame (augment mode) or '@new' (create mode)
+        n_rows: Number of rows to generate
+        strategy: Strategy dictionary
+        preset: Preset name
+        **kwargs: Mode-specific parameters
+        
+    Returns:
+        DataFrameResult with synthetic data
+        
+    Modes:
+        - augment: Add synthetic rows to existing data
+        - create: Create synthetic data from scratch
+        - preset: Use preset configuration
+        
+    Examples:
+        >>> # Augment mode
+        >>> result = synthetic(df, n_rows=100)
+        >>> result = synthetic(df, n_rows="50%")
+        
+        >>> # Create mode
+        >>> result = synthetic('@new', n_rows=100, strategy={
+        ...     'id': 'increment:start=1',
+        ...     'age': 'range:18-65',
+        ...     'status': 'choice:[Active,Inactive,Pending]'
+        ... })
+        
+        >>> # Preset mode
+        >>> result = synthetic('@new', n_rows=100, preset='users')
+    """
+    logger = Logger()
+    logger.info("[synthetic] Starting synthetic() function")
+    
+    try:
+        # Detect mode
+        mode = detect_mode(df_or_mode, strategy, preset)
+        logger.info(f"Mode detected: {mode}")
+        
+        if mode == 'augment':
+            # Validate and convert
+            validate_dataframe(df_or_mode)
+            validate_not_empty(df_or_mode)
+            backend = detect_backend(df_or_mode)
+            polars_df = to_polars(df_or_mode)
+            
+            # Augment
+            result = augment_data(polars_df, n_rows, strategy)
+            
+        elif mode == 'create':
+            # Create from scratch
+            if not n_rows:
+                raise ValueError("n_rows is required for create mode")
+            
+            result = generate_data(n_rows, strategy)
+            backend = 'polars'
+            
+        elif mode == 'preset':
+            # Use preset
+            if not n_rows:
+                raise ValueError("n_rows is required for preset mode")
+            
+            result = apply_preset(preset, n_rows)
+            backend = 'polars'
+        
+        else:
+            raise ValueError(f"Unknown mode: {mode}")
+        
+        # Convert back
+        result = from_polars(result, backend)
+        
+        logger.info(f"Output: {len(result)} rows × {len(result.columns) if hasattr(result, 'columns') else 'N/A'} columns")
+        logger.info("[synthetic] synthetic() function complete")
+        
+        # Wrap result
+        return wrap_result(result, 'synthetic', metadata={
+            'mode': mode,
+            'rows_generated': n_rows
+        })
+        
+    except Exception as e:
+        logger.error(f"Error in synthetic() function: {e}", error_location="synthetic")
+        raise
+

additory/functions/synthetic/mode_detector.py

@@ -0,0 +1,47 @@
+"""
+Mode detection for synthetic data generation.
+
+This module detects which mode to use: augment, create, or preset.
+"""
+
+from typing import Optional, Dict
+from additory.common.validation import is_dataframe
+
+
+def detect_mode(df_or_mode, strategy: Optional[Dict], preset: Optional[str]) -> str:
+    """
+    Detect synthetic data generation mode.
+    
+    Args:
+        df_or_mode: DataFrame (augment mode) or '@new' (create mode)
+        strategy: Strategy dictionary
+        preset: Preset name
+        
+    Returns:
+        Mode string ('augment', 'create', 'preset')
+        
+    Raises:
+        ValueError: If parameters are invalid
+        
+    Example:
+        >>> mode = detect_mode(df, None, None)  # Returns: 'augment'
+        >>> mode = detect_mode('@new', strategy, None)  # Returns: 'create'
+        >>> mode = detect_mode('@new', None, 'users')  # Returns: 'preset'
+    """
+    # Preset mode takes precedence
+    if preset is not None:
+        return 'preset'
+    
+    # Check if it's a DataFrame first (augment mode)
+    elif is_dataframe(df_or_mode):
+        return 'augment'
+    
+    # Create mode
+    elif df_or_mode == '@new':
+        return 'create'
+    
+    else:
+        raise ValueError(
+            "Invalid parameters for synthetic(). "
+            "First parameter must be a DataFrame or '@new'"
+        )

additory/functions/synthetic/strategies/__init__.py

@@ -0,0 +1 @@
+# Synthetic strategies module

additory/functions/synthetic/strategies/advanced.py

@@ -0,0 +1,35 @@
+"""
+Advanced synthetic data generation strategies.
+
+This module provides advanced strategies like SMOTE, correlations, etc.
+(Placeholder for future implementation)
+"""
+
+import polars as pl
+from typing import Dict
+
+from additory.core.logging import Logger
+
+
+def apply_advanced_strategy(df: pl.DataFrame, strategy: Dict) -> pl.DataFrame:
+    """
+    Apply advanced synthetic data strategy.
+    
+    Args:
+        df: Input DataFrame
+        strategy: Advanced strategy configuration
+        
+    Returns:
+        DataFrame with synthetic data
+        
+    Note:
+        This is a placeholder for future advanced strategies like:
+        - SMOTE (Synthetic Minority Over-sampling Technique)
+        - Conditional generation
+        - Time series forecasting
+        - Correlation preservation
+    """
+    logger = Logger()
+    logger.warning("Advanced strategies not yet implemented")
+    
+    return df

additory/functions/synthetic/strategies/augmentative.py

@@ -0,0 +1,160 @@
+"""
+Augment existing data with synthetic rows.
+
+This module provides functionality to add synthetic rows to existing data.
+"""
+
+import polars as pl
+from typing import Dict, Optional, Union
+import numpy as np
+
+from additory.common.validation import validate_dataframe, validate_not_empty
+from additory.common.distributions import generate_normal, generate_uniform
+from additory.core.logging import Logger
+
+
+def augment_data(
+    df: pl.DataFrame,
+    n_rows: Union[int, str],
+    strategy: Optional[Dict] = None
+) -> pl.DataFrame:
+    """
+    Add synthetic rows to existing data.
+    
+    Args:
+        df: Input DataFrame
+        n_rows: Number of rows (int or percentage string like '50%')
+        strategy: Optional augmentation strategy
+        
+    Returns:
+        DataFrame with original + synthetic rows
+        
+    Example:
+        >>> result = augment_data(df, n_rows=100)  # Add 100 rows
+        >>> result = augment_data(df, n_rows="50%")  # Add 50% more rows
+    """
+    logger = Logger()
+    
+    # Validate
+    validate_dataframe(df)
+    validate_not_empty(df)
+    
+    # Parse n_rows
+    n_synthetic = parse_n_rows(n_rows, len(df))
+    
+    logger.info(f"Augmenting {len(df)} rows with {n_synthetic} synthetic rows")
+    
+    # Generate synthetic rows
+    synthetic_df = generate_synthetic_rows(df, n_synthetic, strategy)
+    
+    # Concatenate
+    result = pl.concat([df, synthetic_df])
+    
+    logger.info(f"Augmentation complete: {len(result)} total rows")
+    
+    return result
+
+
+def parse_n_rows(n_rows: Union[int, str], df_len: int) -> int:
+    """
+    Parse n_rows parameter.
+    
+    Args:
+        n_rows: Number of rows (int or percentage string)
+        df_len: Length of DataFrame
+        
+    Returns:
+        Number of rows to generate
+        
+    Example:
+        >>> parse_n_rows(100, 1000)
+        100
+        >>> parse_n_rows("50%", 1000)
+        500
+    """
+    if isinstance(n_rows, int):
+        return n_rows
+    
+    elif isinstance(n_rows, str) and n_rows.endswith('%'):
+        percentage = float(n_rows.rstrip('%'))
+        return int(df_len * percentage / 100)
+    
+    else:
+        raise ValueError(f"Invalid n_rows: {n_rows}. Must be int or percentage string")
+
+
+def generate_synthetic_rows(
+    df: pl.DataFrame,
+    n_rows: int,
+    strategy: Optional[Dict]
+) -> pl.DataFrame:
+    """
+    Generate synthetic rows matching existing data.
+    
+    Args:
+        df: Input DataFrame
+        n_rows: Number of rows to generate
+        strategy: Optional strategy
+        
+    Returns:
+        DataFrame with synthetic rows
+    """
+    logger = Logger()
+    
+    # Generate each column
+    columns = {}
+    
+    for col in df.columns:
+        logger.info(f"Generating synthetic column: {col}")
+        
+        # Get column dtype
+        dtype = df[col].dtype
+        
+        # Generate based on dtype
+        if dtype in [pl.Int8, pl.Int16, pl.Int32, pl.Int64,
+                     pl.UInt8, pl.UInt16, pl.UInt32, pl.UInt64]:
+            # Integer column - match distribution
+            col_data = df[col].drop_nulls()
+            if len(col_data) > 0:
+                mean = float(col_data.mean())
+                std = float(col_data.std())
+                synthetic = generate_normal(n_rows, mean, std).cast(dtype)
+                columns[col] = synthetic
+            else:
+                columns[col] = pl.Series([None] * n_rows, dtype=dtype)
+        
+        elif dtype in [pl.Float32, pl.Float64]:
+            # Float column - match distribution
+            col_data = df[col].drop_nulls()
+            if len(col_data) > 0:
+                mean = float(col_data.mean())
+                std = float(col_data.std())
+                columns[col] = generate_normal(n_rows, mean, std)
+            else:
+                columns[col] = pl.Series([None] * n_rows, dtype=dtype)
+        
+        elif dtype == pl.Utf8:
+            # String column - sample from existing values
+            col_data = df[col].drop_nulls()
+            if len(col_data) > 0:
+                values = col_data.to_list()
+                synthetic = np.random.choice(values, n_rows)
+                columns[col] = pl.Series(synthetic)
+            else:
+                columns[col] = pl.Series([None] * n_rows, dtype=dtype)
+        
+        elif dtype == pl.Boolean:
+            # Boolean column - match distribution
+            col_data = df[col].drop_nulls()
+            if len(col_data) > 0:
+                true_ratio = float(col_data.sum()) / len(col_data)
+                synthetic = np.random.random(n_rows) < true_ratio
+                columns[col] = pl.Series(synthetic)
+            else:
+                columns[col] = pl.Series([None] * n_rows, dtype=dtype)
+        
+        else:
+            # Other types - just use nulls
+            columns[col] = pl.Series([None] * n_rows, dtype=dtype)
+    
+    return pl.DataFrame(columns)