gephi-ai 1.18.0__tar.gz

gephi_ai-1.18.0/.gitignore

@@ -0,0 +1,27 @@
+gephi-ai-plugin/target/
+
+# Personal Claude Code config (machine-specific hooks, not for other contributors)
+.claude/settings.local.json
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+mcp-server/dist/
+
+# MCPB build artifacts
+mcpb/server/lib/
+*.mcpb
+
+# Local drafts and internal notes — never publish (LinkedIn posts, papers, scratch)
+docs/
+*-draft.md
+*-draft.*
+
+# Probe verdicts are per-install and must never ship or be committed
+mcp-server/caveats.local.json
+.artifact-verified

gephi_ai-1.18.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: gephi-ai
+Version: 1.18.0
+Summary: MCP Server for controlling Gephi Desktop via remote API
+Project-URL: Homepage, https://www.mattartz.me
+Project-URL: Repository, https://github.com/MattArtzAnthro/gephi-ai
+Author: Matt Artz
+License: Apache-2.0
+Keywords: claude,gephi,graph,mcp,network,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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 :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp<3,>=2.1
+Requires-Dist: nltk>=3.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gephi-ai
+
+MCP server that bridges any [Model Context Protocol](https://modelcontextprotocol.io) client
+to a running [Gephi Desktop](https://gephi.org) instance, exposing **113 tools** for graph
+construction, statistics, community detection, layout, styling, filtering, and
+publication-ready export.
+
+It translates MCP tool calls into HTTP requests against the Gephi AI plugin's local API
+(`http://127.0.0.1:8080`). Each tool has a typed signature, so clients receive a precise
+per-field JSON schema rather than an opaque blob.
+
+This is the **MCP server** component of [gephi-ai](https://github.com/MattArtzAnthro/gephi-ai);
+see the top-level repository for the Gephi plugin, the Claude Code plugin, and full docs.
+
+## Install
+
+No install needed with [uv](https://docs.astral.sh/uv/) — point your MCP client at:
+
+```bash
+uvx gephi-ai
+```
+
+`uvx` fetches [`gephi-ai` from PyPI](https://pypi.org/project/gephi-ai/) on first run
+and caches it. For a persistent `gephi-ai` command on your `PATH` instead, use
+`pipx install gephi-ai` (or `pipx install .` from this directory). Avoid plain
+`pip install -e .` inside a virtual environment: the command is then only visible on
+that venv's `PATH`, and MCP clients launched outside your shell won't find it.
+
+## Use
+
+The Gephi AI plugin must be installed and Gephi Desktop running first. Then point any MCP
+client at the `gephi-ai` command, e.g. for Claude Desktop:
+
+```json
+{ "mcpServers": { "gephi-mcp": { "command": "uvx", "args": ["gephi-ai"] } } }
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `GEPHI_API_URL` | `http://127.0.0.1:8080` | Gephi plugin HTTP API base URL |
+| `GEPHI_REQUEST_TIMEOUT` | `60.0` | Per-request timeout (seconds) |
+
+## Development
+
+```bash
+pip install -e . pytest pytest-asyncio ruff
+ruff check .
+pytest -q
+```
+
+## License
+
+Apache-2.0 — see the [repository LICENSE](https://github.com/MattArtzAnthro/gephi-ai/blob/main/LICENSE).

gephi_ai-1.18.0/README.md

@@ -0,0 +1,55 @@
+# gephi-ai
+
+MCP server that bridges any [Model Context Protocol](https://modelcontextprotocol.io) client
+to a running [Gephi Desktop](https://gephi.org) instance, exposing **113 tools** for graph
+construction, statistics, community detection, layout, styling, filtering, and
+publication-ready export.
+
+It translates MCP tool calls into HTTP requests against the Gephi AI plugin's local API
+(`http://127.0.0.1:8080`). Each tool has a typed signature, so clients receive a precise
+per-field JSON schema rather than an opaque blob.
+
+This is the **MCP server** component of [gephi-ai](https://github.com/MattArtzAnthro/gephi-ai);
+see the top-level repository for the Gephi plugin, the Claude Code plugin, and full docs.
+
+## Install
+
+No install needed with [uv](https://docs.astral.sh/uv/) — point your MCP client at:
+
+```bash
+uvx gephi-ai
+```
+
+`uvx` fetches [`gephi-ai` from PyPI](https://pypi.org/project/gephi-ai/) on first run
+and caches it. For a persistent `gephi-ai` command on your `PATH` instead, use
+`pipx install gephi-ai` (or `pipx install .` from this directory). Avoid plain
+`pip install -e .` inside a virtual environment: the command is then only visible on
+that venv's `PATH`, and MCP clients launched outside your shell won't find it.
+
+## Use
+
+The Gephi AI plugin must be installed and Gephi Desktop running first. Then point any MCP
+client at the `gephi-ai` command, e.g. for Claude Desktop:
+
+```json
+{ "mcpServers": { "gephi-mcp": { "command": "uvx", "args": ["gephi-ai"] } } }
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `GEPHI_API_URL` | `http://127.0.0.1:8080` | Gephi plugin HTTP API base URL |
+| `GEPHI_REQUEST_TIMEOUT` | `60.0` | Per-request timeout (seconds) |
+
+## Development
+
+```bash
+pip install -e . pytest pytest-asyncio ruff
+ruff check .
+pytest -q
+```
+
+## License
+
+Apache-2.0 — see the [repository LICENSE](https://github.com/MattArtzAnthro/gephi-ai/blob/main/LICENSE).

gephi_ai-1.18.0/bipartite.py

@@ -0,0 +1,116 @@
+"""Two-mode networks: people by events, authors by concepts, informants by sites.
+
+Gephi draws a two-mode network as though every node were the same kind of thing, which
+misrepresents the data at a glance and has no fix in the application: gephi/gephi#3131 asked for a
+bipartite layout and notes the only plugin offering one was removed from the current release, and
+gephi-plugins#130 asked for multimode support in 2016. Projection, the operation that collapses a
+two-mode network into a one-mode one, does not exist in Gephi at all.
+
+Both are computed here in Python. The layout is pushed as coordinates and the projection as a new
+graph, so neither needs a Gephi layout plugin or any change to the Java side.
+
+Gephi has no concept of a node's mode, so the mode is whatever column the researcher names. That
+is a convention rather than a property of the data, which is why a column carrying more than two
+values is refused rather than guessed at.
+"""
+
+from __future__ import annotations
+
+from itertools import combinations
+from typing import Any
+
+Graph = dict[str, Any]
+
+
+def _value(attributes: dict[str, Any], column: str) -> Any:
+    wanted = column.replace("_", "").replace(" ", "").lower()
+    for key, value in (attributes or {}).items():
+        if key.replace("_", "").replace(" ", "").lower() == wanted:
+            return value
+    return None
+
+
+def split_modes(graph: Graph, column: str) -> tuple[list[str], list[str]]:
+    """The two groups of nodes named by `column`, in the order the values first appear."""
+    seen: dict[Any, list[str]] = {}
+    for node in graph.get("nodes", []):
+        value = _value(node.get("attributes"), column)
+        if value is None:
+            continue
+        seen.setdefault(value, []).append(node["key"])
+    if not seen:
+        raise ValueError(
+            f"No node carries a value in {column!r}, so the two modes cannot be told apart.")
+    if len(seen) != 2:
+        raise ValueError(
+            f"{column!r} holds {len(seen)} distinct values ({sorted(map(str, seen))}). A bipartite "
+            "graph has exactly two modes; name a column that separates them.")
+    left, right = seen.values()
+    return left, right
+
+
+def project_bipartite(graph: Graph, column: str, keep: str) -> dict[str, Any]:
+    """Collapse a two-mode network onto one mode, joining nodes that share a partner.
+
+    Two people who attended the same event become connected, weighted by how many events they
+    shared. Nodes sharing nothing are kept with no edges: dropping them would silently delete
+    people from the network, which is a different graph rather than a tidier one.
+    """
+    left, right = split_modes(graph, column)
+    modes = {}
+    for node in graph.get("nodes", []):
+        modes[node["key"]] = _value(node.get("attributes"), column)
+
+    kept = [k for k in (left + right) if str(modes.get(k)) == str(keep)]
+    if not kept:
+        raise ValueError(
+            f"No node has {column}={keep!r}. Present values: "
+            f"{sorted({str(v) for v in modes.values() if v is not None})}.")
+
+    partners: dict[str, set[str]] = {k: set() for k in kept}
+    within = 0
+    for edge in graph.get("edges", []):
+        s, t = edge["source"], edge["target"]
+        if modes.get(s) == modes.get(t):
+            within += 1
+            continue
+        for node, other in ((s, t), (t, s)):
+            if node in partners:
+                partners[node].add(other)
+
+    edges = []
+    for a, b in combinations(sorted(kept), 2):
+        shared = len(partners[a] & partners[b])
+        if shared:
+            edges.append({"source": a, "target": b, "weight": shared})
+
+    result: dict[str, Any] = {
+        "nodes": sorted(kept),
+        "edges": edges,
+        "kept_mode": keep,
+        "within_mode_edges": within,
+    }
+    if within:
+        result["warning"] = (
+            f"{within} edge(s) join two nodes of the same mode, so this graph is not bipartite. "
+            "Those edges were ignored in the projection; check the mode column before relying on "
+            "the result.")
+    return result
+
+
+def bipartite_positions(graph: Graph, column: str, *,
+                        separation: float = 600.0, spacing: float = 60.0) -> list[dict[str, Any]]:
+    """Coordinates placing each mode in its own column, which is what makes the shape legible.
+
+    Returned in the shape gephi_batch_set_positions accepts, so the layout is pushed rather than
+    implemented as a Gephi layout plugin.
+    """
+    left, right = split_modes(graph, column)
+    positions = []
+    for index, members in enumerate((left, right)):
+        x = -separation / 2 if index == 0 else separation / 2
+        span = (len(members) - 1) * spacing
+        for row, key in enumerate(members):
+            positions.append({"id": key, "x": float(x),
+                              "y": float(row * spacing - span / 2)})
+    return positions

gephi_ai-1.18.0/caveats.json

@@ -0,0 +1,189 @@
+{
+  "schema": 1,
+  "note": "Known defects in Gephi's own statistics, surfaced alongside the numbers they affect. An entry is only asserted as live once a probe has reproduced it against a running Gephi; until then its status is 'unverified' and its text says so. Run the probe suite (tests/probes/) to update the verification blocks.",
+  "caveats": [
+    {
+      "id": "gephi-2034",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/2034"
+      ],
+      "metrics": [
+        "modularity"
+      ],
+      "applies_when": {
+        "param_not_default": {
+          "name": "resolution",
+          "default": 1.0
+        }
+      },
+      "severity": "reporting",
+      "says": "Gephi applies the modularity resolution parameter as the RECIPROCAL of the convention used in Blondel et al., the paper its own dialogue cites. A resolution reported from Gephi does not mean what a reader of that literature will take it to mean, and higher values here yield FEWER communities rather than more. The issue has been open since 2018 and concludes it cannot be changed without invalidating every value users have already recorded, so treat this as permanent. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2018-10-03",
+      "verification": {
+        "status": "unverified",
+        "probe": "probe_gephi_2034"
+      }
+    },
+    {
+      "id": "gephi-1872",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/1872"
+      ],
+      "metrics": [
+        "closeness",
+        "harmonic_closeness",
+        "avg_path_length"
+      ],
+      "applies_when": {
+        "always": true
+      },
+      "severity": "reporting",
+      "says": "Closeness centrality is normalised whether or not the normalisation checkbox was ticked, while betweenness respects the setting. Two measures from the same dialogue therefore behave differently, and a closeness value cannot be assumed to be on the scale you asked for. This one cannot be checked automatically from here, so it is reported as filed rather than confirmed.",
+      "reported_open_since": "2017-12-09",
+      "verification": {
+        "status": "not_probeable",
+        "why": "Cannot be probed through this API: confirming it needs the normalisation toggle off, and the statistics endpoint exposes no such parameter."
+      }
+    },
+    {
+      "id": "gephi-2191",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/2191"
+      ],
+      "metrics": [
+        "pagerank"
+      ],
+      "applies_when": {
+        "undirected": true
+      },
+      "severity": "wrong",
+      "says": "PageRank is reported to be computed incorrectly for undirected graphs, and this graph is undirected. Treat the values as unreliable for ranking until checked against an independent implementation. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2020-05-20",
+      "verification": {
+        "status": "unverified",
+        "why": "Deciding this needs an independent implementation of the measure to compare against, and a mismatch of conventions between the two would look identical to a fix. No probe is written rather than one that could give a false all-clear."
+      }
+    },
+    {
+      "id": "gephi-557",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/557",
+        "https://github.com/gephi/gephi/issues/1817"
+      ],
+      "metrics": [
+        "betweenness",
+        "closeness",
+        "harmonic_closeness",
+        "eigenvector"
+      ],
+      "applies_when": {
+        "weights_vary": true
+      },
+      "severity": "wrong",
+      "says": "This graph carries edge weights that vary, but Gephi's centrality measures are reported not to use them, so the result describes an unweighted version of your network. If the weights carry meaning, this number is not measuring what you think it measures. Open since 2012. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2012-03-14",
+      "verification": {
+        "status": "unverified",
+        "probe": "probe_gephi_557"
+      }
+    },
+    {
+      "id": "gephi-modularity-unstable",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/2002",
+        "https://github.com/gephi/gephi/issues/2735",
+        "https://github.com/gephi/gephi/issues/2888"
+      ],
+      "metrics": [
+        "modularity"
+      ],
+      "applies_when": {
+        "always": true
+      },
+      "severity": "unstable",
+      "says": "This partition is one draw, not the answer. Gephi's community detection is reported to give different results between runs with randomisation switched off, to change with the order the node and edge tables were imported, and to change after a layout has been run, which should not touch a partition at all. Do not describe these communities as findings until you know they are stable: call gephi_community_stability to run detection repeatedly and report which groups hold up. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2018-08-01",
+      "verification": {
+        "status": "unverified",
+        "probe": "probe_modularity_unstable"
+      }
+    },
+    {
+      "id": "gephi-2951",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/2951"
+      ],
+      "metrics": [
+        "closeness",
+        "harmonic_closeness"
+      ],
+      "applies_when": {
+        "always": true
+      },
+      "severity": "wrong",
+      "says": "Closeness centrality is reported to produce wrong results. The report is untriaged, so the conditions under which it goes wrong are not established. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2024-10-11",
+      "verification": {
+        "status": "unverified",
+        "why": "Deciding this needs an independent implementation of the measure to compare against, and a mismatch of conventions between the two would look identical to a fix. No probe is written rather than one that could give a false all-clear."
+      }
+    },
+    {
+      "id": "gephi-2145",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/2145"
+      ],
+      "metrics": [
+        "eigenvector"
+      ],
+      "applies_when": {
+        "always": true
+      },
+      "severity": "wrong",
+      "says": "Eigenvector centrality is reported not to be calculated properly. The report is untriaged. Check against an independent implementation before ranking on it. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2019-10-10",
+      "verification": {
+        "status": "unverified",
+        "why": "Deciding this needs an independent implementation of the measure to compare against, and a mismatch of conventions between the two would look identical to a fix. No probe is written rather than one that could give a false all-clear."
+      }
+    },
+    {
+      "id": "gephi-858",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/858"
+      ],
+      "metrics": [
+        "clustering_coefficient"
+      ],
+      "applies_when": {
+        "always": true
+      },
+      "severity": "wrong",
+      "says": "The average clustering coefficient is reported to be wrong. Open and untriaged since 2013. Not verified against your Gephi: run the probe suite to confirm it still holds.",
+      "reported_open_since": "2013-11-22",
+      "verification": {
+        "status": "unverified",
+        "probe": "probe_gephi_858"
+      }
+    },
+    {
+      "id": "gephi-1784",
+      "issues": [
+        "https://github.com/gephi/gephi/issues/1784"
+      ],
+      "metrics": [
+        "betweenness"
+      ],
+      "applies_when": {
+        "always": true
+      },
+      "severity": "reporting",
+      "says": "Betweenness centrality from Gephi is reported to differ from NodeXL on the same graph, with no explanation recorded on the issue. If you are comparing figures with work done in another tool, the difference may be the tool rather than the data. This one cannot be checked automatically from here, so it is reported as filed rather than confirmed.",
+      "reported_open_since": "2017-09-16",
+      "verification": {
+        "status": "not_probeable",
+        "why": "Cannot be probed through this API: confirming it needs NodeXL, or another independent implementation, to compare against."
+      }
+    }
+  ]
+}

gephi_ai-1.18.0/community_stability.py

@@ -0,0 +1,120 @@
+"""Consensus analysis over repeated community detection.
+
+Gephi runs community detection once and reports a partition as though it were the answer. It is
+one draw. The same graph run again can give a different partition (gephi#2002), and the result
+changes with the order the tables were imported (gephi#2888) and even after a layout has run
+(gephi#2735), which should not touch a partition at all.
+
+gephi#2968 asked Gephi for exactly this analysis and was closed as not planned, so nothing in this
+ecosystem can currently answer the first question anyone should ask of a community result: are
+these groups real, or are they an artefact of one run?
+
+The measure used here is co-assignment. Across N runs, every pair of nodes has a rate at which the
+two landed in the same community. A rate of 1.0 or 0.0 is decisive; 0.5 is a coin flip. A node's
+stability is the average decisiveness of its relations with every other node, so 1.0 means every
+relation came out the same way every time, and 0.5 means the node's membership is undetermined.
+
+The consensus partition keeps the pairs that agreed more often than not, which leaves a node that
+agrees with nobody standing on its own rather than being forced into a group it only half joined.
+"""
+
+from __future__ import annotations
+
+from itertools import combinations
+from typing import Any
+
+Partition = dict[str, Any]
+
+
+def _canonical(partition: Partition) -> frozenset[frozenset[str]]:
+    """A partition as its set of groups, so arbitrary community labels stop mattering.
+
+    Gephi numbers communities differently between runs. {a,b}|{c,d} is the same partition whether
+    the groups are called 1 and 2 or 7 and 3, and counting relabellings as different outcomes
+    would report instability that is not there.
+    """
+    groups: dict[Any, set[str]] = {}
+    for node, community in partition.items():
+        groups.setdefault(community, set()).add(node)
+    return frozenset(frozenset(g) for g in groups.values())
+
+
+def _co_assignment(runs: list[Partition]) -> tuple[dict[tuple[str, str], float], list[str]]:
+    """For every pair of nodes, the fraction of the runs containing both that grouped them."""
+    nodes = sorted({n for run in runs for n in run})
+    rates: dict[tuple[str, str], float] = {}
+    for a, b in combinations(nodes, 2):
+        shared = [r for r in runs if a in r and b in r]
+        if not shared:
+            continue
+        together = sum(1 for r in shared if r[a] == r[b])
+        rates[(a, b)] = together / len(shared)
+    return rates, nodes
+
+
+def _components(nodes: list[str], edges: set[tuple[str, str]]) -> list[list[str]]:
+    parent = {n: n for n in nodes}
+
+    def find(x: str) -> str:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for a, b in edges:
+        ra, rb = find(a), find(b)
+        if ra != rb:
+            parent[ra] = rb
+
+    groups: dict[str, list[str]] = {}
+    for n in nodes:
+        groups.setdefault(find(n), []).append(n)
+    return [sorted(g) for g in groups.values()]
+
+
+def consensus(runs: list[Partition]) -> dict[str, Any]:
+    """Summarise how reproducible a set of community-detection runs was.
+
+    Returns the number of genuinely distinct partitions seen, a stability score per node, the
+    least stable nodes, and a consensus partition built from the pairs that agreed more often
+    than not.
+
+    A single run returns `mean_stability: None` and a warning rather than a score. One draw
+    carries no information about reproducibility, and reporting 1.0 there would assert exactly
+    the thing the caller asked us to check.
+    """
+    runs = [r for r in (runs or []) if r]
+    if not runs:
+        return {"runs": 0, "distinct_partitions": 0, "node_stability": {},
+                "mean_stability": None, "unstable_nodes": [], "consensus_groups": [],
+                "warning": "No runs were recorded, so nothing can be said about stability."}
+
+    distinct = len({_canonical(r) for r in runs})
+
+    if len(runs) == 1:
+        return {"runs": 1, "distinct_partitions": distinct, "node_stability": {},
+                "mean_stability": None, "unstable_nodes": [],
+                "consensus_groups": [sorted(g) for g in _canonical(runs[0])],
+                "warning": ("Only one run was recorded. One draw says nothing about whether the "
+                            "partition is reproducible; run it several times to find out.")}
+
+    rates, nodes = _co_assignment(runs)
+
+    stability: dict[str, float] = {}
+    for node in nodes:
+        decisiveness = [max(p, 1.0 - p)
+                        for (a, b), p in rates.items() if node in (a, b)]
+        stability[node] = round(sum(decisiveness) / len(decisiveness), 4) if decisiveness else 1.0
+
+    agreed = {pair for pair, p in rates.items() if p > 0.5}
+    groups = _components(nodes, agreed)
+
+    ranked = sorted(stability.items(), key=lambda kv: (kv[1], kv[0]))
+    return {
+        "runs": len(runs),
+        "distinct_partitions": distinct,
+        "node_stability": stability,
+        "mean_stability": round(sum(stability.values()) / len(stability), 4),
+        "unstable_nodes": [{"node": n, "stability": s} for n, s in ranked[:10]],
+        "consensus_groups": sorted(groups, key=lambda g: (-len(g), g[0])),
+    }