Rewrite AGENTS.md with comprehensive DSL v2 API reference and operational guidance

[Copilot]

The existing AGENTS.md lacked a complete, authoritative DSL v2 reference. Agents had to guess APIs or read source code, leading to hallucinated methods and incorrect usage patterns.

Changes

DSL v2 Complete Reference (1370 lines, 41% of doc)

• Mental model: builder lifecycle (lazy/eager), grouping semantics, compute vs aggregate
• 60+ QueryBuilder methods documented with signatures, return types, semantics, failure modes
• Layer algebra (L), uncertainty (UQ), parameters (Param), field expressions (F) fully specified
• QueryResult API: .to_pandas(), .to_networkx(), .to_arrow(), .group_summary(), .counterexample()

Operational Guidance

• Golden Paths: 5 end-to-end workflow blueprints (CSV analysis, UQ centrality, temporal queries, dynamics, hypothesis testing)
• Decision Guide: When to use DSL v2 vs legacy/dplyr/pipeline/CLI with decision trees
• Performance: Network size recommendations, metric complexity table, optimization strategies
• Reproducibility: Determinism guarantees, provenance tracking, seed requirements

Structure & Deduplication

• 26 focused sections (down from 42)
• Reduced from 5760 to 3318 lines (-42%) through refactoring
• Single canonical names enforced (Q/UQ/L, "DSL v2", "legacy SQL-like DSL")
• All examples runnable or explicitly marked PSEUDOCODE

Example: DSL v2 Grouping Pattern

Before (ambiguous):

# Agent guesses at API
result = Q.nodes().per_layer().top_k(5).coverage("all")  # What does coverage do?

After (documented):

# Fully specified with semantics
result = (
    Q.nodes()
     .per_layer()              # Group by layer
       .top_k(5, "degree")     # Top-5 per group by degree
     .end_grouping()           # Marker for readability
     .coverage(mode="all")     # Keep items in ALL layers (cross-group filter)
     .execute(net)
)

Documentation now specifies:

• .per_layer() → groups by layer (nodes only, raises for edges)
• .top_k(k, key) → keeps top-k per group (not global)
• .coverage(mode="all") → filters to items appearing in all groups
• Requires prior grouping, raises GroupingError otherwise

Verification

• All API references validated against py3plex/dsl/builder.py (4600+ lines)
• Method signatures match implementation
• No hallucinated APIs (PSEUDOCODE marked for planned features only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>md</issue_title>
<issue_description>You are a senior technical writer + library maintainer + “agent ergonomics” designer.

Your task is to rewrite and upgrade the existing documentation file:

AGENTS.md (located at the root of this repository)

Goal
Make this single markdown file fully self-sufficient for an LLM agent to design correct, reproducible, performant py3plex pipelines end-to-end (discover → decide → build → validate → export) without guessing or hallucinating APIs.

This document must function as:

• an operational playbook (not just API docs),
• a decision guide (when to use what),
• a set of known-good pipeline blueprints,
• and a reproducibility + performance policy.

━━━━━━━━━━━━━━━━━━━━
Hard constraints (non-negotiable)
━━━━━━━━━━━━━━━━━━━━

• DO NOT create any new markdown files.
• Edit ONLY AGENTS.md.
• Do NOT invent APIs. If something is uncertain, explicitly label it PSEUDOCODE and explain the closest real alternative already documented.
• Use one canonical name per concept (e.g. “DSL v2 (Q/UQ/L)”, “legacy SQL-like DSL”).
• Keep examples runnable where possible; otherwise clearly label them PSEUDOCODE.
• Keep the Table of Contents accurate and in sync with headings.
• Prefer operational guidance over feature listings.
• Reduce duplication; refactor instead of copy-pasting.

━━━━━━━━━━━━━━━━━━━━
NEW CRITICAL REQUIREMENT — DSL v2 must be fully specified
━━━━━━━━━━━━━━━━━━━━
The updated AGENTS.md MUST include a dedicated, comprehensive section:

DSL v2 (Q / UQ / L) — Complete Reference

It MUST be sufficient for an agent to author DSL v2 pipelines without reading source code.

Rules for this section:

• If a method/operator is mentioned anywhere in AGENTS.md examples (or implied by Cookbook/Golden Paths), it MUST be defined here with:
  • signature (or pseudo-signature if Python typing isn’t available),
  • what it returns (Query builder vs QueryResult),
  • semantics,
  • common usage pattern,
  • failure modes.
• If any method cannot be confirmed from the repo, it MUST be labeled PSEUDOCODE and replaced with the nearest confirmed capability.
• Include a “Minimal mental model” that explains:
  • Query builder lifecycle (build → execute),
  • what is lazy vs eager,
  • how grouping works (per_layer/per_layer_pair/etc),
  • how compute/aggregate differ,</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes md #1013

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.