neuroflow-viz 0.2.0
Lightweight dataflow tracer for Python functions
Requires Python: >=3.8
Keywords: dataflow, tracing, debugging, computational-graph, visualization

# NeuroFlow 🧠✨

[![PyPI version](https://badge.fury.io/py/neuroflow-viz.svg)](https://badge.fury.io/py/neuroflow-viz)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Ever wondered how your Python functions actually compute results?** 🤔

**NeuroFlow** transforms your mathematical functions into **beautiful, interactive visual stories**! Just add one decorator and watch your calculations come alive with stunning flowcharts that show exactly how your code thinks.

**Perfect for:** Students learning algorithms • Developers debugging complex math • Researchers explaining computations • Anyone curious about how code works!

---

## 🎯 What Makes NeuroFlow Special?

**Before NeuroFlow:** Your function is a black box 📦  
**After NeuroFlow:** Every step is crystal clear! 🔍✨

## ✨ Why You'll Love NeuroFlow

🎯 **Zero Learning Curve** - Add `@trace` and you're done!  
🎨 **Instagram-Worthy Graphs** - Emojis, colors, and crystal-clear flow  
⚡ **Instant Insights** - See exactly where your math goes wrong (or right!)  
🔬 **Debug Like a Pro** - Trace complex algorithms step-by-step  
📚 **Perfect for Teaching** - Students finally "get" how algorithms work  
🚀 **Production Ready** - Thread-safe, type-safe, and battle-tested

## 🚀 Get Started in 30 Seconds

```bash
pip install neuroflow-viz
```

**That's it!** No complex setup, no heavy dependencies. Just pure Python magic! ✨

## 🎬 See It In Action (30-Second Demo)

```python
from neuroflow import trace

@trace  # ← This single line creates magic! ✨
def compound_interest(principal, rate, years):
    return principal * (1 + rate)**years

# Run normally - but now you get BOTH result AND visual story!
result, graph = compound_interest(1000, 0.08, 3)
print(f"💰 Your $1000 became: ${result:.2f}")  # $1259.71

# See the beautiful visualization
graph.save_dot("my_calculation.dot")
# 👆 Paste this at: https://dreampuf.github.io/GraphvizOnline/
```

**🤯 Mind = Blown!** Your function now tells its own story!

## 🎨 Prepare to Be Amazed

**These aren't your typical boring flowcharts.** NeuroFlow creates **visual masterpieces** that make math beautiful:

> *"Finally, I can SEE what my code is thinking!"* - Every Developer Ever

### 💰 **Compound Interest** - Watch Your Money Grow!
![Compound Interest Graph](images/compound.png)
*Every step from $1000 → $1259.71 visualized with emojis and colors*

### 📐 **Distance Formula** - Geometry Made Visual
![Distance Formula Graph](images/distance.png)
*See Pythagorean theorem in action: 3² + 4² = 5²*

### 🔢 **Quadratic Formula** - Algebra Comes Alive
![Quadratic Formula Graph](images/quadratic.png)
*Watch the discriminant calculation unfold step-by-step*

### 🧠 **Neural Network** - AI Demystified
![Neural Activation Graph](images/Nueral.png)
*See how artificial neurons actually "think"*

## 🎮 Interactive Demo - Try It Now!

**Want to see the magic yourself?** Run our demo and prepare to be amazed:

```bash
python demo.py  # 🎬 4 stunning visualizations in seconds!
```

**You'll get:**
- 💡 **"Aha!" moments** as complex math becomes crystal clear
- 🎨 **Beautiful graphs** you'll want to frame on your wall
- 🧠 **Deep understanding** of how algorithms really work
- 📸 **Screenshots** to impress your colleagues

*Warning: May cause sudden understanding of mathematics* 😄

## 🛠️ Real-World Examples (Copy & Paste Ready)

### 🎓 **For Students** - Finally Understand Math!
```python
@trace
def quadratic_formula(a, b, c):
    """See the discriminant calculation step-by-step!"""
    discriminant = b**2 - 4*a*c
    sqrt_discriminant = discriminant**0.5
    return (-b + sqrt_discriminant) / (2*a)

result, graph = quadratic_formula(1, -5, 6)
# 🎯 Now you can SEE why the answer is 3.0!
```

### 💼 **For Finance Pros** - Visualize Your Models
```python
@trace
def compound_interest(principal, rate, years):
    """Show clients exactly how their money grows!"""
    return principal * (1 + rate)**years

result, graph = compound_interest(1000, 0.08, 3)
# 📈 Perfect for client presentations!
```

### 🎮 **For Game Developers** - Debug Physics
```python
@trace
def distance_formula(x1, y1, x2, y2):
    """Visualize collision detection calculations!"""
    dx = x2 - x1
    dy = y2 - y1
    return (dx**2 + dy**2)**0.5

result, graph = distance_formula(0, 0, 3, 4)
# 🎯 See exactly how distance is calculated!
```

## 🖼️ Turn Code Into Art

**Two ways to see your beautiful graphs:**

### 🌐 **Instant Online Viewing** (Recommended)
1. Copy your `.dot` file content
2. Paste at [GraphvizOnline](https://dreampuf.github.io/GraphvizOnline/)
3. **BAM!** Instant beautiful visualization! ✨

### 💻 **Local Rendering** (For Pros)
```bash
# Install Graphviz once
sudo apt-get install graphviz  # Ubuntu/Debian
brew install graphviz          # macOS
# Windows: Download from graphviz.org

# Create stunning images
dot -Tpng your_graph.dot -o your_graph.png
```

## 📚 Simple API (You'll Master in 5 Minutes)

### 🎯 **The Magic Decorator**
```python
@trace  # ← This is literally all you need!
def your_function(args):
    return result

result, graph = your_function(inputs)  # Get both result AND visualization!
```

### 📊 **Graph Superpowers**
```python
# Quick text summary
print(graph.summary())  # See all operations at a glance

# Save beautiful visualization
graph.save_dot("my_graph.dot")  # Ready for viewing!

# Advanced: Direct DOT access
dot_content = graph.to_dot()  # Full control over output
```

### 🎨 **Pro Visualization**
```python
from neuroflow import visualize_graph

# One-liner to create and save
visualize_graph(graph, "output.dot")  # Done!
```

## 🧮 What Can NeuroFlow Trace?

**Everything you need for mathematical computing:**

✅ **All Math Operations**: `+` `-` `*` `/` `//` `%` `**`  
✅ **Advanced Functions**: `abs()` `-x` (negation)  
✅ **Smart Comparisons**: `==` `<` `<=` `>` `>=`  
✅ **Complex Data**: Lists, tuples, dictionaries (nested too!)  
✅ **Real-World Code**: Financial models, ML algorithms, physics simulations

*If it's math, NeuroFlow can visualize it!* 🎯

## 🛡️ Built-in Safety Net

**NeuroFlow catches errors before they catch you:**

```python
@trace
def risky_calculation(x):
    return x / 0  # Uh oh!

try:
    result, graph = risky_calculation(10)
except ZeroDivisionError as e:
    print(f"NeuroFlow saved you: {e}")  # Clear, helpful errors!
```

**No more mysterious crashes!** 🎯

## ⚡ Production-Ready Features

🔒 **Thread-Safe**: Use in multi-threaded apps without worry  
🎯 **Type-Safe**: Full type hints for better IDE support  
🚀 **Performance**: Minimal overhead, maximum insight  
🧪 **Battle-Tested**: Comprehensive test suite ensures reliability

## 🎯 Perfect For

✅ **Mathematical Functions** - See every calculation step  
✅ **Algorithm Learning** - Understand how code works  
✅ **Debugging Complex Math** - Find errors instantly  
✅ **Teaching & Presentations** - Make code visual  
✅ **Research & Analysis** - Document your computations

**Note:** Focuses on arithmetic operations (the heart of most algorithms!)

## 🤝 Join the NeuroFlow Community

**Love NeuroFlow? Help make it even better!**

- 🐛 **Found a bug?** Open an issue
- 💡 **Have an idea?** Start a discussion  
- 🔧 **Want to contribute?** Submit a PR
- ⭐ **Enjoying it?** Star the repo!

**Together, we're making code visualization accessible to everyone!** 🌟

---

## 🎉 Ready to Transform Your Code?

```bash
pip install neuroflow-viz
```

**In 30 seconds, you'll be creating beautiful visualizations that make complex math crystal clear!**

*Your future self (and your colleagues) will thank you.* 😊

---

**MIT License** | **Made with ❤️ by [Nipun Sujesh](https://github.com/Luc0-0)**

*NeuroFlow v0.2.0 - Where Code Meets Art* 🎨