Getting Started — Python Package

The eigenvue Python package lets you launch the same interactive visualizations you see on eigenvue.web.app — directly from your terminal, scripts, or notebooks.

Installation

Install from PyPI:

pip install eigenvue

Requirements:

• Python 3.10 or later
• The only runtime dependency is Flask, which is installed automatically

Verify the installation:

import eigenvue

print(eigenvue.__version__)

Quick Start — Listing Algorithms

Use eigenvue.list() to see every algorithm the package ships with:

import eigenvue

algorithms = eigenvue.list()

for algo in algorithms:
    print(f"{algo.id:30s} {algo.category:20s} {algo.name}")

list() returns a list of AlgorithmInfo objects — frozen dataclasses, so read their fields with attribute access rather than subscripting. Each one carries id, name, category, description, difficulty, time_complexity and space_complexity.

category is one of "classical", "deep-learning", "generative-ai" or "quantum", and list() accepts one to filter by:

classical = eigenvue.list(category="classical")

Quick Start — Opening a Visualization

Call eigenvue.show() with an algorithm ID to launch the visualizer in your default browser:

import eigenvue

eigenvue.show("bubble-sort", inputs={"array": [5, 3, 8, 1, 2]})

A local Flask server starts in the background and serves the interactive three-panel visualizer. The browser tab opens automatically. Press Ctrl+C in the terminal to stop the server when you are done.

Custom inputs go in the inputs dictionary, and its keys are the parameter names that algorithm declares — array for the sorting algorithms, array and target for binary search, and so on. Each algorithm’s reference page lists its parameters, and eigenvue.list() is the quickest way to find an algorithm’s ID. Omit inputs entirely to use the algorithm’s defaults.

Inputs are checked against the algorithm’s schema before anything runs, so a misspelled parameter or an out-of-range value raises ValueError describing exactly what was wrong rather than producing a misleading visualization. See Input Validation.

Programmatic Step Access

When you need raw step data — for analysis, testing, or integration with other tools — use eigenvue.steps():

import eigenvue

steps = eigenvue.steps("binary-search", inputs={"array": [1, 3, 5, 7, 9], "target": 7})

print(f"Total steps: {len(steps)}")

for step in steps:
    print(f"Step {step['index']}: {step['title']}")
    print(f"  {step['explanation']}")
    print(f"  State: {step['state']}")

steps() returns a list of step dictionaries in the step format, with camelCase keys for JSON compatibility. The keys you will use most often:

Key	Type	Description
index	int	Position in the sequence, starting at 0
id	str	Stable identifier for this kind of step, e.g. "calculate_mid"
title	str	Short heading for the step
explanation	str	Plain-language description of what just happened
state	dict	Snapshot of the algorithm’s variables at this point
codeHighlight	dict	{"language": str, "lines": list[int]} — the lines to highlight
isTerminal	bool	True only for the final step

Steps also carry visualActions and an optional phase. The list is never empty, and only the last entry has isTerminal set.

This makes it straightforward to write assertions in tests, collect metrics, or feed step data into your own visualisation pipeline.

Type Safety

The package ships with a py.typed marker and full type hints on every public function. If you use a type checker such as mypy or Pyright, you get autocompletion and static analysis out of the box:

# Your editor will infer the return type automatically.
steps: list[dict[str, object]] = eigenvue.steps("merge-sort", inputs={"array": [9, 4, 7]})

Type stubs are bundled inside the package — no extra install is required.