py3plex 1.1.4__tar.gz → 1.1.7__tar.gz

{py3plex-1.1.4/py3plex.egg-info → py3plex-1.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py3plex
-Version: 1.1.4
+Version: 1.1.7
 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
 
 
@@ -100,10 +109,11 @@ Dynamic: license-file
 [![Formal Verification](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml)
 [![Fuzzing](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml)
 [![PyPI version](https://img.shields.io/pypi/v/py3plex.svg)](https://pypi.org/project/py3plex/)
+[![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-206.0K-blue)
-![Test Count](https://img.shields.io/badge/tests-8.9K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-211.4K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.1K-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.
@@ -163,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
@@ -226,8 +244,38 @@ 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.
+
 ### MCP Integration (AI Agents)
 
 py3plex provides a Model Context Protocol (MCP) server for integration with AI coding assistants:

{py3plex-1.1.4 → py3plex-1.1.7}/README.md

@@ -10,10 +10,11 @@
 [![Formal Verification](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml)
 [![Fuzzing](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml)
 [![PyPI version](https://img.shields.io/pypi/v/py3plex.svg)](https://pypi.org/project/py3plex/)
+[![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-206.0K-blue)
-![Test Count](https://img.shields.io/badge/tests-8.9K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-211.4K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.1K-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.
@@ -73,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
@@ -136,8 +145,38 @@ 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.
+
 ### MCP Integration (AI Agents)
 
 py3plex provides a Model Context Protocol (MCP) server for integration with AI coding assistants:

{py3plex-1.1.4 → py3plex-1.1.7}/py3plex/__init__.py

@@ -51,8 +51,8 @@ For detailed documentation, see: https://skblaz.github.io/py3plex/
 """
 
 # Version information
-__version__ = "1.1.4"
-__api_version__ = "1.1.4"
+__version__ = "1.1.7"
+__api_version__ = "1.1.7"
 
 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 (
@@ -146,6 +147,7 @@ from py3plex.pipeline import (
     ComputeStats,
     FilterNodes,
     SaveNetwork,
+    NodeEmbedding,
 )
 
 # Config-driven workflows
@@ -162,7 +164,6 @@ from py3plex.datasets import (
     make_random_multiplex,
     make_social_network,
 )
-
 # Dynamics module for simulating dynamical processes
 from py3plex.dynamics import (
     D,
@@ -197,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
@@ -284,6 +323,7 @@ __all__ = [
     "ComputeStats",
     "FilterNodes",
     "SaveNetwork",
+    "NodeEmbedding",
     # Workflows
     "WorkflowConfig",
     "WorkflowRunner",
@@ -297,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",
@@ -324,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-1.1.7/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.4 → py3plex-1.1.7}/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.4 → py3plex-1.1.7}/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