docs: fix installation version conflicts and remove duplicate section - #180
Conversation
- Align Python version to 3.12 across installation.md and getting-started.md - Add pyqt=5 to conda install command in installation.md (matching CLAUDE.md) - Unify conda env name to revodesign - Remove duplicate section 3 (Install the PyMOL Plugin) from getting-started.md - Add Package Manager figure before First Launch section - Fix figure caption: recipe mechanism, not YAML/JSON config - Fix Python version (3.11→3.12), add pyqt=5, fix env name in .docx manual [skip ci]
Add English rule file and enrich OpenKinetics client with comprehensive docstrings, improved API-key persistence (process env + ConfigBus fallback), better error handling and validation, CSV/tempfile handling, request/result polling comments, and small clarifications. Update tests to add missing test dependencies (pocket/surface sessions) and add a bootstrap/dependency marker for surface in prepare tests.
Changes: 1. **SingletonAbstract**: Convert `initialized` from an attribute to a @Property that checks `_instance is not None`, eliminating manual tracking. 2. **set_cache_dir()**: Add validation to check if ConfigBus is initialized before accessing configuration, raising UnexpectedWorkflowError if not. 3. **Documentation**: Enhance docstrings for `decide()` and `set_cache_dir()` with detailed Args, Returns, and usage examples.
|
Warning Review limit reached
Next review available in: 13 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. 📝 WalkthroughWalkthroughUpdates documentation (onboarding steps, installation requirements), adds an ChangesDocumentation and configuration rules
Singleton and config bootstrap logic
OpenKinetics client docstrings and error handling
Tab test dependency wiring
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Not up to standards ⛔🔴 Issues
|
| Category | Results |
|---|---|
| BestPractice | 2 minor |
| Documentation | 4 minor |
🟢 Metrics 0 complexity · 0 duplication
Metric Results Complexity 0 Duplication 0
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
 |
|
Overall Grade |
Security  Reliability Complexity Hygiene  |
Code Review Summary
| Analyzer | Status | Updated (UTC) | Details |
|---|---|---|---|
| Python |  |
Jul 6, 2026 7:00a.m. | Review ↗ |
Important
AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6cf1114d8f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @property | ||
| def initialized(cls) -> bool: |
There was a problem hiding this comment.
When any SingletonAbstract subclass is instantiated, this added initialized property makes hasattr(self, "initialized") in __init__ return true before singleton_init() has ever run, so every singleton is returned without its required attributes (for example ConfigBus() never creates cfg_group). It also is not a class property, so ConfigBus.initialized evaluates to the truthy property object rather than a boolean.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/REvoDesign/basic/abc_singleton.py (1)
147-189: 🩺 Stability & Availability | 🔴 Critical | ⚡ Quick winMake
initializeda real boolean flag.@propertymakesConfigBus.initializedtruthy on class access, andhasattr(self, "initialized")in__init__is already true beforesingleton_init()runs, so new singleton instances skip initialization. Store a real flag on the class or instance instead.🤖 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/REvoDesign/basic/abc_singleton.py` around lines 147 - 189, The singleton initialization guard in `abc_singleton.py` is broken because `initialized` is defined as a property, which makes class-level access truthy and causes `__init__` to skip `singleton_init()` due to `hasattr(self, "initialized")` already succeeding. Update `initialized` to be a real boolean flag managed on the singleton instance or class, and adjust `__init__`, `__new__`, and the `initialized` accessor so initialization runs exactly once and correctly reflects whether the singleton has been set up.
🤖 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/REvoDesign/magician/designers/openkinetics/_client.py`:
- Around line 68-69: The fallback persistence path in OpenKineticsClient does
not match the documented OpenKineticsConfigurationError contract, because direct
file writes can throw raw I/O or OmegaConf exceptions instead of the wrapped
error. Update the fallback branch in the OpenKinetics client’s configuration
save flow to catch persistence failures the same way the ConfigBus branch does,
and re-raise them as OpenKineticsConfigurationError with the original exception
attached. Keep the behavior consistent with the existing API key validation and
environment persistence logic so callers can reliably handle one exception type.
---
Outside diff comments:
In `@src/REvoDesign/basic/abc_singleton.py`:
- Around line 147-189: The singleton initialization guard in `abc_singleton.py`
is broken because `initialized` is defined as a property, which makes
class-level access truthy and causes `__init__` to skip `singleton_init()` due
to `hasattr(self, "initialized")` already succeeding. Update `initialized` to be
a real boolean flag managed on the singleton instance or class, and adjust
`__init__`, `__new__`, and the `initialized` accessor so initialization runs
exactly once and correctly reflects whether the singleton has been set up.
🪄 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: f2d48682-0622-4129-b56d-37cda05057c7
📒 Files selected for processing (9)
.lingma/rules/lan.mddocs/getting-started.mddocs/user-guide/installation.mdsrc/REvoDesign/basic/abc_singleton.pysrc/REvoDesign/bootstrap/set_config.pysrc/REvoDesign/magician/designers/openkinetics/_client.pytests/cases/tabs/test_cluster.pytests/cases/tabs/test_mutate.pytests/cases/tabs/test_prepare.py
| OpenKineticsConfigurationError: If the API key is empty or if persistence to environ.yaml fails. | ||
| """ |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Docstring promises exception wrapping the fallback path doesn't provide.
The docstring states OpenKineticsConfigurationError is raised "if persistence to environ.yaml fails," and the ConfigBus branch (lines 80-101) does wrap failures in OpenKineticsConfigurationError. However, the fallback direct-file-write path (lines 103-113, used when ConfigBus is unavailable/uninitialized) has no try/except — any I/O failure (OSError, OmegaConf errors, etc.) propagates as a raw exception, not the documented type. Callers relying on the documented contract to catch OpenKineticsConfigurationError will miss these failures.
🐛 Proposed fix to align fallback path with documented behavior
from REvoDesign.bootstrap import REVODESIGN_CONFIG_DIR
environ_path = Path(REVODESIGN_CONFIG_DIR) / "environ.yaml"
logging.debug("ConfigBus is not initialized; writing OpenKinetics API key directly to %s.", environ_path)
- environ_path.parent.mkdir(parents=True, exist_ok=True)
- config = OmegaConf.load(environ_path) if environ_path.exists() else OmegaConf.create({"variables": {}})
- OmegaConf.update(config, f"variables.{DEFAULT_OPENKINETICS_API_KEY_ENV}", api_key, force_add=True)
- OmegaConf.save(config, environ_path)
+ try:
+ environ_path.parent.mkdir(parents=True, exist_ok=True)
+ config = OmegaConf.load(environ_path) if environ_path.exists() else OmegaConf.create({"variables": {}})
+ OmegaConf.update(config, f"variables.{DEFAULT_OPENKINETICS_API_KEY_ENV}", api_key, force_add=True)
+ OmegaConf.save(config, environ_path)
+ except Exception as exc:
+ raise OpenKineticsConfigurationError(f"Failed to persist OpenKinetics API key to {environ_path}.") from exc
logging.info("OpenKinetics API key saved to %s and applied immediately.", environ_path)
return api_keyAlso applies to: 103-113
🤖 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/REvoDesign/magician/designers/openkinetics/_client.py` around lines 68 -
69, The fallback persistence path in OpenKineticsClient does not match the
documented OpenKineticsConfigurationError contract, because direct file writes
can throw raw I/O or OmegaConf exceptions instead of the wrapped error. Update
the fallback branch in the OpenKinetics client’s configuration save flow to
catch persistence failures the same way the ConfigBus branch does, and re-raise
them as OpenKineticsConfigurationError with the original exception attached.
Keep the behavior consistent with the existing API key validation and
environment persistence logic so callers can reliably handle one exception type.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #180 +/- ##
==========================================
- Coverage 73.23% 73.02% -0.21%
==========================================
Files 121 121
Lines 15002 15002
==========================================
- Hits 10986 10955 -31
- Misses 4016 4047 +31 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
[ci skip]
1 participant
Changes
installation.mdandgetting-started.mdpyqt=5to conda install command ininstallation.md(matching CLAUDE.md)revodesigngetting-started.md(was identical to section 2).docxmanualTest results
make fast-test: 606 passed, 39 failed, 75 skipped, 67 errors — all failures are pre-existing (cfg_group,called_citations,setFont) and unrelated to docs.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Bug Fixes
Documentation
Tests