hg-mc-auto 0.1.0__tar.gz

hg_mc_auto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chufan Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hg_mc_auto-0.1.0/PKG-INFO

@@ -0,0 +1,501 @@
+Metadata-Version: 2.4
+Name: hg-mc-auto
+Version: 0.1.0
+Summary: Element-aware automation toolkit for isotope analysis workflows.
+Author: IGeochemCloud
+License: MIT
+Project-URL: Homepage, https://github.com/IGeochemCloud/Hg-MC-Auto
+Project-URL: Repository, https://github.com/IGeochemCloud/Hg-MC-Auto
+Project-URL: Issues, https://github.com/IGeochemCloud/Hg-MC-Auto/issues
+Keywords: isotope,mc-icp-ms,automation,mcp,agent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ml
+Requires-Dist: scikit-learn>=1.6; extra == "ml"
+Requires-Dist: xgboost>=2.1; extra == "ml"
+Requires-Dist: joblib>=1.2; extra == "ml"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.0; extra == "release"
+Dynamic: license-file
+
+# Hg-MC-Auto
+
+Hg-MC-Auto is an element-aware automation toolkit for isotope analysis workflows, with bilingual CLI support, agent-facing MCP tooling, and cross-platform Python packaging.
+![alt text](<docs/Graphic abstract.png>)
+
+- [A data-driven, post-acquisition quality diagnostic pipeline for isotope analysis by MC-ICP-MS](https://pubs.rsc.org/ja/article-abstract/41/5/1894/1230352/A-data-driven-post-acquisition-quality-diagnostic?redirectedFrom=fulltext)
+
+
+## Quick summary
+
+- User-ready package: `pip install hg-mc-auto`
+- CLI entry points: `hgmc` and `hg-mc-auto`
+- Supported elements: `hg`, `fe`, `cd`
+- Platforms: Windows, Linux, macOS
+- Release flow: `hgmc-release` and `hgmc release`
+
+---
+
+## 1) User guide
+
+### Install
+
+```bash
+python -m venv hg-mc-auto
+source hg-mc-auto/bin/activate
+pip install --upgrade pip
+pip install hg-mc-auto
+```
+
+On Windows PowerShell:
+
+```powershell
+python -m venv hg-mc-auto
+hg-mc-auto\Scripts\activate
+pip install --upgrade pip
+pip install hg-mc-auto
+```
+
+### Start the app
+
+```bash
+hgmc
+```
+
+Or:
+
+```bash
+hg-mc-auto
+```
+
+### Common CLI commands
+
+```bash
+hgmc --help
+hgmc list-elements
+hgmc workflow --element fe
+hgmc run --element fe --task export --language zh
+hgmc language --lang en
+hgmc platform
+hgmc project-summary
+hgmc guide --element hg --language zh
+```
+
+Use `hgmc list-elements` to check maturity. At present, Hg is the production
+legacy workflow; Fe and Cd are scaffolds, not validated element-specific
+analytical pipelines. The generic `run` command resolves task metadata and must
+not be mistaken for executing a complete scientific workflow for every element.
+
+### Structured QC and optional LLM interpretation
+
+The QC assistant accepts structured metrics, results, and anomaly flags. It does
+not send raw instrument files by default, and an LLM response is advisory only:
+the result remains `pending_human_review`.
+
+```bash
+hgmc qc --input docs/qc_packet.example.json
+```
+
+For a near-real-time, read-only directory monitor, point the command at the
+directory where the calculation or prediction workflow writes result files:
+
+```bash
+hgmc monitor --directory results --element hg --once
+```
+
+Remove `--once` to keep polling. The monitor emits a `qc.v1` packet when a JSON,
+CSV, or Excel result file is created or modified. It does not change instrument
+settings or automatically approve a recommendation.
+
+To request an interpretation through an OpenAI-compatible provider such as
+OrcaRouter, set the provider key first:
+
+```bash
+export ORCA_KEY="your-key"
+hgmc qc --input docs/qc_packet.example.json --llm --language zh
+```
+
+The assistant can explain quality signals, rank plausible causes, and suggest
+checks. It must not directly change instrument parameters or start an
+instrument run.
+
+### Install with MCP support
+
+```bash
+pip install "hg-mc-auto[mcp]"
+hgmc mcp --action status
+```
+
+### Connect this checkout to VS Code Agent
+
+When opening this repository as the VS Code workspace, it includes
+`.vscode/mcp.json`. Run **MCP: List Servers**, select `hg-mc-auto`, then start
+the server. In Chat, choose Agent mode and enable the server's tools. If VS Code
+does not discover the configuration, run **Developer: Reload Window** and
+inspect **MCP: Show Installed Servers**.
+
+The workspace configuration uses the repository-local virtual environment. If
+you moved or renamed that environment, update the command in `.vscode/mcp.json`.
+
+Try asking the Agent: “Use Hg-MC-Auto MCP to list the supported elements and
+explain the Hg workflow.” It should call `list_elements` and `resolve_workflow`.
+
+Current tools provide metadata, workflow routing, plans, and structured QC
+packet creation. In particular, `run_element_task` only resolves the target
+script; it does not execute Evaluation GUI automation or control the instrument.
+
+### Notes
+
+- If you only need normal usage, `pip install hg-mc-auto` is enough.
+- `hgmc` is the recommended command for end users.
+- `python src/main.py` remains available for legacy local development workflows.
+
+---
+
+## 2) Developer guide
+
+### Clone and set up the repo
+
+```bash
+git clone https://github.com/IGeochemCloud/Hg-MC-Auto.git
+cd Hg-MC-Auto
+python -m venv hg-mc-auto
+source hg-mc-auto/bin/activate
+pip install --upgrade pip
+pip install -e .
+pip install -r requirements.txt
+```
+
+### Run tests
+
+```bash
+PYTHONPATH=. python -m unittest tests.test_main_cli -v
+```
+
+### CLI development
+
+```bash
+hgmc --help
+hgmc list-elements
+hgmc workflow --element fe
+hgmc run --element cd --task export --language en
+```
+
+See [docs/ELEMENT_EXPANSION.md](docs/ELEMENT_EXPANSION.md) for reviewed
+MC-ICP-MS method references, element support gates, and the proposed plugin
+contract.
+
+### MCP development
+
+```bash
+hgmc mcp --action status
+hgmc mcp --action tools
+hgmc mcp --action json
+hgmc mcp --action stdio
+```
+
+The stdio action is intended for agent/IDE integrations. It is compatible with the installed `mcp` 2.x API and exposes the project’s tool surface over standard input/output.
+
+The MCP layer can later expose the same structured QC packet and advisory
+assessment to an agent. Keep the human approval step outside the model: an
+agent may prepare a review, but a qualified operator confirms any action.
+
+### Release flow
+
+The recommended way to publish a new version to both GitHub and PyPI is the
+one-command sync helper. It validates the version, refuses to run with
+uncommitted changes, checks credentials, then builds, tags, pushes to GitHub,
+and uploads to PyPI.
+
+```bash
+# 1. Bump the version in pyproject.toml (e.g. 0.1.1)
+# 2. Commit your changes
+# 3. Export your PyPI token (never commit it)
+export PYPI_TOKEN="your-token"
+
+# 4. Dry-run to validate without publishing
+hgmc-release sync --version 0.1.1 --dry-run
+
+# 5. Publish to GitHub and PyPI together
+hgmc-release sync --version 0.1.1 --message "release 0.1.1"
+```
+
+The sync helper will fail early if the requested version does not match
+`pyproject.toml`, if the git tag already exists, if the working tree is dirty,
+or if `PYPI_TOKEN` / `twine` are missing.
+
+Individual steps are also available:
+
+```bash
+hgmc-release check
+hgmc-release build
+hgmc-release publish
+```
+
+### PyPI publishing
+
+```bash
+python -m build
+python -m twine upload dist/*
+```
+
+Set `PYPI_TOKEN` before publishing if you are using automation. Create the token
+at https://pypi.org/manage/account/token/ and use `__token__` as the username.
+
+### OrcaRouter open-source maintainer application
+
+The project can apply through [OrcaRouter Built With](https://www.orcarouter.ai/zh-CN/built-with).
+The page currently states that the repository must be public, owned by the
+applicant, and contain commits from the applicant's GitHub account; approval is
+manual. Listing is attribution and support, not an endorsement or an exclusive
+provider agreement. Other model providers can remain supported.
+
+Before applying, publish the repository and make the project description clear:
+structured MC-ICP-MS QC, bilingual workflow support, MCP integration, and
+human-confirmed recommendations. Do not include API keys, raw laboratory data,
+or private instrument credentials in the repository.
+
+---
+
+## 3) Project structure
+
+![alt text](<docs/Overall Architecture Diagram.png>)
+
+```bash
+Hg-MC-Auto/
+├── src/
+│   ├── main.py
+│   ├── hg_mc_auto/
+│   │   ├── cli.py
+│   │   ├── mcp_server.py
+│   │   ├── release.py
+│   │   ├── core/
+│   │   └── ...
+│   └── ...
+├── tests/
+├── docs/
+├── data/
+├── model/
+├── results/
+├── pyproject.toml
+├── requirements.txt
+├── README.md
+├── LICENSE
+└── .gitignore
+```
+
+---
+
+## 4) Platform notes
+
+### Windows
+
+```powershell
+python -m venv hg-mc-auto
+hg-mc-auto\Scripts\activate
+pip install -e .
+hgmc --help
+```
+
+### Linux
+
+```bash
+python3 -m venv hg-mc-auto
+source hg-mc-auto/bin/activate
+pip install -e .
+hgmc --help
+```
+
+### macOS
+
+```bash
+python3 -m venv hg-mc-auto
+source hg-mc-auto/bin/activate
+pip install -e .
+hgmc --help
+```
+
+---
+
+## 5) Release status
+
+This project is currently in a release-oriented v0.1.0 state with:
+
+- bilingual CLI support
+- generalized element routing for `hg`, `fe`, and `cd`
+- agent-oriented MCP tooling
+- PyPI packaging support
+- structured QC packets with advisory LLM interpretation
+- mandatory human confirmation before operational action
+- Windows / Linux / macOS compatibility notes
+
+---
+
+## 6) Citation and contact
+
+If you use this project in published work, please cite the project and associated manuscript as appropriate for your workflow and repository policy.
+
+For development questions or collaboration, use the repository issue tracker or project maintainer contact listed in the upstream project metadata.
+│   ├── 3_Empirical_model.py           # Expert rule-based classification
+│   ├── 4_ML_Predict.py                # ML model prediction interface
+│   ├── 5_Exter_ML_train.py            # Binary classifier training
+│   └── 6.Inter_ML_train.py            # Multi-class classifier training
+│
+├── custom_ranges_config.json          # User-configurable acceptance ranges
+├── mouse_coordinates.config           # RPA coordinate settings
+├── requirements.txt                   # Python dependencies
+├── LICENSE                            # MIT License
+└── README.md                          # This file
+```
+## 📖 Usage Guide
+Launching the Application
+After installation, run:
+
+```bash
+python src/main.py
+```
+
+You will see the interactive interface:
+
+```bash
+Welcome to Hg_MC_Auto!
+============================================================
+
+Please select a task:
+1. Automatically export isotope data
+2. Automatically export instrument parameters, merge isotope data, and calculate isotope fractionation values
+3. Classify data using an empirical model
+4. Classify data using a machine learning model
+5. Train your own machine learning expert model
+0. Exit
+```
+## Task Options Explained
+Option 1: Automated Data Export
+Converts proprietary .dat files to structured CSV format
+
+Merges with corresponding instrument log files
+
+Uses RPA for vendor software interaction
+
+Option 2: Isotope Calculation
+Calculates δ202Hg values relative to NIST SRM 3133
+
+Computes mass-independent fractionation anomalies (Δ-values)
+
+Batch processes entire datasets
+
+Option 3: Empirical Model Classification
+Applies literature-based acceptance ranges (Table 1 in manuscript)
+
+Flags measurements outside 95% confidence intervals
+
+User-configurable thresholds via custom_ranges_config.json
+
+Option 4: ML Model Prediction
+Uses pre-trained ensemble models for quality assessment
+
+Provides confidence scores for each prediction
+
+Identifies probable causes for abnormal measurements
+
+Option 5: Custom Model Training
+Train laboratory-specific models using your annotated data
+
+Supports both binary and multi-class classification
+
+Adapts to different instrument performances and sample matrices
+
+## 🤖 Models
+Binary Classification Models
+Purpose: Distinguish between "Normal" and "Abnormal" measurements
+
+Performance: Test F1-score: 0.9960, AUC: 0.999-1.0
+
+Algorithms: Random Forest, XGBoost, Bagging Classifiers
+
+Sampling Strategies: SMOTE, ADASYN, SMOTEENN, UnderSampling
+
+Multi-class Diagnostic Models
+Purpose: Identify root causes of abnormalities
+
+Categories:
+
+"Possible instrument instability"
+
+"Potential concentration anomaly"
+
+"Combined factors"
+
+"Other reasons, retesting recommended"
+
+Features: Internal precision metrics, concentration mismatch ratios
+
+## 📊 Performance Highlights
+Metric	Binary Classification	Multi-class Diagnosis
+Accuracy	99.61%	99.84%
+F1-Score	0.9960	0.9909 (balanced)
+Recall (Normal)	99.8%	-
+AUC	0.999-1.0	-
+Based on validation with 26,218 historical measurements
+
+## 📝 Citation
+If you use Hg-MC-Auto in your research, please cite:
+
+bibtex
+@article{zhou2025selfdriving,
+  title={A Data‑Driven, Post‑Acquisition Quality Diagnostic Pipeline for Isotope Analysis by MC-ICP-MS},
+  author={Zhou, Chufan and Huang, Qiang and Tang, Yang and Zhong, Ying and Feng, Xinbin},
+  journal={Journal of Analytical Atomic Spectrometry},
+  year={2025},
+  doi={10.1039/D5JA00519A}
+}
+## 🤝 Contributing
+We welcome contributions! Please:
+
+Fork the repository
+
+Create a feature branch
+
+Submit a pull request
+
+Ensure code follows PEP 8 guidelines
+
+Include tests for new functionality
+
+## 🐛 Issues and Support
+Bug Reports: Use the GitHub Issues page
+
+Questions: Check the Wiki or open a discussion
+
+Feature Requests: Submit via GitHub Issues with the "enhancement" label
+
+## 📧 Contact
+Laboratory of Karst Environmental Evolution and Ecological Security, 
+Institute of Geochemistry, Chinese Academy of Sciences,
+Guiyang, Guizhou 550081, China
+
+We welcome experts from different laboratories to contribute their expertise 
+and make contributions to the intelligent geochemistry laboratory. 
+Welcome to join us and make a change together.
+
+Chufan Zhou:
+📧 zhouchufan@mail.gyig.ac.cn
+🔗 ORCID: [0009-0008-0144-9017](https://orcid.org/0009-0008-0144-9017)
+
+Qiang Huang (Corresponding Author):
+📧 huangqiang@mail.gyig.ac.cn
+🔗 ORCID: [0000-0003-1568-9042](https://orcid.org/0000-0003-1568-9042)
+
+📄 License
+This project is licensed under the MIT License - see the LICENSE file for details.