algo-learn 0.1.0

An educational Python package for learning algorithms through step-by-step tracking and visualization

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

# 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

pip install -e ".[dev]"

📖 Quick Start

Basic Usage

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

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

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:

# 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

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:

@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