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

additory/common/result.py

@@ -0,0 +1,380 @@
+"""
+Result wrapper classes for Additory operations.
+
+Provides DataFrameResult and AnalysisResult classes that wrap
+operation results with metadata and helper methods.
+"""
+
+from typing import Any, Dict, List, Optional
+import polars as pl
+import json
+import time
+
+
+class DataFrameResult:
+    """
+    Enhanced DataFrame wrapper with metadata and helper methods.
+    
+    Used by: to, transform, snapshot, synthetic, expressions functions
+    
+    Attributes:
+        df: Polars DataFrame (the actual result)
+        metadata: Dictionary of operation metadata
+        operation: Operation name ('to', 'transform', 'snapshot', 'synthetic')
+        input_shape: Original DataFrame shape
+        output_shape: Result DataFrame shape
+        columns_added: List of columns added
+        columns_removed: List of columns removed
+        execution_time: Time taken for operation
+    """
+    
+    def __init__(self, df: pl.DataFrame, operation: str, metadata: Dict[str, Any]):
+        """
+        Initialize result wrapper.
+        
+        Args:
+            df: Result DataFrame
+            operation: Operation name
+            metadata: Operation metadata
+        """
+        self.df = df
+        self.operation = operation
+        self.metadata = metadata
+        
+        # Extract common metadata
+        self.input_shape = metadata.get('input_shape', (0, 0))
+        self.output_shape = (df.height, df.width)
+        self.columns_added = metadata.get('columns_added', [])
+        self.columns_removed = metadata.get('columns_removed', [])
+        self.execution_time = metadata.get('execution_time', 0.0)
+    
+    def info(self) -> Dict[str, Any]:
+        """
+        Get summary information about the result.
+        
+        Returns:
+            Dictionary with shape, columns, operation info
+            
+        Example:
+            result = add.to(df, ...)
+            print(result.info())
+            # {'operation': 'to', 'rows': 1000, 'columns': 15, ...}
+        """
+        return {
+            'operation': self.operation,
+            'rows': self.output_shape[0],
+            'columns': self.output_shape[1],
+            'columns_added': self.columns_added,
+            'columns_removed': self.columns_removed,
+            'execution_time': self.execution_time,
+            'input_shape': self.input_shape,
+            'output_shape': self.output_shape,
+            'metadata': self.metadata
+        }
+    
+    def summary(self) -> str:
+        """
+        Get human-readable summary of the operation.
+        
+        Returns:
+            Formatted string summary
+            
+        Example:
+            result = add.to(df, ...)
+            print(result.summary())
+            # "Added 1 column (price) to 1000 rows in 0.05s"
+        """
+        parts = []
+        
+        # Operation name
+        parts.append(f"Operation: add.{self.operation}()")
+        
+        # Columns added
+        if self.columns_added:
+            cols_str = ', '.join(self.columns_added)
+            parts.append(f"Added {len(self.columns_added)} column(s): {cols_str}")
+        
+        # Columns removed
+        if self.columns_removed:
+            cols_str = ', '.join(self.columns_removed)
+            parts.append(f"Removed {len(self.columns_removed)} column(s): {cols_str}")
+        
+        # Shape change
+        if self.input_shape != self.output_shape:
+            parts.append(
+                f"Shape: {self.input_shape[0]}x{self.input_shape[1]} → "
+                f"{self.output_shape[0]}x{self.output_shape[1]}"
+            )
+        
+        # Execution time
+        parts.append(f"Time: {self.execution_time:.3f}s")
+        
+        return '\n'.join(parts)
+    
+    def explain(self) -> str:
+        """
+        Get detailed explanation of what happened.
+        
+        Returns:
+            Detailed explanation string
+            
+        Example:
+            result = add.to(df, ...)
+            print(result.explain())
+            # "Operation: add.to()
+            #  - Looked up 'price' from reference DataFrame
+            #  - Matched on 'product_id' (1000 matches)
+            #  - Used 'fetch if unique' mode
+            #  - Added column at position 'after:product_id'"
+        """
+        lines = [f"Operation: add.{self.operation}()"]
+        
+        # Add metadata details
+        for key, value in self.metadata.items():
+            if key not in ['input_shape', 'execution_time', 'columns_added', 'columns_removed']:
+                lines.append(f" - {key}: {value}")
+        
+        # Add summary info
+        if self.columns_added:
+            lines.append(f" - Added columns: {', '.join(self.columns_added)}")
+        if self.columns_removed:
+            lines.append(f" - Removed columns: {', '.join(self.columns_removed)}")
+        
+        lines.append(f" - Execution time: {self.execution_time:.3f}s")
+        
+        return '\n'.join(lines)
+    
+    def to_polars(self) -> pl.DataFrame:
+        """
+        Get the underlying Polars DataFrame.
+        
+        Returns:
+            Polars DataFrame
+        """
+        return self.df
+    
+    def to_pandas(self):
+        """
+        Convert result to pandas DataFrame.
+        
+        Returns:
+            pandas DataFrame
+        """
+        return self.df.to_pandas()
+    
+    def to_arrow(self):
+        """
+        Convert result to Arrow Table.
+        
+        Returns:
+            Arrow Table
+        """
+        return self.df.to_arrow()
+    
+    def __repr__(self) -> str:
+        """String representation of result."""
+        return (
+            f"DataFrameResult(operation='{self.operation}', "
+            f"shape={self.output_shape}, "
+            f"columns_added={len(self.columns_added)}, "
+            f"columns_removed={len(self.columns_removed)})"
+        )
+    
+    def __getattr__(self, name: str) -> Any:
+        """
+        Delegate attribute access to underlying DataFrame.
+        
+        Args:
+            name: Attribute name
+            
+        Returns:
+            Attribute from DataFrame
+            
+        Example:
+            result = add.to(df, ...)
+            result.select(['name', 'age'])  # Delegates to df.select()
+        """
+        # Avoid infinite recursion for special attributes
+        if name in ['df', 'operation', 'metadata', 'input_shape', 'output_shape',
+                    'columns_added', 'columns_removed', 'execution_time']:
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+        
+        # Delegate to underlying DataFrame
+        return getattr(self.df, name)
+
+
+class AnalysisResult:
+    """
+    Special result wrapper for analyze() function.
+    
+    Used by: analyze function
+    
+    Attributes:
+        quality: Quality analysis results
+        cardinality: Cardinality analysis results
+        distributions: Distribution analysis results
+        correlations: Correlation analysis results
+        features: Feature analysis results
+        types: Type analysis results
+        patterns: Pattern analysis results
+        outliers: Outlier analysis results
+        duplicates: Duplicate analysis results
+        timeseries: Time series analysis results (if applicable)
+        imputation: Imputation recommendations
+        metadata: Analysis metadata
+    """
+    
+    def __init__(self, analyses: Dict[str, Any], metadata: Dict[str, Any]):
+        """
+        Initialize analysis result.
+        
+        Args:
+            analyses: Dictionary of analysis results
+            metadata: Analysis metadata
+        """
+        self.metadata = metadata
+        
+        # Store individual analysis results
+        self.quality = analyses.get('quality')
+        self.cardinality = analyses.get('cardinality')
+        self.distributions = analyses.get('distributions')
+        self.correlations = analyses.get('correlations')
+        self.features = analyses.get('features')
+        self.types = analyses.get('types')
+        self.patterns = analyses.get('patterns')
+        self.outliers = analyses.get('outliers')
+        self.duplicates = analyses.get('duplicates')
+        self.timeseries = analyses.get('timeseries')
+        self.imputation = analyses.get('imputation')
+        
+        # Store all analyses
+        self._analyses = analyses
+    
+    def summary(self) -> str:
+        """
+        Get summary of all analyses.
+        
+        Returns:
+            Formatted summary string
+        """
+        lines = ["Analysis Summary"]
+        lines.append("=" * 50)
+        
+        # Count available analyses
+        available = [k for k, v in self._analyses.items() if v is not None]
+        lines.append(f"Analyses performed: {len(available)}")
+        lines.append("")
+        
+        # Summarize each analysis
+        for analysis_name in available:
+            result = self._analyses[analysis_name]
+            lines.append(f"{analysis_name.upper()}:")
+            
+            if isinstance(result, dict):
+                for key, value in result.items():
+                    if isinstance(value, (int, float, str, bool)):
+                        lines.append(f"  {key}: {value}")
+                    elif isinstance(value, list):
+                        lines.append(f"  {key}: {len(value)} items")
+                    elif isinstance(value, pl.DataFrame):
+                        lines.append(f"  {key}: DataFrame ({value.height}x{value.width})")
+            else:
+                lines.append(f"  {result}")
+            
+            lines.append("")
+        
+        # Add metadata
+        if self.metadata:
+            lines.append("METADATA:")
+            for key, value in self.metadata.items():
+                lines.append(f"  {key}: {value}")
+        
+        return '\n'.join(lines)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert all results to dictionary.
+        
+        Returns:
+            Dictionary of all analysis results
+        """
+        result = {}
+        
+        for key, value in self._analyses.items():
+            if value is None:
+                continue
+            
+            # Convert DataFrames to dictionaries
+            if isinstance(value, pl.DataFrame):
+                result[key] = value.to_dict()
+            elif isinstance(value, dict):
+                # Recursively convert nested DataFrames
+                result[key] = {}
+                for k, v in value.items():
+                    if isinstance(v, pl.DataFrame):
+                        result[key][k] = v.to_dict()
+                    else:
+                        result[key][k] = v
+            else:
+                result[key] = value
+        
+        # Add metadata
+        result['metadata'] = self.metadata
+        
+        return result
+    
+    def to_json(self) -> str:
+        """
+        Convert all results to JSON.
+        
+        Returns:
+            JSON string
+        """
+        return json.dumps(self.to_dict(), indent=2, default=str)
+    
+    def __repr__(self) -> str:
+        """String representation."""
+        available = [k for k, v in self._analyses.items() if v is not None]
+        return f"AnalysisResult(analyses={len(available)})"
+
+
+def wrap_result(df: pl.DataFrame, operation: str, metadata: Dict[str, Any]) -> DataFrameResult:
+    """
+    Convenience function to wrap DataFrame as result.
+    
+    Called by: to, transform, snapshot, synthetic, expressions functions
+    
+    Args:
+        df: DataFrame to wrap
+        operation: Operation name
+        metadata: Operation metadata
+        
+    Returns:
+        DataFrameResult instance
+        
+    Example:
+        result = wrap_result(df, 'to', {'columns_added': ['price']})
+    """
+    return DataFrameResult(df, operation, metadata)
+
+
+def wrap_analysis(analyses: Dict[str, Any], metadata: Dict[str, Any]) -> AnalysisResult:
+    """
+    Convenience function to wrap analysis results.
+    
+    Called by: analyze function
+    
+    Args:
+        analyses: Dictionary of analysis results
+        metadata: Analysis metadata
+        
+    Returns:
+        AnalysisResult instance
+        
+    Example:
+        result = wrap_analysis(
+            {'quality': {...}, 'cardinality': {...}},
+            {'execution_time': 0.5}
+        )
+    """
+    return AnalysisResult(analyses, metadata)

additory/common/strategy_parser.py

@@ -0,0 +1,243 @@
+"""
+Strategy parsing and validation utilities for Additory.
+
+Provides functions to parse and validate strategy dictionaries
+used across multiple functions (to, transform, synthetic).
+"""
+
+from typing import Any, Dict, List, Tuple
+import polars as pl
+
+
+def parse_strategy(strategy: Dict, context: str) -> Dict:
+    """
+    Parse and validate strategy dictionary for a given context.
+    
+    Args:
+        strategy: Dictionary containing strategy configuration
+        context: Context string ('to', 'transform', 'synthetic')
+        
+    Returns:
+        Validated and normalized strategy dictionary
+        
+    Example:
+        strategy = {'price': {'mode': 'first', 'position': 'after:id'}}
+        parsed = parse_strategy(strategy, context='to')
+    """
+    # Define allowed keys for each context
+    allowed_keys_by_context = {
+        'to': ['mode', 'position', 'default', 'deduce'],
+        'transform': ['mode', 'from_unit', 'to_unit', 'features', 'deduce'],
+        'synthetic': ['mode', 'distribution', 'min', 'max', 'mean', 'std', 
+                     'categories', 'deduce', 'correlation']
+    }
+    
+    if context not in allowed_keys_by_context:
+        raise ValueError(f"Invalid context: {context}. Must be one of: {list(allowed_keys_by_context.keys())}")
+    
+    allowed_keys = allowed_keys_by_context[context]
+    
+    # Validate and normalize each column strategy
+    parsed = {}
+    for column, column_strategy in strategy.items():
+        if isinstance(column_strategy, dict):
+            # Validate keys
+            validate_strategy_keys(column_strategy, allowed_keys)
+            
+            # Normalize values
+            normalized = {}
+            for key, value in column_strategy.items():
+                normalized[key] = normalize_strategy_value(value, key)
+            
+            parsed[column] = normalized
+        else:
+            # Simple value (e.g., 'deduce:expression')
+            parsed[column] = normalize_strategy_value(column_strategy, 'simple')
+    
+    return parsed
+
+
+def validate_strategy_keys(strategy: Dict, allowed_keys: List[str]) -> bool:
+    """
+    Validate that strategy contains only allowed keys.
+    
+    Args:
+        strategy: Strategy dictionary to validate
+        allowed_keys: List of allowed keys for this context
+        
+    Returns:
+        True if valid
+        
+    Raises:
+        ValueError: If strategy contains invalid keys
+    """
+    invalid_keys = set(strategy.keys()) - set(allowed_keys)
+    
+    if invalid_keys:
+        raise ValueError(
+            f"Invalid strategy keys: {invalid_keys}. "
+            f"Allowed keys: {allowed_keys}"
+        )
+    
+    return True
+
+
+def normalize_strategy_value(value: Any, value_type: str) -> Any:
+    """
+    Normalize strategy value to expected type.
+    
+    Args:
+        value: Value to normalize
+        value_type: Expected type ('mode', 'position', 'expression', etc.)
+        
+    Returns:
+        Normalized value
+    """
+    if value_type == 'mode':
+        # Mode should be a string
+        if not isinstance(value, str):
+            raise ValueError(f"Mode must be a string, got {type(value)}")
+        return value.lower()
+    
+    elif value_type == 'position':
+        # Position should be a string (e.g., 'after:id', 'before:name')
+        if not isinstance(value, str):
+            raise ValueError(f"Position must be a string, got {type(value)}")
+        return value.lower()
+    
+    elif value_type == 'deduce':
+        # Deduce should be a string (expression or reference)
+        if not isinstance(value, str):
+            raise ValueError(f"Deduce must be a string, got {type(value)}")
+        return value
+    
+    elif value_type == 'distribution':
+        # Distribution should be a string
+        if not isinstance(value, str):
+            raise ValueError(f"Distribution must be a string, got {type(value)}")
+        return value.lower()
+    
+    elif value_type in ['min', 'max', 'mean', 'std', 'correlation']:
+        # Numeric values
+        if not isinstance(value, (int, float)):
+            raise ValueError(f"{value_type} must be numeric, got {type(value)}")
+        return float(value)
+    
+    elif value_type == 'categories':
+        # Categories should be a list
+        if not isinstance(value, list):
+            raise ValueError(f"Categories must be a list, got {type(value)}")
+        return value
+    
+    elif value_type == 'features':
+        # Features should be a list
+        if not isinstance(value, list):
+            raise ValueError(f"Features must be a list, got {type(value)}")
+        return value
+    
+    elif value_type in ['from_unit', 'to_unit']:
+        # Units should be strings
+        if not isinstance(value, str):
+            raise ValueError(f"{value_type} must be a string, got {type(value)}")
+        return value.lower()
+    
+    elif value_type == 'default':
+        # Default can be any type
+        return value
+    
+    elif value_type == 'simple':
+        # Simple value (not in a dict)
+        return value
+    
+    else:
+        # Unknown type, return as-is
+        return value
+
+
+def parse_deduce_strategy(strategy_value: str, df: pl.DataFrame) -> pl.Series:
+    """
+    Parse 'deduce:' strategy (inline expression or reference).
+    
+    Args:
+        strategy_value: Strategy string starting with 'deduce:'
+        df: DataFrame for expression evaluation
+        
+    Returns:
+        Polars Series with computed values
+        
+    Example:
+        # Inline expression
+        result = parse_deduce_strategy('deduce:weight / (height ** 2)', df)
+        
+        # Reference expression
+        result = parse_deduce_strategy('deduce:inbuilt:bmi', df)
+    """
+    if not strategy_value.startswith('deduce:'):
+        raise ValueError(f"Strategy value must start with 'deduce:', got: {strategy_value}")
+    
+    # Remove 'deduce:' prefix
+    expression_part = strategy_value[7:]  # len('deduce:') = 7
+    
+    # Check if it's a reference (contains ':')
+    if ':' in expression_part:
+        # It's a reference like 'inbuilt:bmi' or 'myfolder:roi'
+        namespace, expr_name = extract_namespace_from_reference(expression_part)
+        
+        # For now, we'll return a placeholder since expressions.engine is not yet implemented
+        # This will be replaced when expressions.engine is available
+        raise NotImplementedError(
+            f"Expression references not yet implemented. "
+            f"Namespace: {namespace}, Expression: {expr_name}"
+        )
+    else:
+        # It's an inline expression like 'weight / (height ** 2)'
+        # For now, we'll try to evaluate it directly using Polars
+        try:
+            # Try to evaluate as a simple Polars expression
+            # This is a simplified version - full implementation will use expressions.engine
+            result = df.select(pl.lit(expression_part).alias('result'))['result']
+            return result
+        except Exception as e:
+            raise ValueError(
+                f"Failed to evaluate inline expression: {expression_part}. "
+                f"Error: {str(e)}"
+            )
+
+
+def extract_namespace_from_reference(reference: str) -> Tuple[str, str]:
+    """
+    Extract namespace and expression name from reference.
+    
+    Args:
+        reference: Reference string like 'inbuilt:bmi' or 'myfolder:roi'
+        
+    Returns:
+        Tuple of (namespace, expression_name)
+        
+    Example:
+        namespace, expr_name = extract_namespace_from_reference('inbuilt:bmi')
+        # Returns: ('inbuilt', 'bmi')
+    """
+    if ':' not in reference:
+        raise ValueError(
+            f"Invalid reference format: {reference}. "
+            f"Expected format: 'namespace:expression_name'"
+        )
+    
+    parts = reference.split(':', 1)
+    if len(parts) != 2:
+        raise ValueError(
+            f"Invalid reference format: {reference}. "
+            f"Expected format: 'namespace:expression_name'"
+        )
+    
+    namespace = parts[0].strip()
+    expr_name = parts[1].strip()
+    
+    if not namespace or not expr_name:
+        raise ValueError(
+            f"Invalid reference format: {reference}. "
+            f"Both namespace and expression name must be non-empty"
+        )
+    
+    return namespace, expr_name