[heavyrain-lzy]

Summary

Add FlagOS engine support and has been verified on Nvidia platform. Unify environment variable naming, add FlagGems duplicate-load protection, and supplement user documentation and test coverage.

Motivation

Changes

• Rename environment variable: USE_FLAGGEMS → TRAINING_FL_FLAGGEMS_ENABLE to align with the training-phase variable prefix
• FlagGems deduplication: Add sys.modules check in may_enable_flag_gems() to prevent redundant enable calls in collocated processes
• New environment variable keys: Add TE_FL_PLUGIN_MODULES and TE_FL_SKIP_CUDA to env snapshot management
• FSDP engine log level: Change fsdp_flagos.py default log level from WARN to INFO for easier debugging
• Documentation: Add install_guidance.md, quick_start.md, env_reference.md, and faq.md
• Test coverage: Fix tests using the old variable name, add TestMayEnableFlagGems class covering deduplication logic, whitelist/blacklist conflict detection, and env snapshot validation

Testing

• pytest tests/ -v -k "TestFLEnvManager or TestMayEnableFlagGems" — all 16 cases pass
• Manually verified FSDP + FlagGems training pipeline on Nvidia A100
• pytest tests/ -v passes (Engine/Platform registration tests depend on upstream verl vendor parameter support, pending verl#6086 ([hardware] feat: add platform abstraction layer and plugin-based engine override system verl#6086))

Checklist

• Code follows the project's style and passes pre-commit checks
• Documentation updated
• No secrets or credentials included

[gemini-code-assist]

Code Review

This pull request updates the FlagOS documentation and refactors environment variable handling, transitioning from USE_FLAGGEMS to TRAINING_FL_FLAGGEMS_ENABLE for training. Feedback highlights the need for phase-awareness when checking if FlagGems is enabled, warns against a fragile sys.modules check that could bypass enablement, and corrects a git checkout command in the installation guide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

There are two issues with the current implementation:

1. Phase-awareness: It calls FLEnvManager.is_flaggems_enabled() without passing the phase argument, meaning it will always check TRAINING_FL_FLAGGEMS_ENABLE even when phase="rollout".
2. Fragile sys.modules check: Checking "flag_gems" in sys.modules to skip enablement is highly fragile. If flag_gems is imported anywhere else in the codebase (or by a dependency) prior to this function call, it will be present in sys.modules but its operators will not have been enabled. This will cause may_enable_flag_gems to silently return early without actually enabling FlagGems. Since flag_gems.enable and flag_gems.only_enable are already called with once=True (which internally handles deduplication safely), this manual check is redundant and should be removed.

Suggested change

	if not FLEnvManager.is_flaggems_enabled():
	logger.debug("FlagGems is not enabled (USE_FLAGGEMS not set)")
	logger.debug("FlagGems is not enabled (TRAINING_FL_FLAGGEMS_ENABLE not set)")
	return
	# collocate processes should have the same FlagGems state, so we check if it's already imported
	# to avoid redundant enable calls
	if "flag_gems" in sys.modules:
	logger.debug("FlagGems is already imported, skipping enable")
	return
	if not FLEnvManager.is_flaggems_enabled(phase):
	logger.debug("FlagGems is not enabled for %s phase", phase)
	return

[gemini-code-assist]

The is_flaggems_enabled method currently only checks TRAINING_FL_FLAGGEMS_ENABLE. However, for the rollout/inference phase, the environment variable USE_FLAGGEMS is used instead (as documented in env_reference.md and faq.md). To support both phases correctly, is_flaggems_enabled should accept a phase parameter and check the appropriate environment variable depending on the phase.

Suggested change

	@classmethod
	def is_flaggems_enabled(cls) -> bool:
	return os.getenv("USE_FLAGGEMS", "").lower() in ("1", "true")
	return os.getenv("TRAINING_FL_FLAGGEMS_ENABLE", "").lower() in ("1", "true")
	@classmethod
	def is_flaggems_enabled(cls, phase: str = "training") -> bool:
	if phase == "training":
	return os.getenv("TRAINING_FL_FLAGGEMS_ENABLE", "").lower() in ("1", "true")
	return os.getenv("USE_FLAGGEMS", "true").lower() in ("1", "true")