fair-ly-accurate 0.3.0__tar.gz

fair_ly_accurate-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Match requires-python = ">=3.9"; test the ends of the range.
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (with dev + cluster/geo extras)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[all,dev]"
+
+      - name: Run tests
+        run: python -m pytest -q
+
+  build:
+    name: Build & check distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*

fair_ly_accurate-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+# Build, then publish to PyPI via Trusted Publishing (OIDC) — no API tokens stored.
+# Triggered when you publish a GitHub Release (which carries a vX.Y.Z tag).
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Verify the release tag matches the package version
+        run: |
+          pkg_version="$(ls dist/*.tar.gz | sed -E 's#.*/fair_ly_accurate-(.*)\.tar\.gz#\1#')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          echo "package=$pkg_version  tag=$tag_version"
+          if [ "$pkg_version" != "$tag_version" ]; then
+            echo "::error::Release tag $GITHUB_REF_NAME does not match package version $pkg_version. Bump the version in pyproject.toml and src/fairly/__init__.py before tagging."
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fair-ly-accurate
+    permissions:
+      id-token: write        # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

fair_ly_accurate-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+*.npy
+*.pickle
+*.emb.*
+.ror_cache/
+.geo_cache/
+.DS_Store

fair_ly_accurate-0.3.0/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-08-27
+
+### Changed
+- **First public PyPI release.** Distribution name is `fair-ly-accurate`
+  (`pip install fair-ly-accurate`); the import name remains `fairly`.
+
+### Added
+- Automated publishing via **PyPI Trusted Publishing (OIDC)** on GitHub Release
+  (`.github/workflows/publish.yml`), a CI workflow running the test suite on
+  Python 3.9/3.12 (`.github/workflows/ci.yml`), and a `RELEASING.md` runbook.
+
+## [0.2.1] - 2026-07-16
+
+### Added
+- Licenses: parse Creative Commons `rightsUri` values and spelled-out CC names.
+
+## [0.2.0] - 2026-07-14
+
+### Added
+- **Controlled-vocabulary normalization** (`fairly.controlled.ControlledVocabulary`): a
+  deterministic normalizer for fixed-vocabulary fields (license ids, country codes, units,
+  resource types). Folds surface strings (`fold_key`: strip diacritics/case/punctuation) and
+  resolves them against the canonical set + an alias map to a single canonical id — never
+  merging two distinct ids (`CC-BY-SA-4.0` vs `CC-BY-NC-4.0`), which embedding clustering
+  cannot guarantee. New `strategy="controlled"` for `FieldConfig`/`Normalizer`.
+- **`fairly.licenses`**: a ready SPDX/CC license `ControlledVocabulary` + `classify()`
+  (allowed/blocked/unknown) policy. The `rights` preset now uses it instead of clustering.
+- Documented in `docs/methods.md` §6.5. On the posters.science corpus this approach
+  reclassified ~6,100 license values a plain whitelist match had missed.
+
+## [0.1.1] - 2026-07-10
+
+### Added
+- **Reference gold sets** (`gold/`) for `affiliation`, `funderName`, `publisher`,
+  `subject`, `rights` — true synonym groups plus adversarial near-misses.
+- **V-measure validation of the default presets.** A sweep (eps 0.05–1.0) against
+  the gold sets confirms every preset `eps` sits on its field's optimal plateau
+  (funder/subject V=1.00, publisher 0.99, affiliation 0.96, rights 0.82) and
+  documents the per-field over-merge cliff. Results and interpretation added to
+  `docs/methods.md` §8.
+
+### Changed
+- Docs and preset docstrings now describe the `eps` values as V-measure validated
+  (not "proposed"). No `eps` values changed — validation confirmed the existing
+  settings. `rights` flagged as better served by a controlled vocabulary.
+
+## [0.1.0] - 2026-07-10
+
+Initial release. A generalizable, authority-aware synonym-normalization tool for
+FAIR / DataCite metadata fields, distilled from the methods proven on the
+posters.science corpus.
+
+### Added
+- **Synonym-lustre engine** (`fairly.cluster`): gte-large embeddings + HDBSCAN
+  (`min_cluster_size=2, min_samples=1, cluster_selection_epsilon, leaf`) with a
+  most-frequent-canonical (centroid tie-break) rule; disk-cached embeddings keyed
+  on model id + cache version.
+- **Abbreviation / short-token holdout** (`fairly.holdout`): `< 4`-char and
+  all-caps single-token terms are held out of clustering (map to themselves) to
+  prevent short-string over-merges (`ZHAW → Z`).
+- **ROR authority split** (`fairly.authorities.ror`): build a `name → ROR id`
+  index from a ROR v2 dump (ambiguous names dropped) and split semantic clusters
+  that span two or more institutions.
+- **Geocoding normalization** (`fairly.authorities.geocode`): geocode place
+  fields (Nominatim, cached, rate-limited) and group by `(country, city)` →
+  `"City, Country"`; pluggable resolver.
+- **Deterministic cleaners** (`fairly.cleaners`): composable steps + `ORG`,
+  `SUBJECT`, `MINIMAL` presets (balanced quote-unwrap, preamble strip, placeholder
+  / generic / hedge / citation drop, word-boundary-safe).
+- **V-measure validation** (`fairly.validate`): gold-set homogeneity /
+  completeness / V-measure across an `eps` sweep, with explicit noise handling, to
+  tune `cluster_selection_epsilon` per field.
+- **DataCite field presets** (`fairly.presets`): `publisher`, `funderName`,
+  `affiliation`, `subject`, `rights`, `geoLocationPlace`.
+- **Field-path I/O** (`fairly.io`): CSV/TSV columns and dotted JSON/JSONL paths
+  through nested dicts and lists (`creators[].affiliation[].name`).
+- **CLI** (`fairly`): `presets`, `build-ror-index`, `validate`, `normalize`.
+- Packaging (`fairly-synonyms`), optional `cluster` / `geo` / `all` extras, MIT
+  license, and a test suite (30 tests) covering the pure-logic and clustering paths.
+
+[0.2.0]: https://github.com/fairdataihub/fair-ly-accurate-text-synonyms-for-data-cleaning/releases/tag/v0.2.0
+[0.1.1]: https://github.com/fairdataihub/fair-ly-accurate-text-synonyms-for-data-cleaning/releases/tag/v0.1.1
+[0.1.0]: https://github.com/fairdataihub/fair-ly-accurate-text-synonyms-for-data-cleaning/releases/tag/v0.1.0

fair_ly_accurate-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FAIR Data Innovations Hub
+
+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.

fair_ly_accurate-0.3.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: fair-ly-accurate
+Version: 0.3.0
+Summary: Fair-ly accurate text synonyms for data cleaning: authority-aware synonym collapsing and normalization of FAIR / DataCite metadata fields.
+Project-URL: Homepage, https://github.com/fairdataihub/fair-ly-accurate-text-synonyms-for-data-cleaning
+Project-URL: Repository, https://github.com/fairdataihub/fair-ly-accurate-text-synonyms-for-data-cleaning
+Author: FAIR Data Innovations Hub
+License: MIT License
+        
+        Copyright (c) 2026 FAIR Data Innovations Hub
+        
+        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.
+License-File: LICENSE
+Keywords: DataCite,FAIR,ROR,clustering,entity-resolution,metadata,normalization,synonyms
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: all
+Requires-Dist: geopy>=2.3; extra == 'all'
+Requires-Dist: scikit-learn>=1.3; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2; extra == 'all'
+Provides-Extra: cluster
+Requires-Dist: scikit-learn>=1.3; extra == 'cluster'
+Requires-Dist: sentence-transformers>=2.2; extra == 'cluster'
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: geo
+Requires-Dist: geopy>=2.3; extra == 'geo'
+Description-Content-Type: text/markdown
+
+# fair-ly accurate text synonyms for data cleaning
+
+**`fairly`** collapses spelling and format variants of FAIR / DataCite metadata
+field values onto a single canonical form — *fairly accurately* — so that
+`Univ. of California, Berkeley`, `University of California-Berkeley` and
+`UC Berkeley` all become one publisher/affiliation, while genuinely different
+entities (`University of Washington` vs `Washington University`) stay apart.
+
+It packages four cooperating strategies, each earning its place against a real
+failure mode:
+
+| Strategy | What it does | Guards against |
+|---|---|---|
+| **Synonym-lustre** | embed distinct values (`gte-large`) → cluster (HDBSCAN) → map each cluster to its most-frequent member | spelling/format/punctuation variants |
+| **Abbreviation holdout** | keep acronyms and `< 4`-char tokens *out* of clustering | `ZHAW → Z`, `LUH → HU` over-merges |
+| **ROR authority split** | split a cluster that spans two real institutions using a local ROR dump | `University of Washington` vs `Washington University` |
+| **Geocoding** | for place fields, geocode and group by `(country, city)` → `"City, Country"` | `Graz` merging into `Vienna` ("city in Austria") |
+| **Controlled vocab** | for fixed-vocabulary fields (licenses, codes), deterministically fold + alias-resolve to a canonical id | `CC-BY-SA` collapsing into `CC-BY-NC` — clustering can't tell them apart |
+
+Quality is measured, not assumed: a **V-measure** harness tunes the clustering
+threshold per field against a small gold set.
+
+> Method background and per-field recommendations: **[docs/methods.md](docs/methods.md)**.
+
+## Install
+
+```bash
+pip install fair-ly-accurate                 # core (cleaners, ROR index, I/O, V-measure math)
+pip install "fair-ly-accurate[cluster]"      # + embeddings & HDBSCAN (semantic clustering)
+pip install "fair-ly-accurate[geo]"          # + geopy (place geocoding)
+pip install "fair-ly-accurate[all]"          # everything
+```
+
+(The distribution installs as `fair-ly-accurate`; the import name is `fairly`: `from fairly import Normalizer`.)
+
+The heavy ML/geo dependencies are optional extras, so the deterministic cleaners,
+ROR index and field-path I/O install light.
+
+## Quickstart (CLI)
+
+```bash
+# 0. (once, for institution fields) build a ROR index from a ROR v2 dump
+fairly build-ror-index --dump v2-ror-data.json --out ror_index.pickle
+
+# 1. tune the threshold for a field against a gold set (variant<TAB>true_canonical)
+fairly validate --gold affiliation_gold.tsv --preset affiliation --field affiliation
+
+# 2. build + apply a synonym map to a DataCite-shaped field, with review + ROR split
+fairly normalize \
+  --input records.jsonl \
+  --field-path 'creators[].affiliation[].name' \
+  --preset affiliation \
+  --ror-index ror_index.pickle \
+  --review affiliation_review.tsv \
+  --output records.normalized.jsonl
+```
+
+The `--field-path` understands dotted paths through nested dicts and lists, e.g.
+`publisher.name`, `fundingReferences[].funderName`, `subjects[].subject`,
+`creators[].affiliation[].name`. Tabular inputs use the column name as the path.
+
+**Always eyeball the `--review` TSV before trusting an apply** — especially for
+homogeneous fields like funders, where over-merge is easy. Add `--dry-run` to
+build the map and review without writing.
+
+## Quickstart (library)
+
+```python
+from fairly import Normalizer, get_preset
+from fairly.authorities.ror import RorIndex
+from fairly.io import collect_counts, read_records, map_values
+
+records = read_records("records.jsonl")
+counts  = collect_counts(records, "fundingReferences[].funderName")
+
+norm = Normalizer(get_preset("funderName"), cache_dir=".cache")
+smap = norm.build(counts, authority=RorIndex.load("ror_index.pickle"))
+smap.write_review("funder_review.tsv", counts)     # review gate
+
+for rec in records:
+    map_values(rec, "fundingReferences[].funderName", lambda v: norm.normalize(v, smap))
+```
+
+## Field presets
+
+Built-in `FieldConfig` presets for common DataCite/FAIR fields (`fairly presets`):
+
+| Field | Strategy | eps | Holdout | Authority |
+|---|---|---|---|---|
+| `publisher` | semantic | 0.30 | yes | ROR |
+| `funderName` | semantic | 0.07 | yes | ROR |
+| `affiliation` | semantic | 0.07 | yes | ROR |
+| `subject` | semantic | 0.10 | yes | — |
+| `rights` | **controlled** | — | — | SPDX/CC vocab |
+| `geoLocationPlace` | geocode | — | — | — |
+
+These `eps` values are **V-measure validated** against the curated gold sets in
+[`gold/`](gold/) — each sits on its field's optimal plateau (funder/subject 1.00,
+publisher 0.99, affiliation 0.96; `rights` 0.82, so prefer a controlled vocabulary
+for licenses). **Re-tune for your data** with `fairly validate` — see
+[docs/methods.md](docs/methods.md#8-v-measure-validation) for the full sweep and why
+each field wants a different threshold.
+
+## Why these choices
+
+- **Most-frequent canonical** gives clean, recognizable labels (the common form
+  wins), with centroid-closeness only breaking ties.
+- **Holdout** exists because short/all-caps tokens carry too little signal for an
+  embedding to place; left in, they become spurious join keys.
+- **Authority split** is what lets us cluster *aggressively* for coverage without
+  paying for it in precision: the embedding proposes merges, ROR/geocoding vetoes
+  the wrong ones.
+- **V-measure** turns "did we over-merge?" into a number: homogeneity penalizes
+  over-merge (the costly direction), completeness penalizes under-merge.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

fair_ly_accurate-0.3.0/README.md

@@ -0,0 +1,118 @@
+# fair-ly accurate text synonyms for data cleaning
+
+**`fairly`** collapses spelling and format variants of FAIR / DataCite metadata
+field values onto a single canonical form — *fairly accurately* — so that
+`Univ. of California, Berkeley`, `University of California-Berkeley` and
+`UC Berkeley` all become one publisher/affiliation, while genuinely different
+entities (`University of Washington` vs `Washington University`) stay apart.
+
+It packages four cooperating strategies, each earning its place against a real
+failure mode:
+
+| Strategy | What it does | Guards against |
+|---|---|---|
+| **Synonym-lustre** | embed distinct values (`gte-large`) → cluster (HDBSCAN) → map each cluster to its most-frequent member | spelling/format/punctuation variants |
+| **Abbreviation holdout** | keep acronyms and `< 4`-char tokens *out* of clustering | `ZHAW → Z`, `LUH → HU` over-merges |
+| **ROR authority split** | split a cluster that spans two real institutions using a local ROR dump | `University of Washington` vs `Washington University` |
+| **Geocoding** | for place fields, geocode and group by `(country, city)` → `"City, Country"` | `Graz` merging into `Vienna` ("city in Austria") |
+| **Controlled vocab** | for fixed-vocabulary fields (licenses, codes), deterministically fold + alias-resolve to a canonical id | `CC-BY-SA` collapsing into `CC-BY-NC` — clustering can't tell them apart |
+
+Quality is measured, not assumed: a **V-measure** harness tunes the clustering
+threshold per field against a small gold set.
+
+> Method background and per-field recommendations: **[docs/methods.md](docs/methods.md)**.
+
+## Install
+
+```bash
+pip install fair-ly-accurate                 # core (cleaners, ROR index, I/O, V-measure math)
+pip install "fair-ly-accurate[cluster]"      # + embeddings & HDBSCAN (semantic clustering)
+pip install "fair-ly-accurate[geo]"          # + geopy (place geocoding)
+pip install "fair-ly-accurate[all]"          # everything
+```
+
+(The distribution installs as `fair-ly-accurate`; the import name is `fairly`: `from fairly import Normalizer`.)
+
+The heavy ML/geo dependencies are optional extras, so the deterministic cleaners,
+ROR index and field-path I/O install light.
+
+## Quickstart (CLI)
+
+```bash
+# 0. (once, for institution fields) build a ROR index from a ROR v2 dump
+fairly build-ror-index --dump v2-ror-data.json --out ror_index.pickle
+
+# 1. tune the threshold for a field against a gold set (variant<TAB>true_canonical)
+fairly validate --gold affiliation_gold.tsv --preset affiliation --field affiliation
+
+# 2. build + apply a synonym map to a DataCite-shaped field, with review + ROR split
+fairly normalize \
+  --input records.jsonl \
+  --field-path 'creators[].affiliation[].name' \
+  --preset affiliation \
+  --ror-index ror_index.pickle \
+  --review affiliation_review.tsv \
+  --output records.normalized.jsonl
+```
+
+The `--field-path` understands dotted paths through nested dicts and lists, e.g.
+`publisher.name`, `fundingReferences[].funderName`, `subjects[].subject`,
+`creators[].affiliation[].name`. Tabular inputs use the column name as the path.
+
+**Always eyeball the `--review` TSV before trusting an apply** — especially for
+homogeneous fields like funders, where over-merge is easy. Add `--dry-run` to
+build the map and review without writing.
+
+## Quickstart (library)
+
+```python
+from fairly import Normalizer, get_preset
+from fairly.authorities.ror import RorIndex
+from fairly.io import collect_counts, read_records, map_values
+
+records = read_records("records.jsonl")
+counts  = collect_counts(records, "fundingReferences[].funderName")
+
+norm = Normalizer(get_preset("funderName"), cache_dir=".cache")
+smap = norm.build(counts, authority=RorIndex.load("ror_index.pickle"))
+smap.write_review("funder_review.tsv", counts)     # review gate
+
+for rec in records:
+    map_values(rec, "fundingReferences[].funderName", lambda v: norm.normalize(v, smap))
+```
+
+## Field presets
+
+Built-in `FieldConfig` presets for common DataCite/FAIR fields (`fairly presets`):
+
+| Field | Strategy | eps | Holdout | Authority |
+|---|---|---|---|---|
+| `publisher` | semantic | 0.30 | yes | ROR |
+| `funderName` | semantic | 0.07 | yes | ROR |
+| `affiliation` | semantic | 0.07 | yes | ROR |
+| `subject` | semantic | 0.10 | yes | — |
+| `rights` | **controlled** | — | — | SPDX/CC vocab |
+| `geoLocationPlace` | geocode | — | — | — |
+
+These `eps` values are **V-measure validated** against the curated gold sets in
+[`gold/`](gold/) — each sits on its field's optimal plateau (funder/subject 1.00,
+publisher 0.99, affiliation 0.96; `rights` 0.82, so prefer a controlled vocabulary
+for licenses). **Re-tune for your data** with `fairly validate` — see
+[docs/methods.md](docs/methods.md#8-v-measure-validation) for the full sweep and why
+each field wants a different threshold.
+
+## Why these choices
+
+- **Most-frequent canonical** gives clean, recognizable labels (the common form
+  wins), with centroid-closeness only breaking ties.
+- **Holdout** exists because short/all-caps tokens carry too little signal for an
+  embedding to place; left in, they become spurious join keys.
+- **Authority split** is what lets us cluster *aggressively* for coverage without
+  paying for it in precision: the embedding proposes merges, ROR/geocoding vetoes
+  the wrong ones.
+- **V-measure** turns "did we over-merge?" into a number: homogeneity penalizes
+  over-merge (the costly direction), completeness penalizes under-merge.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

fair_ly_accurate-0.3.0/RELEASING.md

@@ -0,0 +1,57 @@
+# Releasing `fair-ly-accurate` to PyPI
+
+Publishing is automated with **PyPI Trusted Publishing (OIDC)** — GitHub Actions
+mints a short-lived token per run, so there are no API tokens to store or rotate.
+The workflow lives in [`.github/workflows/publish.yml`](.github/workflows/publish.yml):
+publishing a **GitHub Release** builds the distributions and uploads them to PyPI.
+
+## One-time setup
+
+Register this repo as a *trusted publisher* on PyPI. Because the project does not
+exist yet, use the "pending publisher" form:
+
+- **PyPI** — https://pypi.org/manage/account/publishing/ → *Add a pending publisher*
+  - PyPI Project Name: `fair-ly-accurate`
+  - Owner: `fairdataihub`
+  - Repository name: `fair-ly-accurate-text-synonyms-for-data-cleaning`
+  - Workflow name: `publish.yml`
+  - Environment name: `pypi`
+
+The first successful publish creates the `fair-ly-accurate` project owned by the account
+that registered the pending publisher.
+
+(Optional, recommended) In GitHub → *Settings → Environments*, create an
+environment named `pypi` and add yourself as a **required reviewer**, so a publish
+needs a human click even though the repo may have other maintainers with write
+access.
+
+## Cutting a release
+
+1. Bump the version in **both** places (they must match, or the workflow fails the build):
+   - `pyproject.toml` → `version = "X.Y.Z"`
+   - `src/fairly/__init__.py` → `__version__ = "X.Y.Z"`
+   - Add a `CHANGELOG.md` entry.
+2. Commit, then tag and push:
+   ```bash
+   git commit -am "Release X.Y.Z"
+   git tag vX.Y.Z
+   git push && git push --tags
+   ```
+3. Create a **GitHub Release** for that tag
+   (Releases → Draft a new release → choose `vX.Y.Z` → Publish). That triggers the
+   PyPI publish job.
+4. Confirm:
+   ```bash
+   pip install fair-ly-accurate==X.Y.Z
+   ```
+
+PyPI refuses to overwrite an existing version, so every release needs a fresh
+version number.
+
+## Local build check
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```