Metadata-Version: 2.4
Name: additory
Version: 0.1.3a8
Summary: Elegant data operations for DataFrames
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: polars>=0.19.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pandas>=1.3.0; extra == "dev"

# Additory v0.1.3a5

**Elegant data operations for DataFrames**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()

---

## Overview

Additory is a data transformation library that provides a unified API for common data operations with support for both Polars and Pandas DataFrames.

**Note:** This is an alpha release (v0.1.3a5) with Python-only implementation. Rust-accelerated operations will be available in v0.1.4.

### Key Features

- 🔄 **Flexible** - Works seamlessly with both Polars and Pandas
- 🎯 **Type-safe** - Strong typing with clear, actionable error messages
- 🧪 **Tested** - Comprehensive test coverage (198 tests passing)
- 📚 **Documented** - Complete API documentation and usage examples
- 🐍 **Python-only** - Pure Python implementation (Rust acceleration coming in v0.1.4)

---

## Installation

```bash
pip install additory==0.1.3a5
```

### Requirements

- Python 3.8+
- Polars >= 0.19.0
- NumPy >= 1.20.0

### Optional Dependencies

```bash
# For development
pip install additory[dev]

# For deduce strategy (TF-IDF)
pip install scikit-learn>=1.0.0
```

---

## Quick Start

```python
import additory as add
import polars as pl

# Create sample data with missing values
df = pl.DataFrame({
    'age': [25, None, 35, None, 45],
    'salary': [50000, 60000, None, 70000, 80000]
})

# KNN imputation (Python-only mode)
result = add.transform('@knn', df,
    fetch=['age', 'salary'],
    strategy={'k': 3})

print(result)
# ┌─────┬────────┐
# │ age ┆ salary │
# ├─────┼────────┤
# │ 25  ┆ 50000  │
# │ 30  ┆ 60000  │  ← imputed
# │ 35  ┆ 65000  │  ← imputed
# │ 40  ┆ 70000  │
# │ 45  ┆ 80000  │
# └─────┴────────┘
```

**Note:** This alpha release includes Python-only features. Rust-accelerated operations (add.to(), most add.transform() modes) will be available in v0.1.4.

---

## Features (v0.1.3a5 - Python-only)

### 1. KNN Imputation

Impute missing values using K-Nearest Neighbors:

```python
df = pl.DataFrame({
    'age': [25, None, 35, 40],
    'salary': [50000, 60000, None, 80000]
})

result = add.transform('@knn', df,
    fetch=['age', 'salary'],
    strategy={'k': 3, 'weights': 'distance'})
```

### 2. Configuration

Configure global settings:

```python
# Set user expressions folder
add.set(expressions='/path/to/expressions')

# Enable logging
add.set(logging=True)

# Play games (easter egg)
add.set(play='tictactoe')
```

### 3. Backend Compatibility

Works seamlessly with both Polars and Pandas:

```python
# Polars
df_pl = pl.DataFrame({'a': [1, 2], 'b': [3, 4]})
result_pl = add.transform('@knn', df_pl, fetch=['a'])
# Returns: Polars DataFrame

# Pandas
df_pd = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
result_pd = add.transform('@knn', df_pd, fetch=['a'])
# Returns: Pandas DataFrame
```

---

## What's Available in v0.1.3a5

### ✅ Working Features (Python-only)

- **KNN Imputation** - @knn mode for missing value imputation
- **Configuration** - add.set() for global settings
- **Validation** - Parameter validation and normalization
- **Strategy Parsing** - mode:match syntax support
- **Expression Loading** - Load custom expressions from .add files
- **Games** - Easter egg games (tictactoe, sudoku)

### ⏳ Coming in v0.1.4 (Rust-accelerated)

- **add.to()** - Lookup operations with aggregation
- **add.transform()** - Transform modes (@calc, @filter, @sort, @aggregate, etc.)
- **add.synthetic()** - Synthetic data generation
- **5-10x Performance** - Rust-powered operations

### Current Limitations

This alpha release is Python-only. Operations that require Rust bindings will raise `ImportError`:

```python
# This will raise ImportError in v0.1.3a5
result = add.to(df, ref_df, 'age', 'id')
# ImportError: add.to() requires Rust bindings

# This will raise NotImplementedError in v0.1.3a5
result = add.transform('@calc', df, expression='a + b', as_='sum')
# NotImplementedError: Mode @calc requires Rust bindings
```

**Workaround:** Use Python-only features (@knn) or wait for v0.1.4.

---

## Documentation

### Complete Documentation

- **[API Documentation](API_DOCUMENTATION.md)** - Complete API reference
- **[Usage Examples](USAGE_EXAMPLES.md)** - Real-world usage examples
- **[CHANGELOG](CHANGELOG.md)** - Version history and changes

### Additional Resources

- **[Performance Benchmarks](../PERFORMANCE_BENCHMARKS.md)** - Detailed performance analysis
- **[Error Handling](../ERROR_HANDLING_COMPLETE.md)** - Error handling guide
- **[Integration Tests](../INTEGRATION_TESTS_COMPLETE.md)** - Test coverage details

---

## Examples

### KNN Imputation

```python
import additory as add
import polars as pl

df = pl.DataFrame({
    'age': [25, None, 35, None, 45],
    'salary': [50000, 60000, None, 70000, 80000]
})

# Basic KNN
result = add.transform('@knn', df, fetch=['age', 'salary'], strategy={'k': 3})

# With distance weighting
result = add.transform('@knn', df,
    fetch=['age', 'salary'],
    strategy={'k': 3, 'weights': 'distance'})
```

### Configuration

```python
# Set expressions folder
add.set(expressions='/path/to/my_expressions')

# Enable logging
add.set(logging=True)

# Play games (easter egg)
add.set(play='tictactoe')
add.set(play='sudoku')
```

---

## API Reference

### add.transform()

Transform data within a DataFrame.

**Signature:**
```python
def transform(mode: str, df: DataFrame, **kwargs) -> DataFrame
```

**Parameters:**
- `mode` (str): Transform mode ('@calc', '@knn')
- `df` (DataFrame): Input DataFrame (Polars or Pandas)
- `**kwargs`: Mode-specific parameters

**Returns:**
- DataFrame: Transformed DataFrame (same type as input)

### add.set()

Configure global settings.

**Signature:**
```python
def set(**kwargs) -> None
```

**Parameters:**
- `expressions` (str): Path to user expressions folder
- `logging` (bool): Enable/disable logging
- `backend` (str): Preferred backend ('polars' or 'pandas')

---

## Transform Modes

### @knn - KNN Imputation (Available in v0.1.3a5)

Impute missing values using K-Nearest Neighbors.

**Parameters:**
- `fetch` (list[str]): Columns to impute
- `strategy` (dict): KNN parameters (k, weights, metric)

**Example:**
```python
result = add.transform('@knn', df,
    fetch=['age', 'salary'],
    strategy={'k': 3})
```

### Coming in v0.1.4

The following modes will be available in v0.1.4 with Rust acceleration:

- **@calc** - Calculate new columns from expressions
- **@filter** - Filter rows and select columns
- **@sort** - Sort DataFrame
- **@aggregate** - Group by and aggregate
- **@bankers_round** - Banker's rounding
- **@transpose** - Transpose DataFrame
- **@onehotencode** - One-hot encoding
- **@extract** - Feature extraction (datetime)
- **@datetime** - DateTime normalization
- **@harmonize** - Unit harmonization

---

## Error Handling

Additory provides clear, actionable error messages:

```python
try:
    result = add.transform('@calc', df,
        expression='nonexistent + 5',
        as_='result')
except RuntimeError as e:
    print(e)
    # Column 'nonexistent' not found in DataFrame
    # Available columns: a, b, c
```

All errors include:
- Clear description of what went wrong
- Contextual information (available options, etc.)
- Actionable suggestions for fixing the problem

---

## Known Limitations (v0.1.3a5)

### Python-Only Release

This alpha release is Python-only. Rust-accelerated operations are not included:

- ❌ add.to() operations (will raise ImportError)
- ❌ Most add.transform() modes (will raise NotImplementedError)
- ❌ add.synthetic() operations (will raise ImportError)

**Available:**
- ✅ @knn mode (Python implementation)
- ✅ Configuration (add.set())
- ✅ Validation and parameter parsing

### Future Improvements

v0.1.4 will include:
- ✅ Full Rust integration
- ✅ All add.to() operations
- ✅ All add.transform() modes
- ✅ 5-10x performance improvement

---

## Development

### Running Tests

```bash
# Integration tests
cd python-specific
pytest tests/test_integration.py -v

# Rust tests
cd rust-core
cargo test --all

# Benchmarks
cd python-specific
python benchmarks/benchmark_integration.py
```

### Building from Source

```bash
# Build Rust module
cd rust-core
cargo build --release

# Install Python package
cd python-specific
pip install -e .
```

---

## Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

## License

See LICENSE file for details.

---

## Support

For issues or questions:
- Check [API Documentation](API_DOCUMENTATION.md)
- Review [Usage Examples](USAGE_EXAMPLES.md)
- Contact development team

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

---

## Acknowledgments

Built with:
- [Rust](https://www.rust-lang.org/) - Systems programming language
- [PyO3](https://pyo3.rs/) - Rust bindings for Python
- [Polars](https://www.pola.rs/) - Fast DataFrame library
- [Pandas](https://pandas.pydata.org/) - Data analysis library

---

**Status:** Alpha Release  
**Version:** 0.1.3a5  
**Date:** February 13, 2026
