Summary

gepa-viz offers real-time, interactive visualization for GEPA prompt optimization runs. It targets DSPy and base GEPA users, visualizing prompt evolution via a force-directed graph on a Pareto frontier. This provides crucial insight into optimization decisions and candidate performance, allowing users to observe and analyze the prompt engineering process dynamically.

How It Works

The tool renders the GEPA candidate tree as a force-directed graph. Accepted candidates are visualized as donuts, with ring segments colored green or red based on per-example validation scores. Rejected proposals appear as small grey nodes, revealing feedback upon hover. Detailed node views expose candidate prompts, differences from their parents, reflection minibatch results, and the Pareto frontier grid. The GepaVizCallback context manager integrates seamlessly, streaming updates via Server-Sent Events (SSE) for live visualization in embedded or remote modes, or generating static run.json files for offline analysis. This approach provides dynamic, granular insight into prompt optimization dynamics.

Quick Start & Requirements

Installation is straightforward via pip: pip install gepa-viz. Development prerequisites include Node.js, npm, uv, and the just build tool. Running examples (just dev-py) necessitates an OPENAI_API_KEY. Usage modes include:

• Embedded: Integrate GepaVizCallback directly into Python code for an automatic local server and browser launch.
• Remote: Stream data to a standalone gepa-viz live server for distributed optimization runs.
• Static: Use live=False in the callback to generate a run.json file, viewable later with the gepa-viz serve command.

Highlighted Details

• Real-time visualization of prompt candidates evolving across a Pareto frontier.
• Interactive force-directed graph mapping candidate relationships and feedback loops.
• Granular inspection of individual candidate details, including prompt diffs, reflection outcomes, and per-example scoring.
• Flexible deployment options: embedded local visualization, remote streaming, or static file serving.

Maintenance & Community

The provided README lacks specific details on maintainers, community channels (e.g., Discord, Slack), or project roadmaps.

Licensing & Compatibility

The project is released under the permissive MIT license, which generally allows for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

Development and example execution (just dev-py) depend on the availability of an OPENAI_API_KEY, indicating a reliance on OpenAI's API services for full functionality during development. The tool is specifically tailored for GEPA optimization runs, and its applicability outside this context is not detailed.