algoviz-python 0.1.2

Visualize algorithm execution to build intuition

🧠 AlgoViz — Algorithm Intuition Visualizer

See your algorithm think.

AlgoViz is a Python library that executes your algorithm and visualizes how it evolves step by step — pointer movement, recursion trees, sliding windows, dynamic programming state changes, AND generic function behavior patterns — all without print-debugging or heavyweight debuggers.

Perfect for:

• 📚 Learning algorithms
• 🎯 Interview prep (LeetCode-style)
• 👩‍🏫 Teaching & explanations
• 👀 Code reviews and intuition building
• 🔍 Understanding ANY function's behavior

---

Documentation

📖 See user documentation in docs/ directory
👨‍💻 See developer documentation in developer_doc/ directory

Quick Start for Users

1. docs/project/CHANGELOG.md - Version history
2. docs/project/CONTRIBUTING.md - How to contribute

For Developers & Contributors

1. developer_doc/START_HERE.md (5 min) - Orientation
2. developer_doc/architecture/ARCHITECTURE_DEEP_DIVE.md (40 min) - Complete system explanation
3. developer_doc/getting-started/QUICK_START.md (10 min) - Practical examples

---

✨ Why AlgoViz?

Tool	What it shows
Debugger	What happened
Profiler	How long it took
AlgoViz	Why it happened

AlgoViz focuses on algorithmic patterns and state evolution, not just execution.

---

� Installation

pip install algo-viz

Requirements:

• Python 3.9+
• Zero external dependencies!

---

🚀 Quick Start

Example 1: Two Pointers Algorithm

from algo_viz import visualize

@visualize()
def two_sum(nums, target):
    l, r = 0, len(nums) - 1
    while l < r:
        s = nums[l] + nums[r]
        if s == target:
            return l, r
        elif s < target:
            l += 1
        else:
            r -= 1

two_sum([1, 2, 3, 4, 5], 8)

Output:

[*] Detected patterns: Two Pointers

[*] Two Pointers Visualization
----------------------------------------------------------------------

Array: [1, 2, 3, 4, 5]

Step 1: [1] [2](l) [3] [4] [5](r)
  l=1 r=4

Step 2: [1] [2] [3](l) [4] [5](r)
  l=2 r=4

[*] Algorithm Trace
----------------------------------------
Step 02 | line 6 | l: 0 -> 1
Step 03 | line 8 | s: 6 -> 7
Step 04 | line 6 | l: 1 -> 2

Example 2: Dynamic Programming

from algo_viz import visualize

@visualize()
def climbing_stairs(n):
    dp = [0] * (n + 1)
    dp[0], dp[1] = 1, 1
    
    for i in range(2, n + 1):
        dp[i] = dp[i - 1] + dp[i - 2]
    
    return dp[n]

climbing_stairs(5)

Output:

[*] Detected patterns: Dynamic Programming

[*] DP Table Evolution
--------------------------------------------------
Step 01 | Line 7 | dp[0] = 1
Step 02 | Line 7 | dp[1] = 1
Step 03 | Line 7 | dp[2] = dp[i - 1]=1 + dp[i - 2]=1 -> 2
Step 04 | Line 7 | dp[3] = dp[i - 1]=2 + dp[i - 2]=1 -> 3
Step 05 | Line 7 | dp[4] = dp[i - 1]=3 + dp[i - 2]=2 -> 5

Example 3: Recursion

from algo_viz import visualize

@visualize()
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

fibonacci(4)

Output:

[*] Detected patterns: Recursion

[*] Recursion Tree
----------------------------------------
[+] fibonacci(n=4)
  [+] fibonacci(n=3)
    [+] fibonacci(n=2)
      [+] fibonacci(n=1)
      [-] return 1
      [+] fibonacci(n=0)
      [-] return 0
    [-] return 1
    ...

---

🔍 Supported Patterns

✅ Dynamic Programming

• Automatically detects DP patterns
• Shows formula dependencies: dp[i] = dp[i-1] + dp[i-2]
• Visualizes DP table evolution

✅ Two Pointers

• Visualizes pointer positions in array
• Shows pointer movement step-by-step
• Marks current positions clearly

✅ Sliding Window

• Shows window boundaries
• Visualizes element inclusion/exclusion
• Tracks window size changes

✅ Recursion / DFS

• Call tree visualization
• Shows function arguments
• Tracks call depth and returns

---

🎨 Output Modes

ASCII (Default)

@visualize(mode="ascii")
def my_algorithm(data):
    pass

Terminal-friendly output with step-by-step trace.

HTML

@visualize(mode="html")
def my_algorithm(data):
    pass

Generates algo_viz.html with interactive timeline visualization.

---

🛠 API Reference

@visualize Decorator

@visualize(mode="ascii")
def algorithm(data):
    """Visualize algorithm execution"""
    pass

Parameters:

• mode (str): Output format - "ascii" (default) or "html"

Features:

• Zero configuration required
• Automatic pattern detection
• Works with any Python function
• No code modifications needed

---

📖 Documentation

AlgoViz now includes generic function analysis in addition to algorithm visualization:

• QUICK_START_GENERIC.md - Get started in 5 minutes
• GENERIC_ANALYSIS.md - Complete feature guide
• DEVELOPER_GENERIC.md - Extension & API reference
• UPGRADE_GUIDE.md - Backward compatibility info

---

⚙️ How It Works

AlgoViz uses Python's built-in sys.settrace() to:

1. Trace function execution at the bytecode level
2. Capture variable assignments and changes
3. Detect algorithmic patterns automatically
4. Extract formulas and dependencies
5. Render step-by-step visualizations

No AST rewriting, no bytecode manipulation - pure runtime tracing!

---

🚀 Features

• ✅ Zero-configuration execution tracing
• ✅ Automatic algorithm pattern detection
• ✅ Step-by-step visualization
• ✅ ASCII and HTML renderers
• ✅ Python-native (runtime-based, no AST rewriting)
• ✅ Zero external dependencies
• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ Works with LeetCode problems out of the box

---

🔧 Advanced Usage

Custom Visualization

Extend AlgoViz by importing pattern detectors:

from algo_viz.tracer.tracer import ExecutionTracer
from algo_viz.detectors.dp import detect_dp

def my_algorithm(data):
    # your code
    pass

tracer = ExecutionTracer()
result, events = tracer.run(my_algorithm, data)

if detect_dp(events):
    print("DP pattern detected!")

---

📝 Examples

The examples/ directory contains ready-to-run demonstrations:

• 70_climbingStairs.py - Dynamic Programming
• two_pointers.py - Two Pointer Technique
• 50_fibonacci.py - Recursion
• longestSubstringWithoutRepeatedCharacters.py - Sliding Window

Run any example:

python examples/70_climbingStairs.py

---

⚠️ Limitations

• Single-threaded algorithms only
• No support for generator functions
• Limited to algorithm-style code (not general-purpose debugging)
• Overhead is significant for performance-critical code

---

🤝 Contributing

Contributions are welcome! Areas for improvement:

• More algorithm pattern detectors
• Additional visualization formats
• Performance optimizations
• Documentation improvements

---

📄 License

MIT License - see LICENSE for details

---

🎓 Learning Resources

• Algorithm Visualizations - Complementary tool for understanding algorithms
• LeetCode - Practice problems
• GeeksforGeeks - Algorithm tutorials

---

💬 Feedback

Have ideas or found bugs? Open an issue on GitHub!

AlgoViz helps you:

• see pointer movement
• feel recursion
• understand state changes

If AlgoViz helped you, consider giving it a ⭐

---

⚠️ Notes

• Pattern detection is heuristic-based
• Visualization depends on executed inputs
• Designed for learning and intuition, not formal verification