feature/SOF 7901 qol

[VsevolodX]

Update: add ability to pass uploads folder path

Summary by CodeRabbit

• New Features

  • Enhanced relaxation workflow with improved data persistence handling and flexible storage options.

• Bug Fixes

  • Improved robustness of Pyodide environment compatibility for MACE calculations.

• Refactor

  • Streamlined internal package structure and module imports for better maintainability.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors the material I/O infrastructure to support flexible folder paths for persistence and refines Pyodide patch application logic. The MACE-MP relaxation notebook is updated to leverage the new set_materials() API and apply patches unconditionally, while the torch module becomes defensive with environment detection.

Changes

Material I/O Infrastructure and Notebook Integration

Layer / File(s)	Summary
Package namespace discovery src/py/mat3ra/__init__.py	Package initialization now extends module search path using pkgutil.extend_path for namespace-style discovery.
Flexible folder path support for material persistence src/py/mat3ra/notebooks_utils/core/entity/material/io.py, src/py/mat3ra/notebooks_utils/core/io.py, src/py/mat3ra/notebooks_utils/io.py	set_data_python, set_data, and set_materials all accept optional folder_path parameter (defaulting to UPLOADS_FOLDER). The stack threads folder paths through serialization, creates missing directories, and logs material send operations with material count.
Pyodide environment detection for patch application src/py/mat3ra/notebooks_utils/pyodide/packages/torch.py	apply_all_patches() now conditionally applies patches only when is_pyodide_environment() returns True, with fallback warning message for non-Pyodide environments.
MACE relaxation notebook integration other/materials_designer/workflows/local/relaxation_mlff_mace.ipynb	Notebook calls set_materials(material_relaxed, FOLDER) for persistence (removing prior explicit basis label reset), applies patches unconditionally, reformats Plotly callback to multiline style, and updates Usage documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Exabyte-io/api-examples#289: Introduced the original MACE-MP relaxation notebook with Pyodide/torch patching logic; this PR refactors the I/O infrastructure and refines patch application for that workflow.

Suggested reviewers

• timurbazhirov

Poem

A rabbit hops through folders far,
With paths that wind both near and far,
The MACE-MP relaxes with care so bright,
Torch patches patch when stars align just right,
Materials flow where needed—stored with delight! 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'feature/SOF 7901 qol' is vague and generic, using a non-descriptive ticket reference and abbreviation ('qol') without conveying what quality-of-life improvements are actually made.	Clarify the title to describe the main feature or improvement, e.g., 'Add ability to pass uploads folder path to set_materials' or 'Enable folder-level configuration for material uploads' to better reflect the changeset.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/SOF-7901-qol

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/py/mat3ra/notebooks_utils/io.py (1)

25-37: ⚡ Quick win

folder_path is silently ignored in the Pyodide path.

If callers pass a custom path while running in Pyodide, the value is dropped with no signal. Please add an explicit warning (or clear docstring note at runtime) when folder_path != UPLOADS_FOLDER in the Pyodide branch.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/py/mat3ra/notebooks_utils/io.py` around lines 25 - 37, The Pyodide branch
of set_data silently ignores the folder_path argument; update set_data so that
when ENVIRONMENT == EnvironmentsEnum.PYODIDE and folder_path != UPLOADS_FOLDER
it emits an explicit runtime warning (e.g., using warnings.warn or your module
logger) indicating that custom folder_path is ignored in Pyodide and that
set_data_pyodide will use UPLOADS_FOLDER; keep the existing calls to
set_data_pyodide and set_data_python unchanged and reference the functions
set_data, set_data_pyodide, set_data_python, ENVIRONMENT, EnvironmentsEnum, and
UPLOADS_FOLDER when making this change.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/py/mat3ra/notebooks_utils/core/io.py`:
- Around line 45-46: The code currently does a check-then-create using
os.path.exists(folder_path) followed by os.makedirs(folder_path), which can race
under concurrent calls; update the logic to create the directory atomically by
calling os.makedirs(folder_path, exist_ok=True) (or wrap os.makedirs in
try/except catching FileExistsError) wherever this pattern appears (refer to the
folder_path variable and the os.makedirs call) so directory creation is safe
under concurrent execution.

---

Nitpick comments:
In `@src/py/mat3ra/notebooks_utils/io.py`:
- Around line 25-37: The Pyodide branch of set_data silently ignores the
folder_path argument; update set_data so that when ENVIRONMENT ==
EnvironmentsEnum.PYODIDE and folder_path != UPLOADS_FOLDER it emits an explicit
runtime warning (e.g., using warnings.warn or your module logger) indicating
that custom folder_path is ignored in Pyodide and that set_data_pyodide will use
UPLOADS_FOLDER; keep the existing calls to set_data_pyodide and set_data_python
unchanged and reference the functions set_data, set_data_pyodide,
set_data_python, ENVIRONMENT, EnvironmentsEnum, and UPLOADS_FOLDER when making
this change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ed0fdfa6-96df-4e8c-80b1-45bc7700ca87

📥 Commits

Reviewing files that changed from the base of the PR and between 19f57a8 and 36eaf92.

📒 Files selected for processing (6)

• other/materials_designer/workflows/local/relaxation_mlff_mace.ipynb
• src/py/mat3ra/__init__.py
• src/py/mat3ra/notebooks_utils/core/entity/material/io.py
• src/py/mat3ra/notebooks_utils/core/io.py
• src/py/mat3ra/notebooks_utils/io.py
• src/py/mat3ra/notebooks_utils/pyodide/packages/torch.py

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Avoid check-then-create for output directory creation.

This pattern can fail under concurrent calls (FileExistsError) between the existence check and creation.

Proposed fix

-    if not os.path.exists(folder_path):
-        os.makedirs(folder_path)
+    os.makedirs(folder_path, exist_ok=True)

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if not os.path.exists(folder_path):
	os.makedirs(folder_path)
	os.makedirs(folder_path, exist_ok=True)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/py/mat3ra/notebooks_utils/core/io.py` around lines 45 - 46, The code
currently does a check-then-create using os.path.exists(folder_path) followed by
os.makedirs(folder_path), which can race under concurrent calls; update the
logic to create the directory atomically by calling os.makedirs(folder_path,
exist_ok=True) (or wrap os.makedirs in try/except catching FileExistsError)
wherever this pattern appears (refer to the folder_path variable and the
os.makedirs call) so directory creation is safe under concurrent execution.