Add machine-facing agent API and structured DSL ergonomics for deterministic, low-ambiguity workflows

[Copilot]

This PR makes py3plex materially easier for LLM/agent workflows by adding a thin stable task API and structured pre-execution/query-result surfaces. It targets ambiguity traps (replica vs physical nodes, degree semantics, grouped top-k semantics) while preserving existing DSL behavior.

• Machine-facing task API (py3plex.agent)

  • Added stable, task-oriented entrypoints with uniform JSON-serializable contracts:
    • load_network_from_path
    • top_hubs_by_layer
    • uncertainty_centrality
    • community_detection_with_uq
    • temporal_slice
    • reproducible_export_bundle
    • compare_networks
    • summarize_result
  • All responses include: status, assumptions, warnings, result, provenance, replay, export_paths.

• Structured validation + plan introspection

  • Added QueryBuilder.validate() returning structured data for agent preflight:
    • target, selected layers, computed measures, grouping mode, UQ config, provenance mode
    • ambiguity flags, performance risk flags, missing prerequisites, recommended fixes
  • Added QueryBuilder.explain_plan_json() for machine-readable plan preview without execution.

• Ambiguity-safe helpers in core DSL/result surfaces

  • Added explicit top-k semantics:
    • top_k_global(...)
    • top_k_per_layer(...)
    • top_k_across_layers(...)
  • Added node identity helpers on QueryResult:
    • replica_nodes()
    • physical_nodes()
  • Added kind support in compute AST path (compute(..., kind=...) -> ComputeItem.kind) to explicitly carry degree intent.

• Structured diagnostics/warnings contract

  • Added STRUCTURED_WARNING_CATALOG + build_structured_warning(...) with stable fields:
    • code, severity, message, cause, likely_intent, suggested_fixes, autofixable
  • Executor now attaches structured ambiguity warnings to result metadata where applicable.

• Canonical machine serialization on query results

  • Added:
    • summary_dict()
    • inspect_json()
    • canonical_export_dict()
  • Canonical payload preserves items, attributes, grouping metadata, warnings, provenance, replay-relevant summary.

• Agent regression coverage

  • Added tests/test_agent_api.py for:
    • deterministic seeded workflows
    • structured validation/planning outputs
    • ambiguity helpers and explicit top-k semantics
    • replay/export bundle surface
    • serialization stability expectations
  • New module py3plex/agent.py is covered at 100%.

Example

from py3plex.agent import top_hubs_by_layer
from py3plex.dsl import Q

# Stable task API response for agent pipelines
payload = top_hubs_by_layer(net, top_k=10, measure="degree", seed=42)
print(payload["status"])
print(payload["result"]["summary"])
print(payload["replay"])  # seed / ast_hash / fingerprint / replayable

# Structured pre-execution validation
v = Q.nodes().order_by("pagerank").validate()
print(v["missing_prerequisites"])  # [{"code": "missing_metric", ...}]

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.