Inspiration
Serpent Monte Carlo input files are compact but unforgiving. A duplicated definition, missing surface, contradictory region expression, or detector binning mistake can waste substantial computation time and be difficult to locate.
What it does
SerpentGuard is a local Streamlit preflight checker for a deliberately limited, documented subset of Serpent syntax. It parses local files and produces source-located, deterministic findings without relying on AI. Current checks cover selected surf, cell, mat, ene, and det syntax, including duplicate and undefined references, contradictory or repeated signed conditions, detector and energy-grid sanity checks, and unsupported syntax.
The interface separates two views:
- Geometry view colors the supported sampled model by material or cell.
- Diagnostic view maps overlap candidates, undefined-region candidates, incomplete areas, and boundary uncertainty.
Universe-local XY sampling supports only the documented limited surface subset. Sandboxed PBED support can resolve explicitly uploaded or explicitly authorized local placement data referenced by the supported pbed card, with path, file-size, and record-count safeguards. General include resolution, lattice expansion, transformations, and full 3D CSG are not implemented. The Streamlit interface supports English and Japanese.
Privacy-preserving AI review
Deterministic analysis remains local. Raw Serpent input, full comments, full material composition, absolute paths, and API keys are excluded from the versioned AIReviewPayload. Before any optional OpenAI request, the user sees the exact JSON preview, gives consent, and explicitly presses Generate AI explanation. Only that reviewed payload is sent. Static findings remain visible and authoritative if AI review is unavailable or fails.
How we built it
SerpentGuard uses Python 3.11+, Streamlit, Pydantic, NumPy, Matplotlib, pytest, Ruff, and the optional OpenAI API. Codex and GPT-5.6 were used as implementation partners across incremental milestones: architecture, authoritative syntax research, independent synthetic fixtures, parser and rule development, geometry and PBED support, bilingual presentation, privacy-boundary design, tests, and corrective engineering review. Runtime findings remain deterministic; AI does not perform or override the core checks.
How to test
Supported platforms are Windows, macOS, and Linux with Python 3.11 or newer.
git clone https://github.com/TogashiToshiyuki/SerpentGuard.git
cd SerpentGuard
python -m venv .venv
Activate the environment with .venv\Scripts\Activate.ps1 on Windows PowerShell or source .venv/bin/activate on macOS/Linux.
For deterministic use:
python -m pip install --upgrade pip
python -m pip install --editable .
streamlit run app.py
For the optional AI feature, install python -m pip install --editable ".[ai]" and configure OPENAI_API_KEY locally. Public synthetic demo inputs are under examples/demo/; no private research data, hosted service, test credentials, or API key is required for deterministic testing.
Limitations
SerpentGuard is an experimental, limited preflight tool—not complete Serpent compatibility. Sampling can miss narrow defects and does not replace Serpent's geometry plotter. Detector checks do not judge physics suitability. PBED placement visualization does not prove packing or three-dimensional overlap validity. AI explanations may be incomplete or wrong and never override deterministic findings. SerpentGuard does not replace Serpent, physical validation, qualified engineering review, or reactor/criticality safety review.