GitHub Copilot, read this carefully before suggesting anything.

PROJECT CONTEXT

- You are working inside the "py3plex" repository.

- py3plex is a Python library for multilayer / multiplex network analysis and visualization

built on top of NetworkX and related tools.

- The design goals are:

* A clean, well-defined public API for multilayer networks.

* A small SQL-like DSL for querying networks.

* dplyr-style chaining, sklearn-style pipelines, and good visualization.

* Solid tests (pytest), type hints (mypy), and style (ruff/black-ish).

GLOBAL CONVENTIONS

- Use modern Python (3.10+), type hints everywhere, and dataclasses where helpful.

- Keep code ruff- and mypy-friendly. Avoid unused imports, wildcard imports, etc.

- Prefer pure functions and small, composable methods.

- Write docstrings that briefly describe arguments, return types, and behavior.

CURRENT TASK

Implement and improve the core public-facing layer of py3plex, focusing on:

1) PUBLIC API SURFACE

- Identify and expose the "blessed" imports in these modules:

* py3plex.core (multi_layer_network and related helpers)

* py3plex.dsl (DSL query entry points)

* py3plex.datasets (built-in datasets and loaders)

* py3plex.pipeline (sklearn-style pipelines for multilayer workflows)

* py3plex.visualization (high-level plotting helpers)

- In each of these modules:

* Define an explicit all list with the symbols meant for users.

* Add concise docstrings that make it clear how a user should call them.

2) TYPE HINTS FOR CORE

- Add or refine type hints for:

* multi_layer_network constructor and key methods (add_nodes, add_edges,

querying methods, I/O).

* DSL entry points, e.g. execute_query(...) and any high-level "run" or

"compile" functions.

* Dataset loader functions (clear argument and return types).

- Run mypy mentally when you write code:

* Avoid Any where possible.

* Prefer collections.abc interfaces (Iterable, Mapping, Sequence) for arguments.

3) VISUALIZATION CLEANUP

- For high-level visualization functions:

* Accept an optional Matplotlib Axes object instead of always creating one.

* DO NOT call plt.show() inside library code. Return the figure or axes so

the caller controls rendering.

* Separate layout/encoding logic from rendering:

- One function to compute node positions and edge attributes.

- Another function to actually draw them on an Axes.

4) DSL ROBUSTNESS

- Improve the DSL entry points by:

* Defining and using clear exception types (e.g. DSLSyntaxError, DSLExecutionError).

* Validating queries before executing them (basic syntax and supported operators).

* Providing human-readable error messages (include the offending token/segment).

5) TESTS

- For each new or changed public function:

* Add or update pytest tests.

* Cover both success paths and key failure modes (especially for DSL errors).

- Make tests deterministic and fast. Avoid heavyweight random graphs unless required.

STYLE OF CHANGES

- Prefer small, incremental, composable changes.

- When you add a new concept, add a small, focused docstring example or a short

usage note in the module-level docstring.

- Do not introduce new heavy dependencies unless absolutely necessary.

WHEN YOU GENERATE CODE

- First, show or sketch the relevant function or class in its entirety.

- Then show the corresponding tests.

- Keep names descriptive but not verbose.

Start by improving a single module (e.g. py3plex.core or py3plex.dsl):

- Add explicit all.

- Add or refine type hints for its main public functions/classes.

- Refactor any visualization helpers there to accept an optional Axes and avoid plt.show().