nlp2sql 0.2.0rc15__tar.gz → 0.2.0rc17__tar.gz

nlp2sql-0.2.0rc17/.github/scripts/verify_release_tag.py

@@ -0,0 +1,48 @@
+"""Check that a release tag matches the package version before publishing.
+
+The publish workflows run this before building, so a package is only ever
+published from a tag named ``v`` + the ``[project].version`` of pyproject.toml.
+
+Usage: python .github/scripts/verify_release_tag.py v0.2.0rc16
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+import tomllib
+
+TAG_PATTERN = re.compile(r"v\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?")
+PYPROJECT = Path(__file__).resolve().parents[2] / "pyproject.toml"
+SEE_DOCS = "See 'Releasing (maintainers)' in CONTRIBUTING.md."
+
+
+def fail(message: str) -> int:
+    print(f"::error title=Release tag check failed::{message} {SEE_DOCS}")
+    return 1
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Check that a release tag matches the version in pyproject.toml.")
+    parser.add_argument("tag", help="release tag, for example v0.2.0rc16")
+    tag = parser.parse_args(argv).tag
+
+    if not TAG_PATTERN.fullmatch(tag):
+        return fail(f"'{tag}' is not a release tag: expected vX.Y.Z, optionally followed by aN, bN or rcN.")
+
+    with PYPROJECT.open("rb") as file:
+        version = tomllib.load(file)["project"]["version"]
+    if tag != f"v{version}":
+        return fail(
+            f"Tag {tag} does not match the pyproject.toml version ({version}) of the checked-out commit. "
+            "Was the release created before the version bump was pushed?"
+        )
+
+    print(f"Tag {tag} matches the pyproject.toml version {version}.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nlp2sql-0.2.0rc17/.github/workflows/ci.yml

@@ -0,0 +1,137 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v7
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      run: python -m pip install uv
+
+    - name: Install dependencies
+      run: |
+        uv pip install --system .
+        uv pip install --system ".[dev]"
+
+    - name: Unit tests
+      env:
+        PYTHONPATH: src
+      run: pytest -m "not integration and not llm" -q
+
+  pgvector-integration:
+    runs-on: ubuntu-24.04
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: testuser
+          POSTGRES_PASSWORD: testpass
+          POSTGRES_DB: testdb
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U testuser -d testdb"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v7
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      run: python -m pip install uv
+
+    - name: Install dependencies (with pgvector extra)
+      run: |
+        uv pip install --system ".[dev]"
+        uv pip install --system ".[pgvector]"
+
+    - name: Load the e-commerce test schema
+      env:
+        PGPASSWORD: testpass
+      run: psql -h localhost -U testuser -d testdb -v ON_ERROR_STOP=1 -q -f docker/init-schema.sql
+
+    # Scoped suites so the job stays self-contained (the broader integration
+    # suite also needs LocalStack Redshift, out of scope here).
+    # NLP2SQL_REQUIRE_INTEGRATION makes the fixtures FAIL instead of skip, so a
+    # misconfigured service goes red rather than green-via-skip.
+    - name: pgvector integration tests
+      env:
+        PYTHONPATH: src
+        NLP2SQL_REQUIRE_INTEGRATION: "1"
+        NLP2SQL_TEST_POSTGRES_HOST: localhost
+        NLP2SQL_TEST_POSTGRES_PORT: "5432"
+        NLP2SQL_TEST_POSTGRES_USER: testuser
+        NLP2SQL_TEST_POSTGRES_PASS: testpass
+        NLP2SQL_TEST_POSTGRES_DB: testdb
+      run: pytest tests/test_pgvector_example_repository.py -m integration -q
+
+    # README Quick Start per provider, the false-invalid gold set and the cost of
+    # one question (LLM calls, tokens, database connections), with the OpenAI SDK
+    # pointed at tests/fakes/fake_openai.py (no keys, no cost).
+    - name: First-run regression tests
+      env:
+        PYTHONPATH: src
+        NLP2SQL_REQUIRE_INTEGRATION: "1"
+        NLP2SQL_TEST_POSTGRES_HOST: localhost
+        NLP2SQL_TEST_POSTGRES_PORT: "5432"
+        NLP2SQL_TEST_POSTGRES_USER: testuser
+        NLP2SQL_TEST_POSTGRES_PASS: testpass
+        NLP2SQL_TEST_POSTGRES_DB: testdb
+      run: pytest tests/test_first_run.py tests/test_false_invalid_regression.py tests/test_cost_per_question.py -m integration -q
+
+  # Installs the built wheel the way a user does: fresh environment, no lock
+  # file, latest dependency versions. Catches undeclared dependencies (rc13-rc15
+  # could not be imported without pyyaml) that the locked dev environment hides.
+  clean-install:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v7
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+
+    - name: Build the wheel
+      run: |
+        python -m pip install build
+        python -m build --wheel
+
+    - name: Install the wheel in a fresh environment
+      run: |
+        python -m venv "$RUNNER_TEMP/clean"
+        "$RUNNER_TEMP/clean/bin/pip" install dist/*.whl
+        "$RUNNER_TEMP/clean/bin/pip" list | grep -iE "^(openai|anthropic|google-generativeai|pyyaml) "
+
+    - name: Import the package and run the CLI
+      working-directory: ${{ runner.temp }}
+      run: |
+        "$RUNNER_TEMP/clean/bin/python" -c "import nlp2sql; print('nlp2sql', nlp2sql.__version__)"
+        "$RUNNER_TEMP/clean/bin/nlp2sql" --help

nlp2sql-0.2.0rc17/.github/workflows/publish-pypi.yml

@@ -0,0 +1,115 @@
+name: Publish Python Package to PyPI
+
+# Production releases are decided by a tag: run this workflow from the release
+# tag (Run workflow -> Use workflow from -> Tags -> vX.Y.Z). A run from a branch
+# fails before anything is checked out. See "Releasing (maintainers)" in
+# CONTRIBUTING.md.
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm_production:
+        description: 'Type "PRODUCTION" to confirm publishing to live PyPI'
+        required: true
+        default: ''
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+
+    steps:
+    - name: Require a tag ref
+      run: |
+        if [ "$GITHUB_REF_TYPE" != "tag" ]; then
+          echo "::error title=Not a tag::Run this workflow from a release tag (Use workflow from -> Tags), not from '$GITHUB_REF_NAME'."
+          exit 1
+        fi
+
+    - name: Validate production confirmation
+      env:
+        CONFIRM_PRODUCTION: ${{ inputs.confirm_production }}
+      run: |
+        if [ "$CONFIRM_PRODUCTION" != "PRODUCTION" ]; then
+          echo "::error::Production confirmation required. Type PRODUCTION to confirm."
+          exit 1
+        fi
+
+    - name: Require a published GitHub Release for the tag
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        is_draft=$(gh release view "$GITHUB_REF_NAME" -R "$GITHUB_REPOSITORY" --json isDraft -q .isDraft) || {
+          echo "::error::No GitHub Release found for $GITHUB_REF_NAME. Create and publish the release first."
+          exit 1
+        }
+        if [ "$is_draft" != "false" ]; then
+          echo "::error::The GitHub Release for $GITHUB_REF_NAME is still a draft."
+          exit 1
+        fi
+
+    - name: Checkout the tag
+      uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+
+    - name: Verify the tag matches the package version
+      run: |
+        echo "Tag: $GITHUB_REF_NAME, commit: $GITHUB_SHA"
+        python .github/scripts/verify_release_tag.py "$GITHUB_REF_NAME"
+
+    - name: Install uv
+      run: python -m pip install uv
+
+    - name: Install project dependencies with uv
+      run: |
+        uv pip install --system .
+        uv pip install --system ".[dev]"
+
+    - name: Install build
+      run: python -m pip install build
+
+    - name: Run tests
+      env:
+        PYTHONPATH: src
+      run: pytest
+
+    - name: Build package
+      run: python -m build
+
+    - name: Upload distributions
+      uses: actions/upload-artifact@v7
+      with:
+        name: dist
+        path: dist/
+        if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+
+    # Only this job can request a PyPI token (Trusted Publishing via OIDC), and
+    # it runs no project or third-party Python code.
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download distributions
+      uses: actions/download-artifact@v8
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://upload.pypi.org/legacy/

nlp2sql-0.2.0rc17/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,90 @@
+name: Publish Python Package to Test PyPI
+
+# Runs automatically on the release tag when a GitHub Release is published, and
+# can be re-run manually from a tag (Use workflow from -> Tags -> vX.Y.Z). A run
+# from a branch fails before anything is checked out. See "Releasing
+# (maintainers)" in CONTRIBUTING.md.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+
+    steps:
+    - name: Require a tag ref
+      run: |
+        if [ "$GITHUB_REF_TYPE" != "tag" ]; then
+          echo "::error title=Not a tag::Run this workflow from a release tag (Use workflow from -> Tags), not from '$GITHUB_REF_NAME'."
+          exit 1
+        fi
+
+    - name: Checkout the tag
+      uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+
+    - name: Verify the tag matches the package version
+      run: |
+        echo "Tag: $GITHUB_REF_NAME, commit: $GITHUB_SHA"
+        python .github/scripts/verify_release_tag.py "$GITHUB_REF_NAME"
+
+    - name: Install uv
+      run: python -m pip install uv
+
+    - name: Install project dependencies with uv
+      run: |
+        uv pip install --system .
+        uv pip install --system ".[dev]"
+
+    - name: Install build
+      run: python -m pip install build
+
+    - name: Run tests
+      env:
+        PYTHONPATH: src
+      run: pytest
+
+    - name: Build package
+      run: python -m build
+
+    - name: Upload distributions
+      uses: actions/upload-artifact@v7
+      with:
+        name: dist
+        path: dist/
+        if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: testpypi
+
+    # Only this job can request a Test PyPI token (Trusted Publishing via OIDC),
+    # and it runs no project or third-party Python code.
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download distributions
+      uses: actions/download-artifact@v8
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to Test PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/

nlp2sql-0.2.0rc17/CHANGELOG.md

@@ -0,0 +1,185 @@
+# 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).
+
+## Versioning policy
+
+- **MAJOR** — incompatible public API changes (removing/renaming a public symbol
+  or changing a port/ABC contract in a non-backward-compatible way).
+- **MINOR** — backward-compatible functionality (new adapters, new optional
+  parameters, new optional extras).
+- **PATCH** — backward-compatible bug fixes.
+
+Pre-1.0 the project ships release candidates (e.g. `0.2.0rcN`). Public surface
+changes — moving/renaming exported symbols, or adding methods to a published
+port such as `ExampleRepositoryPort` — MUST be recorded under `Unreleased`
+before release and called out as **Breaking** if they affect external
+implementers. Backward-compatible shims are preferred over hard breaks while
+pre-1.0.
+
+## [Unreleased]
+
+## [0.2.0rc17] - 2026-10-20
+
+### Changed
+- **User-visible: the LLM no longer reviews its own SQL by default.** Every `ask()`
+  made a second LLM call that sent the whole schema context back to the model; it
+  doubled the latency of each question and its tokens were not reported. Column,
+  dialect, semantic and read-only checks still run, and execution modes still
+  validate against the database. Turn the review back on with
+  `connect(..., llm_validation=True)`, `NLP2SQL_LLM_VALIDATION=true` or
+  `nlp2sql query --llm-validation`. `NLP2SQL.validate(sql)` still asks the LLM.
+- `QueryResult.tokens_used` now counts every LLM call made for the question
+  (retries, repairs and LLM validation); it used to report only the last
+  generation call. `metadata["token_usage"]` has the breakdown.
+- `refresh_schema()` (PostgreSQL and Redshift) now drops the cached table list so
+  the next `get_tables()` reads the database again. PostgreSQL no longer runs
+  `ANALYZE` on the whole database on the first `connect()` and every 24 hours.
+- Provider calls are retried only on rate limits, timeouts, connection errors and
+  provider-side errors. Authentication and request errors fail on the first
+  attempt, instead of after about 8 seconds and 3 requests.
+- An answer from the model that is not the expected JSON (not JSON, not an object,
+  or without `sql`) is asked for again once, without waiting; it used to be retried
+  up to 3 times with 4-10 second waits. Both answers count in `tokens_used` and in
+  `metadata["token_usage"]["llm_calls"]`.
+- An answer cut off at `max_tokens` (OpenAI `finish_reason="length"`, Anthropic
+  `stop_reason="max_tokens"`, Gemini `MAX_TOKENS`) fails on the first attempt with a
+  `ProviderException` that says to raise `max_tokens`, instead of "Invalid JSON
+  response" after 3 attempts. Anthropic refusals and Gemini safety blocks raise
+  `ProviderRequestError`.
+
+### Added
+- `llm_validation` option on `connect()`, `create_query_service()` and
+  `create_and_initialize_service()`, `NLP2SQL_LLM_VALIDATION`, and
+  `nlp2sql query --llm-validation`.
+- `ProviderAuthenticationError`, `ProviderRequestError`, `ProviderRateLimitError`
+  and `ProviderUnavailableError`, subclasses of `ProviderException`, raised by the
+  OpenAI, Anthropic and Gemini adapters and available as the `__cause__` of the
+  `QueryGenerationException` raised by `ask()`.
+- `ProviderResponseFormatError` (subclass of `ProviderException`): the model answered
+  twice without the expected JSON. `details["tokens_used"]` has the tokens of both
+  answers.
+
+### Fixed
+- Each `ask()` opened 5 new database connections per table in the schema context
+  (41 for a multi-table question). The context is now built from the table list
+  loaded at `connect()`, with no extra connections.
+- `RedshiftRepository.refresh_schema()` was a no-op.
+- The Anthropic and Gemini adapters raised `TypeError` instead of
+  `TokenLimitException` when the context was too large, and dropped the SDK error
+  as the cause of generation failures.
+- The Anthropic adapter reported its own errors as "Failed to parse response: ...".
+- `docs/API.md` showed catching `TokenLimitException` and `ProviderException`
+  directly from `ask()`; they arrive as the cause of `QueryGenerationException`.
+
+## [0.2.0rc16] - 2026-10-19
+
+### Changed
+- Release: packages are published to PyPI only from a release tag whose name
+  matches the `pyproject.toml` version and that has a published GitHub Release.
+  The publish workflows build in one job and upload from another, so only the
+  upload job can request a PyPI token.
+- CI: runs on `ubuntu-24.04` with the Node 24 versions of `actions/checkout` and
+  `actions/setup-python`, and fails when any copy of the package version is out
+  of sync with `pyproject.toml`.
+- CI: a `clean-install` job installs the built wheel in a fresh environment
+  without the lock file, and the integration lane runs the README Quick Start
+  and a false-invalid regression set against a local fake of the OpenAI API.
+
+### Fixed
+- `import nlp2sql` failed on a plain `pip install nlp2sql` since 0.2.0rc13
+  (`No module named 'yaml'`): `pyyaml` is now a declared dependency.
+- `connect()` raised `Unknown embedding provider` with
+  `ProviderConfig(provider="anthropic")` or `"gemini"`, and with OpenAI failed
+  unless `OPENAI_API_KEY` was exported, because the `ProviderConfig` key never
+  reached the embedding adapter. Without an explicit embedding provider,
+  OpenAI chat now uses OpenAI embeddings with the same key; other providers use
+  local embeddings when `nlp2sql[embeddings-local]` is installed and no
+  embeddings otherwise. Few-shot examples share that provider, and are skipped
+  with a warning when there is none.
+- Correct queries came back with `is_valid=False` when they did not use the
+  table the heuristic intent plan guessed from the question (4 of 14 in a
+  sample of realistic questions), even with no semantic layer. Plan-derived
+  expectations are now warnings; rules from a semantic layer are still errors.
+- `is_valid` was `True` for queries that write (`DELETE ...` in the default
+  `generate_only` mode) and for queries whose execution failed. Both are now
+  invalid, with the reason in the validation errors.
+- The read-only check rejected valid queries with keywords inside string
+  literals (`WHERE name = 'Gift Set'`), and allowed functions with side effects
+  such as `pg_terminate_backend`, `set_config`, `nextval` or `dblink`. It now
+  ignores literals and rejects those functions.
+- `generate_sql(max_tokens=...)` and the CLI `--max-tokens` (default 1000) also
+  capped the schema context sent to the model; the schema budget is now always
+  `NLP2SQL_MAX_SCHEMA_TOKENS`.
+- `nlp2sql setup` crashed when configuring a database (it called the
+  nonexistent `click.choice`), and offered MySQL and SQLite, which have no
+  adapter. It now offers PostgreSQL and Redshift.
+
+## [0.2.0rc15] - 2026-09-18
+
+### Changed
+- Default chat models refreshed to current, non-retired IDs. **User-visible: cost,
+  latency and SQL style change for anyone who does not pin `model`.**
+  - OpenAI: `gpt-4o-mini` -> `gpt-5.6-luna` (1.05M context, 922K input, 128K output).
+    `gpt-4o-mini` remains callable; pin it with `ProviderConfig(model="gpt-4o-mini")`.
+  - Anthropic: `claude-sonnet-4-20250514` (retired by Anthropic on 2026-06-15) ->
+    `claude-sonnet-5` (1M context, 128K output).
+  - Gemini: `gemini-2.0-flash` (shut down by Google on 2026-06-01) ->
+    `gemini-3.6-flash` (1,048,576 context, 65,536 output).
+- `ProviderConfig.DEFAULT_MODELS` is now the single source of truth for provider
+  defaults; the adapters, `Settings.get_provider_config()` and `nlp2sql providers list`
+  read from it.
+- `AnthropicAdapter` no longer sends `temperature` to the Messages API: Claude 4.7+
+  models reject non-default sampling parameters (HTTP 400) and the `anthropic` SDK
+  removes the keyword in 1.0. `ProviderConfig(temperature=...)` is still accepted for
+  Anthropic but ignored (logged at INFO); explicitly pinned older Claude models now run
+  at the API default temperature.
+- `OpenAIAdapter` sends `max_completion_tokens` instead of the deprecated `max_tokens`.
+  For reasoning models (every model outside the `gpt-3.5`, `gpt-4` and `chatgpt-4o`
+  families, including `gpt-5.6-*`) it sets `reasoning_effort` (default `low`, new
+  `reasoning_effort` constructor argument) and omits `temperature`; `gpt-4o`/`gpt-4.1`
+  keep receiving `temperature`. Response metadata gains `reasoning_effort` and
+  `reasoning_tokens`.
+- Unknown model IDs no longer fall back to crippling context limits (OpenAI 8,192,
+  Gemini 30,720, Anthropic 100,000). They resolve by model family where possible and
+  otherwise fall back to 128,000 / 1,048,576 (Gemini family) / 200,000, logging a
+  warning when the adapter is constructed.
+- `OpenAIAdapter` token counting maps the `gpt-5`, `gpt-4.1`, `gpt-4o` and `o1`-`o4`
+  families to `o200k_base` (tiktoken has no entry for `gpt-5.6-*`) and falls back to
+  `o200k_base`, never `cl100k_base`, for unknown IDs.
+- `GeminiAdapter` reads token usage from `usage_metadata` instead of issuing extra
+  `count_tokens` calls after each response.
+- Minimum dependency versions raised: `openai>=1.58.0` (`reasoning_effort`),
+  `tiktoken>=0.7.0` (`o200k_base`), `google-generativeai>=0.8.5` (`usage_metadata`).
+
+### Fixed
+- `connect()` / `ask()` failed out of the box for Anthropic and Gemini because their
+  default model IDs had been retired by the providers.
+- Reasoning/thinking models that exhaust `max_tokens` before emitting content now raise
+  an actionable `ProviderException` instead of "Invalid JSON response" or
+  "Failed to parse response".
+- `AnthropicAdapter` and `GeminiAdapter` re-raise `ProviderException` after exhausting
+  retries instead of surfacing `tenacity.RetryError`.
+
+## [0.2.0rc14] - 2026-09-16
+
+### Added
+- `PgvectorExampleRepository`: a Postgres + `pgvector` implementation of
+  `ExampleRepositoryPort`, an alternative to the on-disk FAISS `ExampleStore`
+  for storing and semantically searching few-shot examples. Stores examples in
+  a single table with a `namespace` column (per-database isolation via
+  `md5(database_url:schema_name)`, byte-identical to `ExampleStore`), cosine
+  distance search over an HNSW index, and idempotent `auto_migrate` DDL.
+- Optional `pgvector` extra: `pip install 'nlp2sql[pgvector]'`.
+- CI: a `pgvector-integration` job that runs the adapter's integration tests
+  against a `pgvector/pgvector:pg16` service. The job fails (rather than skips)
+  when the database or `vector` extension is unavailable
+  (`NLP2SQL_REQUIRE_INTEGRATION`).
+
+### Changed
+- `docker/docker-compose.yml`: the `postgres` service image is now
+  `pgvector/pgvector:pg16` (drop-in replacement for `postgres:16`, adds the
+  `vector` extension) so integration tests run out of the box.

{nlp2sql-0.2.0rc15 → nlp2sql-0.2.0rc17}/CONTRIBUTING.md

@@ -233,6 +233,22 @@ Brief description of changes and why they're needed.
 4. **Documentation review** for user-facing changes
 5. **Merge** after approval
 
+## Releasing (maintainers)
+
+Packages are published only from a release tag. Both publish workflows refuse to run from a branch and check that the tag name is `v` followed by the `version` in `pyproject.toml`, so the latest commit on `main` never goes to PyPI by accident.
+
+1. **Bump the version** in every copy and move the `CHANGELOG.md` entries from `[Unreleased]` to a new `## [X.Y.Z] - YYYY-MM-DD` section. The copies are `pyproject.toml`, `src/nlp2sql/__init__.py`, `src/nlp2sql/config/settings.py`, `mcp_server/pyproject.toml` (`[project]` and `[tool.mcp]`), `mcp_server/__init__.py` and `uv.lock` (run `uv lock`). `tests/test_version_consistency.py` fails if any of them is out of sync.
+2. **Push the bump to `main` before creating the release.** The new tag points to whatever `main` is at that moment. To check a tag name against the current version, run `python .github/scripts/verify_release_tag.py vX.Y.Z`.
+3. **Create the GitHub Release** with a new tag `vX.Y.Z` targeting `main`. Publishing the release runs "Publish Python Package to Test PyPI" on that tag automatically.
+4. **Run the integration tests locally** on the tagged commit, with the test databases running (see [Development Setup](#development-setup)).
+5. **Publish to PyPI**: in **Actions**, open **Publish Python Package to PyPI**, click **Run workflow**, pick the tag under **Use workflow from** (Tags tab) and type `PRODUCTION`. From the command line:
+
+   ```bash
+   gh workflow run publish-pypi.yml --ref vX.Y.Z -f confirm_production=PRODUCTION
+   ```
+
+The PyPI workflow stops before building if the run is not on a tag, if the tag has no published GitHub Release, or if the tag does not match the package version. Only its final job, which runs no project code, can request a PyPI token.
+
 ## Enterprise Contribution Guidelines
 
 ### Performance Considerations

{nlp2sql-0.2.0rc15 → nlp2sql-0.2.0rc17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nlp2sql
-Version: 0.2.0rc15
+Version: 0.2.0rc17
 Summary: Enterprise-ready Natural Language to SQL converter with multi-provider support. Built for production scale (1000+ tables) with Clean Architecture.
 Project-URL: Homepage, https://github.com/luiscarbonel1991/nlp2sql
 Project-URL: Bug Tracker, https://github.com/luiscarbonel1991/nlp2sql/issues
@@ -36,6 +36,7 @@ Requires-Dist: psycopg2-binary>=2.9.0
 Requires-Dist: psycopg[binary]>=3.2.13
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: redis>=5.0.0
 Requires-Dist: scikit-learn>=1.3.0
 Requires-Dist: sqlalchemy-redshift>=0.7.0