ergonomics

[SkBlaz]

Improve py3plex so it is materially easier for LLM-based agents and agentic workflows to use correctly on the first try.

Context you must respect:

• py3plex already has strong agent-oriented documentation, DSL v2, golden paths, ergonomic hints, semantic warnings, provenance, and testing patterns.
• Your job is not to add vague “AI support”; your job is to turn the existing strengths into strict, machine-friendly interfaces with fewer ambiguity traps.
• Preserve backward compatibility unless a break is absolutely necessary.
• Prefer code, tests, and examples over prose-heavy additions.
• Do not invent APIs blindly. Inspect the repo first, reuse existing patterns, and extend the current architecture cleanly.

Primary goal:
Create a thin, stable, machine-facing layer that lets an agent do discover -> decide -> build -> validate -> execute -> export with minimal guessing and maximal reproducibility.

Implement the following:

1. Add an agent-facing stable API surface
   Create a small, opinionated module such as py3plex.agent, py3plex.llm, or an equivalent package-consistent location.
   This layer should expose a handful of task-oriented entrypoints with stable JSON-serializable outputs, for example:

• load_network_from_path(...)
• top_hubs_by_layer(...)
• uncertainty_centrality(...)
• community_detection_with_uq(...)
• temporal_slice(...)
• reproducible_export_bundle(...)
• compare_networks(...)
• summarize_result(...)

Requirements:

• Each function must accept plain Python primitives.
• Each function must return a structured result object or dict with keys like:
  • status
  • assumptions
  • warnings
  • result
  • provenance
  • replay
  • export_paths
• Do not return raw pandas objects as the only contract.
• Make outputs deterministic when seed is provided.
• Include compact machine-readable warnings instead of only human prose.

2. Add machine-readable query validation and planning
   Extend DSL v2 so agents can inspect and repair plans before execution.
   Add functionality equivalent to:

• QueryBuilder.validate()
• QueryBuilder.explain_plan(machine=True)
• QueryResult.summary_dict() or QueryResult.inspect_json()

Validation output must include:

• target
• selected layers
• computed measures
• grouping mode
• uncertainty config
• provenance mode
• ambiguity flags
• performance risk flags
• missing prerequisites
• recommended fixes

This must be structured data, not just formatted strings.

3. Remove common multilayer ambiguity traps with explicit helpers
   Add explicit helper APIs for the most common agent mistakes:

• physical node count vs replica count
• aggregate degree vs intra-layer vs inter-layer degree
• top-k globally vs per-layer vs across-layer coverage
• grouped vs ungrouped result semantics

Possible implementations:

• result.physical_nodes()
• result.replica_nodes()
• compute("degree", kind="aggregate|intra|inter")
• top_k_global(...)
• top_k_per_layer(...)
• top_k_across_layers(...)

If these exact names do not fit the codebase, choose idiomatic names, but solve the ambiguity directly in code.

4. Make warnings and errors structured and self-repairable
   The repo already values pedagogical errors and semantic/performance warnings.
   Upgrade this into machine-readable diagnostics:

• warning codes
• severity
• cause
• likely intent
• suggested fixes
• autofixability boolean

Examples:

• execute_too_early
• replica_vs_physical_node_ambiguity
• aggregate_degree_ambiguity
• expensive_centrality
• high_uq_cost
• missing_metric
• active_grouping_required
• grouping_not_ended

Keep human-readable messages, but also expose structured metadata so an agent can react programmatically.

5. Standardize reproducibility and replay surfaces
   Every agent-facing execution path should make it easy to:

• see the seed
• see the AST hash
• see the network fingerprint
• see the network_version
• know whether the result is replayable
• export a reproducible bundle

Implement or improve a compact provenance contract that is easy for agents to store and compare.
If there are multiple existing provenance shapes, unify them behind one canonical accessor.

6. Add stable task recipes as code, not just documentation
   Promote the current golden paths into executable helpers or example-backed integration utilities.
   At minimum, cover:

• CSV/edgelist -> per-layer hubs
• uncertainty-aware centrality
• temporal slice query
• community detection with reproducible settings
• export bundle for replay
• one end-to-end pipeline example from load to export

Each recipe should:

• use current canonical APIs
• set seeds where relevant
• emit structured outputs
• be easy for an agent to copy or call

7. Improve result export contracts for agent workflows
   Agents need stable serialization more than pretty tables.
   Ensure there is a canonical export path for:

• dict / JSON
• pandas
• arrow
• CSV bundle
• replay bundle

Add one compact, guaranteed-stable serialization intended for agent handoff.
It should preserve:

• items
• attributes
• grouping metadata
• uncertainty metadata
• provenance
• warnings

8. Add an agent regression test suite
   Create tests that specifically validate LLM/agent usability.
   Include:

• determinism tests for seeded workflows
• differential tests across equivalent APIs
• provenance/replay tests
• metamorphic tests for grouped and coverage-based logic
• diagnostics tests for warning/error codes
• self-repair style tests for common incorrect query patterns
• serialization stability tests for agent-facing outputs

At minimum, test:

• top hubs by layer
• UQ centrality
• semantic ambiguity handling
• structured validation output
• replay/export bundle roundtrip

9. Keep the architecture clean
   Before adding new abstractions:

• inspect existing DSL, pipeline, provenance, warning, and result layers
• reuse existing classes where possible
• avoid duplicate logic
• avoid introducing an AI-only fork of the library
• keep the agent layer thin and compositional

10. Produce a high-signal implementation report
    When done, report:

• what you changed
• why each change improves agent usability
• which files were added/modified
• which APIs are now the recommended machine-facing entrypoints
• what tests were added
• any remaining ambiguity or follow-up work

Acceptance criteria:

• A coding agent can accomplish common py3plex workflows with fewer hidden assumptions.
• Ambiguous multilayer semantics are surfaced explicitly and programmatically.
• Query planning, validation, warnings, provenance, and export are available in structured form.
• There is a small, stable task-oriented API surface for common workflows.
• Deterministic and replayable execution is easy to inspect and verify.
• The change is backed by focused tests, not only documentation.

Non-goals:

• Do not add generic chatbot wrappers.
• Do not add marketing language.
• Do not add speculative AI features with no clear execution path.
• Do not replace DSL v2; build on top of it.

Start by inspecting the existing DSL, QueryResult, provenance, warnings, golden paths, and tests, then implement the smallest coherent set of changes that materially improves agent usability. No new md allowed.