neuroflow-viz 0.2.0

Lightweight dataflow tracer for Python functions

NeuroFlow 🧠✨

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

pip install neuroflow-viz

That's it! No complex setup, no heavy dependencies. Just pure Python magic! ✨

🎬 See It In Action (30-Second Demo)

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!

Every step from $1000 → $1259.71 visualized with emojis and colors

📐 Distance Formula - Geometry Made Visual

See Pythagorean theorem in action: 3² + 4² = 5²

🔢 Quadratic Formula - Algebra Comes Alive

Watch the discriminant calculation unfold step-by-step

🧠 Neural Network - AI Demystified

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:

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!

@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

@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

@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
3. BAM! Instant beautiful visualization! ✨

💻 Local Rendering (For Pros)

# 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

@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

# 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

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:

@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?

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

NeuroFlow v0.2.0 - Where Code Meets Art 🎨