ciaochris/Vers3Dynamics-Civil-Reactor-Expert-3B

Vers3Dynamics Civil Reactor Expert 3B

Civil reactor reasoning, constrained by safety, built for auditable learning.

Vers3Dynamics Civil Reactor Expert 3B is a domain-specialized PEFT LoRA adapter for Qwen/Qwen2.5-3B-Instruct, built for civil reactor engineering education, point kinetics, xenon/iodine transient analysis, decay heat dynamics, non-operational safeguards reasoning, and defensive cyber-physical resilience. It ships with policy-enforced refusal boundaries around weapons, enrichment/separation recipes, safeguards evasion, sabotage, exploit payloads, and plant operational manipulation — enforced by an auditable serving-layer prefilter and taught by refusal training examples. Those boundaries are not benchmarked as jailbreak-proof; see Limitations and TECHNICAL_REPORT.md.

Property	Description
What	LoRA adapter (rank 4, α 8, dropout 0.05) targeting q_proj/v_proj on Qwen2.5-3B-Instruct
For	Civil-nuclear tutoring, point kinetics, xenon transient education, safeguards accountancy, defensive ICS concepts
Not for	Weapons, enrichment/separation recipes, safeguards evasion, sabotage, cyber offense, live plant operation
Grounded Tools	Includes civil_tools.py for exact, test-covered deterministic physics calculations (kinetics, xenon, decay heat, units)
Ships with	Machine-readable prompt policy, training/eval JSONL datasets, fail-closed data generators, guarded endpoint, test suite
Trained on	Compact synthetic, curated SFT data (QLoRA, 4-bit NF4). Published weights are a 5-step validation run — see Training Procedure
Benchmarks	None claimed — validation is schema-based, numeric-tolerance verified, and heuristic by design

⚠️ Required disclaimer. This model is for education, research prototyping, and safeguards reasoning demonstrations only. It encodes no licensed operating procedure and must never be used for real plant operation, licensing, compliance, emergency response, or safety-critical decisions.

📊 Dataset and Eval Audit. The expanded dataset (697 examples) and eval suite (180 prompts) surfaced and fixed a critical calculation bug: prior decay heat formulas lacked an exp() decay factor, returning impossible negative values. Detailed empirical findings across 3B, 9B, and 30B-A3B adapters are documented in evaluation_report.md and TECHNICAL_REPORT.md.

---

Defense in Depth Architecture

Safety and accuracy in Vers3Dynamics are layered so that every constraint is inspectable, executable, and reproducible:

flowchart TD
    User([User Prompt]) --> Filter[1. Policy Pre-Filter / Serving Layer\nblocked_topic_matches]
    Filter -- Disallowed Topic --> Refuse[Safe Refusal & Civil Redirection]
    Filter -- Allowed Topic --> Dispatcher{Numeric Physics Question?}
    Dispatcher -- Yes --> ToolLayer[2. Grounded Engine Tool Layer\ncivil_tools.py]
    ToolLayer --> Engines[Audited Deterministic Engines\nkinetics.py / xenon.py / units.py / reactor_types]
    Engines --> Formatter[Response Contract Formatter]
    Dispatcher -- No / Explanatory --> Model[3. Qwen2.5-3B-Instruct + PEFT LoRA Adapter]
    Model --> Formatter
    Formatter --> Response([Structured Response Contract Output])

1. Data layer — civil_discovery_dataset.py generates training examples deterministically and fails closed: any candidate matching blocked topics is rejected with an error.
2. Training layer — SFT training sets include explicit refusal examples for every disallowed domain, instilling refusal structure alongside civil reasoning.
3. Policy layer — prompt_policy.json encodes the machine-readable response contract and civil boundaries.
4. Grounded Tool layer — civil_tools.py routes arithmetic and physics evaluations directly to audited ODE & analytic engines (kinetics.py, xenon.py, units.py, reactor_types/physics.py), eliminating model arithmetic hallucination by construction.
5. Serving layer — examples/serve_local_endpoint.py enforces policy prefiltering before generation.
6. Evaluation layer — eval_safety_and_quality.py and eval_numeric_correctness.py score refusal precision/recall and numeric tolerance against exact physics ground truth.

---

Why This Exists

Most domain adapters ship weights and a brief description. This repository provides an open, auditable demonstration that domain-specific AI safety can be achieved through transparent, layered constraints — a scoped training set, an explicit prompt policy, refusal-required evaluation categories, fail-closed data generators, and a guarded serving layer with grounded physics computation. Every safety claim maps to a file you can read, a script you can run, and a test you can re-execute.

What This Is

• A domain-specialized Qwen/Qwen2.5-3B-Instruct LoRA adapter trained on compact civil-nuclear supervised examples.
• A safety-bounded civil reactor reasoning package for auditable learning and research prototyping.
• A structured asset repository: prompt policy, eval prompts, training examples, and training configurations are inspectable and regenerable.
• A Vers3Dynamics release focused on transparent engineering reasoning, not operational authority.

What This Is Not

• Not a full model checkpoint. This is a PEFT LoRA adapter; it requires the base model Qwen/Qwen2.5-3B-Instruct.
• Not a converged fine-tune. The published root weights come from a hardware-bounded 5-step validation run (see Training Procedure).
• Not a benchmarked safety system. No HarmBench/AdvBench score is claimed. Shipped checks are heuristic smoke tests.
• Not a plant operating tool. It encodes no licensed plant procedures and must never inform real-world control decisions.

Intended Use

• Civil reactor physics tutoring and conceptual education.
• Delayed-neutron groups and point kinetics concept explanation.
• Xenon-135 / Iodine-135 transient explanation and qualitative diagnosis.
• Axial flux shape interpretation and numerical quality-control discussions.
• Decay heat fundamentals and decay-chain inventory education.
• Non-operational safeguards material-balance (MUF) examples and measurement uncertainty review.
• Defensive cyber-physical architecture concepts for civil energy infrastructure.

Out-of-Scope Use

The model and repository must not be used for:

• Nuclear weapon design, component selection, yield estimation, or weapon effects.
• Fissile-material production optimization.
• Enrichment, separation, reprocessing, or recovery recipes.
• Safeguards evasion, concealment, tampering, or inspection defeat.
• Sabotage or physical/cyber vulnerability exploitation.
• ICS/SCADA exploit instructions, payloads, bypass logic, or intrusion steps.
• Real plant operating procedures or safety-critical reactor-control decisions.

Safety Scope Table

Domain	Allowed	Disallowed
Reactor physics	Conceptual tutoring, simplified equations, qualitative transient interpretation	Real plant procedures, setpoint changes, safety-critical control decisions
Kinetics	Delayed-neutron concepts, pcm/$\beta$ units, educational feedback accounting	Operational transient management or plant-specific action guidance
Xenon/iodine	Non-operational explanation of poisoning, lag, and axial effects	Procedure-level maneuver advice
Safeguards	Material-balance education, uncertainty, covariance, anomaly triage	Evasion, concealment, tampering, or avoiding detection
Fuel cycle	High-level civil accounting and burnup concepts	Production optimization, enrichment/separation/reprocessing recipes
Cyber-physical	Defensive architecture, segmentation, monitoring, incident-response concepts	Exploits, payloads, bypasses, sabotage, or intrusion workflows
Weapons	None	Design, effects, yield, material optimization, or targeting

---

Model Architecture

• Base model: Qwen/Qwen2.5-3B-Instruct
• Adapter type: PEFT LoRA (peft $\ge$ 0.10.0)
• Adapter rank: 4 (lora_alpha = 8, lora_dropout = 0.05) — see adapter_config.json
• Target modules: q_proj, v_proj
• Training approach: QLoRA SFT (4-bit NF4 quantization, double quant, fp16 compute)
• Primary language: English

---

Quickstart: Transformers + PEFT

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

BASE_MODEL_ID = "Qwen/Qwen2.5-3B-Instruct"
ADAPTER_ID = "ciaochris/Vers3Dynamics-Civil-Reactor-Expert-3B"

SYSTEM_PROMPT = (
    "You are Vers3Dynamics Civil Reactor Expert. Stay civil-nuclear only "
    "and use the required safety-bounded response structure."
)

tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL_ID)
base = AutoModelForCausalLM.from_pretrained(
    BASE_MODEL_ID, torch_dtype=torch.float16, device_map="auto"
)
model = PeftModel.from_pretrained(base, ADAPTER_ID)

# 1. Text Generation / Civil Engineering Q&A
messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": "Explain why Xe-135 can peak after a civil power reduction."},
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=512, do_sample=False)
print("--- Civil Q&A ---")
print(tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))

# 2. Reactor Feedback Classification (via Instruction Prompting)
classify_prompt = """Classify the following reactor feedback mechanism into one of [Doppler, Moderator Temperature, Void, Xenon Poisoning]:

Mechanism: Reactivity decreases as fuel temperature rises due to resonance absorption broadening in U-238.
Category:"""
inputs = tokenizer(classify_prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=20, do_sample=False)
print("\n--- Classification ---")
print(tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))

# 3. Technical Summarization
sum_messages = [
    {"role": "system", "content": "You are a civil nuclear engineering assistant. Provide a concise 3-bullet technical summary."},
    {"role": "user", "content": "Summarize the differences between delayed neutron fractions in U-235 vs Pu-239 thermal systems."},
]
prompt = tokenizer.apply_chat_template(sum_messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=256, do_sample=False)
print("\n--- Summarization ---")
print(tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))

---

Grounded Tools and Numeric-Correctness Evaluation

A 3B language model excels at conceptual explanation, but token-prediction models can hallucinate arithmetic, unit conversions, or signs. Vers3Dynamics pairs the adapter with audited, test-covered deterministic engines (kinetics.py, xenon.py, units.py, reactor_types/physics.py).

1. Grounded Tool Layer (civil_tools.py)

Exposes standard functions with OpenAI-compatible parameter schemas:

# List available tools
python civil_tools.py --list

# Compute equilibrium xenon and worth deterministically
python civil_tools.py --call xenon_equilibrium \
  --args '{"flux_n_cm2_s": 2.0e13, "sigma_f_per_cm": 0.043}'

# Calculate reactor period for a +50 pcm reactivity insertion
python civil_tools.py --call reactor_period \
  --args '{"rho_pcm": 50.0}'

2. Numeric-Correctness Evaluation (eval_numeric_correctness.py)

Perplexity metrics often reward template memorization. eval_numeric_correctness.py scores answers against ground truth computed on-the-fly by the physical engines:

# Run self-check validation on the numeric suite (no GPU needed)
python eval_numeric_correctness.py --self-check

# Score model responses against exact ground-truth values within tolerance
python eval_numeric_correctness.py --endpoint-url http://127.0.0.1:8017/v1/chat/completions

---

Quickstart: Local Guarded Endpoint

Launch the guarded OpenAI-compatible API endpoint:

python examples/serve_local_endpoint.py --host 127.0.0.1 --port 8017 --backend guarded-template

Query via curl or the provided client:

python examples/call_local_endpoint.py \
  --url http://127.0.0.1:8017/v1/chat/completions \
  --prompt "Explain delayed neutron groups for a civil reactor kinetics student."

---

Training Data Overview

Training datasets are stored as JSONL chat examples:

File	Contents	Examples
training_examples.jsonl	Seed SFT examples	10
discovery_training_examples.jsonl	Deterministic safe examples from civil discovery patterns	6
expanded_training_examples.jsonl	Combined SFT dataset (seed, calculations, safeguards, decay, refusals)	36
tinker_training_examples_v2.jsonl	Expanded multi-phrasing SFT set with corrected decay heat formulas	697

---

Training Procedure

train_lora.py supports:

• Dry-run configuration and dataset diagnostics without ML dependencies.
• Deterministic seed handling (seed = 42).
• QLoRA 4-bit NF4 configuration with double quantization and paged optimizers.

# Dry-run validation (no ML dependencies required)
python train_lora.py --dry-run

# Run local QLoRA fine-tuning
pip install -r requirements-train.txt
python train_lora.py

Material disclosure: training_config.json uses max_steps=5 with batch size 1 and gradient accumulation 4. Published root weights are a pipeline-validation artifact, not a converged fine-tune.

---

Evaluation Methodology

The evaluation suite (eval_prompts.jsonl, eval_prompts_v2.jsonl) tests both civil technical reasoning and mandatory refusal boundaries:

# Schema validation & category summary (no GPU needed)
python eval_safety_and_quality.py --dry-run

# Score live endpoint for refusal precision, recall, and false-positive rates
python eval_safety_and_quality.py --endpoint-url http://127.0.0.1:8017/v1/chat/completions

---

Safety Evaluation Methodology

The safety evaluation suite verifies:

• JSONL schema integrity and zero duplicate prompt IDs.
• Deterministic refusal of prohibited requests (weapons, enrichment recipes, safeguards evasion, sabotage, cyber intrusion).
• Absence of false-positive over-refusal on legitimate safe civil prompts.
• Fail-closed error handling in tool execution.

---

Response Contract

All civil nuclear responses follow a standardized, auditable structure:

## System Boundaries & Assumptions
## Governing Physics / Logic
## Civil Analysis
## Reliability & Safety Considerations
## Limitations

Math: Valid LaTeX expressions with defined variables, units, and clear physical assumptions.
Code: Typed, modular implementations with no operational execution payloads.

---

File Inventory

File	Purpose
README.md	Model card and repository guide
TECHNICAL_REPORT.md	Evidence audit, provenance, and experimental results
evaluation_report.md	Scaling, generalization, and decay-heat bugfix findings
adapter_config.json	PEFT LoRA configuration
adapter_model.safetensors	LoRA adapter weights
prompt_policy.json	Machine-readable safety policy and response contract
civil_tools.py	Grounded tool execution layer (OpenAI schemas + exact physics)
eval_numeric_correctness.py	Numeric tolerance evaluation harness
kinetics.py	Six-group point kinetics and inhour equation solver
xenon.py	Xe-135 / I-135 transient equations and reactivity worth
units.py	Dimensional analysis and reactivity unit conversions
reactor_types/	PWR, BWR, and CANDU parameters and physics models
civil_safety.py	Safety filter and dataset schema validators
train_lora.py	Dry-run and LoRA/QLoRA training script
examples/serve_local_endpoint.py	Guarded local OpenAI-compatible endpoint
tests/	Complete pytest test suite covering physics, tools, and safety

---

Reproducibility

pip install -e ".[dev]"
make validate
make eval-numeric
make test

Direct script commands:

python civil_discovery_dataset.py --output discovery_training_examples.jsonl --seed 42 --summary
python model_quality_assets.py --seed 42
python eval_safety_and_quality.py --dry-run
python eval_numeric_correctness.py --self-check
python -m pytest tests/

---

Limitations and Failure Modes

• Validation Artifact: The published root 3B adapter is a 5-step validation artifact.
• Arithmetic in Token Prediction: Language models can miscalculate numbers when generating directly from weights. Route numeric physics queries through civil_tools.py.
• Simplified Point Kinetics: The equations assume a point reactor with separable spatial flux and do not model full 3D nodal kinetics.
• English Plaintext Policy: The lightweight safety prefilter is single-turn and English-focused. In sensitive environments, deploy behind multi-layer content moderation.
• Non-Operational: The model encodes no plant-specific operating procedures, technical specifications, or emergency protocols.

---

Reporting Issues

Found a safety edge case, an under-refusal, or a calculation issue? Open an issue in the Community Tab with the prompt, observed output, and runtime configuration.

---

License

The adapter is released under the Qwen Research License inherited from the base model Qwen/Qwen2.5-3B-Instruct.

---

Citation and Attribution

@misc{vers3dynamics_civil_reactor_expert_3b,
  title        = {Vers3Dynamics Civil Reactor Expert 3B},
  author       = {Woodyard, Christopher},
  organization = {Vers3Dynamics},
  year         = {2026},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/ciaochris/Vers3Dynamics-Civil-Reactor-Expert-3B}}
}

---

Vers3Dynamics Project Note

Vers3Dynamics is an independent research practice spanning theoretical physics, structural economics, adaptive AI, and wellness tooling. This release applies its core values to civil-nuclear AI: constrained scope, auditable reasoning, refusal of unsafe use, and transparent tooling.

---

Disclaimer

This model is for education, research prototyping, and safeguards reasoning demonstrations only. It is not a validated engineering tool, not a source of operational guidance, and not a safety-qualified system. The published weights are a short validation run, not a converged fine-tune. Do not use it for real plant operation, licensing, compliance, emergency response, or any safety-critical decision. All safety boundaries here are auditable but unbenchmarked: deploy behind the included policy prefilter and treat every output as educational content requiring independent expert review.