nrtqclib 0.1.0__tar.gz

nrtqclib-0.1.0/.github/workflows/check_package.yml

@@ -0,0 +1,27 @@
+name: Check Package
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main", "develop" ]
+
+# Test fixtures are committed under tests/data/, so there is no download step.
+
+jobs:
+  build:
+    name: python
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+      - name: Run tests
+        run: uv run pytest -v tests

nrtqclib-0.1.0/.github/workflows/code_coverage.yml

@@ -0,0 +1,30 @@
+name: Code Coverage
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    name: python
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+      - name: Run code coverage
+        run: uv run pytest --cov --cov-branch --cov-report=xml
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: AIQC-Hub/nrtqclib

nrtqclib-0.1.0/.github/workflows/publish_to_pypi.yml

@@ -0,0 +1,74 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

nrtqclib-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.idea/
+
+# Sphinx build output
+docs/build/
+
+# Test-generated output (fixtures under tests/data/ are tracked)
+tests/data/test/
+
+# Personal, machine-local Claude Code instructions (not shared)
+CLAUDE.local.md
+
+# Claude Code local settings (machine-specific paths, not for the repo)
+.claude/settings.local.json

nrtqclib-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

nrtqclib-0.1.0/.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py

nrtqclib-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+As this project is still in active development, it does not yet strictly adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-05
+### Added
+- NRT QC pipeline (read input, run QC, concat flags, compare flags), its config, schema and template, moved from `aiqclib` 0.13.0; outputs match `aiqclib` 0.14.0 on the test fixture
+- Public API: `run_nrt_qc`, `read_config`, `read_config_template`, `write_config_template`, `run_batch` (no `stage`/`mode` arguments; options after the first are keyword-only for the writer and batch)
+- `NRTQCConfig` serves its own `nrt_qc_sets` schema and template through the `aiqclib` 0.14 config hooks
+- `run_batch` runs the `nrt_qc` phase on the `aiqclib` batch engine
+- Batch processing how-to and API reference pages

nrtqclib-0.1.0/CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md
+
+`nrtqclib`: near-real-time QC (NRT QC) pipeline for CTD ocean profiles, split out of `aiqclib` (sibling checkout at `../aiqclib`). It **depends on `aiqclib`**: the QC items (`aiqclib/prepare/features/qc_*.py`), feature registry, flag utilities and config/dataset base classes stay there; this repo owns the pipeline, its config, docs and tests. Source in `src/nrtqclib/` (`step1_read_input` to `step4_compare_flags`, `config/`, `loader/`, `interface/`). Design docs (outside the Sphinx build) in `docs/design/`.
+
+## Migration status (delete this section when the port is done)
+
+- Plan: `docs/design/NRTQCLIB_plan.md`. Phases 2 and 3 happen here; Phases 1 and 4 happen in `aiqclib`. Phase 1 is released as `aiqclib` 0.14.0 (PyPI, 2026-11-05). Do not edit `../aiqclib` from this repo; read it for reference only.
+- Done on `feature/move-nrtqc`: imports rewritten to `nrtqclib.*`; `NRTQCConfig` overrides `get_yaml_schema` / `get_template_text`; `nrtqclib.read_config`, `read_config_template`, `write_config_template` (`interface/config.py`) and `run_batch` (`interface/batch.py`, `NRT_QC_PHASE` on `aiqclib.interface.batch.run_phases`); the remaining aiqclib NRT QC tests ported; `how-to/batch_processing.rst`; `docs/source/api/` generated. Parity with `aiqclib.run_nrt_qc` 0.14.0 verified (identical step 2, 3, 4 outputs on the fixture).
+- `pytest.ini` turns aiqclib's "is moving to the nrtqclib package" `DeprecationWarning` into an error, so an import pointing back at aiqclib's copy fails the suite.
+- The `aiqclib` names this package may import are listed in `CONTRACT` in aiqclib `tests/test_common_public_api.py`. Importing a name not listed there needs a matching addition in `aiqclib` first.
+- Released as `nrtqclib` 0.1.0 (Phase 3 step 7). Remaining: Phase 4 in `aiqclib`.
+- `aiqclib` comes from PyPI (`aiqclib>=0.14,<0.15`). Do not add a `[tool.uv.sources]` path to `../aiqclib`: CI's `uv sync --locked` cannot see it. To test against unreleased aiqclib code, use `uv run --with-editable ../aiqclib pytest` for that run only.
+
+## Environment
+
+- Use **`uv`**: `uv sync` installs everything, `uv run <cmd>` runs in the env. No separate install step.
+- Shell commands go through **RTK** (global hook, see `~/.claude/RTK.md`) to cut output tokens. Keep output small: run single test files or `-k` selections with `-q`, read file ranges instead of whole files.
+
+## Tests
+
+- `uv run pytest` (small suite). Fixtures are committed: `tests/data/input/nrt_cora_bo_test.parquet`, `tests/data/config/test_dataset_invalid.yaml`. Test outputs go to `tests/data/test/` (gitignored).
+
+## Lint & format
+
+- `uv run ruff format src tests` then `uv run ruff check src tests`. Always run both before merging a feature branch.
+
+## Writing style
+
+- **Never use em or en dashes** anywhere (docs, README, CHANGELOG, docstrings, comments, commit messages). Use a colon, comma, semicolon, parentheses or two sentences; plain hyphen for ranges and minus signs.
+- Do not write `--` / `---` in `.rst` as a substitute: `docs/source/conf.py` sets `smartquotes_action = "qe"`; keep it.
+- Check: `git ls-files -z | xargs -0 grep -lP '[\x{2013}\x{2014}]'` must print nothing.
+
+## Git (gitflow)
+
+- `main` (releases), `develop` (integration), plus `feature/*`, `release/*`, `hotfix/*`.
+- Branch off `develop` for features, off `main` for hotfixes. Do **not** commit directly to `main` or `develop` (the initial import commit is the only exception).
+
+## Releasing
+
+- Checklist in `RELEASING.md`. Order: check the `aiqclib` pin, ruff (+ `sphinx-apidoc` if needed), `CHANGELOG.md`, bump `version` in `pyproject.toml`, `uv sync` (updates `uv.lock`), GitHub release triggers PyPI publish.
+- Keep `CHANGELOG.md` **compact**: terse one-line bullets under `### Added/Changed/Fixed/Removed` in `## [Unreleased]` (Keep a Changelog).
+- A fix to a QC item ships in `aiqclib` first; this package then raises its `aiqclib` lower bound if it needs the fix.

nrtqclib-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing & Development
+
+For the release process, see [RELEASING.md](RELEASING.md).
+
+## Environment setup
+
+We use **uv** for the development environment. Install it with
+`mamba install -n base -c conda-forge uv`, `pip install uv`, or the
+[standalone installer](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv sync    # creates .venv and installs nrtqclib (editable) with all dependencies
+```
+
+`aiqclib` comes from PyPI (`aiqclib>=0.14,<0.15`). To try the tests against
+an unreleased `aiqclib`, overlay a local checkout for one run without touching
+`pyproject.toml` or `uv.lock`:
+
+```bash
+uv run --with-editable ../aiqclib pytest
+```
+
+## Running tests
+
+The test fixtures are small and committed under `tests/data/`, so no download
+is needed.
+
+```bash
+uv run pytest -v
+```
+
+## Code style
+
+We use **Ruff** for linting and formatting.
+
+```bash
+uv run ruff format src tests
+uv run ruff check src tests
+```

nrtqclib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takaya Saito
+
+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.

nrtqclib-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: nrtqclib
+Version: 0.1.0
+Summary: Near-real-time quality control (NRT QC) for CTD ocean profiles, built on aiqclib
+Author-email: Takaya Saito <takaya.saito@outlook.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: aiqclib<0.15,>=0.14
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: polars>=1.30.0
+Requires-Dist: pyyaml>=6.0.2
+Description-Content-Type: text/markdown
+
+# nrtqclib
+
+Near-real-time quality control (NRT QC) for CTD ocean profiles. `nrtqclib`
+applies automated real-time QC tests (Argo/CTD RTQC tests) to temperature and
+salinity profiles, producing per-item flag columns and a final NRT flag per
+variable, and can compare those flags with existing ones.
+
+The QC items are implemented in [`aiqclib`](https://github.com/AIQC-Hub/aiqclib),
+which this package depends on. The same tests are available there as training
+features for its machine-learning models.
+
+> **Status:** moved out of `aiqclib` (where it shipped as
+> `aiqclib.run_nrt_qc` from v0.5.0). See
+> [`docs/design/NRTQCLIB_plan.md`](docs/design/NRTQCLIB_plan.md). Install
+> with `pip install nrtqclib`.
+
+## Usage
+
+```python
+import nrtqclib as nq
+
+nq.write_config_template("nrt_qc_config.yaml")
+# Edit the paths, variables and QC items, then:
+config = nq.read_config("nrt_qc_config.yaml")
+nq.run_nrt_qc(config)
+
+# Or over a table of datasets (column `nrt_qc_set_name`):
+summary = nq.run_batch("datasets.txt", nrt_qc_config="nrt_qc_config.yaml")
+```
+
+Migrating from `aiqclib`: the functions keep their names and arguments,
+minus `stage` (config functions) and `mode` (`run_batch`). The pipeline,
+configuration format and outputs are unchanged.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT

nrtqclib-0.1.0/README.md

@@ -0,0 +1,41 @@
+# nrtqclib
+
+Near-real-time quality control (NRT QC) for CTD ocean profiles. `nrtqclib`
+applies automated real-time QC tests (Argo/CTD RTQC tests) to temperature and
+salinity profiles, producing per-item flag columns and a final NRT flag per
+variable, and can compare those flags with existing ones.
+
+The QC items are implemented in [`aiqclib`](https://github.com/AIQC-Hub/aiqclib),
+which this package depends on. The same tests are available there as training
+features for its machine-learning models.
+
+> **Status:** moved out of `aiqclib` (where it shipped as
+> `aiqclib.run_nrt_qc` from v0.5.0). See
+> [`docs/design/NRTQCLIB_plan.md`](docs/design/NRTQCLIB_plan.md). Install
+> with `pip install nrtqclib`.
+
+## Usage
+
+```python
+import nrtqclib as nq
+
+nq.write_config_template("nrt_qc_config.yaml")
+# Edit the paths, variables and QC items, then:
+config = nq.read_config("nrt_qc_config.yaml")
+nq.run_nrt_qc(config)
+
+# Or over a table of datasets (column `nrt_qc_set_name`):
+summary = nq.run_batch("datasets.txt", nrt_qc_config="nrt_qc_config.yaml")
+```
+
+Migrating from `aiqclib`: the functions keep their names and arguments,
+minus `stage` (config functions) and `mode` (`run_batch`). The pipeline,
+configuration format and outputs are unchanged.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT

nrtqclib-0.1.0/RELEASING.md

@@ -0,0 +1,40 @@
+# Releasing (for Maintainers)
+
+For development setup, tests and linting, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Release checklist
+
+Follow these steps in order. Steps marked *if necessary* only apply when the
+relevant code has changed since the last release.
+
+1. **Check the `aiqclib` dependency.** `pyproject.toml` must pin a released
+   `aiqclib` range (for example `aiqclib>=0.14,<0.15`), and the development-only
+   `[tool.uv.sources]` path entry must be removed. Widen the upper bound only
+   after the tests pass against the new `aiqclib` minor version.
+2. **Lint and format** *(if necessary)*:
+   ```bash
+   uv run ruff format src tests
+   uv run ruff check src tests
+   ```
+3. **Update API documentation** *(if necessary)*: see
+   [Building docs locally](#building-docs-locally).
+4. **Update `CHANGELOG.md`**: record the changes for the new version.
+5. **Bump the version** in `pyproject.toml`, then run `uv sync` so `uv.lock`
+   records it.
+6. **Commit, then create the release**: once merged into `main`, creating a
+   GitHub release triggers the PyPI publish.
+
+## Building docs locally
+
+```bash
+uv run sphinx-apidoc -f --remove-old --module-first -o docs/source/api src/nrtqclib
+cd docs; uv run make html; cd ..
+```
+
+Open `docs/build/html/index.html` to view the site.
+
+## Deployment
+
+The package is published to PyPI by `.github/workflows/publish_to_pypi.yml`
+whenever a GitHub release is created. The PyPI project needs a trusted
+publisher configured for this repository and the `pypi` environment.

nrtqclib-0.1.0/codecov.yaml

@@ -0,0 +1,2 @@
+ignore:
+  - 'tests/*'

nrtqclib-0.1.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)