Add MATCH queries and layer clauses to DSL (DSL v3)

[Copilot]

• Explore repository structure and locate existing DSL code
• Understand the existing DSL parser, tokenizer, and interpreter in py3plex/dsl.py
• Verify existing DSL tests pass (64 tests)
• Add MATCH pattern syntax (Cypher-like)
  • Add MatchQuery node type to internal representation (NodePattern, EdgePattern, PathPattern, MatchQuery dataclasses)
  • Extend tokenizer to recognize MATCH, RETURN, IN, LAYER, LAYERS, edge patterns (-[, ]->)
  • Parse node patterns: (alias:Label) and (alias)
  • Parse edge patterns: -[alias:Type]-> and -[alias]->
  • Parse RETURN clause: RETURN * or RETURN alias1, alias2
  • Implement MATCH query execution (pattern matching against graph)
• Add layer scoping clauses
  • Add IN LAYER 'name' clause support for SELECT queries
  • Add IN LAYERS ('a', 'b') clause support for SELECT queries
  • Add layer clause support for MATCH queries
• Extend WHERE clause for alias.attribute syntax in MATCH queries
• Add tests for new features (30 new tests, 94 total)
  • Test MATCH pattern parsing and execution
  • Test SELECT with IN LAYER clause
  • Test SELECT with IN LAYERS clause
  • Test backward compatibility with existing queries
• Run code review and address feedback
• Run security checks (CodeQL) - no issues found
• Add execute_query as first-class method on multi_layer_network class (99 tests passing)
  • Users can now call network.execute_query(query) directly

Original prompt

---

This section details on the original issue you should resolve

<issue_title>dsl v3</issue_title>
<issue_description>You are helping extend the EXISTING py3plex DSL implementation (do NOT rewrite it from scratch).

Context:

• py3plex already has a DSL for querying networks.
• The current DSL is SQL-like (e.g. SELECT ... FROM ... WHERE ...).
• We want to ADD new syntax and behaviors, while keeping full backward compatibility with existing queries and code.

Your tasks:

1. Locate the existing DSL code

   • Find the module(s) that implement parsing and interpreting the current DSL.
   • Typical names may include: dsl, query_language, parser, interpreter, query_engine, etc.
   • Read the current code and understand:
     • How tokens / grammar are defined.
     • How queries are represented internally (AST-like objects, dicts, etc.).
     • How queries are executed against py3plex multilayer graphs.

2. Keep the current API and syntax working

   • Do not remove, rename, or break existing public functions used by external code (e.g. run_query, parse_query, interpret_query, etc.).
   • Do not change existing query semantics unless strictly necessary.
   • All existing tests for the DSL must still pass.
   • New features should be added in a way that gracefully extends the current design, not replaces it.

3. NEW features to ADD to the DSL

   3.1. MATCH pattern syntax (Cypher-like)

   • Add a new top-level statement form:

     MATCH (g:Gene)-[r:REGULATES]->(t:Gene) IN LAYER 'reg' WHERE g.degree > 10 RETURN g, t;

   • Requirements:

     • Node pattern: (alias[:Label]?)
       • Example: (g:Gene), (t), (x:Protein)
       • alias is required, label is optional.
     • Edge pattern: -[alias[:Type]?]-> between nodes
       • Example: -[r:REGULATES]->, -[e]->, -[:INTERACTS]->
     • A MATCH statement may be followed by:
       • optional layer clause (see 3.2)
       • optional WHERE clause using existing condition syntax
       • optional RETURN clause:
         • RETURN * → return full binding dictionary
         • RETURN g, t → return only the specified aliases
     • Internally, you should:
       • Extend the current parser/grammar to parse MATCH statements into a suitable internal structure (AST node or equivalent).
       • Extend the interpreter so that:
         • MATCH queries are dispatched to a dedicated execution function.
         • This function can either:
           • Use an existing pattern-matching facility in py3plex, OR
           • For now, be implemented as a placeholder that clearly documents what needs to be done later.
       • WHERE conditions inside MATCH should support:
         • alias.attribute syntax (e.g. g.degree, t.color).
         • Plain attribute names, interpreted in a reasonable way given the existing code.

   3.2. Layer scoping clauses

   • Add support for:

     IN LAYER 'layer_name'
     IN LAYERS ('layer_a', 'layer_b', ...)

   • These clauses may appear in:

     • SELECT queries:
       SELECT * FROM nodes IN LAYER 'ppi' WHERE degree > 10;
       SELECT id, degree FROM nodes IN LAYERS ('ppi', 'coexpr') WHERE color = 'red';
     • MATCH queries:
       MATCH (g:Gene)-[r:REGULATES]->(t:Gene) IN LAYER 'reg' WHERE g.degree > 10 RETURN g, t;

   • Behavior:

     • Extend the parser to recognize these clauses without breaking existing queries.
     • Pass the selected layer(s) cleanly through the internal query representation and into the interpreter.
     • The interpreter should limit the nodes / edges / patterns to those belonging to the specified layer(s).
     • If the underlying py3plex API already supports layer filtering, reuse that.
     • If not, add a small abstraction that filters nodes/edges by a layer attribute, but keep it well isolated.

   3.3. WHERE expression semantics (augmentation, not replacement)

   • Reuse the existing WHERE parsing and evaluation logic.
   • Extend it minimally to support:
     • alias.attribute references for MATCH queries, e.g. g.degree > 10.
     • Keep existing behavior for plain identifiers (like "degree") in SELECT queries.
   • If the current implementation already distinguishes evaluation contexts, integrate alias support in a way that does not break existing code.

4. Implementation guidelines

   • Work with the existing architecture:
     • If there's a hand-written parser, extend the same style (e.g. recursive descent).
     • If there's an existing grammar, extend it instead of introducing a brand new parsing library.
   • Add new internal data structures (e.g., new AST node types) only when necessary:
     • Example: add a MatchQuery node type if the system already has something like SelectQuery.
   • Keep code readable and documented:
     • Add docstrings for new functions/classes.
     • Add comments where behavior is non-obvious or where TODOs for later optimizations are needed.

5. Tests and examples

   • Add or update tests to cover at least:
     1. Basic MATCH pattern:
        MATCH (g:Gene)-[r:REGUL...

• Fixes dsl v3 #646

---

💡 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.

[SkBlaz]

@copilot make it also first class, multinet.execute_query(...

[Copilot]

@copilot make it also first class, multinet.execute_query(...

Added execute_query as a first-class method on multi_layer_network in commit 0661aa5. Users can now call:

net = multi_layer_network() result = net.execute_query('SELECT nodes WHERE layer="ppi"') result = net.execute_query('MATCH (a:Gene)-[r]->(b:Gene) RETURN a, b')