Metadata-Version: 2.4
Name: synapse-tracer
Version: 1.0.0
Summary: Neural-style execution graph visualizer for Python projects
Author: Nikhil Wankhede
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyvis
Requires-Dist: psutil

# SYNAPSE

## Project Tagline

A Python runtime execution visualizer that traces program behavior and represents it as a neural-style execution graph.

## Overview

SYNAPSE is a Python execution tracing tool designed to capture runtime events, including function calls, line execution, returns, and exceptions. These events are recorded chronologically and subsequently utilized to generate an interactive graphical representation of program behavior. The primary objective is to facilitate developer comprehension of code flow within a project and to pinpoint error occurrences during execution.

## Core Concept

Departing from traditional stack traces or log analysis, SYNAPSE offers a visual paradigm for understanding program execution.

Each module or file is conceptualized as a node within a graph, with execution transitions between files depicted as edges. During runtime playback, nodes illuminate to signify the flow of execution, analogous to neuronal activation in a neural network.

## Features

### Pending Features (Session 1)

- Python runtime tracing utilizing `sys.settrace`.
- Capture of call, line, return, and exception events.
- Recording of execution timelines into JSON format.
- Tracking of call stack depth.
- Monitoring of execution transitions between modules.
- Capture of exception type and associated message.

### Planned Features

- Static dependency graph generation.
- Three-dimensional neural-style graph visualization.
- Timeline-based playback of execution events.
- Interactive debugging interface.
- Error highlighting within the execution graph.

## Usage

To execute the tracer on a target script, employ the following command:

```bash
python synapse.py demo_project/main.py
```

This command initiates the tracer, resulting in the generation of `events.json`, which contains the recorded execution timeline.

## Technology Stack

| Technology | Purpose |
| :--- | :--- |
| Python | Core programming language |
| Runtime Tracing | `sys.settrace` for event capture |
| JSON | Event logging and timeline storage |
| AST Parsing | (Planned) For static analysis |
| 3D Visualization | (Planned) For neural-style graph rendering |

## Project Goal

The long-term objective of SYNAPSE is to establish a visual debugging tool that renders program execution as an interactive neural network. This will enable developers to replay execution timelines, inspect errors, and comprehend intricate code flows through an intuitive visual interface.
