Metadata-Version: 2.4
Name: algo_learn
Version: 0.1.0
Summary: An educational Python package for learning algorithms through step-by-step tracking and visualization
Author-email: Student Developer <student@example.edu>
License: MIT
Keywords: algorithms,education,machine-learning,visualization,learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"

# algo_learn - Educational Algorithm Learning Package

## 📚 Overview

`algo_learn` is an educational Python package designed to help students understand classic algorithms and machine learning techniques through **step-by-step tracking**, **visualization**, and a **lightweight conversational interface**.

This package was developed as part of an undergraduate computer science education project. The code prioritizes **pedagogical clarity** over production optimizations, making it ideal for:

- Learning algorithm internals
- Creating visualizations and animations
- Understanding ML training dynamics
- Academic submissions and coursework

## ✨ Features

### Core Algorithms (From Scratch)
- **Sorting**: Bubble Sort, Merge Sort, Quick Sort
- **Searching**: Linear Search, Binary Search
- **Graph Algorithms**: BFS, Dijkstra's Shortest Path
- **Dynamic Programming**: Fibonacci, 0/1 Knapsack
- **String Algorithms**: KMP Pattern Matching

### Machine Learning (No scikit-learn!)
- **Supervised**: Linear Regression, Logistic Regression, K-Nearest Neighbors
- **Unsupervised**: K-Means Clustering, PCA (via SVD)

### Educational Tools
- **Step Tracking**: Every algorithm supports `track=True` mode returning intermediate states
- **Visualization**: Decoupled plotting module for animations and heatmaps
- **Benchmark Utilities**: Timing and operation counting with log-log plots
- **Chat UI**: Natural language interface for algorithm interaction

## 🚀 Installation

```bash
# Install from PyPI (when published)
pip install algo_learn

# Or install from source
git clone https://github.com/yourusername/algo_learn.git
cd algo_learn
pip install -e .
```

### Development Dependencies
```bash
pip install -e ".[dev]"
```

## 📖 Quick Start

### Basic Usage

```python
from algo_learn.sorting import merge_sort
from algo_learn.ml_supervised import LinearRegression
import numpy as np

# Sorting with step tracking
arr = [5, 2, 8, 1, 9]
result, state_log = merge_sort(arr, track=True)
print(f"Sorted: {result}")
print(f"Steps tracked: {len(state_log)}")

# Machine Learning with tracking
X = np.random.randn(100, 3)
y = np.random.randn(100)
model = LinearRegression()
model.fit(X, y, track=True)
predictions = model.predict(X)
```

### Visualization

```python
from algo_learn.visualizer import plot_sorting_animation, plot_loss_curve

# Create sorting animation
plot_sorting_animation(state_log, save_path="sorting_demo.gif")

# Plot ML training loss
plot_loss_curve(model.state_log_, title="Linear Regression Training")
```

### Chat Interface

```python
from algo_learn.chat_ui import ChatUI

chat = ChatUI()
chat.run()

# Example commands:
# "sort [5,2,8] with merge and show steps"
# "explain why quicksort degrades"
# "run k-means on moons data"
```

## 📁 Project Structure

```
algo_learn/
├── pyproject.toml          # Package configuration
├── README.md               # This file
├── src/
│   └── algo_learn/
│       ├── __init__.py         # Public API exports
│       ├── step_logger.py      # Central state manager
│       ├── visualizer.py       # Matplotlib visualizations
│       ├── dataset_gen.py      # Synthetic data generation
│       ├── benchmark.py        # Timing and profiling
│       ├── sorting.py          # Sorting algorithms
│       ├── searching.py        # Search algorithms
│       ├── graphs.py           # Graph algorithms
│       ├── dynamic_programming.py  # DP algorithms
│       ├── string_algos.py     # String algorithms
│       ├── ml_supervised.py    # Supervised ML
│       ├── ml_unsupervised.py  # Unsupervised ML
│       └── chat_ui.py          # Conversational interface
├── examples/
│   └── demo_notebook.ipynb     # Jupyter notebook examples
└── tests/
    └── test_tracking.py        # Unit tests
```

## 🎯 API Design

All algorithms follow a consistent API pattern:

```python
# Classic algorithms
result, state_log = algorithm_name(data, track=False)

# ML estimators
model = AlgorithmName()
model.fit(X, y, track=False)  # Sets model.state_log_ if track=True
predictions = model.predict(X)
```

### State Log Format

When `track=True`, algorithms return a list of dictionaries or pandas DataFrame with columns like:
- `step`: Iteration number
- `array_state`: Current array/list state
- `comparisons`: Number of comparisons made
- `visited`: Nodes/elements visited
- `loss`: Training loss (for ML algorithms)

## 🧪 Testing

```bash
pytest tests/
```

## 📝 Academic Submission Notes

This package was developed following these principles:

1. **Educational Transparency**: Code favors explicit loops and temporary variables over clever one-liners
2. **Pedagogical Comments**: Line-by-line explanations of algorithmic intent
3. **No Black Boxes**: All algorithms implemented from scratch using only numpy, pandas, matplotlib
4. **Reproducible Results**: Deterministic behavior with optional random seeds
5. **Jupyter-Ready**: All outputs compatible with `%matplotlib inline`

### Citation

If you use this package in academic work:

```bibtex
@software{algo_learn2024,
  title = {algo\_learn: Educational Algorithm Learning Package},
  author = {Student Developer},
  year = {2024},
  url = {https://github.com/yourusername/algo_learn}
}
```

## 🔧 Dependencies

- `numpy>=1.20.0` - Numerical computing
- `pandas>=1.3.0` - Data structures and logging
- `matplotlib>=3.4.0` - Visualization

## 📄 License

MIT License - See LICENSE file for details.

## 🤝 Contributing

Contributions welcome! This is an educational project, so please prioritize:
- Clear, commented code
- Pedagogical value
- Test coverage for tracking functionality
