Python Public API

The eigenvue Python package provides a high-level interface for listing algorithms, generating step sequences, launching interactive visualizations, and embedding them in Jupyter notebooks. All four public functions are importable directly from the top-level eigenvue module.

import eigenvue

Installation

pip install eigenvue

The package requires Python 3.10 or later.

---

eigenvue.list

Returns a list of all registered algorithms, optionally filtered by category.

Signature

def list(category: str | None = None) -> list[dict]

Parameters

Parameter	Type	Required	Default	Description
category	str | None	No	None	Filter by algorithm category. Valid values: "classical", "deep-learning", "generative-ai", "quantum". If None, returns all algorithms.

Returns

list[dict] — A list of dictionaries, each containing the algorithm metadata fields id, name, category, description, and complexity.

Example

import eigenvue

# List all algorithms
all_algorithms = eigenvue.list()
for algo in all_algorithms:
    print(f"{algo.id}: {algo.name} ({algo.category})")

# Filter by category
classical = eigenvue.list(category="classical")
genai = eigenvue.list(category="generative-ai")

Example Return Value

[
    {
        "id": "binary-search",
        "name": "Binary Search",
        "category": "classical",
        "description": {
            "short": "Efficiently find a target in a sorted array by halving the search space.",
            "long": "Binary search is a divide-and-conquer algorithm..."
        },
        "complexity": {
            "time": "O(log n)",
            "space": "O(1)",
            "level": "beginner"
        }
    },
    # ... more algorithms
]

Exceptions

Exception	Condition
ValueError	category is not one of the recognized category strings.

---

eigenvue.show

Launches an interactive visualization of the specified algorithm in a local web browser. Starts a lightweight local server on the given port and opens the algorithm page.

Signature

def show(
    algorithm_id: str,
    inputs: dict | None = None,
    port: int | None = None,
) -> None

Parameters

Parameter	Type	Required	Default	Description
algorithm_id	str	Yes	—	The URL-safe identifier of the algorithm (e.g., "binary-search", "self-attention").
inputs	dict | None	No	None	Custom input parameters. Keys and values must match the algorithm’s input schema. If None, the algorithm’s default inputs from meta.json are used.
port	int | None	No	None	Port number for the local server. If None, an available port is selected automatically.

Returns

None — The function opens a browser window and blocks until the server is stopped (e.g., via Ctrl+C).

Example

import eigenvue

# Launch with default inputs
eigenvue.show("binary-search")

# Launch with custom inputs
eigenvue.show("binary-search", inputs={
    "array": [2, 4, 6, 8, 10, 12, 14, 16],
    "target": 10,
})

# Specify a port
eigenvue.show("dijkstra", port=8080)

Exceptions

Exception	Condition
ValueError	algorithm_id is not a recognized algorithm identifier.
ValueError	inputs does not conform to the algorithm’s input schema.
OSError	The specified port is already in use.
KeyboardInterrupt	The user pressed Ctrl+C to stop the server (normal shutdown path).

Thread Safety

The local server runs in a background thread. Calling show() from multiple threads concurrently is not supported. If you need multiple visualizations, open them sequentially or use jupyter() for notebook embedding.

---

eigenvue.steps

Generates the complete step sequence for an algorithm without launching a visualization. Useful for programmatic analysis, testing, and building custom integrations.

Signature

def steps(
    algorithm_id: str,
    inputs: dict | None = None,
) -> list[dict]

Parameters

Parameter	Type	Required	Default	Description
algorithm_id	str	Yes	—	The URL-safe identifier of the algorithm.
inputs	dict | None	No	None	Custom input parameters. If None, the algorithm’s default inputs are used.

Returns

list[dict] — A list of step dictionaries conforming to the Step Format Specification. Each dictionary uses the same camelCase keys as the wire format, so the result can be serialised to JSON unchanged. The list is guaranteed to be non-empty, with the last step having isTerminal: True.

Example

import eigenvue

# Generate steps with default inputs
result = eigenvue.steps("binary-search")
print(f"Total steps: {len(result)}")

# Inspect individual steps
for s in result:
    print(f"Step {s['index']}: {s['title']}")
    print(f"  Phase: {s.get('phase', 'N/A')}")
    print(f"  Actions: {len(s['visualActions'])}")

# Generate with custom inputs
result = eigenvue.steps("bubble-sort", inputs={
    "array": [5, 3, 8, 1, 2],
})

Example Return Value

[
    {
        "index": 0,
        "id": "init",
        "title": "Initialize Binary Search",
        "explanation": "Set left = 0, right = 9, searching for target 13.",
        "state": {
            "array": [1, 3, 5, 7, 9, 11, 13, 15, 17, 19],
            "target": 13,
            "left": 0,
            "right": 9,
            "mid": None,
        },
        "visualActions": [
            {"type": "highlightRange", "from": 0, "to": 9, "color": "highlight"},
            {"type": "movePointer", "id": "left", "to": 0},
            {"type": "movePointer", "id": "right", "to": 9},
        ],
        "codeHighlight": {"language": "pseudocode", "lines": [2, 3]},
        "isTerminal": False,
        "phase": "initialization",
    },
    # ... more steps
]

Key Naming

Step dictionaries keep the wire format’s camelCase keys — visualActions, codeHighlight, isTerminal — rather than being converted to snake_case. That keeps a step identical whether it came from the Python package, the npm package or the web app, so serialised output and cross-language fixtures compare directly. The package’s own function names and parameters follow Python convention; only the step payload preserves the wire format.

Exceptions

Exception	Condition
ValueError	algorithm_id is not a recognized algorithm identifier.
ValueError	inputs does not conform to the algorithm’s input schema.
RuntimeError	The generator produced an invalid step sequence.

Thread Safety

steps() is stateless and safe to call from multiple threads concurrently, provided each call operates on independent inputs. No global state is modified.

---

eigenvue.jupyter

Renders an interactive visualization inline in a Jupyter notebook. Returns an IPython.display.IFrame that embeds the Eigenvue visualization.

Signature

def jupyter(
    algorithm_id: str,
    inputs: dict | None = None,
    width: int = 960,
    height: int = 600,
) -> IFrame

Parameters

Parameter	Type	Required	Default	Description
algorithm_id	str	Yes	—	The URL-safe identifier of the algorithm.
inputs	dict | None	No	None	Custom input parameters. If None, the algorithm’s default inputs are used.
width	int	No	960	Width of the embedded IFrame in pixels. Must be a positive integer.
height	int	No	600	Height of the embedded IFrame in pixels. Must be a positive integer.

Returns

IFrame — An IPython.display.IFrame object. In Jupyter notebooks, this renders automatically when returned as the last expression in a cell. It can also be displayed explicitly with IPython.display.display().

Example

import eigenvue

# Basic usage -- returns an IFrame that renders in the notebook
eigenvue.jupyter("binary-search")

# Custom inputs and dimensions
eigenvue.jupyter(
    "self-attention",
    inputs={"tokens": ["The", "cat", "sat"]},
    width=1200,
    height=800,
)

# Explicit display
from IPython.display import display

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

Exceptions

Exception	Condition
ValueError	algorithm_id is not a recognized algorithm identifier.
ValueError	inputs does not conform to the algorithm’s input schema.
ValueError	width or height is not a positive integer.
ImportError	IPython is not installed (required for IFrame support).

Environment Requirements

This function requires a Jupyter-compatible environment (Jupyter Notebook, JupyterLab, Google Colab, or VS Code with the Jupyter extension). The IPython package must be installed. In non-Jupyter environments, use show() instead.

---

Version

The current package version is accessible via:

import eigenvue
print(eigenvue.__version__)  # "0.1.0"

---

Error Handling Summary

All public functions validate their inputs eagerly and raise descriptive exceptions. The general pattern:

import eigenvue

try:
    result = eigenvue.steps("nonexistent-algorithm")
except ValueError as e:
    print(f"Invalid input: {e}")
except RuntimeError as e:
    print(f"Generator failure: {e}")

All exceptions include the algorithm ID and a description of what went wrong.

---

Input Validation

show() and steps() check the inputs you pass against the algorithm’s declared input schema before running its generator, and raise ValueError if anything does not conform. Every algorithm publishes that schema in its meta.json under inputs.schema, and it is what the Algorithm Reference pages describe.

The checks are:

Rule	Example message
Unknown parameter	Unknown input 'targt'. Expected one of: array, target.
Missing parameter	Missing required input 'array'.
Wrong type	Input 'array' must be an array, got string.
Out of range	Input 'target' must be at most 999, got 5000.
Wrong length	Input 'array' must have at least 1 item, got 0.
Not in the allowed set	Input 'optimizer' must be one of: 'sgd', 'momentum', 'adam'. Got 'nope'.
Out of order	Input 'array' must be sorted in ascending order, but index 1 (3) is less than index 0 (5).

Passing no inputs at all uses the algorithm’s defaults, which always conform. A parameter documented as optional may be omitted; None counts as omitted.

Ordering matters more than it looks. Binary search on an unsorted array does not raise anything by itself — it returns a confidently wrong answer, which is the pitfall that algorithm’s own reference page warns about. Validating the input is what turns that into an error you can act on:

import eigenvue

try:
    eigenvue.steps("binary-search", inputs={"array": [5, 3, 1, 9], "target": 9})
except ValueError as e:
    print(e)
    # Invalid inputs for 'binary-search':
    #   - Input 'array' must be sorted in ascending order, but index 1 (3) is less than index 0 (5).

The npm package applies the same rules and reports the same messages; a cross-language test compares the two implementations case by case.