Merge to production 20261006

.github/workflows/docs.yaml

@@ -25,12 +25,14 @@ jobs:
           python-version: '3.x'
 
       - name: Install dependencies
+        # Pinned: the config relies on this version's renderer options.
         run: |
-          pip install pydoc-markdown
+          pip install 'pydoc-markdown==4.8.2'
 
       - name: Run pydoc-markdown
+        # PYTHONPATH=. lets the config import docs_rst_processor by dotted path.
         run: |
-          pydoc-markdown pydoc-markdown.yml
+          PYTHONPATH=. pydoc-markdown pydoc-markdown.yml
 
       - name: Create Pull Request if docs changed
         uses: peter-evans/create-pull-request@v7

.github/workflows/pre-commit.yaml

@@ -27,13 +27,43 @@ jobs:
           python-version: "3.9"
           cache: 'pip'
 
+      # The `gitleaks` pre-commit hook only sees the staged diff, so under
+      # `pre-commit run --all-files` below it scans nothing. This step is what
+      # actually satisfies "a secret scanner runs on every push" (ENG-3686): it
+      # walks the whole working tree, using the same rules and allowlists from
+      # .gitleaks.toml. Keep GITLEAKS_VERSION in step with the `rev` pinned for
+      # the hook in .pre-commit-config.yaml, and GITLEAKS_SHA256 in step with the
+      # linux_x64 line of that release's gitleaks_<version>_checksums.txt.
+      - name: Scan the full tree for secrets
+        env:
+          GITLEAKS_VERSION: "8.28.0"
+          GITLEAKS_SHA256: "a65b5253807a68ac0cafa4414031fd740aeb55f54fb7e55f386acb52e6a840eb"
+        run: |
+          set -euo pipefail
+          curl -sSfL -o /tmp/gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          # Refuse to run a binary that is not the pinned release.
+          echo "${GITLEAKS_SHA256}  /tmp/gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
+          # `dir` (not `git`) so the scan covers the checked-out tree rather than
+          # a commit range; on a first push the range would be empty.
+          /tmp/gitleaks dir . --config .gitleaks.toml --redact --verbose --no-banner
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install ".[test]"
           pip install pre-commit coverage
 
+      # No TEAM_API_KEY (ENG-3683). The `pytest-check` hook runs `tests/unit`,
+      # which is credential-free by design (ENG-3431), so the key was only ever
+      # exposed to the third-party hook code this job also executes. If this job
+      # ever starts failing on a missing key, the regression is a unit test that
+      # has grown a backend dependency -- not this workflow.
       - name: Run pre-commit hooks
         env:
-          TEAM_API_KEY: ${{ secrets.TEAM_API_KEY }}
+          # The gitleaks hook is staged-diff only, so under --all-files it would
+          # build Go from source just to scan nothing. The step above already
+          # scans the whole tree.
+          SKIP: gitleaks
         run: pre-commit run --all-files

.github/workflows/release.yaml

@@ -15,10 +15,144 @@ on:
 permissions: {}
 
 jobs:
+  # A tag could publish a wheel whose functional suites had never run against a
+  # live backend: this workflow gated only on `pytest tests/unit`, and `main.yaml`
+  # did not run on pull requests at all (ENG-3683). This job refuses to proceed
+  # unless every functional leg went green on the exact commit being released.
+  #
+  # Read-only, and deliberately not a `workflow_run` trigger: `workflow_run` fires
+  # when the *other* workflow finishes, which inverts the dependency (the test run
+  # would have to start the release) and cannot express "the run that already
+  # happened on this SHA".
+  functional-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # `gh api .../actions/runs` and `.../jobs`, which this workflow's deny-all
+      # default does not grant. Read only: this job decides, it never re-runs
+      # anything.
+      actions: read
+    steps:
+      - name: Checkout the tagged commit
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
+      - name: Require a green functional run on the tagged commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          # The commit the tag points at, not the tag name: a tag can be moved,
+          # and what was tested is a SHA.
+          SHA: ${{ github.sha }}
+          # Only used to recognise a manual dispatch of main.yaml on this tag.
+          TAG: ${{ github.ref_name }}
+          SERVER_URL: ${{ github.server_url }}
+        run: |
+          set -euo pipefail
+          python -m pip install --quiet --upgrade pip PyYAML
+
+          # The legs are read from the workflow file at the tagged commit rather
+          # than hardcoded here: a leg added in the same release would otherwise
+          # be quietly optional on the release that first ships it.
+          legs="$(python - <<'PY'
+          import yaml
+
+          with open(".github/workflows/main.yaml") as handle:
+              workflow = yaml.safe_load(handle)
+
+          for leg in workflow["jobs"]["functional"]["strategy"]["matrix"]["suite"]:
+              print(f"functional ({leg})")
+          PY
+          )"
+          test -n "$legs"
+
+          # Only runs that used the production backend and key count: a push to
+          # `main` (the normal flow), or a manual dispatch on this very tag (the
+          # recovery path below). main.yaml's IS_PROD is true for both. A push
+          # to `test`, a PR run or the nightly can sit on the same commit,
+          # but their legs passed against the test backend, and a release
+          # validated there proves nothing about what the wheel is published for
+          # (ENG-3683). The dispatch must be on this tag by name,
+          # not on any ref starting with "v": `version_2` is a branch, and a
+          # dispatch on a branch runs against the test backend.
+          #
+          # `head_branch` is a bare name, though, so a dispatch on a *branch*
+          # named exactly like this tag passes the filter too. Each run's jobs
+          # therefore have to include a successful `production-backend` job,
+          # which main.yaml runs only when IS_PROD is true; see `jobs_filter`.
+          #
+          # Every qualifying completed run, not just the latest: a first run that
+          # failed and a re-run of the failed legs together mean the commit is
+          # green, and only the union says so.
+          runs_filter='.workflow_runs[]
+            | select(.status == "completed")
+            | select((.event == "push" and .head_branch == "main")
+                     or (.event == "workflow_dispatch" and .head_branch == $tag))
+            | .id'
+          runs="$(gh api --paginate \
+            "repos/$REPO/actions/workflows/main.yaml/runs?head_sha=$SHA&per_page=100" \
+            | jq -r --arg tag "$TAG" "$runs_filter")"
+
+          if [ -z "$runs" ]; then
+            echo "::error::no completed production run of main.yaml on $SHA."
+            echo "The functional matrix must have run against the production backend on the exact commit"
+            echo "being released: a push to main, or a manual dispatch on this tag. Runs from a push to"
+            echo "test, a PR or the nightly do not count -- they used the test backend."
+            echo "If this tag was pushed right after the merge, the main run may still be in progress:"
+            echo "wait for it to finish, then re-run this release."
+            echo "Otherwise: run main.yaml against the tag (Actions -> Run Tests -> Run workflow,"
+            echo "ref = $TAG), let it go green, then re-run this release."
+            exit 1
+          fi
+
+          # The names of a run's successful jobs, or nothing at all when its
+          # `production-backend` job did not succeed. Slurped, because
+          # `gh api --paginate` prints one JSON document per page.
+          jobs_filter='[.[].jobs[] | select(.conclusion == "success") | .name]
+            | if any(.[]; . == "production-backend") then .[] else empty end'
+          green="$(mktemp)"
+          for run in $runs; do
+            jobs="$(gh api --paginate "repos/$REPO/actions/runs/$run/jobs?per_page=100" | jq -rs "$jobs_filter")"
+            if [ -z "$jobs" ]; then
+              echo "::warning::run $run did not run against production (no successful production-backend job); not counted."
+              continue
+            fi
+            printf '%s\n' "$jobs" >> "$green"
+          done
+
+          missing=0
+          while IFS= read -r leg; do
+            if grep -Fxq "$leg" "$green"; then
+              echo "ok      $leg"
+            else
+              echo "MISSING $leg"
+              missing=1
+            fi
+          done <<< "$legs"
+
+          if [ "$missing" -ne 0 ]; then
+            echo "::error::functional legs listed as MISSING above never succeeded on $SHA."
+            echo "Runs inspected (production runs only): $(echo "$runs" | tr '\n' ' ')"
+            echo "Re-run the failed legs of one of those runs, or dispatch main.yaml on $TAG, then"
+            echo "re-run this release."
+            echo "See $SERVER_URL/$REPO/actions/workflows/main.yaml"
+            exit 1
+          fi
+          echo "every functional leg is green on $SHA"
+
   # Runs repository code (pip, build, pytest) and therefore holds NO id-token:
   # a compromised build dependency must never share a process with the OIDC
   # credential that can upload to PyPI.
   build:
+    # Nothing is built for a commit the functional matrix has not passed.
+    needs: functional-gate
     runs-on: ubuntu-latest
     timeout-minutes: 20
     permissions:
@@ -77,12 +211,15 @@ jobs:
           print(f"tag {tag} matches declared version {declared}")
           PY
 
-      # The whole unit suite, not just the packaging and CI guards. main.yaml is
-      # push-only and `required_status_checks.contexts` is still empty (this PR
-      # documents the flip but cannot make it), so nothing guarantees the tagged
-      # commit ever passed `unit-coverage`: `git tag v0.2.48 <any-commit> && git
-      # push --tags` would otherwise publish with the suite unrun. The suite is
-      # credential-free (ENG-3431), so it needs no secrets in this job.
+      # The whole unit suite, not just the packaging and CI guards.
+      # `required_status_checks.contexts` is still empty (docs/ci/required-checks.md
+      # documents the flip but a merge cannot make it), so nothing outside this
+      # workflow guarantees the tagged commit ever passed `unit-coverage`: `git tag
+      # v0.2.48 <any-commit> && git push --tags` would otherwise publish with the
+      # suite unrun. `functional-gate` above covers the functional matrix; this
+      # covers the unit suite, and unlike the gate it re-runs the tests here rather
+      # than trusting a recorded result. The suite is credential-free (ENG-3431),
+      # so it needs no secrets in this job.
       #
       # This covers the static half of the ENG-3543 packaging gate. The slow half
       # (a .git-less export and a full module census) is main.yaml's
@@ -94,6 +231,10 @@ jobs:
           # into a collection-time skip, a stray `-k` -- exits 0, and the release
           # would proceed on a tree nothing had checked.
           AIXPLAIN_REQUIRE_EXECUTED_TESTS: "1"
+          # The proportional floor from ENG-3684, matching main.yaml. The unit
+          # suite is credential-free, so anything much below this means tests are
+          # skipping themselves for reasons the release should not ship past.
+          AIXPLAIN_MIN_EXECUTED_RATIO: "0.8"
         run: |
           set -euo pipefail
           pip install ".[test]"
@@ -126,16 +267,23 @@ jobs:
           cd "$RUNNER_TEMP"
           "$RUNNER_TEMP/venv/bin/python" - <<'PY'
           import aixplain
-          import aixplain.base.parameters  # noqa: F401  -> v1/base/, no __init__.py
-          import aixplain.v1.modules.model  # noqa: F401
           import aixplain.v2.core  # noqa: F401
+          import aixplain.v2.api_key  # noqa: F401
+          import aixplain.utils.url_safety  # noqa: F401
 
           assert "site-packages" in aixplain.__file__, (
               f"imported the source tree, not the wheel: {aixplain.__file__}"
           )
+          # v1 was removed in 0.3.0; a wheel that still resolves a legacy path
+          # would mean the removal did not reach the artifact.
+          try:
+              import aixplain.factories  # noqa: F401
+          except ModuleNotFoundError as exc:
+              assert "aix.Agent" in str(exc), f"v1 error no longer names a v2 equivalent: {exc}"
+          else:
+              raise SystemExit("aixplain.factories still imports; v1 leaked into the wheel")
           print("imported", aixplain.__file__)
           PY
-          "$RUNNER_TEMP/venv/bin/aixplain" --help > /dev/null
 
       - name: Upload the distribution for the publish job
         uses: actions/upload-artifact@v4

.gitignore

@@ -48,6 +48,9 @@ brusk.yaml
 pip-log.txt
 pip-delete-this-directory.txt
 
+# Local run-log scratch written by functional runs (distinct from tests/).
+/test/
+
 # Unit test / coverage reports
 htmlcov/
 .tox/

.gitleaks.toml

@@ -0,0 +1,72 @@
+# Secret scanning for the aiXplain SDK (ENG-3686).
+#
+# Live platform keys were committed in plaintext in scratch files and sat in the
+# tree for months. This config backs
+# the `gitleaks` hook in .pre-commit-config.yaml and the full-tree scan in
+# .github/workflows/pre-commit.yaml, which runs on every push.
+#
+# The allowlists below are deliberately narrow. Do NOT allowlist a whole test
+# directory or file: the fixtures under tests/ are exactly where a real key gets
+# pasted "just to try something". Allowlist the specific fake value, and say why.
+
+title = "aiXplain SDK"
+
+[extend]
+# Gitleaks' curated rule set. It matches credential shapes (AWS keys, JWTs,
+# GitHub tokens, high-entropy values next to an api_key-ish assignment) rather
+# than raw entropy, so the repo's 24-hex MongoDB asset IDs are not flagged.
+# detect-secrets was evaluated first and reported ~350 of them (ENG-3686).
+useDefault = true
+
+# The curated rules miss the shapes this repo actually leaked: a 64-hex platform
+# key in `os.environ["TEAM_API_KEY"] = "..."`, in `{"Authorization": "Token ..."}`
+# and passed straight to the client. A leaked assignment line went unreported;
+# only saved notebook output tripped a default rule, so the same notebook saved
+# without outputs would have passed. These two rules close
+# that gap. tests/unit/test_secret_scanning.py checks both against those shapes.
+#
+# The text between the name and the key may hold hex letters (`_PROD`, `_DEV`,
+# `_KEY`), so the rule only asks for a non-hex character right before the key,
+# not for a separator free of a-f. A separator that had to avoid a-f missed
+# `TEAM_API_KEY_PROD="<key>"` and `{"x-aixplain-key": "<key>"}`. Every name
+# below ends in a non-hex letter, so a key written straight after one still has
+# a boundary on its left.
+[[rules]]
+id = "aixplain-platform-key"
+description = "aiXplain platform/team API key: 64 hex characters shortly after a credential name on the same line."
+regex = '''(?i)(?:api[_-]?key|team[_-]?key|access[_-]?key|aixplain[_-]?key|token|secret|authorization)(?:[^\n]{0,40}?[^0-9a-f\n])?([0-9a-f]{64})(?:[^0-9a-f]|$)'''
+secretGroup = 1
+keywords = ["api_key", "api-key", "apikey", "team_key", "team-key", "access_key", "access-key", "aixplain_key", "aixplain-key", "token", "secret", "authorization"]
+
+[[rules]]
+id = "aixplain-client-positional-key"
+description = "aiXplain platform API key passed positionally, as in `Aixplain(\"<key>\")`, where no credential name is on the line."
+regex = '''(?i)\baixplain\(\s*["']([0-9a-f]{64})["']'''
+secretGroup = 1
+keywords = ["aixplain("]
+
+[[allowlists]]
+description = "Build artifacts, not reviewable source. `gitleaks dir .` walks the working tree, so a local run would otherwise re-report every secret-shaped literal frozen into a .pyc. All of these are gitignored and never reach a CI checkout."
+paths = [
+  '''__pycache__/''',
+  '''\.pyc$''',
+  '''^\.venv/''',
+  '''^venv/''',
+  '''^uv\.lock$''',
+]
+
+[[allowlists]]
+description = "Documentation placeholder. A literal instruction to the reader, never a live value."
+regexes = [
+  '''^YOUR_API_KEY$''',
+]
+
+[[allowlists]]
+description = "Hand-written fake credentials in unit tests, matched by exact value. Keep this list literal so a real key pasted next to them still trips the scanner."
+regexes = [
+  '''^abcd1234efgh$''',
+  '''^wxyz5678uvst$''',
+  '''^valid_api_key_123$''',
+  # The planted key in tests/unit/test_secret_scanning.py, which must look like a real one to test the detector.
+  '''^deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef$''',
+]