Tracer

GIF
Tracing a Dynamically Allocated Array
Traced Graph
GIF
Tracing Dijkstra's Algorithm
Example of a BST (beta Tracer)

About the Tracer Project

Inspiration

The Tracer project was born from the desire to demystify code execution and make complex programming concepts more tangible. We recognized the challenges developers and learners face in understanding the step-by-step flow of a program, especially when dealing with algorithms, data structures, and function calls. Our aim was to create an intuitive visual tool that could "trace" code execution, providing clear insights into how code works under the hood.

What it does Tracer is a desktop application built with Pygame that serves as a dynamic code visualization and tracing tool. It offers:

Integrated Text Editor: A dedicated area where users can write and edit Python code.
AI-Powered Step-by-Step Code Execution Visualization: The core feature, allowing users to see their code execute line by line. Leveraging the Google Gemini AI API, Tracer intelligently interprets the user's code and generates visual representations of function calls, variable changes, and data structures as an animation.
Animation Playback: Users can navigate through the execution trace frame by frame, moving forward and backward to analyze specific moments in the program's lifecycle.
Interactive Controls: Custom-designed icon buttons provide intuitive control over code execution (Run) and animation playback (Forward, Backward).
Loading Indicator: A visual cue is displayed during the potentially time-consuming process of compiling the code into animation frames, ensuring a better user experience.

How we built it

Tracer is primarily built using Pygame, a set of Python modules designed for writing video games. Key architectural decisions include:

Modular Design: The project is structured into distinct Python files (buttons.py, configs.py, text_editor.py, viz_window.py, event_handler.py, tracer.py, etc.) to promote code organization, reusability, and maintainability.
Generative AI Integration (Google Gemini API): The Agentic_AI module (comprising agent.py, base_agent.py, and tracer_compiler.py) is central to the visualization process. It uses the Google Gemini AI API to analyze the user's input code. Through Gemini's function-calling capabilities, the AI generates a sequence of predefined drawing function calls (e.g., draw_node, draw_arrow, draw_text) with specific arguments, which then form the individual frames of the code execution animation.
Custom UI Elements: We developed a reusable Button class capable of rendering icon characters, providing a clean and modern interface.
Centralized Configuration: All screen dimensions, colors, font settings, and UI component sizes are managed in configs.py, allowing for easy adjustments and responsive layout.
Shared State Management: A global animation_state dictionary is used to communicate the status of the animation building process (e.g., "idle", "building", "ready") between different modules, enabling the loading indicator functionality.
Event-Driven Architecture: Pygame's event loop is leveraged to handle all user interactions, from keyboard input in the text editor to mouse clicks on buttons.

Challenges we ran into

Developing Tracer presented several interesting challenges:

Blocking Operations & AI Latency: The build_animation_frames process, which involves calling the Gemini API, can be computationally intensive and introduces network latency. While we implemented a visual loading indicator, maintaining full UI responsiveness during this operation without complex multi-threading was a design consideration.
Dynamic UI Layout: Accurately positioning UI elements (text editor, visualization window, and buttons) relative to each other and the overall screen size, while ensuring they adapt gracefully, required careful calculation and iteration.
Pygame Surface Management: Ensuring that elements drawn on sub-surfaces (like the text editor or visualization window) were correctly updated and blitted to the main screen in the right order was crucial to prevent visual artifacts or disappearing elements.
Event Handling Granularity: Precisely routing Pygame events to the correct interactive components (text editor for typing, buttons for clicks) required a robust event dispatcher.
AI Function Calling Design: Crafting the OpenAPI schema for the drawing functions and designing the system prompt for Gemini to reliably generate the correct sequence of drawing calls for arbitrary Python code was a key challenge.

Accomplishments that we're proud of

Successfully creating a functional and interactive code visualization tool using Pygame.
Seamlessly integrating the Google Gemini AI API to intelligently interpret and visualize code execution.
Implementing a clean, modular, and extensible codebase that separates concerns effectively.
Developing custom UI elements like icon buttons that enhance the user experience.
Achieving a dynamic and responsive layout that adapts to different screen resolutions.
Providing clear visual feedback (loading indicator) for background processes.

What we learned

Through the development of Tracer, we gained valuable insights into:

Advanced Pygame application structuring and best practices.
Practical application of generative AI (Google Gemini) for code understanding and visualization.
The importance of robust state management in interactive applications.
Techniques for creating dynamic and adaptable user interfaces.
Strategies for handling potentially long-running operations (including API calls) in a GUI environment.
The nuances of surface drawing order and updates in Pygame.
Designing effective prompts and tool schemas for AI function calling.

What's next for Tracer

Looking ahead, we envision several exciting enhancements for Tracer:

Enhanced AI Capabilities: Further refining the Gemini prompt and tool definitions to support visualization of more complex data structures, algorithms, and advanced Python features.
Improved Text Editor: Adding features such as syntax highlighting, line numbering, and more sophisticated cursor management for a richer coding experience.
Non-Blocking Compilation: Exploring multi-threading to allow the UI to remain fully responsive while the animation frames (including AI processing) are being built in the background.
More Robust Error Handling: Providing more detailed and user-friendly error messages for compilation or runtime issues, especially those originating from the AI interpretation.
Advanced UI/UX: Implementing features like zoom, pan, and customizable themes for the visualization window.
Integration with External Tools: Potentially integrating with a live Python interpreter or debugger for real-time tracing.
Web Deployment Exploration: Investigating solutions like Pyodide or PyScript to bring Tracer to the web browser, making it more accessible without a desktop installation, while still leveraging the AI backend

Built With

Submitted to

GemiKnights

Created by

I developed the Agentic AI side of the project. I leveraged Gemini's function call feature (which I thought was more experimental compared to structured output) to teach the model how to call our custom made, pygame drawing functions. I created an interpreter to execute Gemini's function calls and then draw the visualizations to the screen. I built a simple tiling manager to organize the drawings, and a multi-agent system that leverages one agent making predictions, another double checking those predictions and tweaking the system prompt for the next agent to make the final functional calls. All without langchain, langgraph, or any tools besides python and Gemini :)

Adam Mouedden
I worked on two key features on the backend: implementing the cursor logic and building the copy-and-paste system. What seemed simple on the surface ended up needing more complex logic — from decoding and handling newlines from the clipboard, to dynamically updating the cursor position and making sure pasted text integrated cleanly at the right location.

On the frontend, I developed the scrollbar functionality, which required moving the text content upward as the scrollbar moved downward. Every pixel had to be accounted for -- the text and cursor could only be rendered if they fell within the visible text editor bounds. I also ensured the scrollbar thumb resized proportionally based on the amount of text present.

Working at such a granular level gave me a deep appreciation for the complexity behind seemingly simple UI features!

David Orjuela
Joshua Bandy
Kenta Festag