[❓ Question]: Proposal: Universal Check Interface

[egarciamendez]

Preliminary Checks

• I have read the project documentation.
• I have searched the issue tracker for similar questions.

What Have You Tried?

Proposal: Universal Check Interface

I opened this issue to propose a minimal universal interface for structural checks in Blueprints.
My goal is to gather feedback from the community and reach consensus on the best approach before implementing it.

Sooooo @Blueprints-org/maintainers , let me know what you think!

Problem

At Blueprints we want to support structural checks that engineers can use for a broad variety of cases.
Think of checks like, shear capacity of a concrete beam, bending capacity of a steel section, or bearing capacity of a soil foundation.
Those are just examples, but the goal is to support any engineering check for any material (concrete, steel, soil, etc.) and any complexity level (from simple single checks to complex hierarchical checks composed of sub-checks).

So how are we going to achieve that in a clean, maintainable way and offer our users a consistent experience?

The short answer is you can't. Checks vary widely in their logic, inputs, outputs, and complexity.
However, we can define a minimal universal interface that all checks must implement. This interface will provide a consistent way to interact with any check, regardless of its internal workings.

In that way, users can rely on a common set of methods and properties to work with checks, while the specific implementation details can vary as needed.

Solution: Minimal Universal Interface

class StructuralCheckProtocol(Protocol):
    """Minimal interface for ANY engineering check."""

    name: str  # Check name (instance parameter)
    source_docs: list[str]  # Source references

    def execute(self, **kwargs) -> Any:  # Internal calculations
        """Flexible return type for check-specific logic."""

    def check(self) -> CheckResult:  # Public API
        """Execute check. Always returns CheckResult."""

    def calculation_steps(self) -> dict[str, "StructuralCheckProtocol"]:
        """Return sub-check instances (not results)."""

That's the complete interface. No more, no less.

Design Principles

• Single Responsibility: Each element has one reason to exist

  • name: Identity
  • source_docs: Traceability
  • execute(): Internal logic
  • check(): Verification
  • calculation_steps(): Composition

• Open/Closed: Add new checks without modifying existing code

• Liskov Substitution: Any check works anywhere a check is expected

• Interface Segregation: Only what's needed, nothing extra

• Dependency Inversion: Depend on StructuralCheckProtocol, not implementations

Simple Check Pattern

@dataclass(frozen=True)
class SimpleShearCheck:
    """Minimal implementation."""

    name: str
    source_docs: list[str]
    v_ed: float
    v_rd: float

    def execute(self) -> float:
        return self.v_rd

    def check(self) -> CheckResult:
        return CheckResult.from_comparison(self.v_ed, self.v_rd)

    def calculation_steps(self) -> dict:
        return {}  # No sub-checks
    
    # ... and any other relevant methods that are specific to this check


# Usage
check = SimpleShearCheck(
    name="Shear check for Beam B-1",
    source_docs=["EN 1992-1-1 art. 6.2.2"],
    v_ed=150_000,
    v_rd=200_000,
)
result = check.check()

Composite Check Pattern

@dataclass(frozen=True)
class SteelBeamCheck:
    """Check composed of sub-checks."""

    name: str
    source_docs: list[str]
    m_ed: float
    m_rd: float
    v_ed: float
    v_rd: float

    def execute(self) -> dict[str, BaseCheck]:
        """Create sub-check instances."""
        bending = BendingCheck("Bending", ["EN 1993"], self.m_ed, self.m_rd)
        shear = ShearCheck("Shear", ["EN 1993"], self.v_ed, self.v_rd)
        return {"bending": bending, "shear": shear}

    def check(self) -> CheckResult:
        """Aggregate sub-checks."""
        checks = self.execute()
        return aggregate_checks(checks, mode="all_must_pass")

    def calculation_steps(self) -> dict[str, StructuralCheckProtocol]:
        """Return sub-check instances."""
        return self.execute()
    
    # ... and any other relevant methods that are specific to this check


# Usage
check = SteelBeamCheck(
    name="Steel IPE 300",
    source_docs=["EN 1993-1-1:2005"],
    m_ed=100_000,
    m_rd=150_000,
    v_ed=50_000,
    v_rd=75_000,
)

# Overall result
overall = check.check()

# Inspect sub-checks independently
for name, sub_check in check.calculation_steps().items():
    result = sub_check.check()
    print(f"{name}: {result.is_ok}")

OPTIONAL: BaseCheck ABC

For the case where inheritance is preferred over duck typing:

@dataclass(frozen=True)
class BaseCheck(ABC):
    """Optional base class. Implements StructuralCheckProtocol."""

    name: str
    source_docs: list[str] = field(default_factory=list)

    @abstractmethod
    def execute(self, **kwargs) -> Any:
        pass

    @abstractmethod
    def check(self) -> CheckResult:
        pass
    
    @abstractmethod
    def calculation_steps(self) -> dict[str, "StructuralCheckProtocol"]:
        return {}  # Default: no sub-checks
    
    @abstractmethod
    def report(self) -> LatexReport:
        """Optional: Generate formatted reports."""
        return LatexReport(...)

Choice: Use Protocol (duck typing) OR BaseCheck (structure). Both work identically.

Summary

A minimal, universal interface for structural checks that:

• Scales from simple single-checks to complex hierarchies
• Works for any material (concrete, steel, timber, masonry, etc.)
• Follows SOLID principles
• Maintains backward compatibility
• Provides optional convenience features (BaseCheck, report(), aggregation)

The interface requires only 5 elements:

1. name - Check identity
2. source_docs - Documentation references
3. execute() - Internal calculations
4. check() - Public verification API
5. calculation_steps() - Sub-check composition

So what do you think? Is this the right approach for Blueprints?

1. Should calculation_steps() use a different name? (sub_checks(), components(), children()?)
2. Any material-specific patterns needed?
3. Other suggestions or improvements?
4. ABC or Protocol / Maybe both?

Question Description

I would love to have some feedback on this before starting on the implementation.

Relevant Code or Steps

No response

Confirmation

• I have checked that this question does not already exist in the issue tracker or documentation.
• I have read and understood the contribution guidelines.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• [✨ Feature request]: Support for Additional Structural Design Codes (e.g. NBR 6118, ACI/ASTM) #764
• [📚 Documentation Issue]: seperate checks folder for concrete, steel and (more)  #832
• [✨ Feature request]: Define structure and versioning strategy for National Annexes #855
• [✨ Feature request]: Guide for report for checks #881

👤 Suggested Assignees

• GerjanDorgelo
• viviangiulia
• egarciamendez

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[GerjanDorgelo]

A few thoughts and notes:

• source_docs: i'd love to have this be a connection to the variable in e.g. blueprints\codes\eurocode\en_1992_1_1_2004_init_.py
• calculation_steps: i prefer this word over sub_checks, for two reasons:
  • It may be needed to do some calculations in between the calculation steps. idk a calculation of an standard deviation or something. That feels logical to add in a calculation STEP, though its not sub CHECK.
  • For the lowest level check, the calculation steps are e.g. the calculation of the resistence. This is not a check, but a step.
  • children and components also dont violate the reasoning above, but i feel like its less intuitive from an engineering perspective, though it is intuitive from a programmer perspective
• material-specific patterns? cant think of any that wouldnt follow proposed pattern.
• I see an optional in the abstractmethod report. i'd want that to be mandatory.
• The report could have the output that you and I discussed with options: Table+Equations, Table, Equation complete with units, Equation complete, Equations short, and only final result. It may be not be needed to build a constructor like thing in this abstractmethod itself, but is this the section of code to force on of these options?

[SZeltaat]

Hi @egarciamendez,
Really really nice proposal. Thank you for taking the time to make it this good! 🤟 ❤️

I like a lot of things in your proposal, here are some possible improvements in my opinion:

ABC or Protocol

• At this point, I prefer Protocol. ABC does not add anything.
  • It does not handle any heavy-lifting for the subclasses, so why should it exist?
  • It adds complexity by a thight coupling making it difficult to refactor in the future without breaking things.
  • It becomes harder to justify Open/Closed and Dependency Inversion principles.
• I have proposed an implementation that relies on ABC. Unless we need to rely on standard internal implementations, I would go for Protocol.

Naming

• execute and check are very confusing! Why should the internal logic be different than the verification? This is also not clear in the examples. I'm sure you have a good reason for it, but it is not obvious to me, in this proposal. These are my thoughts on the names, to better show my confusion 😕
  • if execute is an internal method, it should be called _execute. I've seen execute in many libraries as a public API. So, maybe rethink the name all together?
  • I'm not sure about calling the second method, a check method. Suggestion: result or in the form of a verb get_results or run. Even execute might be a better fit here?

source_docs

• I agree with Gerjan that the source_docs should contain references to pre-defined variables, preferably singeltons. The variable defined in the init files of each code is problematic (see discussion on lazy imports and simplifying imports) and if we want to simplify the imports, it should be changed. My suggestion is to define an Enum called SourceDocument and define the names there.
• source_docs can then be a dict of {SourceDocument: str} pairs where the str is the article number, formula number, etc.

class SourceDocument(Enum):
    EN_1993_1_1_2005 = "EN 1993-1-1:2005"
    ...

# Usage
check = SimpleShearCheck(
    name="Shear check for Beam B-1",
    source_docs={SourceDocument.EN_1993_1_1_2005: "art. 6.2.2"},
    v_ed=150_000,
    v_rd=200_000,
)

Composite pattern

This is the perfect fit for the composite pattern. The example however, does not reflect any of its powerful advantages. I think that the implementation of claculation_steps and execute should somehow be the other way around. calculation_steps should provide the steps and execute should execute them. This is now done in check 🤷? It all seems confusing.

This is my proposal to benefit from both ABC and Composite pattern. Keep in mind that I don't really understand the difference between execute and check. I'm just making a distinction between an internal and a private API here.

@dataclass(frozen=True)
class BaseCheck(ABC):
    """Base class for checks."""

    name: str
    source_docs: dict[SourceDocument, str] = field(default_factory=dict)
    _sub_checks: ClassVar[list[TypedDict]] = field(default_factory=list)  # see the example for the keys and values of each TypedDict

    def _execute_sub_checks(self) -> dict[str,Any]:
        """Internal class for executing the subchecks"""
        return {sub_check_name: sub_check._execute() for sub_check_name, sub_check in self.get_sub_checks().items()}  # Each sub_check.execute() returns a dict, so we might want to somehow flatten those dicts either here or in the following steps.

    @abstractmethod
    def _execute_current_check(self) -> dict[str,Any]:
        """Internal class to implement a specific check for the current class."""
        # return {} if not applicable

    def _execute(self) -> dict[str,Any]:
        """Internal method to bundle the specific checks within the class and the sub checks"""
        sub_check_executions = self._execute_sub_checks()  # Or possibly flatten the dicts here!
        current_execution = self._execute_current_check()
        return sub_check_executions | current_execution

    @abstractmethod
    def _aggregate_checks(self, executions: dict[str,Any]) -> CheckResult:
        """Internal method to convert the internal logic to a user-friendly CheckResult object"""
        pass

    def get_check_results(self) -> CheckResult:
        """Standard Public API. Stays the same, while giving the flexibility to modify the logic in _aggregate_checks and _execute_current_check"""
        return self._aggregate_checks(self._execute())
    
    def get_sub_checks(self) -> dict[str, "BaseCheck"]:
        """Standard method to intantiate and return the check objects with correct args and kwargs"""
        return {sub_check["check"].__class__.__name__: sub_check["check"](*sub_check["args"], **self._map_kwargs(sub_check["kwargs"])) for sub_check in self._sub_checks}
    
    @abstractmethod
    def report(self) -> LatexReport:
        """Optional: Generate formatted reports."""
        return LatexReport(...)

    def _map_kwargs(self, kwargs_mapping:dict) -> dict:
        """Details!!! But just to be thorough!"""
        {key: getattr(self, value) for key, value in kwargs_mapping.items()}

Following this base class, we can then implement a subclass like this:

@dataclass(frozen=True)
class SteelBeamCheck(BaseCheck):
    """Check composed of sub-checks."""

    name: str
    m_ed: float
    m_rd: float
    v_ed: float
    v_rd: float
    source_docs=[SourceDocument.EN_1993_1_1_2005: "art. 6.2.2"]
    _sub_checks: ClassVar[list[TypedDict]] = [
        {"check": BendingCheck, "args": ("Bending", ["EN 1993"]), "kwargs": {"m_ed": "m_ed", "m_rd": "m_rd"}},
        {"check": ShearCheck, "args": ("Shear", ["EN 1993"]), "kwargs": {"m_ed": "m_ed", "m_rd": "m_rd"}},
    ]

    def _execute_current_check(self) -> dict[str,Any]:
        """This relies only on sub checks, so returning an empty dict."""
        return {}

    def _aggregate_checks(self, executions: dict[str,Any]) -> CheckResult:
        """Aggregate sub-checks."""
        return CheckResult.from_multiple_executions(executions, mode="all_must_pass")

    
    # ... and any other relevant methods that are specific to this check


# Usage
check = SteelBeamCheck(
    name="Steel IPE 300",
    m_ed=100_000,
    m_rd=150_000,
    v_ed=50_000,
    v_rd=75_000,
)

# Overall result
overall = check.get_check_results()

# Inspect sub-checks independently
for name, sub_check in check.get_sub_checks().items():
    result = sub_check.get_check_results()
    print(f"{name}: {result.is_ok}")

Final thoughts

If we want to benefit from the composite pattern, we need to provide the internals for it. Composite pattern has many benefits, but we have to ask ourselves if those benefits are worth the extra complexity in the base class.
Your proposed Protocol is very simple and that is a great advantage. It just doesn't provide any support for composition.

I personally think that the benefits of composite outweight the complexity of the implementation. Keep in mind that this complexity only stays within the base class. The subclasses remain simple. Exactly like the implementation of our Formula class.