ragless 0.1.0__tar.gz

ragless-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --cov=ragless --cov-report=term-missing --cov-fail-under=85
+
+  test-semantic-slow:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,semantic]"
+      - run: pytest -q --run-slow -m slow
+
+  build:
+    needs: [test, test-semantic-slow]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - run: pip install dist/*.whl
+      - name: Smoke test the built wheel
+        run: |
+          cd /tmp
+          python -c "
+          import ragless
+          r = ragless.Retriever(['hello world', 'goodbye world'])
+          assert r.search('hello')
+          print('ragless', ragless.__version__, 'smoke test OK')
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

ragless-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --cov=ragless --cov-fail-under=85
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ragless/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ragless-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+.ragless_cache/

ragless-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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/).
+
+## [0.1.0] - 2026-11-12
+
+### Added
+
+- `Retriever`: library-first API indexing a directory or in-memory text.
+- `LineChunker`: overlapping line-window chunking that preserves file path
+  and 1-indexed start/end line numbers.
+- `BM25Retriever`: Okapi BM25 keyword search (pure NumPy, no extra deps).
+- `FuzzyRetriever`: fuzzy string matching via `rapidfuzz`.
+- `SemanticRetriever`: local embedding search (`fastembed`, optional
+  `semantic` extra) with NumPy cosine similarity.
+- Reciprocal Rank Fusion (`reciprocal_rank_fusion`) to combine engine
+  rankings, with configurable weights and `k`.
+- `CrossEncoderReranker`: optional cross-encoder reranking of fused results.
+- On-disk embedding cache (`EmbeddingCache`) as plain `.npy`/`.json` sidecar
+  files, keyed by file mtime/size, so only changed files are re-embedded.
+- Metadata and path filters on `search()`.
+- Pluggable chunkers, retrievers, and embedders.

ragless-0.1.0/DECISIONS.md

@@ -0,0 +1,105 @@
+# Autonomous build decisions
+
+Decisions made while building `ragless` without the user available to ask.
+
+## Packaging / tooling
+
+- **Build backend**: hatchling with a `src/` layout. Simple, no `setup.py`,
+  plays well with editable installs and PyPI trusted publishing.
+- **Python support**: `>=3.10`. Chosen as a modern-but-not-bleeding-edge
+  floor; CI covers 3.10-3.13 on Ubuntu and macOS.
+- **GitHub owner/repo**: created under the authenticated `gh` account
+  `mohmdqasim`, repo name `ragless` (public). `pyproject.toml` URLs point
+  at `https://github.com/mohmdqasim/ragless`.
+- **Linting**: `ruff` (check + format), configured in `pyproject.toml`
+  (`[tool.ruff]`). CI fails on any lint or formatting diff.
+- **Coverage gate**: `--cov-fail-under=85` in CI, matching the 85%+ target.
+  Actual achieved coverage on the fast suite is ~90%.
+
+## Dependencies
+
+- **BM25**: implemented from scratch (`ragless/retrievers/bm25.py`) using
+  only NumPy, rather than pulling in `rank-bm25` or a search engine. Keeps
+  the core dependency surface to just `numpy` + `rapidfuzz`.
+- **Fuzzy**: `rapidfuzz` (explicitly requested in the spec), used via
+  `rapidfuzz.process.extract`.
+- **Semantic embeddings**: `fastembed` (ONNX runtime-based), not
+  `sentence-transformers`/`torch`. Much lighter install for an optional
+  extra, still fully local with no API keys. Default model:
+  `BAAI/bge-small-en-v1.5` (verified available in fastembed's supported
+  model list at build time).
+- **Cross-encoder rerank**: also via `fastembed` (`fastembed.rerank.
+  cross_encoder.TextCrossEncoder`), under the same `semantic` extra rather
+  than a separate `rerank` extra, since it's the same dependency. Default
+  model: `Xenova/ms-marco-MiniLM-L-6-v2`.
+- Both default model names were confirmed against the installed fastembed
+  version's `list_supported_models()` before being hardcoded.
+
+## API shape
+
+- `Retriever(source, *, texts=None, chunker=None, engines=None,
+  embedder=None, cache_dir=None, include=None, exclude=None, metadata=None,
+  encoding="utf-8", rrf_k=60, weights=None)`.
+  - `source` accepts a directory path, a single file path, or a sequence of
+    raw strings (in-memory documents) directly as the first positional arg,
+    per the spec's "should also accept in-memory text". `texts=` is an
+    additional kwarg so in-memory notes can be mixed in alongside a
+    directory source.
+  - `engines` defaults to `("bm25", "fuzzy")` only -- semantic is opt-in via
+    `engines=[..., "semantic"]`, keeping the core install light as required.
+    It also accepts a `Mapping[str, BaseRetriever]` for full pluggability
+    (bring your own retriever implementation under any engine name).
+  - `metadata` can be a constant dict or a `path -> dict` callable, so
+    per-file metadata tagging doesn't require a separate data structure.
+- **Filters** are two separate mechanisms, matching the spec's "metadata and
+  path filters": `filters={"key": value_or_predicate}` against chunk
+  metadata, and `path_filter="*glob*"` (or a list of globs) against the
+  chunk's file path. In-memory chunks (`path is None`) never match a
+  `path_filter`.
+- **Fusion**: Reciprocal Rank Fusion with `k=60` (the constant from the
+  original Cormack et al. RRF paper), configurable per-`Retriever` via
+  `rrf_k=` and per-engine `weights=`.
+- **Caching**: one `.npy` + `.json` sidecar pair per *source file* (not per
+  chunk), keyed by `sha256(path :: embedder_name)[:24]` to keep filenames
+  short and collision-resistant, with the original path stored inside the
+  JSON for debuggability. Invalidated on `(mtime, size)` signature change,
+  embedder name/dim change, or chunk id list change (covers chunker/config
+  changes too, not just file edits). In-memory text is never cached (no
+  stable file identity to invalidate against).
+- Binary files and files that fail to decode under the given `encoding` are
+  silently skipped rather than raising, matching "works on folders" robustly
+  without per-file configuration. (Detected via a null-byte check in the
+  first 8KB, then a decode attempt.)
+
+## Testing
+
+- `tests/conftest.py` provides a dependency-free `FakeEmbedder` (hashed
+  bag-of-words) so semantic-retriever logic, caching, and fusion can all be
+  tested without downloading a real model.
+- Real-model tests (`tests/test_semantic_real_model.py`) are marked
+  `@pytest.mark.slow` and additionally gated by a `--run-slow` CLI flag
+  (added in `conftest.py`); they're skipped by default and run in a
+  dedicated CI job (`test-semantic-slow`) that installs the `semantic`
+  extra. The fast test suite never needs network access or fastembed
+  installed (verified by running it in a venv with no semantic extra).
+- "Missing optional extra" behavior is tested by monkeypatching
+  `sys.modules["fastembed"] = None` rather than requiring a real
+  extra-less environment for every test run -- `FastEmbedEmbedder` and
+  `CrossEncoderReranker` both import `fastembed` lazily inside `__init__`,
+  so this reliably triggers the same `ImportError` path.
+
+## CI / publishing
+
+- `ci.yml`: `lint` (ruff) -> `test` (matrix: ubuntu/macos x 3.10-3.13,
+  `--cov-fail-under=85`) + `test-semantic-slow` (ubuntu/3.12 only, installs
+  `semantic` extra, runs `--run-slow -m slow`) -> `build` (sdist/wheel +
+  wheel-install smoke test).
+- `publish.yml`: triggers on `v*` tags; re-runs the test matrix and a build
+  job *inside this workflow* (a separate workflow run can't `needs:` another
+  workflow's jobs), then `publish` (environment `pypi`, `permissions:
+  id-token: write`) uses `pypa/gh-action-pypi-publish` with OIDC trusted
+  publishing -- no API token stored in the repo.
+- **PyPI trusted publisher registration is a manual, credential-gated step**
+  that this session cannot perform (it requires logging into pypi.org as
+  the account that will own the `ragless` project). See `PROGRESS.md` for
+  exactly what to do.

ragless-0.1.0/LICENSE

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

ragless-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: ragless
+Version: 0.1.0
+Summary: File-based retrieval for RAG, no vector database required
+Project-URL: Homepage, https://github.com/mohmdqasim/ragless
+Project-URL: Repository, https://github.com/mohmdqasim/ragless
+Project-URL: Issues, https://github.com/mohmdqasim/ragless/issues
+Project-URL: Changelog, https://github.com/mohmdqasim/ragless/blob/main/CHANGELOG.md
+Author-email: Qasim Arshad <mohmdqasim0@gmail.com>
+Maintainer-email: Qasim Arshad <mohmdqasim0@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bm25,embeddings,information-retrieval,rag,retrieval,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: rapidfuzz>=3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: semantic
+Requires-Dist: fastembed>=0.3; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# ragless
+
+File-based retrieval for RAG, with no vector database.
+
+`ragless` indexes a folder of text files (or in-memory strings) and lets you
+search them with BM25 keyword search, fuzzy string matching, and optional
+local semantic embeddings -- combined with Reciprocal Rank Fusion. Everything
+lives on disk as plain files (or in memory): no Postgres/pgvector, no
+Pinecone/Weaviate/Chroma server, nothing to run.
+
+```python
+from ragless import Retriever
+
+r = Retriever("./docs")
+for hit in r.search("how do I configure retries", mode="hybrid"):
+    print(f"{hit.path}:{hit.start_line}-{hit.end_line}  score={hit.score:.3f}")
+    print(hit.text)
+```
+
+## Install
+
+```bash
+pip install ragless                # BM25 + fuzzy (no heavy deps)
+pip install 'ragless[semantic]'    # + local embeddings and cross-encoder rerank
+```
+
+## Quickstart
+
+```python
+from ragless import Retriever
+
+# Index a directory of files.
+r = Retriever("./docs")
+results = r.search("installation steps", mode="hybrid", top_k=5)
+
+# Or index in-memory text directly -- no files required.
+r = Retriever(
+    [
+        "ragless indexes folders of text files for retrieval.",
+        "BM25, fuzzy matching, and semantic search are combined with RRF.",
+    ]
+)
+results = r.search("how are results combined?")
+
+for hit in results:
+    print(hit.path, hit.start_line, hit.end_line, hit.score)
+    print(hit.text)
+```
+
+### Search modes
+
+```python
+r.search("query", mode="hybrid")  # fuse every configured engine (default)
+r.search("query", mode="bm25")  # keyword search only
+r.search("query", mode="fuzzy")  # fuzzy string matching only
+r.search("query", mode="semantic")  # embeddings only (requires the extra)
+```
+
+### Semantic search and caching
+
+```python
+from ragless import Retriever
+
+r = Retriever(
+    "./docs",
+    engines=["bm25", "fuzzy", "semantic"],
+    cache_dir="./.ragless_cache",  # embeddings cached here as .npy/.json
+)
+r.search("query", mode="hybrid")
+```
+
+Embeddings are cached per source file, keyed by the file's mtime/size and the
+embedder's name. Editing one file only re-embeds that file's chunks on the
+next run; untouched files are loaded straight from the cache.
+
+### Cross-encoder rerank
+
+```python
+r.search("query", mode="hybrid", rerank=True)
+```
+
+Reranking takes the top fused candidates and rescoring them with a small
+local cross-encoder (also via `fastembed`, under the `semantic` extra) for
+higher precision at the top of the list.
+
+### Filters
+
+```python
+# Only chunks whose metadata says category="guide"
+r.search("query", filters={"category": "guide"})
+
+# Only chunks from markdown files
+r.search("query", path_filter="*.md")
+
+# Per-document metadata, assigned when building the index
+r = Retriever(
+    "./docs",
+    metadata=lambda path: {"category": "guide"} if path and "guide" in path else {},
+)
+```
+
+### Pluggable components
+
+Chunkers, retrievers, and embedders are all swappable:
+
+```python
+from ragless import Retriever, Chunker, BaseRetriever
+from ragless.chunking import LineChunker
+
+r = Retriever("./docs", chunker=LineChunker(lines_per_chunk=60, overlap=10))
+
+# Bring your own retriever/embedder implementation:
+r = Retriever("./docs", engines={"bm25": MyRetriever(), "fuzzy": FuzzyRetriever()})
+```
+
+Implement `ragless.chunking.Chunker`, `ragless.retrievers.base.BaseRetriever`,
+or `ragless.embedders.base.Embedder` to plug in your own.
+
+## Why
+
+Most "RAG" tutorials reach for a vector database before checking whether they
+need one. For a folder of a few thousand files, plain keyword search (BM25),
+fuzzy matching, and a small local embedding model get you most of the way
+there, with:
+
+- No server to run, no API keys, no network calls (semantic search runs a
+  small model locally via [fastembed](https://github.com/qdrant/fastembed)).
+- No ingestion pipeline: point it at a directory and it chunks and indexes on
+  construction.
+- Caching as plain sidecar files (`.npy` + `.json`) next to your index, not a
+  database you have to back up and migrate.
+- Every result keeps the file path and line range it came from.
+
+| | ragless | vector DB (Pinecone/Chroma/pgvector) |
+|---|---|---|
+| Infra | none | a running database/service |
+| Setup | `Retriever("./docs")` | provision, configure, ingest |
+| Keyword search | built in (BM25) | usually bolted on separately |
+| Fuzzy/typo tolerance | built in | usually absent |
+| Good for | a few thousand files, local tools, CLIs, CI | large, constantly-changing, multi-tenant corpora |
+| Cold start | instant | needs the service up and reachable |
+
+If you need to search tens of millions of chunks with concurrent writers
+across a fleet of machines, use a vector database. If you need to search the
+docs folder sitting next to your code, `ragless` is simpler.
+
+## How it works
+
+1. **Load** -- read files from a directory (or accept raw in-memory strings).
+   Binary files and undecodable text are skipped automatically.
+2. **Chunk** -- split each document into overlapping line-based windows,
+   keeping the file path and 1-indexed `start_line`/`end_line` for every
+   chunk (`ragless.chunking.LineChunker`, pluggable).
+3. **Index** -- each configured engine builds its own index over the chunks:
+   - `BM25Retriever`: classic Okapi BM25 over tokenized text (NumPy).
+   - `FuzzyRetriever`: `rapidfuzz` string similarity.
+   - `SemanticRetriever`: dense embeddings (`fastembed`) with cosine
+     similarity (NumPy), cached to disk as `.npy`/`.json` sidecar files.
+4. **Search** -- query every configured engine, fuse their rankings with
+   [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf),
+   apply metadata/path filters, and optionally rerank the top candidates with
+   a cross-encoder.
+
+## Status
+
+0.1.0 -- the API may still shift. Feedback and issues welcome.
+
+## License
+
+MIT

ragless-0.1.0/PROGRESS.md

@@ -0,0 +1,86 @@
+# Progress
+
+Autonomous build log for `ragless`. Updated as work proceeds.
+
+## Status: build complete, CI green on GitHub, publishing blocked on a manual PyPI step
+
+### Done
+
+- [x] Full package implemented under `src/ragless/` (chunking, BM25, fuzzy,
+      semantic, fusion, rerank, cache, core `Retriever`), pluggable
+      throughout, with type hints and docstrings.
+- [x] Test suite: 61 fast tests (chunker, each retriever, fusion, cache
+      invalidation, filters, directory/in-memory loading, binary/empty/
+      unicode/large-file edge cases, missing-extra error messages, custom
+      reranker) + 2 slow tests gated behind `--run-slow`/`-m slow`.
+- [x] Fast suite passes in a venv **without** the `semantic` extra installed
+      (confirms the core install is genuinely light).
+- [x] Slow suite passes with the real `fastembed` model
+      (`BAAI/bge-small-en-v1.5` + `Xenova/ms-marco-MiniLM-L-6-v2`).
+- [x] `ruff check .` and `ruff format --check .` both clean.
+- [x] Coverage: 90% (gate set at 85% in CI).
+- [x] `python -m build` produces sdist + wheel; installed the wheel into a
+      fresh venv and ran an import + search smoke test successfully.
+- [x] README (quickstart, API examples, how it works, comparison table),
+      CHANGELOG.md, `examples/` (4 runnable scripts, all manually run and
+      verified, including the semantic+rerank one).
+- [x] `.github/workflows/ci.yml` (lint, test matrix ubuntu/macos x
+      3.10-3.13, slow-model job, build+smoke-test job).
+- [x] `.github/workflows/publish.yml` (triggers on `v*` tags, reruns tests,
+      builds, then publishes via OIDC trusted publishing to the `pypi`
+      environment).
+
+- [x] `git init` + initial commit, history kept to clean, correctly-authored
+      commits (`Qasim Arshad <mohmdqasim0@gmail.com>`), no AI/trailer
+      mentions anywhere.
+- [x] `twine check dist/*` passes (sdist + wheel); PyPI page will render the
+      full README as `text/markdown` with correct author/maintainer and
+      project URLs (Homepage/Repository/Issues/Changelog).
+- [x] Public GitHub repo created at https://github.com/mohmdqasim/ragless
+      (the repo was first created under the wrong, auto-selected `gh`
+      account and was recreated here after the user logged `gh` into their
+      personal account; the old repo was deleted by the user).
+- [x] `pypi` GitHub Environment created on the repo via `gh api`.
+- [x] CI green on `main`: lint, test matrix (ubuntu/macos x 3.10-3.13),
+      slow-model job, and build+smoke-test job all passed
+      (https://github.com/mohmdqasim/ragless/actions).
+
+### Next
+
+- [ ] Tag `v0.1.0`, push the tag, watch the publish workflow run.
+- [ ] Verify with `pip install ragless` in a fresh venv + a quick search.
+
+## Blocking item: PyPI trusted publisher registration
+
+**This cannot be completed autonomously** -- it requires logging into
+pypi.org with human credentials, which this session does not have and
+should not attempt to obtain.
+
+`publish.yml` is wired for PyPI's OIDC "trusted publishing": no API token is
+stored anywhere, but PyPI must be told in advance which GitHub repo/workflow
+is allowed to publish the `ragless` project. For a project that has never
+been published before, this is done once via PyPI's web UI as a **pending
+publisher**, which reserves the name and links it to this workflow ahead of
+the first publish.
+
+### What you need to do (takes ~1 minute)
+
+1. Log into https://pypi.org (create an account first if you don't have
+   one).
+2. Go to https://pypi.org/manage/account/publishing/
+3. Under "Add a new pending publisher", fill in:
+   - **PyPI project name**: `ragless`
+   - **Owner**: `mohmdqasim`
+   - **Repository name**: `ragless`
+   - **Workflow name**: `publish.yml`
+   - **Environment name**: `pypi`
+4. Submit. That's it -- no token to copy anywhere.
+
+Once that's set up, the next tag push (or a re-run of a failed `publish.yml`
+run) will publish successfully. If this step hasn't been done yet when this
+session tags `v0.1.0` and pushes it, the `publish` job in the workflow run
+will fail at the PyPI upload step with an authentication error -- that is
+expected and not a bug in the workflow; it just means the pending publisher
+above still needs to be registered, after which re-running that same
+workflow run (via the GitHub Actions UI, or pushing a new tag like `v0.1.1`)
+will succeed.