feat: add environment compatibility checker for robust local setup

README.md

@@ -140,7 +140,7 @@ Outputs:
 
 <!-- LATEST_PROGRESS_START -->
 ## Latest Progress
-- 2026-03-22 15:21:52 UTC — Improved QA: added inference fallback unit tests + CI test stage
+- 2026-03-22 15:22:20 UTC — Added environment compatibility guardrail
 - Full log: `logs/progress.md`
 <!-- LATEST_PROGRESS_END -->
 
@@ -462,3 +462,12 @@ python src/space_smoke_test.py
 ```
 Output:
 - `docs/SPACE_SMOKE_TEST.md`
+
+
+## Environment Compatibility Check
+Validate runtime compatibility before full dependency install:
+```bash
+python src/env_compat_check.py
+```
+Output:
+- `docs/ENV_COMPAT.md`

docs/ENV_COMPAT.md

@@ -0,0 +1,13 @@
+# Environment Compatibility Check
+
+Generated: 2026-03-22 15:22 UTC
+- Python: `3.14.3`
+- Platform: `macOS-26.1-arm64-arm-64bit-Mach-O`
+
+## Issues
+- Python 3.14 may fail building scipy from source on some macOS setups (Fortran toolchain missing).
+
+## Recommendations
+- Use Python 3.11/3.12 for smoother scientific package installation.
+- Prefer virtualenv: `python3 -m venv .venv && source .venv/bin/activate`
+- Install base test deps for lightweight checks: `pip install numpy joblib`

logs/progress.md

@@ -167,3 +167,7 @@ Implemented `src/space_smoke_test.py` to verify both Hugging Face page URL and h
 ## 2026-03-22 15:21:52 UTC — Improved QA: added inference fallback unit tests + CI test stage
 
 Added `tests/test_infer_fallback_unittest.py` and extended CI workflow to run unit tests for streaming + inference fallback reliability.
+
+## 2026-03-22 15:22:20 UTC — Added environment compatibility guardrail
+
+Implemented `src/env_compat_check.py` to detect Python/scipy compatibility risks (e.g., py3.14 + Fortran build issues) and provide setup recommendations in `docs/ENV_COMPAT.md`.

src/env_compat_check.py

@@ -0,0 +1,50 @@
+"""
+Environment compatibility check for reliable local setup.
+Focus: Python version and scientific stack installability constraints.
+"""
+from pathlib import Path
+import platform
+from datetime import datetime, timezone
+
+
+def main():
+    py = platform.python_version()
+    major_minor = tuple(map(int, py.split('.')[:2]))
+
+    issues = []
+    recs = []
+
+    if major_minor >= (3, 14):
+        issues.append('Python 3.14 may fail building scipy from source on some macOS setups (Fortran toolchain missing).')
+        recs.append('Use Python 3.11/3.12 for smoother scientific package installation.')
+    else:
+        recs.append('Python version is compatible with common scipy wheels.')
+
+    recs.append('Prefer virtualenv: `python3 -m venv .venv && source .venv/bin/activate`')
+    recs.append('Install base test deps for lightweight checks: `pip install numpy joblib`')
+
+    ts = datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')
+    lines = [
+        '# Environment Compatibility Check',
+        '',
+        f'Generated: {ts}',
+        f'- Python: `{py}`',
+        f'- Platform: `{platform.platform()}`',
+        '',
+        '## Issues',
+    ]
+    if issues:
+        lines += [f'- {x}' for x in issues]
+    else:
+        lines += ['- None detected.']
+
+    lines += ['', '## Recommendations']
+    lines += [f'- {x}' for x in recs]
+
+    out = Path('docs/ENV_COMPAT.md')
+    out.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+    print(f'Generated {out}')
+
+
+if __name__ == '__main__':
+    main()