[EQL] Cleaning, Dataclass Failures, Refactor Quantification Constraints, Doc update

[AbdelrhmanBassiouny]

This pull request refactors how result quantification constraints are specified and handled in the entity query language package. The main change is replacing the previous approach of passing separate at_least, at_most, and exactly arguments with a unified quantification constraint object. This improves clarity, extensibility, and error handling for queries. The update also introduces new exception classes and refactors documentation and usage examples to match the new API.

Result quantification constraint API overhaul:

• Introduced the ResultQuantificationConstraint class hierarchy (Exactly, AtLeast, AtMost, Range) in src/krrood/entity_query_language/result_quantification_constraint.py, replacing separate cardinality arguments for queries.
• Refactored the an function in src/krrood/entity_query_language/entity.py to accept a single quantification argument of type ResultQuantificationConstraint, removing at_least, at_most, and exactly.
• Updated the ResultQuantifier class in src/krrood/entity_query_language/symbolic.py to use the new constraint object and refactored cardinality limit logic accordingly. [1] [2]
• Changed the The quantifier to use Exactly(1) as its default constraint.

Exception and error handling improvements:

• Refactored and expanded exception classes in src/krrood/entity_query_language/failures.py, including new types for negative cardinality, invalid entity types, and clearer error messages using dataclasses. [1] [2]

Documentation and usage updates:

• Updated examples in examples/eql/result_quantifiers.md to use the new quantification parameter, demonstrating usage with Exactly, AtLeast, AtMost, and Range. [1] [2] [3] [4] [5]
• Adjusted import statements and usage in example files to match the new API and domain model conventions. [1] [2] [3]

Codebase cleanup and consistency:

• Removed obsolete cardinality validation logic and unused imports related to the old quantification approach. [1] [2] [3] [4]

These changes make the quantification API more robust, easier to use, and extensible for future enhancements.

[Copilot]

Pull Request Overview

This PR refactors the quantification constraint API in the Entity Query Language (EQL) by introducing a new type-safe constraint system based on dataclasses. The main changes include converting exception classes to use a dataclass pattern and replacing the previous at_least/at_most/exactly parameters with explicit constraint types (AtLeast, AtMost, Exactly, and Range).

• Introduces new ResultQuantificationConstraint hierarchy with type-safe constraint classes
• Converts exception classes to use the DataclassException base pattern
• Updates API to use explicit constraint objects instead of integer parameters
• Updates documentation and examples to reflect the new API

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/krrood/entity_query_language/result_quantification_constraint.py	New file defining the constraint class hierarchy
src/krrood/utils.py	Adds DataclassException base class for exception pattern
src/krrood/entity_query_language/failures.py	Converts exceptions to dataclass pattern and adds new exception types
src/krrood/entity_query_language/symbolic.py	Refactors ResultQuantifier to use new constraint objects
src/krrood/entity_query_language/entity.py	Updates an() function API to use constraint parameter
test/test_eql/test_core/test_queries.py	Updates tests to use new constraint API
examples/eql/writing_rule_trees.md	Updates documentation example
examples/eql/result_quantifiers.md	Updates documentation with new API usage

Comments suppressed due to low confidence (1)

src/krrood/entity_query_language/failures.py:112

• Missing space between sentences in the error message. Add a space at the end of line 111 or beginning of line 112 to properly separate 'compute.' from 'To'.

            f" because it is ambiguous and can be very expensive to compute."
            f"To Negate Conditions do:"

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[LucaKro]

cool stuff, just some small notes 💪