gp3sequencespy 0.1.2__tar.gz → 0.1.4__tar.gz

{gp3sequencespy-0.1.2 → gp3sequencespy-0.1.4}/.github/workflows/create-stable-release.yml

@@ -12,6 +12,7 @@ on:
 
 permissions:
   contents: write
+  actions: write
 
 jobs:
   release:
@@ -196,3 +197,13 @@ jobs:
             --verify-tag \
             --title "gp3sequencespy $VERSION" \
             --notes-file release-notes.md
+
+      - name: Trigger exact-artifact Trusted Publishing
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run publish-pypi.yml \
+            --repo "$GITHUB_REPOSITORY" \
+            --ref main \
+            -f "tag=$TAG"

gp3sequencespy-0.1.4/.github/workflows/publish-pypi.yml

@@ -0,0 +1,151 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing stable GitHub Release tag to publish, for example v0.1.2
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  verify-release-assets:
+    name: Verify release distributions
+    if: >-
+      (github.event_name == 'release' && github.event.release.draft == false && github.event.release.prerelease == false) ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.target.outputs.tag }}
+    steps:
+      - name: Resolve stable release tag
+        id: target
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          DISPATCH_TAG: ${{ inputs.tag }}
+        run: |
+          case "$GITHUB_EVENT_NAME" in
+            release)
+              TAG="$RELEASE_TAG"
+              ;;
+            workflow_dispatch)
+              TAG="$DISPATCH_TAG"
+              ;;
+            *)
+              echo "unsupported event: $GITHUB_EVENT_NAME" >&2
+              exit 1
+              ;;
+          esac
+          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "stable vX.Y.Z tag required, got $TAG" >&2
+            exit 1
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "Publishing exact GitHub Release assets for $TAG"
+
+      - name: Require published stable GitHub Release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.target.outputs.tag }}
+        run: |
+          gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json tagName,isDraft,isPrerelease > release.json
+          TAG="$TAG" python - <<'PY'
+          import json
+          import os
+          release = json.load(open('release.json', encoding='utf-8'))
+          assert release['tagName'] == os.environ['TAG']
+          assert release['isDraft'] is False
+          assert release['isPrerelease'] is False
+          print('stable GitHub Release: PASS', release['tagName'])
+          PY
+
+      - name: Download exact GitHub Release distributions and checksums
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.target.outputs.tag }}
+        run: |
+          mkdir -p dist
+          gh release download "$TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --pattern "gp3sequencespy-*.whl" \
+            --pattern "gp3sequencespy-*.tar.gz" \
+            --pattern "SHA256SUMS.txt" \
+            --dir dist
+
+      - name: Require exact checksums and filenames matching stable tag
+        shell: bash
+        env:
+          TAG: ${{ steps.target.outputs.tag }}
+        run: |
+          cd dist
+          sha256sum --check SHA256SUMS.txt
+          cd ..
+          python - <<'PY'
+          import glob
+          import os
+          import re
+
+          wheels = glob.glob('dist/*.whl')
+          sdists = glob.glob('dist/*.tar.gz')
+          if len(wheels) != 1 or len(sdists) != 1:
+              raise SystemExit(f'expected one wheel and one sdist; got {wheels=} {sdists=}')
+
+          tag = os.environ['TAG']
+          if not re.fullmatch(r'v\d+\.\d+\.\d+', tag):
+              raise SystemExit(f'stable release tag required, got {tag!r}')
+
+          version = tag[1:]
+          expected_wheel = f'dist/gp3sequencespy-{version}-py3-none-any.whl'
+          expected_sdist = f'dist/gp3sequencespy-{version}.tar.gz'
+          if wheels[0].replace('\\', '/') != expected_wheel:
+              raise SystemExit(f'wheel filename does not match release tag: {wheels[0]!r}')
+          if sdists[0].replace('\\', '/') != expected_sdist:
+              raise SystemExit(f'sdist filename does not match release tag: {sdists[0]!r}')
+          print('release filenames and checksums match stable tag', tag)
+          PY
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+
+      - name: Validate release distributions
+        run: uv tool run --from twine==7.0.0 twine check --strict dist/*.whl dist/*.tar.gz
+
+      - name: Upload verified distributions for publish job
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: verified-pypi-distributions
+          path: |
+            dist/gp3sequencespy-*.whl
+            dist/gp3sequencespy-*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+
+  pypi-publish:
+    name: Publish verified distributions
+    needs: verify-release-assets
+    if: needs.verify-release-assets.result == 'success'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gp3sequencespy/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: verified-pypi-distributions
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gp3sequencespy-0.1.2/.hypothesis/constants/27ea81ecf5b94751 → gp3sequencespy-0.1.4/.hypothesis/constants/6490da55911cc2f9

@@ -1,4 +1,4 @@
 # file: /home/runner/work/gp3sequencespy/gp3sequencespy/src/gp3sequencespy/__init__.py
 # hypothesis_version: 6.165.10
 
-['0.1.2', 'CovariateSequenceHMM', 'GP3SequencesError', 'GrpStringInput', 'ModelFitError', 'MotifPositionResult', 'ParityError', 'ValidationError', 'WideSequenceAdapter', 'as_arules_sequences', 'as_grpstring_data', 'as_seqhmm_sequences', 'audit_sequence_data', 'cluster_sequences', 'encode_sequence_data', 'fit_sequence_hmm', 'plot_sequence_index', 'plot_sequence_motifs', 'predict_next_state']
+['0.1.4', 'CovariateSequenceHMM', 'GP3SequencesError', 'GrpStringInput', 'ModelFitError', 'MotifPositionResult', 'ParityError', 'ValidationError', 'WideSequenceAdapter', 'as_arules_sequences', 'as_grpstring_data', 'as_seqhmm_sequences', 'audit_sequence_data', 'cluster_sequences', 'encode_sequence_data', 'fit_sequence_hmm', 'plot_sequence_index', 'plot_sequence_motifs', 'predict_next_state']

{gp3sequencespy-0.1.2 → gp3sequencespy-0.1.4}/CHANGELOG.md

@@ -7,6 +7,53 @@ All notable changes to `gp3sequencespy` are documented here. The project follows
 
 No changes yet.
 
+## [0.1.4] - 2026-10-09
+
+*Documentation-only maintenance candidate.*
+
+### Documentation
+
+- Integrate the reviewed methods-briefing guide on estimation-visualization boundaries for participant-level scalar sequence summaries versus transition, HMM and other structured estimands.
+- Keep all underlying scientific implementation and the frozen 81-API/R parity surface unchanged; do not advertise new experimental methods.
+- Require existing frozen parity, exact coverage, mutation smoke, strict documentation, fresh wheel, immutable release-asset checks, and trusted PyPI publication gates to pass before publishing.
+
+## [0.1.3] - 2026-09-21
+
+### Changed
+
+- Hardened exact-artifact GitHub Release to PyPI Trusted Publishing,
+  including guarded stable-release verification, filename checks,
+  checksum verification, and explicit manual-dispatch support.
+- Refined stable-release orchestration so GitHub Release distributions
+  remain the authoritative artifacts consumed by PyPI without rebuilding.
+- Redesigned and refined the public MkDocs homepage, navigation, visual
+  system, repository front page, and shared Python Suite branding.
+- Added the September 2026 ecosystem methods update and strengthened the
+  documentation rendering contract.
+
+### Validation
+
+- **293 / 293** Python tests pass on the certified pre-release tree.
+- **4,564 / 4,564** executable statements are covered (**100.00%**).
+- **1,702 / 1,702** branches are covered (**100.00%**).
+- Mutation smoke remains **3 / 3 killed**.
+- Frozen API remains **81 / 81**.
+- Frozen R test-block ledger remains **130 / 130**.
+- Frozen public signatures remain **81 / 81** with **0 unexplained drift**.
+- Local Ruff, mypy, strict MkDocs, wheel/sdist build, Twine validation,
+  clean wheel installation, and clean sdist installation pass.
+
+### Scientific/API status
+
+- No scientific implementation files under `src/gp3sequencespy` changed
+  between `v0.1.2` and the 0.1.3 release preparation tree except the
+  required package version string.
+- No breaking scientific API or public-signature change is introduced.
+- The frozen `gp3sequences` 0.3.0 behavioral reference remains unchanged.
+- The twelve additional names in Python `__all__` remain deliberate
+  Python public classes, exceptions, adapters, and audit objects outside
+  the frozen 81-function R parity manifest.
+
 ## [0.1.2] - 2026-08-31
 
 ### Added

{gp3sequencespy-0.1.2 → gp3sequencespy-0.1.4}/CITATION.cff

@@ -7,8 +7,8 @@ type: software
 authors:
   - family-names: Balaskas
     given-names: Stefanos
-version: 0.1.2
-date-released: 2026-08-31
+version: 0.1.4
+date-released: 2026-10-09
 license: MIT
 repository-code: https://github.com/stefanosbalaskas/gp3sequencespy
 url: https://stefanosbalaskas.github.io/gp3sequencespy/

gp3sequencespy-0.1.4/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.5
+Name: gp3sequencespy
+Version: 0.1.4
+Summary: Transparent, reproducible, and auditable analysis of ordered categorical sequences in Python.
+Project-URL: Homepage, https://stefanosbalaskas.github.io/gp3sequencespy/
+Project-URL: Documentation, https://stefanosbalaskas.github.io/gp3sequencespy/
+Project-URL: Source, https://github.com/stefanosbalaskas/gp3sequencespy
+Project-URL: Issues, https://github.com/stefanosbalaskas/gp3sequencespy/issues
+Project-URL: Changelog, https://github.com/stefanosbalaskas/gp3sequencespy/blob/main/CHANGELOG.md
+Project-URL: Archive, https://doi.org/10.5281/zenodo.22166449
+Author: Stefanos Balaskas
+Maintainer: Stefanos Balaskas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: categorical-sequences,eye-tracking,reproducibility,scanpaths,sequence-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: networkx>=3.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scipy>=1.11
+Provides-Extra: data
+Requires-Dist: polars>=1; extra == 'data'
+Requires-Dist: pyarrow>=17; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.6; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.29; extra == 'docs'
+Provides-Extra: hmm
+Requires-Dist: hmmlearn>=0.3.3; extra == 'hmm'
+Provides-Extra: performance
+Requires-Dist: numba>=0.61; extra == 'performance'
+Provides-Extra: release
+Requires-Dist: twine>=6; extra == 'release'
+Requires-Dist: validate-pyproject>=0.24; extra == 'release'
+Provides-Extra: time
+Requires-Dist: mssm<1.3,>=1.2.5; extra == 'time'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stefanosbalaskas/gp3sequencespy/main/docs/assets/python-suite-logo.png" width="260" alt="Python Suite research packages logo">
+</p>
+
+<h1 align="center">gp3sequencespy</h1>
+
+<p align="center">
+  <strong>Transparent, reproducible sequence analysis in Python.</strong><br>
+  Audit ordered categorical data, discover recurring structure, compare trajectories,
+  model transitions and latent states, test group differences, and report every analytical choice.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/gp3sequencespy/"><img alt="PyPI" src="https://img.shields.io/pypi/v/gp3sequencespy?logo=pypi&logoColor=white"></a>
+  <a href="https://pypi.org/project/gp3sequencespy/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/gp3sequencespy?logo=python&logoColor=white"></a>
+  <a href="https://github.com/stefanosbalaskas/gp3sequencespy/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/stefanosbalaskas/gp3sequencespy/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="https://github.com/stefanosbalaskas/gp3sequencespy/actions/workflows/docs.yml"><img alt="Docs" src="https://github.com/stefanosbalaskas/gp3sequencespy/actions/workflows/docs.yml/badge.svg?branch=main"></a>
+  <a href="https://github.com/stefanosbalaskas/gp3sequencespy/actions/workflows/quality-completion.yml"><img alt="Quality" src="https://github.com/stefanosbalaskas/gp3sequencespy/actions/workflows/quality-completion.yml/badge.svg?branch=main"></a>
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-4c1.svg"></a>
+  <a href="https://doi.org/10.5281/zenodo.22166449"><img alt="DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.22166449.svg"></a>
+</p>
+
+<p align="center">
+  <a href="https://stefanosbalaskas.github.io/gp3sequencespy/"><strong>Documentation</strong></a>
+  · <a href="https://stefanosbalaskas.github.io/gp3sequencespy/quickstart/">Quickstart</a>
+  · <a href="https://stefanosbalaskas.github.io/gp3sequencespy/method-map/">Method map</a>
+  · <a href="https://stefanosbalaskas.github.io/gp3sequencespy/plots/">Plot gallery</a>
+  · <a href="https://stefanosbalaskas.github.io/gp3sequencespy/reference/">API reference</a>
+  · <a href="https://github.com/stefanosbalaskas/gp3sequencespy/releases/tag/v0.1.4">v0.1.4</a>
+</p>
+
+---
+
+`gp3sequencespy` is the Python implementation of **gp3sequences 0.3.0** for ordered categorical sequences and scanpaths. The frozen R 0.3.0 tarball is the behavioral reference: scientific contracts are preserved and tested explicitly, while deliberate R→Python translations are documented rather than hidden.
+
+The package is designed for research workflows where **data preparation, method choice, reproducibility, and interpretation need to remain visible from input to report**.
+
+## Install
+
+```bash
+pip install gp3sequencespy==0.1.4
+```
+
+With `uv`:
+
+```bash
+uv add gp3sequencespy==0.1.4
+```
+
+Python **3.11–3.14** is supported. Optional extras are available for HMM backends, Arrow/Polars data interoperability, performance helpers, time-varying models, documentation, and development.
+
+```bash
+pip install "gp3sequencespy[hmm]"
+pip install "gp3sequencespy[data]"
+pip install "gp3sequencespy[time]"
+```
+
+## A 60-second workflow
+
+```python
+import pandas as pd
+import gp3sequencespy as g
+
+# One row per observed state occurrence.
+data = pd.DataFrame(
+    {
+        "sequence_id": ["s1", "s1", "s1", "s2", "s2", "s2"],
+        "sequence_order": [1, 2, 3, 1, 2, 3],
+        "state": ["home", "search", "checkout", "home", "product", "checkout"],
+    }
+)
+
+# Audit and prepare explicitly.
+validation = g.validate_sequence_data(
+    data,
+    "sequence_id",
+    "sequence_order",
+    "state",
+)
+prepared = g.prepare_sequence_data(
+    data,
+    "sequence_id",
+    "sequence_order",
+    "state",
+)
+
+# Compare complete trajectories.
+distance = g.compute_sequence_distance(
+    prepared.data,
+    method="lcs",
+    normalise="max_length",
+)
+
+# Inspect transition structure.
+network = g.create_transition_network(
+    prepared.data,
+    normalise="from",
+)
+
+# Visualise complete paths.
+ax = g.plot_sequence_index(prepared.data)
+```
+
+For the complete path from raw long-format data to summaries, motifs, clustering, networks, plots, and analysis auditing, see the **[Quickstart](https://stefanosbalaskas.github.io/gp3sequencespy/quickstart/)**.
+
+## What you can do
+
+| Research task | Capabilities | Start here |
+| --- | --- | --- |
+| **Audit & prepare** | ordering, missing states, duplicate positions, durations, state policies, preparation provenance | [Validation & preparation](https://stefanosbalaskas.github.io/gp3sequencespy/articles/sequence-data-validation-and-preparation/) |
+| **Describe sequences** | state occupancy, transitions, paths, consensus, representatives | [Examples](https://stefanosbalaskas.github.io/gp3sequencespy/examples/) |
+| **Find recurring structure** | contiguous motifs, bounded non-contiguous subsequences, motif filtering and visualisation | [Motif workflow](https://stefanosbalaskas.github.io/gp3sequencespy/articles/contiguous-motif-workflow/) |
+| **Compare trajectories** | Levenshtein, LCS, optimal matching, transition-profile distances, clustering and stability | [Distances & clustering](https://stefanosbalaskas.github.io/gp3sequencespy/articles/distances-clustering-and-stability/) |
+| **Model transitions** | transition networks, centrality, communities, higher-order transition structure | [Networks & higher-order models](https://stefanosbalaskas.github.io/gp3sequencespy/articles/transition-networks-and-higher-order-models/) |
+| **Fit latent models** | categorical, multichannel, covariate-dependent and time-varying HMM workflows | [Latent models](https://stefanosbalaskas.github.io/gp3sequencespy/articles/latent-models-and-optional-adapters/) |
+| **Test group structure** | design-aware randomization and sequence-group inference | [Inference & randomization](https://stefanosbalaskas.github.io/gp3sequencespy/articles/sequence-inference-and-randomization/) |
+| **Visualise & report** | sequence index, state distributions, distance heatmaps, transition networks, audit trails | [Plot gallery](https://stefanosbalaskas.github.io/gp3sequencespy/plots/) |
+
+Not sure which family fits your question? Use the **[method map](https://stefanosbalaskas.github.io/gp3sequencespy/method-map/)** to move from research question → assumptions → method family.
+
+## Parity and validation
+
+Version **0.1.4** is a maintenance release preserving the 0.1.2 scientific contracts while strengthening release automation and public documentation.
+
+| Validation contract | Status |
+| --- | ---: |
+| Frozen R public counterparts | **81 / 81** |
+| Frozen R public signatures audited | **81 / 81** |
+| Frozen R `test_that()` blocks translated | **130 / 130** |
+| Python tests | **293** |
+| Statement coverage | **100%** |
+| Branch coverage | **100%** |
+| Mutation smoke | **3 / 3 killed** |
+| CI platforms | **Linux · macOS · Windows** |
+| CI Python versions | **3.11 · 3.12 · 3.13 · 3.14** |
+| Python-native articles | **15** |
+
+The deterministic core, hierarchical/PAM, and time-varying-model cross-language oracle tranches have been executed against frozen R 0.3.0. Remaining deliberate boundaries are recorded in [`PARITY_EXCEPTIONS.md`](PARITY_EXCEPTIONS.md), with broader parity evidence in [`PARITY_TEST_MATRIX.md`](PARITY_TEST_MATRIX.md) and the [online parity guide](https://stefanosbalaskas.github.io/gp3sequencespy/parity/).
+
+## Documentation routes
+
+| If you want to… | Go to |
+| --- | --- |
+| get from install to first analysis quickly | [Quickstart](https://stefanosbalaskas.github.io/gp3sequencespy/quickstart/) |
+| choose a method by research question | [Method map](https://stefanosbalaskas.github.io/gp3sequencespy/method-map/) |
+| copy complete analysis recipes | [Examples](https://stefanosbalaskas.github.io/gp3sequencespy/examples/) |
+| inspect available figure families | [Plot gallery](https://stefanosbalaskas.github.io/gp3sequencespy/plots/) |
+| read the full methodological guides | [Articles](https://stefanosbalaskas.github.io/gp3sequencespy/articles/) |
+| translate from the R package | [R → Python](https://stefanosbalaskas.github.io/gp3sequencespy/r-to-python/) |
+| browse functions and signatures | [API reference](https://stefanosbalaskas.github.io/gp3sequencespy/reference/) |
+| document a reproducible analysis | [Reproducibility](https://stefanosbalaskas.github.io/gp3sequencespy/reproducibility/) · [Reporting guide](https://stefanosbalaskas.github.io/gp3sequencespy/reporting/) |
+
+## Reproducibility and release governance
+
+The package treats release and parity evidence as part of the scientific software contract.
+
+- [`REPRODUCIBILITY.md`](REPRODUCIBILITY.md) — frozen-reference and reproducibility policy
+- [`PARITY_EXCEPTIONS.md`](PARITY_EXCEPTIONS.md) — deliberate R→Python boundaries
+- [`SIGNATURE_PARITY.md`](SIGNATURE_PARITY.md) — frozen public-signature audit
+- [`QUALITY_COMPLETION.md`](QUALITY_COMPLETION.md) — 100% coverage and mutation-hardening evidence
+- [`RELEASE_CHECKLIST.md`](RELEASE_CHECKLIST.md) — stable-release gates
+- [`PYPI_PUBLISHING.md`](PYPI_PUBLISHING.md) — Trusted Publishing and artifact verification
+- [`CHANGELOG.md`](CHANGELOG.md) — release history
+
+Stable releases publish the exact validated GitHub Release wheel and source distribution to PyPI through GitHub OIDC Trusted Publishing. Each publication is subsequently checked against the GitHub Release SHA-256 hashes and with a clean PyPI installation.
+
+## Development
+
+```bash
+uv sync --all-extras --python 3.12
+uv run pytest -q
+```
+
+Full quality gate:
+
+```bash
+uv run pytest -q \
+  --cov=gp3sequencespy \
+  --cov-branch \
+  --cov-report=term-missing \
+  --cov-fail-under=100
+
+uv run python scripts/run_mutation_smoke.py
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution guidance and [`SECURITY.md`](SECURITY.md) for the security policy.
+
+## Citation
+
+If `gp3sequencespy` contributes to your research, use the repository citation metadata in [`CITATION.cff`](CITATION.cff) and the archived Zenodo record:
+
+**DOI: [10.5281/zenodo.22166449](https://doi.org/10.5281/zenodo.22166449)**
+
+## Scientific interpretation guardrail
+
+> Sequence structure does not independently establish emotion, cognition, comprehension, personality, intention, deception, diagnosis, or causality. Observational group contrasts are associational unless a valid randomized design supports a causal interpretation.
+
+---
+
+<p align="center">
+  <a href="https://stefanosbalaskas.github.io/gp3sequencespy/">Documentation</a>
+  · <a href="https://pypi.org/project/gp3sequencespy/">PyPI</a>
+  · <a href="https://github.com/stefanosbalaskas/gp3sequencespy/releases">Releases</a>
+  · <a href="https://doi.org/10.5281/zenodo.22166449">Zenodo</a>
+</p>

gp3sequencespy-0.1.4/PYPI_PUBLISHING.md

@@ -0,0 +1,75 @@
+# PyPI publishing
+
+`gp3sequencespy` uses exact-artifact publication: stable wheel and source distributions are first built, validated, checksummed, and attached to a GitHub Release, then those same files are published to PyPI without rebuilding.
+
+## 0.1.0 publication identity
+
+- Git commit: `28f06a571889bf9db760d00c47e1252d3836679a`
+- Git tag: `v0.1.0`
+- Wheel: `gp3sequencespy-0.1.0-py3-none-any.whl`
+- Wheel SHA-256: `97725d0b34872b79c9f9cb4da57f14a788a8920880a0a415c13669d281a39525`
+- Source distribution: `gp3sequencespy-0.1.0.tar.gz`
+- Source SHA-256: `e01ff3ac4ec0cbede48b1019e4bcabddd38b9587df3fe541ce66aff585bf7e19`
+
+PyPI's JSON API was queried after upload and both published hashes matched the frozen GitHub Release artifacts exactly.
+
+## 0.1.2 publication identity
+
+Version **0.1.2** was published on 2026-08-31 through PyPI Trusted Publishing after the complete quality-completion release gate passed.
+
+- Release commit: `564dfb3f97dde9e9228819bf4792821584b02934`
+- Annotated tag: `v0.1.2`
+- Annotated tag object: `c2ee786031c0badb9127529601e08893e90af70d`
+- GitHub Release ID: `379432726`
+- Wheel: `gp3sequencespy-0.1.2-py3-none-any.whl`
+- Wheel SHA-256: `3fd063414f0c8c37fb5ae9a6aacf103a89afd0e6e2135ab3b81248b38b9ba847`
+- Source distribution: `gp3sequencespy-0.1.2.tar.gz`
+- Source SHA-256: `58b5e81149accf95d1b1a7e205f8cdf7a21846f0138b8aae00cfddd5db4289d9`
+- Stable-release workflow run: `33342028606` — **PASS**
+- Trusted Publishing workflow run: `33342198803` — **PASS**
+- Post-PyPI verification run: `33342235019` — **PASS**
+- Verification artifact: `9740897782`
+
+The independent verifier compared the GitHub Release SHA-256 values against PyPI's published-file SHA-256 values and confirmed exact equality for both distributions. It then created a clean virtual environment and successfully installed `gp3sequencespy==0.1.2` from PyPI.
+
+The full machine-readable publication ledger is stored in `reference/release_publication_0.1.2.json`.
+
+## Trusted Publishing
+
+The PyPI project has an active GitHub Actions Trusted Publisher for `.github/workflows/publish-pypi.yml` using the `pypi` environment.
+
+### Active PyPI configuration
+
+- **Owner:** `stefanosbalaskas`
+- **Repository:** `gp3sequencespy`
+- **Workflow name:** `publish-pypi.yml`
+- **Environment name:** `pypi`
+
+The publishing job alone receives `id-token: write`; no long-lived PyPI credential is required by the automated path.
+
+### Release behavior
+
+The permanent workflow supports two guarded entry points:
+
+1. a published stable GitHub Release; or
+2. an explicit manual dispatch naming an existing stable `vX.Y.Z` GitHub Release.
+
+The manual-dispatch path exists because GitHub intentionally suppresses workflow chaining when one workflow creates a Release using `GITHUB_TOKEN`.
+
+For either entry point the verification job:
+
+1. resolves and validates the stable `vX.Y.Z` tag;
+2. requires an existing non-draft, non-prerelease GitHub Release;
+3. downloads the exact wheel, sdist, and `SHA256SUMS.txt` attached to that Release;
+4. verifies the release checksums;
+5. requires filenames to match the stable tag;
+6. runs `twine check --strict`;
+7. passes only the verified wheel and sdist to the publishing job as a short-lived Actions artifact.
+
+The publishing job downloads that verified artifact and invokes `pypa/gh-action-pypi-publish@release/v1`. It does not build package distributions.
+
+## API-token cleanup
+
+The 0.1.0 first publication used a manually supplied PyPI API token because the project did not yet exist on PyPI when release automation was prepared. The Trusted Publisher was registered on 2026-08-30. Version 0.1.1 confirmed the OIDC path end-to-end, and version 0.1.2 independently reconfirmed exact-artifact Trusted Publishing plus post-publication hash and clean-install verification.
+
+Any API token created solely for `gp3sequencespy` is therefore no longer required by the automated release path and can be revoked in PyPI account/project settings if it still exists.