RAI imports convention RFC

[maciejmajek]

Summary This RFC raises the need to define a consistent convention for how imports should be written across the RAI framework. It aims to open a discussion about whether we should favor top-level imports or deep/internal module imports, and to establish a project-wide guideline going forward.

Motivation As the framework continues to grow in complexity, the current use of imports has become inconsistent. Some modules import components from public, top-level interfaces, while others reach into deep internal paths. Although both styles work, the lack of a unified convention has created:

• A fragmented structure that makes navigation and maintenance harder.
• Inconsistent assumptions about which modules are part of the public API.
• Increased potential for coupling to internal implementation details.
• Creating an import convention now will help maintain the clarity, scalability, and usability of the codebase as the project evolves.

Current situation Examples of current import styles:

Top-level (public-style):

from rai.communication.ros2 import ROS2ARIConnector

Deep/internal:

from rai.communication.ros2.connectors.ari_connector import ROS2ARIConnector

There is no official guideline or consensus on which style should be preferred.

Open Questions

• Should we expose components via top-level modules and encourage shallow imports?
• Is it acceptable to import directly from deep internal paths within the package?

[rachwalk]

In general I believe that for public APIs at most 3 levels of import is preferable. It comes with some strong advantages:

• Reorganizing internal module structure doesn't break things: e.g. if we split api.py file into multiple files, all other code remains unaffected, making for cleaner PRs (change to communication/ros2/api/api.py doesn't cause cascading changes in extensions/vision/gdino_agent.py and 30 other files due to reorganized imports).
• Makes a clean distinction between public API and internal logic - the user knows what's meant to be used outside.
• While it may not be included in python guidlines the Law of Demeter, or the principle of least knowledge has been generally accepted as a good design practice for all OOP development
• Also it looks clean

It does come with some drawbacks:

• the slightly increased development cost to ensure consistency
• might require additional module jumping during development/debugging

That being said I think RAI has reached the level of maturity, that we should aim for clarity in which classes are meant as public API (and use this as convention in inter-module development). The biggest benefit I believe is the first one, namely reorganizing internal (private) API of a module, shouldn't break imports in 4 other modules. It also provides a very clear guideline for which things are the public API i.e. which components, if altered, would constitute a breaking API change. This is in general helpful for release notes, as it will make it easy to review if there are breaking API changes, which should be reflected in release notes. This would be even more important should semver be adopted, as it will allow to easily distinguish minor and major releases.