TalkPipe 0.14.2__tar.gz → 1.0.0__tar.gz

{talkpipe-0.14.2 → talkpipe-1.0.0}/.cursor/skills/update-entry-points/scripts/update_entry_points.py

@@ -18,7 +18,7 @@ from pathlib import Path
 _project_root = Path(__file__).resolve().parent.parent.parent.parent.parent
 sys.path.insert(0, str(_project_root / "src"))
 
-from talkpipe.app.chatterlang_generate_entry_points import (
+from talkpipe.app.chatterlang_generate_entry_points import (  # noqa: E402
     generate_toml_section,
     scan_directory,
 )
@@ -35,6 +35,22 @@ def _find_entry_points_start(content: str) -> int:
     return -1
 
 
+def _find_entry_points_end(content: str, start: int) -> int:
+    """Return the index just past the last talkpipe entry-point table.
+
+    The generated block covers the ``talkpipe.sources`` and ``talkpipe.segments``
+    tables only; whatever follows (``[tool.*]`` and so on) is preserved.
+    """
+    pos = start
+    while True:
+        match = re.compile(r"^\[[^\]]+\]", re.MULTILINE).search(content, pos)
+        if match is None:
+            return len(content)
+        if not re.match(r'\[project\.entry-points\.["\']talkpipe\.', match.group(0)):
+            return match.start()
+        pos = match.end()
+
+
 def update_pyproject(
     pyproject_path: Path,
     source_dir: Path,
@@ -59,20 +75,30 @@ def update_pyproject(
     new_toml = generate_toml_section(results["sources"], results["segments"])
 
     if not new_toml.strip():
-        print("Warning: No entry points generated. Check that sources use @register_source/@register_segment.", file=sys.stderr)
+        print(
+            "Warning: No entry points generated. Check that sources use @register_source/@register_segment.",
+            file=sys.stderr,
+        )
         return False
 
     content = pyproject_path.read_text(encoding="utf-8")
     start = _find_entry_points_start(content)
 
     if start < 0:
-        print("Error: Could not find [project.entry-points.\"talkpipe.sources\"] in pyproject.toml", file=sys.stderr)
+        print(
+            'Error: Could not find [project.entry-points."talkpipe.sources"] in pyproject.toml',
+            file=sys.stderr,
+        )
         return False
 
+    end = _find_entry_points_end(content, start)
     prefix = content[:start]
+    suffix = content[end:]
     # Ensure generated section ends with newline; strip trailing blanks from prefix
     new_section = new_toml.rstrip() + "\n"
     new_content = prefix.rstrip() + "\n\n" + new_section
+    if suffix.strip():
+        new_content += "\n" + suffix.lstrip("\n")
 
     if dry_run:
         print("Generated entry points (dry-run, no file written):")
@@ -87,9 +113,13 @@ def update_pyproject(
 
     if new_content != content:
         pyproject_path.write_text(new_content, encoding="utf-8")
-        print(f"Updated {pyproject_path} with {len(results['sources'])} sources and {len(results['segments'])} segments.")
+        print(
+            f"Updated {pyproject_path} with {len(results['sources'])} sources and {len(results['segments'])} segments."
+        )
     else:
-        print("No changes needed; pyproject.toml already matches generated entry points.")
+        print(
+            "No changes needed; pyproject.toml already matches generated entry points."
+        )
 
     return True
 

talkpipe-1.0.0/.gitea/default_merge_message/MERGE_TEMPLATE.md

@@ -0,0 +1 @@
+Merge branch '${HeadBranch}': ${PullRequestTitle}

talkpipe-1.0.0/.gitea/default_merge_message/SQUASH_TEMPLATE.md

@@ -0,0 +1 @@
+${PullRequestTitle}

{talkpipe-0.14.2 → talkpipe-1.0.0}/.github/CICD.md

@@ -8,16 +8,26 @@ This directory contains the GitHub Actions workflows and configuration for the T
 
 #### `ci-cd.yml` - Main CI/CD Pipeline
 Comprehensive pipeline that runs on:
-- Pushes to `main` and `develop` branches  
-- Pull requests to `main` and `develop`
+- Pushes to `main` and topic branches (`bugfix/**`, `feature/**`, `chore/**`)  
+- Pull requests targeting `main`
 - GitHub releases
 
 **Pipeline Jobs:**
-1. **Test** - Multi-version Python testing (3.11, 3.12) with coverage
-2. **Security Scan** - SAST and dependency vulnerability scanning
-3. **Build Container** - Docker image build and push; multi-architecture (linux/amd64, linux/arm64) on release only, single-platform otherwise
-4. **CodeQL Analysis** - GitHub's semantic code analysis
-5. **Publish Package** - Automated PyPI publishing on releases
+
+Host-neutral jobs run identically on GitHub Actions and on any other
+Actions-compatible runner; jobs that need github.com are guarded with
+`if: github.server_url == 'https://github.com'`.
+
+| Job | Runs | What it does |
+|---|---|---|
+| `test` | everywhere, matrix 3.11 / 3.12 / 3.13 | `pytest --cov=src`; the `[tool.coverage.report] fail_under` floor in `pyproject.toml` fails the job if coverage drops below it. Coverage is uploaded to Codecov from the 3.11 leg. |
+| `lint` | everywhere, 3.11 | `ruff check`, `ruff format --check`, `mypy` — all gating, no advisory mode — plus an entry-point drift check (regenerates the `talkpipe.sources`/`talkpipe.segments` tables from the `@register_*` decorators and fails on any diff to `pyproject.toml`). |
+| `package` | everywhere, 3.11 | Builds the sdist and wheel, `twine check`s them, installs the wheel into a clean venv, imports the package, runs `chatterlang_script --help`, and loads every declared entry point. Catches packaging breakage before release time. |
+| `lockfile-check` | everywhere | `uv lock --check` — the committed `uv.lock` must match `pyproject.toml`. Installs nothing; CI installs with pip on purpose. |
+| `security-scan` | everywhere; needs `test`, `lint` | Bandit (`-c pyproject.toml`, the `[tool.bandit]` table) and Safety. Uses the commercial database when `SAFETY_API_KEY` is set and falls back to the free `safety check` database when it is not (secrets are not passed to pull-request runs); both fail the build on a known vulnerability. |
+| `build-container` | github.com only | Docker image build and Trivy scan on every run; pushes to ghcr.io **on releases only** (`latest` for stable releases, `experimental` for pre-releases); multi-architecture (linux/amd64, linux/arm64) on release only. |
+| `codeql-analysis` | github.com only | GitHub's semantic code analysis. |
+| `publish-package` | on a published release; needs `test`, `lint`, `package`, `security-scan` | `python -m build`, `twine check`, upload to PyPI. Does not depend on the container job, so publishing is not blocked where that job is skipped. |
 
 ### Configuration Files
 
@@ -26,7 +36,7 @@ Comprehensive pipeline that runs on:
 
 ### Root Level Security Files
 
-- **`.bandit`** - Configuration for Bandit static security analysis
+- **`[tool.bandit]` in `pyproject.toml`** - Configuration for Bandit static security analysis
 - **`.dockerignore`** - Optimized Docker build context exclusions
 
 ## Security Scanning
@@ -48,7 +58,7 @@ Docker images are built and pushed to GitHub Container Registry. On **release**,
 Images are available at:
 ```
 ghcr.io/sandialabs/talkpipe:latest
-ghcr.io/sandialabs/talkpipe:<branch-name>
+ghcr.io/sandialabs/talkpipe:experimental
 ghcr.io/sandialabs/talkpipe:<version>
 ```
 
@@ -90,11 +100,20 @@ To enable full functionality, set these secrets in your GitHub repository settin
 Before pushing, you can test components locally:
 
 ```bash
-# Run tests with coverage (matches CI)
-pytest --cov=src --cov-report=xml --cov-report=html
+# Run tests with coverage (matches CI; fails below the fail_under floor)
+pytest --cov=src --cov-report=term --cov-report=xml --cov-report=html
+
+# Lint / format / types (matches CI)
+ruff check . && ruff format --check . && mypy
+
+# Entry-point drift check (matches CI)
+python .cursor/skills/update-entry-points/scripts/update_entry_points.py && git diff --exit-code -- pyproject.toml
+
+# Packaging smoke test (matches CI)
+python -m build && twine check dist/*
 
 # Run security scans
-bandit -r src/
+bandit -c pyproject.toml -r src/
 export SAFETY_API_KEY=your-key   # optional; links results to Safety Platform
 safety scan
 
@@ -110,10 +129,9 @@ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
 
 | Event | Trigger | Jobs Run |
 |-------|---------|----------|
-| Push to main/develop | Automatic | All jobs |
+| Push to main | Automatic | All jobs |
 | Pull Request | Automatic | All except publish |
 | Release published | Automatic | All jobs + PyPI publish |
-| Manual trigger | `workflow_dispatch` | All jobs |
 
 ## Monitoring
 
@@ -144,6 +162,6 @@ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
 4. **Security Scans Fail**:
    - Review Bandit/Safety reports
    - Update vulnerable dependencies
-   - Add exclusions to `.bandit` if needed
+   - Add exclusions to `[tool.bandit]` in `pyproject.toml` if needed
 
 For additional help, check the Actions tab logs or create an issue in the repository.

talkpipe-1.0.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,375 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, 'bugfix/**', 'feature/**', "chore/**" ]
+  pull_request:
+    branches: [ main, 'bugfix/**', 'feature/**', "chore/**" ]
+  release:
+    types: [ published ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Cache pip dependencies
+      uses: actions/cache@v6
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+    
+    - name: Install dependencies
+      run: |
+        # Install into a project venv rather than the interpreter itself. On a
+        # self-hosted runner /opt/hostedtoolcache is a volume shared by every
+        # job, so installing there leaks packages between repos.
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install -e ".[dev,all]"
+    
+    - name: Run tests with coverage
+      run: |
+        # --cov-report=term makes the [tool.coverage.report] fail_under floor
+        # in pyproject.toml fail this step; xml/html are for Codecov and
+        # local inspection.
+        pytest --cov=src --cov-report=term --cov-report=xml --cov-report=html
+    
+    - name: Upload coverage to Codecov
+      if: matrix.python-version == '3.11'
+      uses: codecov/codecov-action@v7
+      with:
+        files: ./coverage.xml
+        flags: unittests
+
+  lint:
+    # Ruff (lint + format) and mypy gate the build; there is no advisory
+    # pass and nothing here may swallow a failure. Local equivalent:
+    # `pre-commit run --all-files`, or the three commands below.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install -e ".[dev,all]"
+
+    - name: Ruff lint
+      run: ruff check --output-format=github .
+
+    - name: Ruff format check
+      run: ruff format --check --diff .
+
+    - name: mypy
+      run: mypy
+
+    - name: Entry points match the registered sources and segments
+      run: |
+        # Regenerate the talkpipe.sources / talkpipe.segments tables from the
+        # @register_* decorators; any diff means a component was added or
+        # renamed without updating pyproject.toml (it would be invisible to
+        # name lookup until its module happened to be imported).
+        python .cursor/skills/update-entry-points/scripts/update_entry_points.py
+        git diff --exit-code -- pyproject.toml
+
+  package:
+    # Build the sdist and wheel the way a release would, then install the
+    # wheel into a clean venv and import/run it. Without this a broken
+    # wheel is only discovered by publish-package, at release time.
+    # Host-neutral: runs unchanged on any Actions-compatible runner.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Build sdist and wheel
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install build twine
+        .venv/bin/python -m build
+        .venv/bin/twine check dist/*
+
+    - name: Install the wheel into a clean venv and smoke-test it
+      run: |
+        python -m venv .smoke
+        .smoke/bin/python -m pip install --upgrade pip
+        .smoke/bin/pip install dist/*.whl
+        # Import the package plus the two subpackages that ship without
+        # __init__.py history, and prove the version metadata resolves.
+        .smoke/bin/python -c "import talkpipe, talkpipe.search.lancedb, talkpipe.data.text.cleaning; print(talkpipe.__version__)"
+        .smoke/bin/chatterlang_script --help
+        # Every declared entry point must resolve in the installed wheel.
+        .smoke/bin/python - <<'PY'
+        from importlib.metadata import entry_points
+        bad = []
+        for group in ("talkpipe.sources", "talkpipe.segments"):
+            for ep in entry_points(group=group):
+                try:
+                    ep.load()
+                except Exception as exc:  # noqa: BLE001
+                    bad.append(f"{group}:{ep.name} -> {exc!r}")
+        if bad:
+            raise SystemExit("unresolvable entry points:\n" + "\n".join(bad))
+        print("all entry points resolve")
+        PY
+
+  lockfile-check:
+    # uv.lock is a development convenience only -- CI installs with pip on
+    # purpose (see README, "Development environment"). This job installs
+    # nothing from the lock; it only fails when uv.lock has drifted out of
+    # sync with pyproject.toml, so the committed lock cannot go stale
+    # unnoticed.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Check uv.lock is in sync with pyproject.toml
+      run: uv lock --check
+
+  security-scan:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    env:
+      SAFETY_API_KEY: ${{ secrets.SAFETY_API_KEY }}
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+    
+    - name: Install dependencies for security scan
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        # `python -m venv` seeds the venv with whatever pip and setuptools the
+        # interpreter bundles, and safety scans the whole venv, so upgrade
+        # both: a stale bundled setuptools fails the scan on an advisory
+        # unrelated to anything this project declares or installs.
+        .venv/bin/python -m pip install --upgrade pip setuptools
+        .venv/bin/pip install -e ".[dev,all]"
+        .venv/bin/pip install bandit safety
+    
+    - name: Run Bandit security scan
+      run: |
+        bandit -c pyproject.toml -r src/ -f json -o bandit-report.json
+        bandit -c pyproject.toml -r src/ -f txt
+
+    - name: Run Safety dependency scan
+      run: |
+        if [ -n "${SAFETY_API_KEY:-}" ]; then
+          # Authenticated: the commercial database, gated by .safety-policy.yml.
+          safety scan --save-as json safety-report.json
+          safety scan
+        else
+          # Repository secrets are not passed to pull-request runs, so the key
+          # is absent there and `safety scan` would only ask us to log in.
+          # Fall back to the free database rather than failing for lack of auth
+          # or, worse, passing without scanning anything. This still fails the
+          # build on a known vulnerability -- the database is just staler than
+          # the authenticated scan that gates pushes to main.
+          echo "SAFETY_API_KEY unavailable; falling back to 'safety check' (free database)."
+          # `check` is the legacy command and the only one that runs without an
+          # account. It rejects .safety-policy.yml because that file is v3.0 and
+          # only `scan` parses v3, so run it from a directory holding no policy
+          # file; it scans the installed environment either way.
+          report="$PWD/safety-report.json"
+          workdir="$(mktemp -d)"
+          (cd "$workdir" && safety check --save-json "$report")
+        fi
+    
+    - name: Upload security scan results
+      uses: actions/upload-artifact@v7
+      # upload-artifact v4+ refuses to run when the server isn't github.com
+      if: always() && github.server_url == 'https://github.com'
+      with:
+        name: security-reports
+        path: |
+          bandit-report.json
+          safety-report.json
+
+  build-container:
+    runs-on: ubuntu-latest
+    needs: [test, lint, security-scan]
+    # pushes to ghcr.io with a GitHub token; only available on github.com
+    if: github.server_url == 'https://github.com'
+    permissions:
+      contents: read
+      packages: write
+      security-events: write
+    
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v7
+    
+    - name: Log in to Container Registry
+      uses: docker/login-action@v4
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    
+    - name: Set up QEMU
+      if: github.event_name == 'release'
+      uses: docker/setup-qemu-action@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v4
+
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@v6
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=sha
+          type=raw,value=latest,enable=${{ github.event_name == 'release' && !github.event.release.prerelease }}
+          type=raw,value=experimental,enable=${{ github.event_name == 'release' && github.event.release.prerelease }}
+    
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v7
+      with:
+        context: .
+        platforms: ${{ github.event_name == 'release' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
+        # only releases publish images; other runs build (and Trivy-scan)
+        # without pushing, so `load` puts the image in the local daemon
+        push: ${{ github.event_name == 'release' }}
+        load: ${{ github.event_name != 'release' }}
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+    
+    - name: Extract first tag for Trivy
+      id: first-tag
+      run: echo "tag=$(echo '${{ steps.meta.outputs.tags }}' | head -n1)" >> $GITHUB_OUTPUT
+    
+    - name: Run container security scan with Trivy
+      uses: aquasecurity/trivy-action@master
+      with:
+        image-ref: ${{ steps.first-tag.outputs.tag }}
+        format: 'sarif'
+        output: 'trivy-results.sarif'
+    
+    - name: Upload Trivy scan results to GitHub Security tab
+      uses: github/codeql-action/upload-sarif@v4
+      if: always()
+      with:
+        sarif_file: 'trivy-results.sarif'
+
+  codeql-analysis:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    # needs GitHub's code-scanning API, only available on github.com
+    if: github.server_url == 'https://github.com'
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+    
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v7
+    
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+    
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v4
+    
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+
+  publish-package:
+    runs-on: ubuntu-latest
+    # build-container is GitHub-only; listing it here would leave publishing
+    # blocked behind a skipped job everywhere else. The container image is
+    # published independently by that job on github.com.
+    needs: [test, lint, package, security-scan]
+    if: github.event_name == 'release' && github.event.action == 'published'
+    
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: python -m build
+    
+    - name: Check package
+      run: twine check dist/*
+    
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*

{talkpipe-0.14.2 → talkpipe-1.0.0}/.gitignore

@@ -180,3 +180,6 @@ extracted_examples.py
 
 # Index directories generated by the tutorials
 full_text_index/
+
+# Local newcomer-usability run results (see workspace CLAUDE.md)
+friction_log*

talkpipe-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Opt-in desktop hooks mirroring the CI lint job: `pre-commit install` once
+# per clone; `pre-commit run --all-files` reproduces the gate locally.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.3  # keep in step with the ruff pin in pyproject.toml
+    hooks:
+      - id: ruff-check
+        args: [--fix, --show-fixes]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        # The project venv's mypy (so versions match uv.lock): install and
+        # run pre-commit from inside it -- `uv run pre-commit ...` or an
+        # activated .venv -- so `mypy` resolves on PATH.
+        entry: mypy
+        language: system
+        types: [python]
+        pass_filenames: false

{talkpipe-0.14.2 → talkpipe-1.0.0}/.safety-policy.yml

@@ -13,8 +13,12 @@ report:
     enabled: true
     auto-ignore-in-report:
       python:
-        environment-results: true
-        unpinned-requirements: true
+        # Both are deliberately false: findings against the installed
+        # environment and against unpinned declared requirements must show up
+        # in the report and fail the scan. Do not flip these back to true to
+        # get a red build green -- fix the requirement instead.
+        environment-results: false
+        unpinned-requirements: false
       cvss-severity: []
 
 

{talkpipe-0.14.2 → talkpipe-1.0.0}/AGENTS.md

@@ -1,10 +1,12 @@
 ## Dev environment tips
 - When running code or pytest, use the .venv environment in the root of the project. Activate it with `source .venv/bin/activate` (or `source .venv/Scripts/activate` on Windows).
 - If the .venv environment doesn't exist and you need to run code or tests, abort and ask the user to create the environment.
+- Local development resolves against the committed `uv.lock` (`uv sync --all-extras`); CI installs with pip and ignores the lock on purpose, so it resolves the way `pip install talkpipe` does. See "Development environment" in [README.md](README.md). The lock is a dev convenience, not a security control — fix a vulnerable dependency by raising its floor in [pyproject.toml](pyproject.toml), and re-run `uv lock` after any dependency change so `uv lock --check` stays green in CI.
 
 ## Important Commands
 - `python -m build` — create a new release
 - `pytest --cov=src` — run unit tests with coverage
+- `ruff check .`, `ruff format --check .`, `mypy` — the code-quality gate. **CI fails on any finding from these three**; run them before pushing. `ruff check --fix . && ruff format .` fixes most lint/format findings; the rule set and mypy config live in `pyproject.toml`. `pre-commit install` (opt-in, per clone) runs the same checks on every commit.
 - `python .cursor/skills/update-entry-points/scripts/update_entry_points.py` — generate entry points from decorators and update pyproject.toml (preferred over chatterlang_generate_entry_points when updating pyproject.toml)
 - `pytest tests/test_doc_examples.py -v` — run all doc examples as tests (requires full_network for LLM examples; skip with `-m "not requires_ollama"` when Ollama unavailable)
 - `run_doc_examples` — extract and run all doc examples (alternative to pytest; requires full_network for LLM examples)