[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-94772":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},94772,"ai-nuclear-spectroscopy","JWP-p\u002Fai-nuclear-spectroscopy","JWP-p","An auditable human–AI workflow from NNDC\u002FENSDF data to gamma-ray GCD lifetime inference.","",null,"Python",78,4,3,1,0,42.1,"Apache License 2.0",false,"main",true,[23,24,25,26,27,28,29,30,31],"ai-for-science","ensdf","gamma-ray-spectroscopy","gcd-lifetime","nndc","nuclear-physics","nuclear-spectroscopy","reproducible-research","scientific-agents","2026-08-24 04:01:22","# AI Nuclear Spectroscopy\n\n[![Tests](https:\u002F\u002Fgithub.com\u002FJWP-p\u002Fai-nuclear-spectroscopy\u002Factions\u002Fworkflows\u002Ftests.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FJWP-p\u002Fai-nuclear-spectroscopy\u002Factions\u002Fworkflows\u002Ftests.yml)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache--2.0-blue.svg)](LICENSE)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11%2B-3776ab.svg)](pyproject.toml)\n[![Scientific status](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-reference%20workflow-orange.svg)](docs\u002Flimitations.md)\n\n**An open, auditable path from nuclear data to gamma-coincidence lifetime inference—for researchers and scientific agents learning to reason from evidence together.**\n\nAI Nuclear Spectroscopy turns a research workflow that is often scattered across database queries, analysis scripts, plots, prompts, and expert memory into an explicit chain of evidence. It connects provenance-preserving NNDC\u002FENSDF retrieval, source-local cascade screening, experimental-statistics checks, structured AI review, a human approval boundary, and generalized centroid-difference (GCD) lifetime estimation.\n\nThis is not a code dump and it is not an automated claim generator. It is a compact reference implementation of how human expertise and machine assistance can meet on inspectable scientific ground: every candidate keeps its source identity, every recommendation carries supporting and opposing evidence, every lifetime estimate states its uncertainty scope, and every formal scientific decision remains with a qualified researcher.\n\n> **Vision:** Make scientific reasoning visible enough that another physicist can challenge it, another laboratory can reproduce it, and a scientific agent can follow the same evidence without silently inventing missing steps.\n\n## Why this project matters\n\nNuclear-spectroscopy analysis is not one calculation. It is a sequence of judgments: which evaluated record was used, whether transitions form a physically consistent path, whether all required peaks have usable statistics, how timing backgrounds were subtracted, whether the prompt-response-difference calibration applies, and which conclusions have passed human review. When those judgments remain implicit, neither people nor AI systems can reliably audit, reproduce, or improve the work.\n\nThis repository makes those decisions first-class data. Its value is the workflow contract:\n\n- **For experimentalists:** a small, readable foundation for screening and documenting lifetime candidates.\n- **For maintainers:** deterministic identifiers, provenance manifests, tests, and explicit release boundaries.\n- **For scientific-agent builders:** structured evidence and counterevidence instead of unconstrained prose or hidden reasoning.\n- **For the wider ecosystem:** a reusable example of AI assistance that preserves human scientific authority.\n\nThe long-term ambition is larger than any one isotope or detector setup: help build a scientific ecosystem in which human researchers and AI agents work from the same transparent evidence, improve one another's questions and tools, and develop better models of nature together. Public availability can make the workflow useful for education, benchmarking, agent evaluation, and future research; it does **not** imply that any organization will use this repository for model training.\n\n## The evidence chain\n\n```mermaid\nflowchart LR\n    A[\"Public NNDC \u002F ENSDF records\"] --> B[\"Provenance-preserving parser\"]\n    B --> C[\"Source-local F-D-G cascade screening\"]\n    C --> D[\"Experimental-statistics assessment\"]\n    D --> E[\"Structured AI evidence review\"]\n    E --> F{\"Explicit human approval\"}\n    F -->|approved scope| G[\"Four-region timing subtraction\"]\n    G --> H[\"Signed iterative centroids\"]\n    H --> I[\"PRD-corrected GCD estimate\"]\n    I --> J[\"Manifest, report, and limitations\"]\n    F -->|not approved| K[\"Hold before lifetime analysis\"]\n```\n\nThe reference pipeline deliberately keeps three outcomes separate:\n\n1. **Machine-supported recommendation** — a traceable prioritization, not a physics conclusion.\n2. **Human-approved analysis scope** — permission to run a defined step, not a publication decision.\n3. **Lifetime estimate** — an analysis output whose formal use still requires detector-specific validation, systematics, review, and collaboration authorization.\n\n## What is implemented\n\n- An opt-in NNDC ENSDF\u002FXUNDL retrieval client that records URLs, retrieval time, dataset identifiers, byte count, and SHA-256.\n- An inspectable subset parser for ENSDF identification, level, and gamma records.\n- Deterministic, source-local three-transition cascade enumeration in both remote-gate orientations.\n- Transparent signal-minus-scaled-background count assessment.\n- Structured, deterministic agent-review records with claim, evidence, counterevidence, confidence, recommendation, and next action.\n- A three-round selector–critic–synthesis trace that demonstrates iterative agent review offline before the human gate.\n- An explicit human-approval gate before the timing stage.\n- Four-region timing subtraction:\n\n  ```text\n  net = peak - scale_x * background_x - scale_y * background_y\n        + scale_xy * background_xy\n  ```\n\n- Signed iterative centroids with convergence and two-cycle handling.\n- A prompt-response-difference model, covariance propagation, and GCD lifetime estimate:\n\n  ```text\n  delta_C = C_delay - C_anti\n  delta_R = R(E_decay) - R(E_feeder)\n  tau     = (delta_C - delta_R) \u002F 2\n  T_1\u002F2   = ln(2) * tau\n  ```\n\n- A fully deterministic synthetic end-to-end example, tests, public-surface scanning, and CI.\n\n## Quick start\n\nThe package has no mandatory third-party runtime dependency.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FJWP-p\u002Fai-nuclear-spectroscopy.git\ncd ai-nuclear-spectroscopy\npython3 -m venv .venv\nsource .venv\u002Fbin\u002Factivate\npython -m pip install -e '.[dev]'\nanspec demo --config configs\u002Fdemo_workflow.json --output demo-output\n```\n\nThe demo uses a fictional nucleus and deterministic synthetic timing spectra. Expected terminal fields include:\n\n```json\n{\n  \"stage\": \"GCD_ESTIMATED\",\n  \"candidate_count\": 4,\n  \"scientific_status\": \"SYNTHETIC_ESTIMATE_NOT_FORMAL_RELEASE\"\n}\n```\n\nInspect the supported ENSDF subset:\n\n```bash\nanspec inspect-ensdf \\\n  --input examples\u002Fsynthetic_ensdf\u002Ffictional_999xx.ens \\\n  --source-id SYNTHETIC_ENSDF_FIXTURE_V1\n```\n\nRetrieve public upstream records only when you explicitly choose to do so:\n\n```bash\nanspec fetch-ensdf \\\n  --nucleus 102Mo \\\n  --source ensdf \\\n  --output-dir local-data\u002F102Mo\n```\n\nUpstream data are intentionally not vendored. Review the generated retrieval manifest and follow NNDC citation guidance before using fetched records in research.\n\n## Demonstration outputs\n\nRunning the synthetic workflow creates:\n\n| File | Purpose |\n|---|---|\n| `workflow_result.json` | Complete machine-readable evidence chain |\n| `workflow_report.md` | Human-readable scientific summary and boundaries |\n| `provenance_manifest.json` | Input hashes, configuration hash, software version, and generation time |\n\nThe demo is useful for software verification and agent-protocol experiments. It is not evidence for a real nucleus, detector, or lifetime.\n\n## Repository map\n\n```text\nsrc\u002Fai_nuclear_spectroscopy\u002F  Reference implementation\nconfigs\u002F                      Synthetic and detector\u002FPRD configuration examples\nexamples\u002F                     Fictional ENSDF fixture and runnable walkthrough\nprompts\u002F                      Evidence-first scientific-agent protocols\ndocs\u002F                         Architecture, methods, governance, vision, and limits\ntests\u002F                        Unit and end-to-end tests\ntools\u002F                        Public-release safety audit\n```\n\nStart with [the scientific workflow](docs\u002Fscientific_workflow.md), then read [the GCD method](docs\u002Fgcd_method.md), [the agent protocol](docs\u002Fagent_protocol.md), [the release verification](docs\u002Fverification.md), and [the scientific limitations](docs\u002Flimitations.md).\n\n## Safety, provenance, and scientific boundaries\n\n- The repository contains **no real experimental event data**, unpublished spectra, credentials, private keys, collaboration-only documents, or machine-specific paths.\n- The bundled nuclear scheme and timing spectra are **fictional and synthetic**.\n- The ENSDF parser is a documented subset, not a replacement for official NNDC\u002FENSDF tooling or evaluator judgment.\n- AI outputs are review records, not authorship, approval, or authority.\n- A passing test suite proves software behavior under its fixtures; it does not validate a detector response, a physical assignment, or a publishable lifetime.\n- Users remain responsible for data rights, collaboration policy, source citation, calibration validity, uncertainty modeling, and formal scientific review.\n\nSee [data governance](docs\u002Fdata_governance.md), [provenance and citation](docs\u002Fprovenance_and_citation.md), [authorship and AI assistance](docs\u002Fauthorship_and_ai.md), and [the public-release audit](docs\u002Fopen_source_audit.md).\n\n## Project status\n\nVersion `0.1.0` is an **alpha reference workflow**. Its synthetic vertical slice and public NNDC integration path are tested; real-experiment adapters, detector-specific validation, full ENSDF coverage, and formal release procedures remain outside this first public version.\n\n## Contributing\n\nContributions that improve auditability, physical correctness, test coverage, documentation, or interoperability are welcome. The fastest way to start is:\n\n1. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [GOVERNANCE.md](GOVERNANCE.md).\n2. Choose a focused issue or propose one before changing a scientific contract.\n3. Use a branch and pull request; keep synthetic fixtures clearly synthetic.\n4. Run `pytest`, `ruff check .`, `python tools\u002Fpublic_surface_audit.py`, and `python tools\u002Fvalidate_release_metadata.py`.\n5. Describe evidence, counterevidence, uncertainty, and remaining scope in the pull request.\n\nGood first contribution areas include ENSDF edge-case tests, GCD\u002FPRD validation, synthetic ROOT\u002Fuproot adapters, agent-schema evaluation, and documentation. Read [SECURITY.md](SECURITY.md) for sensitive reports, and preserve the project's evidence-first and human-approval boundaries.\n\n## Citation\n\nIf this software supports your work, cite the repository metadata in [CITATION.cff](CITATION.cff). Cite every nuclear-data evaluation and experimental source separately; software citation never replaces data citation.\n\n## License\n\nCopyright 2026 PanDa.\n\nLicensed under the [Apache License 2.0](LICENSE). Third-party data and publications retain their own terms and are not redistributed by this repository.\n","这是一个面向核物理研究的可审计人机协同工作流工具，用于从NNDC\u002FENSDF核数据库中提取γ射线谱数据，并完成级联跃迁筛选、统计有效性检验、AI辅助审查及广义质心差分法（GCD）寿命推断。项目采用Python实现，强调证据链可追溯性：每个候选寿命估计均保留原始数据来源、支持与反对证据、不确定性量化，并设置明确的人工审核边界。适用于核谱学实验分析、核数据验证、可复现科研流程构建及科学智能体（scientific agents）的推理训练场景。",2,"2026-08-15 02:30:13","CREATED_QUERY"]