py3plex 1.1.5__tar.gz → 2.0.0__tar.gz

{py3plex-1.1.5/py3plex.egg-info → py3plex-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py3plex
-Version: 1.1.5
+Version: 2.0.0
 Summary: A Multilayer network analysis python3 library
 Author-email: Blaž Škrlj <blaz.skrlj@ijs.si>
 License: MIT
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.8
@@ -27,7 +28,6 @@ Requires-Dist: numpy>=1.19.0
 Requires-Dist: rdflib>=6.0.0
 Requires-Dist: scipy>=1.5.0
 Requires-Dist: networkx>=2.5
-Requires-Dist: cython>=0.29.0
 Requires-Dist: tqdm>=4.40.0
 Requires-Dist: matplotlib>=3.3.0
 Requires-Dist: gensim>=4.0.0
@@ -86,6 +86,15 @@ Provides-Extra: dgl-compat
 Requires-Dist: dgl>=0.9.0; extra == "dgl-compat"
 Provides-Extra: mcp
 Requires-Dist: mcp>=0.9.0; python_version >= "3.10" and extra == "mcp"
+Provides-Extra: optional
+Requires-Dist: infomap>=2.0.0; extra == "optional"
+Requires-Dist: python-louvain>=0.16; extra == "optional"
+Requires-Dist: cdlib>=0.3.0; extra == "optional"
+Requires-Dist: plotly>=5.0.0; extra == "optional"
+Requires-Dist: python-igraph>=0.10.0; extra == "optional"
+Requires-Dist: pyyaml>=5.1; extra == "optional"
+Requires-Dist: pyarrow>=10.0.0; extra == "optional"
+Requires-Dist: mcp>=0.9.0; python_version >= "3.10" and extra == "optional"
 Dynamic: license-file
 
 
@@ -103,8 +112,8 @@ Dynamic: license-file
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/py3plex)](https://pypistats.org/packages/py3plex)
 ![CLI Tool](https://img.shields.io/badge/CLI%20Tool-Available-brightgreen)
 ![Docker](https://img.shields.io/badge/Docker-Available-blue)
-![Lines of Code](https://img.shields.io/badge/lines-209.4K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.0K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-211.4K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.2K-blue)
 
 *Multilayer networks* are complex networks with additional information assigned to nodes or edges (or both). This library includes
 some of the state-of-the-art algorithms for decomposition, visualization and analysis of such networks.
@@ -164,6 +173,14 @@ print(df[["id", "layer", "community_id",
           "betweenness_centrality_ci95_high", "score", "top_neighbors"]].head(10))
 ```
 
+### Safe chaining order (DSL v2)
+
+Use a strict two-phase flow:
+
+1. **Build query** on `Q...` (`.where()`, `.compute()`, `.order_by()`, `.per_layer()`, `.coverage()`, ...)
+2. **Execute once** with `.execute(network)`
+3. **Handle results** on `QueryResult` (`.to_pandas()`, `.group_summary()`, `.to_json()`, ...)
+
 **Example output:**
 ```
     id  layer  community_id  betweenness_centrality__mean  betweenness_centrality_ci95_low  betweenness_centrality_ci95_high     score  top_neighbors
@@ -183,6 +200,30 @@ print(df[["id", "layer", "community_id",
 - **Interpretability**: `.explain()` enriches results with community IDs, top interaction partners, and layer presence
 - **Composite scoring**: Weighted combination of multiple centrality measures for robust ranking
 
+### Ecosystem positioning
+
+| Comparator | Ecosystem | Primary scope | Where it overlaps with py3plex 2.0 | py3plex 2.0 positioning |
+|---|---|---|---|---|
+| **py3plex 2019** | Python | Multilayer network visualization and analysis | Direct historical predecessor: multilayer representation, aggregation, indexing, traversal, visualization, and embedding-assisted layouts | **Historical foundation.** py3plex 2.0 extends the original toolkit from visualization-oriented analysis into a reproducible, query-driven multilayer network science environment. |
+| **pymnet** | Python | General multilayer network representation, metrics, random models, and visualization | Strong overlap on formal multilayer data structures, multilayer metrics, transformations, random models, and visualization | **Closest Python multilayer comparator.** pymnet is strongest as a formal multilayer framework; py3plex 2.0 is strongest as a workflow, DSL, uncertainty, and reproducibility layer. |
+| **MultiNetX** | Python / NetworkX | NetworkX-style multilayer graph manipulation, spectral analysis, and visualization | Overlap on Python-native multilayer graph objects, supra-adjacency/Laplacian workflows, and visualization | **Lightweight Python comparator.** MultiNetX provides compact multilayer graph utilities; py3plex 2.0 provides a broader end-to-end analysis and workflow environment. |
+| **muxViz** | R / desktop ecosystem | Multilayer and multiplex visual analytics | Overlap on multilayer visualization, centrality, community detection, motifs, structural reducibility, and dynamic visualization | **R visual-analytics comparator.** muxViz is strongest for visual exploration; py3plex 2.0 emphasizes Python-native, scriptable, DSL-driven, reproducible analysis. |
+| **R `multinet`** | R | Multiplex and multilayer social-network analysis and mining | Overlap on multilayer representation, import/export, attributes, centrality, community detection, generation, and plotting | **R social-network comparator.** `multinet` is strongest for multiplex social-network analysis; py3plex 2.0 targets broader heterogeneous scientific multilayer workflows in Python. |
+| **tnetwork** | Python | Temporal-network manipulation and dynamic communities | Overlap on temporal slicing, dynamic graphs, and evolving-community analysis | **Temporal-community comparator.** tnetwork focuses on temporal community workflows; py3plex 2.0 embeds temporal analysis inside a broader multilayer DSL/workflow stack. |
+| **DyNetx** | Python / NetworkX | Dynamic graph extension for NetworkX | Overlap on time-varying graph representation, snapshots, interaction streams, and temporal slicing | **Dynamic-NetworkX comparator.** DyNetx handles dynamic graphs; py3plex 2.0 adds multilayer semantics, declarative analysis, integrated dynamics, and reusable workflows. |
+| **Reticula** | Python with C++ core | Fast static and temporal network / hypergraph analysis | Overlap on temporal networks, reachability, randomized models, and dynamical-process analysis | **Performance temporal/hypergraph comparator.** Reticula is stronger for fast temporal and hypergraph analysis; py3plex 2.0 is stronger for multilayer workflow integration and analyst ergonomics. |
+| **Raphtory** | Rust / Python | Temporal graph engine and deployment platform | Overlap on temporal graph views, time-aware querying, reachability, motifs, and deployment-oriented graph analysis | **Modern temporal-engine comparator.** Raphtory is an engine/platform; py3plex 2.0 is a multilayer network-science workflow layer with DSL, uncertainty, dynamics, and reproducible analysis. |
+| **pathpy / pathpyG** | Python / PyTorch ecosystem | Path-centric temporal-network analytics and graph learning | Overlap on temporal analytics, time-respecting paths, temporal centralities, visualization, and graph-learning handoff | **Temporal graph-learning comparator.** pathpy/pathpyG is adjacent; py3plex 2.0 focuses on multilayer network science, layer-aware querying, uncertainty, and reproducible workflows. |
+| **NetworkX** | Python | General graph creation, manipulation, and algorithms | Overlap on core graph algorithms, graph data structures, centrality, communities, and Python graph workflows | **General graph substrate.** NetworkX is the base graph ecosystem; py3plex 2.0 adds multilayer semantics, DSL queries, layer algebra, temporal/dynamics workflows, and structured outputs. |
+| **igraph** | C / R / Python | Efficient general-purpose network analysis | Overlap on centrality, community detection, graph transformations, and scalable graph analysis | **Efficient general-graph comparator.** igraph is the speed/breadth baseline; py3plex 2.0 differentiates through multilayer-specific workflows and reproducible analyst interfaces. |
+| **graph-tool** | Python with C++ core | High-performance graph algorithms and statistical network modeling | Overlap on large-network statistics, community detection, inference, and performance-sensitive graph analysis | **Performance/statistical comparator.** graph-tool is strongest for efficient statistical graph analysis; py3plex 2.0 prioritizes multilayer expressiveness, querying, uncertainty, and workflow integration. |
+| **tidygraph** | R / tidyverse | Tidy, dplyr-style graph manipulation | Overlap on chainable, analyst-friendly node/edge manipulation and graph-as-table workflows | **Analyst-grammar comparator.** tidygraph motivates fluent graph manipulation; py3plex 2.0 adapts this style to Python multilayer networks with DSL, builder APIs, and layer-aware grouping. |
+| **NDlib** | Python | Diffusion and epidemic processes on networks | Overlap on SIS/SIR-style processes, random walks, spreading dynamics, and simulation workflows | **Dynamics comparator.** NDlib specializes in diffusion; py3plex 2.0 embeds dynamics inside multilayer, temporal, queryable, uncertainty-aware workflows. |
+| **PyTorch Geometric** | Python / PyTorch | Graph neural networks and geometric deep learning | Overlap on graph embeddings, graph data preparation, and downstream graph-learning workflows | **Graph-ML comparator.** PyG trains graph neural models; py3plex 2.0 prepares, queries, explains, summarizes, and analyzes multilayer networks. |
+| **DGL** | Python / deep-learning frameworks | Scalable graph deep learning and message passing | Overlap on heterogeneous graph processing, graph learning, and scalable graph ML pipelines | **Scalable graph-ML comparator.** DGL addresses GNN systems engineering; py3plex 2.0 addresses multilayer network science, query abstractions, uncertainty, temporal analysis, and workflows. |
+| **Neo4j / Cypher** | Database systems | Persistent property-graph storage and declarative graph querying | Overlap on declarative graph querying and pattern-style graph access | **Graph-query comparator.** Cypher queries persistent property graphs; py3plex 2.0 provides an in-memory scientific DSL for multilayer network analysis, metrics, uncertainty, and exports. |
+| **py3plex 2.0** | Python | Query-driven, reproducible multilayer network analysis | Integrates capabilities otherwise spread across multilayer libraries, temporal engines, graph libraries, graph-ML frameworks, graph-query systems, and workflow tools | **Current version** py3plex 2.0 is best framed as a Python-native workflow layer for multilayer network science: DSL + builder API, layer algebra, QueryResult exports, uncertainty-first statistics, temporal/dynamics workflows, null models, CLI/config execution, and agent-facing interfaces. |
+
 ![Py3plex Visualization Showcase](example_images/py3plex_showcase.png)
 
 ## Getting Started
@@ -227,8 +268,39 @@ pip install py3plex[viz]
 
 # All optional features
 pip install py3plex[mcp,algos,viz]
+
+# Common optional feature bundle (algorithms + visualization + workflows + arrow + mcp)
+pip install py3plex[optional]
 ```
 
+### Contributing (First PR Quick Path)
+
+If this is your first contribution, use this sequence:
+
+```bash
+# 1) Create local dev environment and install package
+make setup
+make dev-install
+
+# 2) Run formatting and checks before opening a PR
+make format
+make lint
+make test
+```
+
+Helpful commands:
+
+```bash
+make help   # List all project commands
+make ci     # Run lint + tests in CI-style order
+```
+
+Safety notes for contributors:
+- Keep changes focused and add tests next to the feature you modify.
+- Do not add new markdown files unless explicitly requested (enforced by `tests/test_link_checker.py` to prevent documentation drift).
+- Prefer running targeted tests first, then broader checks before opening a PR.
+- For docs-only updates, run `make docs-check` before opening a PR.
+
 ### MCP Integration (AI Agents)
 
 py3plex provides a Model Context Protocol (MCP) server for integration with AI coding assistants:

{py3plex-1.1.5 → py3plex-2.0.0}/README.md

@@ -13,8 +13,8 @@
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/py3plex)](https://pypistats.org/packages/py3plex)
 ![CLI Tool](https://img.shields.io/badge/CLI%20Tool-Available-brightgreen)
 ![Docker](https://img.shields.io/badge/Docker-Available-blue)
-![Lines of Code](https://img.shields.io/badge/lines-209.4K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.0K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-211.4K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.2K-blue)
 
 *Multilayer networks* are complex networks with additional information assigned to nodes or edges (or both). This library includes
 some of the state-of-the-art algorithms for decomposition, visualization and analysis of such networks.
@@ -74,6 +74,14 @@ print(df[["id", "layer", "community_id",
           "betweenness_centrality_ci95_high", "score", "top_neighbors"]].head(10))
 ```
 
+### Safe chaining order (DSL v2)
+
+Use a strict two-phase flow:
+
+1. **Build query** on `Q...` (`.where()`, `.compute()`, `.order_by()`, `.per_layer()`, `.coverage()`, ...)
+2. **Execute once** with `.execute(network)`
+3. **Handle results** on `QueryResult` (`.to_pandas()`, `.group_summary()`, `.to_json()`, ...)
+
 **Example output:**
 ```
     id  layer  community_id  betweenness_centrality__mean  betweenness_centrality_ci95_low  betweenness_centrality_ci95_high     score  top_neighbors
@@ -93,6 +101,30 @@ print(df[["id", "layer", "community_id",
 - **Interpretability**: `.explain()` enriches results with community IDs, top interaction partners, and layer presence
 - **Composite scoring**: Weighted combination of multiple centrality measures for robust ranking
 
+### Ecosystem positioning
+
+| Comparator | Ecosystem | Primary scope | Where it overlaps with py3plex 2.0 | py3plex 2.0 positioning |
+|---|---|---|---|---|
+| **py3plex 2019** | Python | Multilayer network visualization and analysis | Direct historical predecessor: multilayer representation, aggregation, indexing, traversal, visualization, and embedding-assisted layouts | **Historical foundation.** py3plex 2.0 extends the original toolkit from visualization-oriented analysis into a reproducible, query-driven multilayer network science environment. |
+| **pymnet** | Python | General multilayer network representation, metrics, random models, and visualization | Strong overlap on formal multilayer data structures, multilayer metrics, transformations, random models, and visualization | **Closest Python multilayer comparator.** pymnet is strongest as a formal multilayer framework; py3plex 2.0 is strongest as a workflow, DSL, uncertainty, and reproducibility layer. |
+| **MultiNetX** | Python / NetworkX | NetworkX-style multilayer graph manipulation, spectral analysis, and visualization | Overlap on Python-native multilayer graph objects, supra-adjacency/Laplacian workflows, and visualization | **Lightweight Python comparator.** MultiNetX provides compact multilayer graph utilities; py3plex 2.0 provides a broader end-to-end analysis and workflow environment. |
+| **muxViz** | R / desktop ecosystem | Multilayer and multiplex visual analytics | Overlap on multilayer visualization, centrality, community detection, motifs, structural reducibility, and dynamic visualization | **R visual-analytics comparator.** muxViz is strongest for visual exploration; py3plex 2.0 emphasizes Python-native, scriptable, DSL-driven, reproducible analysis. |
+| **R `multinet`** | R | Multiplex and multilayer social-network analysis and mining | Overlap on multilayer representation, import/export, attributes, centrality, community detection, generation, and plotting | **R social-network comparator.** `multinet` is strongest for multiplex social-network analysis; py3plex 2.0 targets broader heterogeneous scientific multilayer workflows in Python. |
+| **tnetwork** | Python | Temporal-network manipulation and dynamic communities | Overlap on temporal slicing, dynamic graphs, and evolving-community analysis | **Temporal-community comparator.** tnetwork focuses on temporal community workflows; py3plex 2.0 embeds temporal analysis inside a broader multilayer DSL/workflow stack. |
+| **DyNetx** | Python / NetworkX | Dynamic graph extension for NetworkX | Overlap on time-varying graph representation, snapshots, interaction streams, and temporal slicing | **Dynamic-NetworkX comparator.** DyNetx handles dynamic graphs; py3plex 2.0 adds multilayer semantics, declarative analysis, integrated dynamics, and reusable workflows. |
+| **Reticula** | Python with C++ core | Fast static and temporal network / hypergraph analysis | Overlap on temporal networks, reachability, randomized models, and dynamical-process analysis | **Performance temporal/hypergraph comparator.** Reticula is stronger for fast temporal and hypergraph analysis; py3plex 2.0 is stronger for multilayer workflow integration and analyst ergonomics. |
+| **Raphtory** | Rust / Python | Temporal graph engine and deployment platform | Overlap on temporal graph views, time-aware querying, reachability, motifs, and deployment-oriented graph analysis | **Modern temporal-engine comparator.** Raphtory is an engine/platform; py3plex 2.0 is a multilayer network-science workflow layer with DSL, uncertainty, dynamics, and reproducible analysis. |
+| **pathpy / pathpyG** | Python / PyTorch ecosystem | Path-centric temporal-network analytics and graph learning | Overlap on temporal analytics, time-respecting paths, temporal centralities, visualization, and graph-learning handoff | **Temporal graph-learning comparator.** pathpy/pathpyG is adjacent; py3plex 2.0 focuses on multilayer network science, layer-aware querying, uncertainty, and reproducible workflows. |
+| **NetworkX** | Python | General graph creation, manipulation, and algorithms | Overlap on core graph algorithms, graph data structures, centrality, communities, and Python graph workflows | **General graph substrate.** NetworkX is the base graph ecosystem; py3plex 2.0 adds multilayer semantics, DSL queries, layer algebra, temporal/dynamics workflows, and structured outputs. |
+| **igraph** | C / R / Python | Efficient general-purpose network analysis | Overlap on centrality, community detection, graph transformations, and scalable graph analysis | **Efficient general-graph comparator.** igraph is the speed/breadth baseline; py3plex 2.0 differentiates through multilayer-specific workflows and reproducible analyst interfaces. |
+| **graph-tool** | Python with C++ core | High-performance graph algorithms and statistical network modeling | Overlap on large-network statistics, community detection, inference, and performance-sensitive graph analysis | **Performance/statistical comparator.** graph-tool is strongest for efficient statistical graph analysis; py3plex 2.0 prioritizes multilayer expressiveness, querying, uncertainty, and workflow integration. |
+| **tidygraph** | R / tidyverse | Tidy, dplyr-style graph manipulation | Overlap on chainable, analyst-friendly node/edge manipulation and graph-as-table workflows | **Analyst-grammar comparator.** tidygraph motivates fluent graph manipulation; py3plex 2.0 adapts this style to Python multilayer networks with DSL, builder APIs, and layer-aware grouping. |
+| **NDlib** | Python | Diffusion and epidemic processes on networks | Overlap on SIS/SIR-style processes, random walks, spreading dynamics, and simulation workflows | **Dynamics comparator.** NDlib specializes in diffusion; py3plex 2.0 embeds dynamics inside multilayer, temporal, queryable, uncertainty-aware workflows. |
+| **PyTorch Geometric** | Python / PyTorch | Graph neural networks and geometric deep learning | Overlap on graph embeddings, graph data preparation, and downstream graph-learning workflows | **Graph-ML comparator.** PyG trains graph neural models; py3plex 2.0 prepares, queries, explains, summarizes, and analyzes multilayer networks. |
+| **DGL** | Python / deep-learning frameworks | Scalable graph deep learning and message passing | Overlap on heterogeneous graph processing, graph learning, and scalable graph ML pipelines | **Scalable graph-ML comparator.** DGL addresses GNN systems engineering; py3plex 2.0 addresses multilayer network science, query abstractions, uncertainty, temporal analysis, and workflows. |
+| **Neo4j / Cypher** | Database systems | Persistent property-graph storage and declarative graph querying | Overlap on declarative graph querying and pattern-style graph access | **Graph-query comparator.** Cypher queries persistent property graphs; py3plex 2.0 provides an in-memory scientific DSL for multilayer network analysis, metrics, uncertainty, and exports. |
+| **py3plex 2.0** | Python | Query-driven, reproducible multilayer network analysis | Integrates capabilities otherwise spread across multilayer libraries, temporal engines, graph libraries, graph-ML frameworks, graph-query systems, and workflow tools | **Current version** py3plex 2.0 is best framed as a Python-native workflow layer for multilayer network science: DSL + builder API, layer algebra, QueryResult exports, uncertainty-first statistics, temporal/dynamics workflows, null models, CLI/config execution, and agent-facing interfaces. |
+
 ![Py3plex Visualization Showcase](example_images/py3plex_showcase.png)
 
 ## Getting Started
@@ -137,8 +169,39 @@ pip install py3plex[viz]
 
 # All optional features
 pip install py3plex[mcp,algos,viz]
+
+# Common optional feature bundle (algorithms + visualization + workflows + arrow + mcp)
+pip install py3plex[optional]
 ```
 
+### Contributing (First PR Quick Path)
+
+If this is your first contribution, use this sequence:
+
+```bash
+# 1) Create local dev environment and install package
+make setup
+make dev-install
+
+# 2) Run formatting and checks before opening a PR
+make format
+make lint
+make test
+```
+
+Helpful commands:
+
+```bash
+make help   # List all project commands
+make ci     # Run lint + tests in CI-style order
+```
+
+Safety notes for contributors:
+- Keep changes focused and add tests next to the feature you modify.
+- Do not add new markdown files unless explicitly requested (enforced by `tests/test_link_checker.py` to prevent documentation drift).
+- Prefer running targeted tests first, then broader checks before opening a PR.
+- For docs-only updates, run `make docs-check` before opening a PR.
+
 ### MCP Integration (AI Agents)
 
 py3plex provides a Model Context Protocol (MCP) server for integration with AI coding assistants:

{py3plex-1.1.5 → py3plex-2.0.0}/py3plex/__init__.py

@@ -51,8 +51,8 @@ For detailed documentation, see: https://skblaz.github.io/py3plex/
 """
 
 # Version information
-__version__ = "1.1.5"
-__api_version__ = "1.1.5"
+__version__ = "2.0.0"
+__api_version__ = "2.0.0"
 
 from py3plex.core.multinet import multi_layer_network
 from py3plex.core.types import (
@@ -123,6 +123,7 @@ from py3plex.profiling import (
     profile_performance,
     timed_section,
 )
+import py3plex.config as config
 
 # Plugin system - import for easy access
 from py3plex.plugins import (
@@ -163,7 +164,6 @@ from py3plex.datasets import (
     make_random_multiplex,
     make_social_network,
 )
-
 # Dynamics module for simulating dynamical processes
 from py3plex.dynamics import (
     D,
@@ -198,6 +198,44 @@ from py3plex.uncertainty import (
     uncertainty_enabled,
     estimate_uncertainty,
 )
+from py3plex.agent import (
+    load_network_from_path,
+    top_hubs_by_layer,
+    uncertainty_centrality,
+    community_detection_with_uq,
+    temporal_slice,
+    reproducible_export_bundle,
+    compare_networks,
+    summarize_result,
+)
+
+
+def save_to_arrow(network, path, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.save_to_arrow`."""
+    from py3plex.io import save_to_arrow as _save_to_arrow
+
+    return _save_to_arrow(network, path, **kwargs)
+
+
+def load_from_arrow(path, as_multinet=True, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.load_from_arrow`."""
+    from py3plex.io import load_from_arrow as _load_from_arrow
+
+    return _load_from_arrow(path, as_multinet=as_multinet, **kwargs)
+
+
+def save_network_to_parquet(network, path, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.save_network_to_parquet`."""
+    from py3plex.io import save_network_to_parquet as _save_network_to_parquet
+
+    return _save_network_to_parquet(network, path, **kwargs)
+
+
+def load_network_from_parquet(path, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.load_network_from_parquet`."""
+    from py3plex.io import load_network_from_parquet as _load_network_from_parquet
+
+    return _load_network_from_parquet(path, **kwargs)
 
 __all__ = [
     # Version info
@@ -299,6 +337,13 @@ __all__ = [
     "make_social_network",
     "list_datasets",
     "get_data_dir",
+    # Config module
+    "config",
+    # I/O convenience functions
+    "save_to_arrow",
+    "load_from_arrow",
+    "save_network_to_parquet",
+    "load_network_from_parquet",
     # Dynamics (simulation)
     "D",
     "SimulationBuilder",
@@ -326,4 +371,13 @@ __all__ = [
     "capabilities",
     "capabilities_flat",
     "capabilities_fingerprint",
+    # Agent-facing stable API
+    "load_network_from_path",
+    "top_hubs_by_layer",
+    "uncertainty_centrality",
+    "community_detection_with_uq",
+    "temporal_slice",
+    "reproducible_export_bundle",
+    "compare_networks",
+    "summarize_result",
 ]

py3plex-2.0.0/py3plex/agent.py

@@ -0,0 +1,216 @@
+"""Stable machine-facing agent API for py3plex workflows."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from py3plex.core import multinet
+from py3plex.dsl.builder import L, Q
+from py3plex.dsl.result import QueryResult
+
+
+def _extract_replay_payload(result: QueryResult) -> Dict[str, Any]:
+    prov = result.provenance or {}
+    query_info = prov.get("query", {}) if isinstance(prov, dict) else {}
+    return {
+        "is_replayable": result.is_replayable,
+        "seed": (prov.get("randomness", {}) or {}).get("seed")
+        if isinstance(prov, dict)
+        else None,
+        "ast_hash": query_info.get("ast_hash"),
+        "network_fingerprint": prov.get("network_fingerprint") if isinstance(prov, dict) else None,
+        "network_version": prov.get("network_version") if isinstance(prov, dict) else None,
+    }
+
+
+def _as_agent_response(
+    *,
+    result: QueryResult,
+    assumptions: Optional[List[str]] = None,
+    warnings: Optional[List[Dict[str, Any]]] = None,
+    export_paths: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    return {
+        "status": "ok",
+        "assumptions": assumptions or [],
+        "warnings": warnings if warnings is not None else result.meta.get("warnings", []),
+        "result": result.canonical_export_dict(),
+        "provenance": result.meta.get("provenance", {}),
+        "replay": _extract_replay_payload(result),
+        "export_paths": export_paths or [],
+    }
+
+
+def load_network_from_path(
+    path: str, *, input_type: str = "edgelist", directed: bool = False
+) -> Dict[str, Any]:
+    """Load a network from path and return stable machine-facing payload."""
+    net = multinet.multi_layer_network(directed=directed)
+    net.load_network(path, input_type=input_type)
+    layers = list(net.get_layers())
+    return {
+        "status": "ok",
+        "assumptions": ["Network path is trusted and readable."],
+        "warnings": [],
+        "result": {
+            "network": net,
+            "network_stats": {
+                "node_replicas": len(list(net.get_nodes())),
+                "edges": len(list(net.get_edges())),
+                "layers": layers,
+                "layer_count": len(layers),
+            },
+        },
+        "provenance": {"source_path": path, "input_type": input_type, "directed": directed},
+        "replay": {},
+        "export_paths": [],
+    }
+
+
+def top_hubs_by_layer(
+    network: Any,
+    *,
+    top_k: int = 10,
+    measure: str = "degree",
+    seed: Optional[int] = 42,
+) -> Dict[str, Any]:
+    """Compute per-layer hubs with reproducible defaults."""
+    query = (
+        Q.nodes()
+        .from_layers(L["*"])
+        .compute(measure, kind="aggregate")
+        .per_layer()
+        .top_k(top_k, measure)
+        .provenance(mode="replayable", seed=seed)
+    )
+    result = query.execute(network)
+    return _as_agent_response(
+        result=result,
+        assumptions=[
+            "Top-k is applied independently per layer.",
+            "Degree kind defaults to aggregate unless explicitly overridden.",
+        ],
+    )
+
+
+def uncertainty_centrality(
+    network: Any,
+    *,
+    measures: Optional[List[str]] = None,
+    method: str = "bootstrap",
+    n_samples: int = 50,
+    ci: float = 0.95,
+    seed: Optional[int] = 42,
+) -> Dict[str, Any]:
+    """Compute uncertainty-aware centrality with structured output."""
+    measures = measures or ["pagerank"]
+    query = (
+        Q.nodes()
+        .compute(*measures)
+        .uq(method=method, n_samples=n_samples, ci=ci, seed=seed)
+        .provenance(mode="replayable", seed=seed)
+    )
+    result = query.execute(network)
+    return _as_agent_response(
+        result=result,
+        assumptions=["Uncertainty summaries use canonical mean/std/CI schema."],
+    )
+
+
+def community_detection_with_uq(
+    network: Any,
+    *,
+    method: str = "leiden",
+    n_samples: int = 20,
+    seed: Optional[int] = 42,
+) -> Dict[str, Any]:
+    """Run reproducible community detection with UQ."""
+    query = (
+        Q.nodes()
+        .community(method=method, random_state=seed)
+        .uq(method="seed", n_samples=n_samples, seed=seed)
+        .provenance(mode="replayable", seed=seed)
+    )
+    result = query.execute(network)
+    return _as_agent_response(
+        result=result,
+        assumptions=["Community uncertainty is estimated via seed ensemble."],
+    )
+
+
+def temporal_slice(
+    network: Any,
+    *,
+    t_start: Optional[float] = None,
+    t_end: Optional[float] = None,
+    at: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Run temporal slice query with structured result contract."""
+    query = Q.edges()
+    assumptions = []
+    if at is not None:
+        query = query.at(float(at))
+        assumptions.append("Temporal query uses point-in-time snapshot semantics.")
+    else:
+        if t_start is None or t_end is None:
+            raise ValueError("Provide either 'at' or both 't_start' and 't_end'.")
+        query = query.during(float(t_start), float(t_end))
+        assumptions.append("Temporal query uses inclusive time window semantics.")
+    result = query.execute(network)
+    return _as_agent_response(result=result, assumptions=assumptions)
+
+
+def reproducible_export_bundle(
+    result: QueryResult, *, path: str, compress: bool = True
+) -> Dict[str, Any]:
+    """Export replay bundle and return stable path metadata."""
+    out_path = str(Path(path))
+    result.export_bundle(out_path, compress=compress)
+    return _as_agent_response(
+        result=result,
+        assumptions=["Bundle includes provenance metadata for replay."],
+        export_paths=[out_path],
+    )
+
+
+def compare_networks(
+    network_a: Any,
+    network_b: Any,
+    *,
+    measure: str = "degree",
+) -> Dict[str, Any]:
+    """Compare two networks via shared machine-facing summary metric."""
+    res_a = Q.nodes().compute(measure).execute(network_a)
+    res_b = Q.nodes().compute(measure).execute(network_b)
+    vals_a = res_a.attributes.get(measure, {})
+    vals_b = res_b.attributes.get(measure, {})
+    mean_a = sum(vals_a.values()) / len(vals_a) if vals_a else 0.0
+    mean_b = sum(vals_b.values()) / len(vals_b) if vals_b else 0.0
+    return {
+        "status": "ok",
+        "assumptions": ["Comparison uses simple mean of selected metric over node replicas."],
+        "warnings": [],
+        "result": {
+            "metric": measure,
+            "mean_a": mean_a,
+            "mean_b": mean_b,
+            "delta": mean_b - mean_a,
+            "count_a": len(vals_a),
+            "count_b": len(vals_b),
+        },
+        "provenance": {},
+        "replay": {},
+        "export_paths": [],
+    }
+
+
+def summarize_result(result: QueryResult) -> Dict[str, Any]:
+    """Return compact structured summary for a QueryResult."""
+    return {
+        "status": "ok",
+        "assumptions": [],
+        "warnings": result.meta.get("warnings", []),
+        "result": result.summary_dict(),
+        "provenance": result.meta.get("provenance", {}),
+        "replay": _extract_replay_payload(result),
+        "export_paths": [],
+    }

{py3plex-1.1.5 → py3plex-2.0.0}/py3plex/algorithms/community_detection/autocommunity_executor.py

@@ -1221,7 +1221,7 @@ def execute_autocommunity_sh(
         import importlib.metadata
         py3plex_version = importlib.metadata.version('py3plex')
     except Exception:
-        py3plex_version = '1.1.2'  # Fallback for development installs
+        from py3plex import __version__ as py3plex_version
     
     provenance = {
         'engine': 'autocommunity_successive_halving',

{py3plex-1.1.5 → py3plex-2.0.0}/py3plex/algorithms/statistics/powerlaw.py

@@ -1409,8 +1409,6 @@ class Truncated_Power_Law(Distribution):
 
     @property
     def _pdf_discrete_normalizer(self):
-        if 0:
-            return False
         from mpmath import (
             exp,  # faster /here/ than numpy.exp
             lerchphi,
@@ -1429,21 +1427,7 @@ class Truncated_Power_Law(Distribution):
     def pdf(self, data=None):
         if data is None and hasattr(self, 'parent_Fit'):
             data = self.parent_Fit.data
-        if not self.discrete and self.in_range() and False:
-            data = trim_to_range(data, xmin=self.xmin, xmax=self.xmax)
-            from mpmath import gammainc
-            from numpy import exp
-            #                (Lambda**(1-alpha))/\
-            #                float(gammainc(1-alpha,Lambda*xmin))
-            likelihoods = (
-                self.Lambda**(1 - self.alpha) /
-                (data**self.alpha * exp(self.Lambda * data) * gammainc(
-                    1 - self.alpha, self.Lambda * self.xmin)).astype(float))
-            # Simplified so as not to throw a nan from infs being divided by each other
-            from sys import float_info
-            likelihoods[likelihoods == 0] = 10**float_info.min_10_exp
-        else:
-            likelihoods = Distribution.pdf(self, data)
+        likelihoods = Distribution.pdf(self, data)
         return likelihoods
 
     def _generate_random_continuous(self, r):

{py3plex-1.1.5 → py3plex-2.0.0}/py3plex/benchmarks/metrics.py

@@ -125,13 +125,13 @@ def _compute_modularity(
         Modularity score
     """
     from py3plex.algorithms.community_detection.multilayer_modularity import (
-        compute_multilayer_modularity,
+        multilayer_modularity,
     )
 
     try:
         # Try multilayer-aware modularity first
-        if hasattr(network, "get_layers") and layers:
-            return compute_multilayer_modularity(network, partition, layers)
+        if hasattr(network, "layers") and layers:
+            return multilayer_modularity(network, partition)
     except Exception:
         pass