additory 0.1.0a1__py3-none-any.whl

additory/core/validator.py

@@ -0,0 +1,27 @@
+"""
+Expression Validator
+
+Validates expression syntax and structure.
+"""
+
+from typing import Dict, Any, List, Tuple
+
+
+def validate_expression(expression: str) -> Tuple[bool, List[str]]:
+    """
+    Validate an expression.
+    
+    Args:
+        expression: Expression string to validate
+        
+    Returns:
+        Tuple of (is_valid, error_messages)
+    """
+    errors = []
+    
+    if not expression or not expression.strip():
+        errors.append("Expression cannot be empty")
+        return (False, errors)
+    
+    # Basic validation - can be expanded later
+    return (True, [])

additory/dynamic_api.py

@@ -0,0 +1,308 @@
+"""
+Dynamic API for Additory
+
+This module provides the main API interface with dynamic attribute access.
+"""
+
+from types import SimpleNamespace
+from typing import Union, Optional, List, Any
+import pandas as pd
+import polars as pl
+
+
+class AdditoryAPI(SimpleNamespace):
+    """
+    Main API class for Additory functionality.
+    
+    Provides access to:
+    - add.augment() - Data augmentation
+    - add.to() - Lookup/join operations
+    - add.synth() - Synthetic data generation
+    - add.scan() - Data profiling and analysis
+    - add.my - User expressions
+    - add.play() - Hidden games (for the curious 😉)
+    - Expression evaluation
+    """
+    
+    def __init__(self):
+        super().__init__()
+        # Initialize expression proxies
+        from additory.expressions.proxy import ExpressionProxy
+        self.my = ExpressionProxy(namespace="user")
+        self._builtin_proxy = ExpressionProxy(namespace="builtin")
+        
+        # Explicitly set the augment method to prevent namespace conflicts
+        self.augment = self._augment_method
+    
+    def __getattr__(self, name):
+        """
+        Dynamic attribute access for expressions.
+        
+        Checks built-in expressions first, then user expressions.
+        This ensures built-in expressions take precedence.
+        """
+        # Check if it's a built-in expression first
+        if self._expression_exists(self._builtin_proxy, name):
+            return getattr(self._builtin_proxy, name)
+        
+        # Check if it's a user expression
+        if self._expression_exists(self.my, name):
+            return getattr(self.my, name)
+        
+        # If not found, raise AttributeError
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+    
+    def _expression_exists(self, proxy, name):
+        """Check if an expression exists in a proxy's namespace"""
+        try:
+            # List expressions in the proxy's namespace
+            expr_list = proxy.list_expressions()
+            return name in expr_list.get("expressions", {})
+        except Exception:
+            return False
+    
+    def _augment_method(self, df, n_rows=5, strategy="auto", seed=None, output_format="pandas", **kwargs):
+        """
+        Augment a dataframe with additional rows or create data from scratch.
+        
+        Three modes:
+        1. Augment mode: Pass a DataFrame to add rows
+        2. Create mode: Pass "@new" to create data from scratch
+        3. Sample mode: Pass "@sample" to load sample data
+        
+        Args:
+            df: DataFrame to augment, "@new" to create, or "@sample" for sample data
+            n_rows: Number of rows (int for create/sample, int/float/str for augment)
+            strategy: Strategy specification (dict for create, str/dict for augment)
+            seed: Random seed for reproducibility
+            output_format: Output format ("pandas", "polars", "cudf")
+            **kwargs: Additional parameters
+            
+        Returns:
+            Augmented or generated DataFrame
+            
+        Examples:
+            # Augment existing data
+            result = add.augment(df, n_rows=100, strategy='auto')
+            
+            # Create from scratch
+            result = add.augment("@new", n_rows=100, strategy={'id': 'increment', 'age': 'range:18-65'})
+            
+            # Load sample data
+            result = add.augment("@sample", n_rows=50)
+        """
+        # Store reference to restore after import (in the correct namespace)
+        import additory
+        original_augment = getattr(additory, 'augment', None)
+        
+        try:
+            # Import and call the implementation
+            from additory.augment.augmentor import augment as augment_impl
+            result = augment_impl(df, n_rows=n_rows, strategy=strategy, seed=seed, 
+                                 output_format=output_format, **kwargs)
+            
+            # Restore the method reference in the additory module namespace
+            # The import above will have overridden additory.augment with the module
+            # We need to restore it to point to this method
+            if original_augment is not None:
+                additory.augment = original_augment
+            else:
+                # If there was no original augment, set it to this method
+                additory.augment = self._augment_method
+            
+            return result
+        except Exception as e:
+            # Restore the method reference even if there's an error
+            if original_augment is not None:
+                additory.augment = original_augment
+            else:
+                additory.augment = self._augment_method
+            raise
+    
+    def to(self, target_df, from_df=None, bring=None, against=None, **kwargs):
+        """
+        Add columns from reference dataframe to target dataframe.
+        
+        Args:
+            target_df: Target dataframe to add columns to
+            from_df: Reference dataframe to get columns from
+            bring: Column(s) to bring from reference dataframe (str or list)
+            against: Column(s) to match on (str or list)
+            **kwargs: Additional parameters
+            
+        Returns:
+            Target dataframe with new columns added
+            
+        Example:
+            result = add.to(orders_df, from_df=products_df, bring='price', against='product_id')
+            result = add.to(orders_df, from_df=products_df, bring=['price', 'name'], against='product_id')
+        """
+        from additory.utilities.lookup import to
+        return to(target_df, from_df, bring=bring, against=against, **kwargs)
+    
+    def synth(self, schema_path: str, rows: int = 1000, engine: Optional[str] = None):
+        """
+        Generate synthetic data from a schema file.
+        
+        Args:
+            schema_path: Path to the .toml schema file
+            rows: Number of rows to generate (default: 1000)
+            engine: Output engine ("pandas" or "polars"). If None, uses default from config
+            
+        Returns:
+            Generated DataFrame in the specified format
+            
+        Example:
+            df = add.synth("customer.toml", rows=5000)
+            df = add.synth("customer.toml", rows=5000, engine="polars")
+        """
+        from additory.synthetic.api import synth as synth_impl
+        return synth_impl(schema_path, rows, engine)
+    
+    def onehotencoding(self, df, columns=None, **kwargs):
+        """
+        One-hot encode categorical columns.
+        
+        Args:
+            df: Input dataframe
+            columns: Column to encode (single column name as string)
+            **kwargs: Additional parameters
+            
+        Returns:
+            DataFrame with one-hot encoded columns
+        """
+        from additory.utilities.encoding import onehotencoding
+        return onehotencoding(df, column=columns, **kwargs)
+    
+    def harmonize_units(self, df, value_column, unit_column, target_unit=None, position="end", **kwargs):
+        """
+        Harmonize units in a dataframe.
+        
+        Args:
+            df: Input dataframe
+            value_column: Column containing numeric values
+            unit_column: Column containing unit strings
+            target_unit: Target unit to convert to (auto-detected if None)
+            position: Where to place new columns ("end", "start", etc.)
+            **kwargs: Additional parameters
+            
+        Returns:
+            DataFrame with harmonized units
+            
+        Example:
+            result = add.harmonize_units(df, value_column='weight', unit_column='unit')
+            result = add.harmonize_units(df, value_column='temp', unit_column='unit', target_unit='F')
+        """
+        from additory.utilities.units import harmonize_units
+        return harmonize_units(df, value_column, unit_column, target_unit, position, **kwargs)
+    
+    def scan(
+        self,
+        df: Union[pl.DataFrame, pd.DataFrame, Any],
+        preset: Optional[str] = None,
+        detect_distributions: bool = True,
+        detect_correlations: bool = True,
+        detect_cardinality: bool = True,
+        top_n_distributions: int = 3,
+        correlation_methods: List[str] = None,
+        correlation_threshold: float = 0.3,
+        cardinality_top_n: int = 10,
+        verbose: bool = True
+    ):
+        """
+        Scan a DataFrame to detect distributions, correlations, and cardinality.
+        
+        Accepts pandas, polars, or cuDF DataFrames. Automatically converts to Polars
+        for processing. Returns ScanResult with analysis results.
+        
+        This function provides comprehensive data profiling including:
+        - Distribution detection for numeric columns
+        - Correlation analysis between columns
+        - Cardinality analysis (unique values)
+        - Data quality metrics
+        
+        Args:
+            df: DataFrame to analyze (pandas, polars, or cuDF)
+            preset: Optional preset ('quick', 'distributions', 'correlations', 'full', 'minimal')
+            detect_distributions: Whether to detect distributions (default: True)
+            detect_correlations: Whether to calculate correlations (default: True)
+            detect_cardinality: Whether to analyze cardinality (default: True)
+            top_n_distributions: Number of top distributions to return per column (default: 3)
+            correlation_methods: Correlation methods to use (default: ['pearson', 'spearman'])
+            correlation_threshold: Minimum correlation to report (default: 0.3)
+            cardinality_top_n: Number of top values to return per column (default: 10)
+            verbose: Whether to print progress messages (default: True)
+            
+        Returns:
+            ScanResult object containing all analysis results
+            
+        Presets:
+            - 'quick': Quality + cardinality only (fast)
+            - 'distributions': Distribution detection only
+            - 'correlations': Correlation analysis only
+            - 'full': All analyses enabled
+            - 'minimal': Quality metrics only (fastest)
+            
+        Example:
+            >>> import pandas as pd
+            >>> import additory as add
+            >>> 
+            >>> # Works with pandas
+            >>> df = pd.DataFrame({
+            ...     'age': [25, 30, 35, 40, 45],
+            ...     'income': [50000, 60000, 70000, 80000, 90000],
+            ...     'category': ['A', 'B', 'A', 'B', 'A']
+            ... })
+            >>> 
+            >>> result = add.scan(df)
+            >>> print(result.summary())
+            >>> 
+            >>> # Use presets
+            >>> result = add.scan(df, preset='quick')
+            >>> result = add.scan(df, preset='distributions', top_n_distributions=5)
+        """
+        from additory.analysis.scan import scan as scan_impl
+        
+        if correlation_methods is None:
+            correlation_methods = ['pearson', 'spearman']
+        
+        return scan_impl(
+            df,
+            preset=preset,
+            detect_distributions_flag=detect_distributions,
+            detect_correlations_flag=detect_correlations,
+            detect_cardinality_flag=detect_cardinality,
+            top_n_distributions=top_n_distributions,
+            correlation_methods=correlation_methods,
+            correlation_threshold=correlation_threshold,
+            cardinality_top_n=cardinality_top_n,
+            verbose=verbose
+        )
+    
+    def play(self, game: str = "tictactoe"):
+        """
+        Play a game! 🎮
+        
+        Hidden feature for the curious. Reinforces row-column thinking.
+        
+        Available games:
+        - 'tictactoe' or 'ttt': Play Tic-Tac-Toe
+        - 'sudoku': Play Sudoku
+        
+        Args:
+            game: Name of the game to play (default: 'tictactoe')
+            
+        Example:
+            >>> import additory
+            >>> additory.add.play('tictactoe')
+            >>> additory.add.play('sudoku')
+        """
+        from additory.utilities.games import play as play_impl
+        return play_impl(game)
+
+
+# Create the singleton API instance
+add = AdditoryAPI()
+
+# Export the instance
+__all__ = ['add']

additory/expressions/__init__.py

@@ -0,0 +1,26 @@
+# additory/expressions/__init__.py
+# Expression system - .add file driven functionality
+
+"""
+Expression System Module
+
+This module handles .add file driven functionality including:
+- Expression parsing and compilation
+- Polars-based expression execution
+- Expression caching and versioning
+- Sample data management
+- Namespace support (builtin vs user)
+"""
+
+# Core expression functionality will be imported here after migration
+# from .proxy import EnhancedExpressionProxy
+# from .engine import PolarsExpressionEngine
+# from .parser import ExpressionParser
+# from .compiler import ExpressionCompiler
+# from .executor import ExpressionExecutor
+# from .registry import ExpressionRegistry
+# from .samples import SampleDataManager
+
+__all__ = [
+    # Will be populated after migration
+]