This section details on the original issue you should resolve

<issue_title>.auto</issue_title>
<issue_description>

Goal

Add two new DSLv2 entrypoints:

1. Q.communities().auto(...)

2. Q.nodes().community_auto(...)

They must behave as described in AGENTS.md (mounted at /mnt/data/AGENTS (7).md) and align with existing DSLv2 Builder → AST → Executor → QueryResult design.

Target user-facing examples (must work)

from py3plex.dsl import Q
from py3plex.core import datasets

net = datasets.fetch_multilayer("human_ppi_gene_disease_drug")

communities table

res = (
Q.communities()
.auto(seed=42, fast=True)
.confidence__gt(0.90)
.execute(net)
)

nodes joined with community stats

res2 = (
Q.nodes()
.community_auto(seed=42, fast=True)
.where(community_size__gt=10)
.compute("pagerank")
.execute(net)
)

Hard requirements

A. Single-run + caching semantics

AutoCommunity must run at most once per .execute() call, even if downstream steps filter/compute multiple times.

Implement as a lazy AST node that resolves during execution.

Cache the computed community assignment table + node annotations in the execution context, keyed by a stable signature (network id + seed + params).

B. Output schema

AutoCommunity produces an assignment table with columns (at minimum):

node

layer (nullable/optional if single-layer)

community

confidence

entropy

margin and derived:

community_size

These names must be filterable with existing DSL predicate machinery:

confidence__gt, entropy__lt, etc.

where(community_size__gt=10) on Q.nodes().community_auto()

C. Integration points

Q.communities().auto(...) returns a QueryResult/table where each row is an assignment record.

Q.nodes().community_auto(...) returns nodes QueryResult augmented with the above annotation fields, enabling .where(...) and .compute(...) like normal.

D. Backward compatibility

Do not break existing Q.communities().auto_select(...) (if present). Keep it working.

auto() is the “planned” ergonomic alias for the new AutoCommunity (v2) behavior.

If only old auto_select_community() exists internally, you may adapt it, but preserve old public APIs.

E. Minimal but strong tests

Add deterministic unit tests that:

1. Smoke test: .auto() returns required columns.

2. Filtering: .confidence__gt(0.9) reduces row count and retains schema.

3. Join: .community_auto() attaches community_size and filtering works.

4. No rerun: prove only one AutoCommunity run per .execute() via spy/mock counter or instrumentation.

5. Multilayer: if your test fixtures include multilayer, ensure layer is present; otherwise allow layer=None and assert column exists.

All tests must pass in CI.

Implementation steps (follow in order)

1. Locate DSLv2 builder/AST/executor files

Search for:

class Q or Q = ...

communities() and nodes() builders

any existing auto_select, auto_select_community, AutoCommunity, autocommunity

predicate machinery implementing field__gt etc.

execution context object used in .execute(network)

Document (in code comments only) where you wired the new nodes and caching.

1. Add new builder methods

CommunitiesBuilder.auto(self, **kwargs)

Accept at least: seed=None, fast=True, plus **kwargs passthrough.

Store params in AST node.

NodesBuilder.community_auto(self, **kwargs)

Same params.

The AST node must specify “join annotations to nodes view”.

Ensure these methods compose with existing chain methods:

.where(...), .compute(...), .top_k(...), etc. must continue to work.

1. Add AST nodes

Create new AST node types (or reuse existing with a new opcode) such as:

AutoCommunityOp(kind="communities")

AutoCommunityOp(kind="nodes_join")

Fields:

params dict (seed/fast/others)

kind enum

optional signature computed at execution time

1. Wire executor

4.1 Implement _run_autocommunity_once(ctx, network, params) -> assignments_df, meta

Compute stable cache key: include network identity (pointer/id or hash if you have one), params, and DSL pipeline seed.

Check ctx.cache["autocommunity"][key].

If absent: run algorithm, store.

4.2 Select algorithm

Prefer the newer AutoCommunity meta-algorithm if present. If not present, wrap existing auto_select_community / auto_select outputs into:

partition_vector for each layer if multilayer

derive confidence/entropy/margin via existing UQ (if present) OR fallback deterministic proxy:

If UQ unavailable, set confidence=1.0, entropy=0.0, margin=1.0 but still expose columns (and document in code comment as fallback). Do not silently omit columns.

4.3 Build assignment table

Produce a pandas DataFrame with required columns. Compute community_size per (layer, community) group.

4.4 Apply to Q.communities().auto()

Return QueryResult in the same format as other table-like community DSL outputs.

4.5 Apply to Q.nodes().community_auto()

Join the assignment-derived annotations back onto nodes view. For multilayer:

If node view is per-layer, join on (node, ...