so101-nexus 0.4.0__tar.gz

so101_nexus-0.4.0/.github/dependabot.yml

@@ -0,0 +1,43 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "10:00"
+      timezone: America/New_York
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: chore
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "10:30"
+      timezone: America/New_York
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: chore
+
+  - package-ecosystem: npm
+    directory: /docs
+    schedule:
+      interval: weekly
+      day: monday
+      time: "11:00"
+      timezone: America/New_York
+    groups:
+      docs-dependencies:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: chore

so101_nexus-0.4.0/.github/scripts/protect_main_branch.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+api_version="${GITHUB_API_VERSION:-2026-03-10}"
+token="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
+branch="${BRANCH:-main}"
+
+remote_url="$(git config --get remote.origin.url)"
+owner_repo="${remote_url#git@github.com:}"
+owner_repo="${owner_repo#https://github.com/}"
+owner_repo="${owner_repo%.git}"
+
+owner="${GITHUB_OWNER:-${OWNER:-${owner_repo%%/*}}}"
+repo="${GITHUB_REPO:-${REPO:-${owner_repo#*/}}}"
+
+if [[ -z "$token" ]]; then
+  cat >&2 <<'EOF'
+Set GITHUB_TOKEN or GH_TOKEN to a token with Administration: write for this repository.
+For a fine-grained PAT, grant Repository administration: read and write.
+EOF
+  exit 2
+fi
+
+api() {
+  local method="$1"
+  local path="$2"
+  shift 2
+
+  curl -fsSL \
+    -X "$method" \
+    -H "Accept: application/vnd.github+json" \
+    -H "Authorization: Bearer ${token}" \
+    -H "X-GitHub-Api-Version: ${api_version}" \
+    "https://api.github.com${path}" \
+    "$@"
+}
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+cat >"$tmpdir/actions-permissions.json" <<'JSON'
+{
+  "enabled": true,
+  "allowed_actions": "selected",
+  "sha_pinning_required": true
+}
+JSON
+
+cat >"$tmpdir/selected-actions.json" <<'JSON'
+{
+  "github_owned_allowed": true,
+  "verified_allowed": false,
+  "patterns_allowed": [
+    "astral-sh/setup-uv@*",
+    "pnpm/action-setup@*",
+    "pypa/gh-action-pypi-publish@*"
+  ]
+}
+JSON
+
+cat >"$tmpdir/workflow-permissions.json" <<'JSON'
+{
+  "default_workflow_permissions": "read",
+  "can_approve_pull_request_reviews": false
+}
+JSON
+
+cat >"$tmpdir/fork-pr-approval.json" <<'JSON'
+{
+  "approval_policy": "all_external_contributors"
+}
+JSON
+
+cat >"$tmpdir/branch-protection.json" <<'JSON'
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [
+      "lint",
+      "test",
+      "docs",
+      "dependency-review"
+    ]
+  },
+  "enforce_admins": true,
+  "required_pull_request_reviews": {
+    "dismiss_stale_reviews": true,
+    "require_code_owner_reviews": false,
+    "required_approving_review_count": 1,
+    "require_last_push_approval": true
+  },
+  "restrictions": null,
+  "required_linear_history": true,
+  "allow_force_pushes": false,
+  "allow_deletions": false,
+  "block_creations": false,
+  "required_conversation_resolution": true,
+  "lock_branch": false,
+  "allow_fork_syncing": true
+}
+JSON
+
+echo "Applying repository Actions policy for ${owner}/${repo}"
+api PUT "/repos/${owner}/${repo}/actions/permissions" \
+  -d @"$tmpdir/actions-permissions.json" >/dev/null
+
+echo "Allowing only GitHub-owned actions and explicit third-party action repositories"
+api PUT "/repos/${owner}/${repo}/actions/permissions/selected-actions" \
+  -d @"$tmpdir/selected-actions.json" >/dev/null
+
+echo "Setting the default GITHUB_TOKEN permission to read-only"
+api PUT "/repos/${owner}/${repo}/actions/permissions/workflow" \
+  -d @"$tmpdir/workflow-permissions.json" >/dev/null
+
+echo "Requiring approval for all external fork pull request workflows"
+api PUT "/repos/${owner}/${repo}/actions/permissions/fork-pr-contributor-approval" \
+  -d @"$tmpdir/fork-pr-approval.json" >/dev/null
+
+echo "Applying branch protection to ${branch}"
+api PUT "/repos/${owner}/${repo}/branches/${branch}/protection" \
+  -d @"$tmpdir/branch-protection.json" >/dev/null
+
+echo "Requiring signed commits on ${branch}"
+api POST "/repos/${owner}/${repo}/branches/${branch}/protection/required_signatures" >/dev/null
+
+echo "Repository Actions policy and ${branch} branch protection are configured."

so101_nexus-0.4.0/.github/scripts/pypi_smoke_check.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Smoke-check the installed so101-nexus package from PyPI."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+import gymnasium as gym
+import tyro
+
+
+def run_mujoco(env_id: str) -> None:
+    """Reset and step a registered MuJoCo env to verify the install works."""
+    import so101_nexus.mujoco  # noqa: F401
+
+    env = gym.make(env_id)
+    try:
+        obs, info = env.reset(seed=0)
+        action = env.action_space.sample()
+        step_result = env.step(action)
+    finally:
+        env.close()
+
+    if obs is None or info is None:
+        raise RuntimeError("MuJoCo smoke check failed: reset returned empty values.")
+    if len(step_result) != 5:
+        raise RuntimeError("MuJoCo smoke check failed: step did not return a 5-tuple.")
+
+
+def run_warp(env_id: str, *, device: str, num_envs: int) -> None:
+    """Reset and step a batched Warp vector env to verify the install works."""
+    import so101_nexus.warp  # noqa: F401
+
+    env = gym.make_vec(
+        env_id, num_envs=num_envs, device=device, vectorization_mode="vector_entry_point"
+    )
+    try:
+        obs, info = env.reset(seed=0)
+        action = env.action_space.sample()
+        step_result = env.step(action)
+    finally:
+        env.close()
+
+    if obs is None or info is None:
+        raise RuntimeError("Warp smoke check failed: reset returned empty values.")
+    if len(step_result) != 5:
+        raise RuntimeError("Warp smoke check failed: step did not return a 5-tuple.")
+
+
+@dataclass
+class Args:
+    """Command-line arguments for the PyPI smoke check."""
+
+    env_id: str
+    backend: Literal["mujoco", "warp"] = "mujoco"
+    device: str = "cpu"
+    num_envs: int = 2
+
+
+def main(args: Args) -> None:
+    """Run the smoke check for the requested backend."""
+    print(f"Running smoke check for backend={args.backend}, env={args.env_id}")
+    if args.backend == "warp":
+        run_warp(args.env_id, device=args.device, num_envs=args.num_envs)
+    else:
+        run_mujoco(args.env_id)
+    print("Smoke check passed.")
+
+
+if __name__ == "__main__":
+    main(tyro.cli(Args))

so101_nexus-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,148 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHON_VERSION: "3.12"
+  UV_CACHE_DEPENDENCY_GLOB: uv.lock
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: ${{ env.UV_CACHE_DEPENDENCY_GLOB }}
+          cache-suffix: ci-lint
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Install dev dependencies
+        run: uv sync --locked --group dev
+      - name: Lint
+        run: make lint
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: System deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb ffmpeg libgl1 libglx-mesa0 libegl1-mesa-dev libosmesa6-dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: ${{ env.UV_CACHE_DEPENDENCY_GLOB }}
+          cache-suffix: ci-test
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install dependencies
+        run: uv sync --locked --group test
+
+      - name: Run tests
+        run: xvfb-run -a make test
+
+  test-warp:
+    name: test-warp
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: System deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgl1 libglx-mesa0 libegl1-mesa-dev libosmesa6-dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: ${{ env.UV_CACHE_DEPENDENCY_GLOB }}
+          cache-suffix: ci-test-warp
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install dependencies
+        run: uv sync --locked --extra warp
+
+      - name: Run Warp tests
+        env:
+          MUJOCO_GL: egl
+        run: make test-warp
+
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: ${{ env.UV_CACHE_DEPENDENCY_GLOB }}
+          cache-suffix: ci-docs
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Set up pnpm
+        uses: pnpm/action-setup@d15e628ca66d93ee5f352c71671a7bc6a97af5c9 # v6.0.8
+        with:
+          version: 9
+      - name: Set up Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+      - name: Cache Next.js build output
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: docs/.next/cache
+          key: ${{ runner.os }}-next-${{ hashFiles('docs/pnpm-lock.yaml') }}-${{ hashFiles('docs/app/**', 'docs/content/**', 'docs/lib/**', 'docs/*.mjs', 'docs/*.ts', 'docs/*.json') }}
+          restore-keys: |
+            ${{ runner.os }}-next-${{ hashFiles('docs/pnpm-lock.yaml') }}-
+      - name: Install dev dependencies
+        run: uv sync --locked --group dev
+      - name: Run docs checks
+        run: make docs-check

so101_nexus-0.4.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,32 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  dependency-review:
+    name: dependency-review
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        with:
+          fail-on-severity: moderate
+          fail-on-scopes: runtime,development
+          vulnerability-check: true
+          license-check: false
+          show-openssf-scorecard: true
+          warn-on-openssf-scorecard-level: 3

so101_nexus-0.4.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,71 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/deploy-docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@d15e628ca66d93ee5f352c71671a7bc6a97af5c9 # v6.0.8
+        with:
+          version: 10
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - name: Cache Next.js build output
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: docs/.next/cache
+          key: ${{ runner.os }}-next-${{ hashFiles('docs/pnpm-lock.yaml') }}-${{ hashFiles('docs/app/**', 'docs/content/**', 'docs/lib/**', 'docs/*.mjs', 'docs/*.ts', 'docs/*.json') }}
+          restore-keys: |
+            ${{ runner.os }}-next-${{ hashFiles('docs/pnpm-lock.yaml') }}-
+
+      - name: Install dependencies
+        working-directory: docs
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: docs
+        run: pnpm build
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/out
+
+  deploy:
+    name: deploy
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

so101_nexus-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.x"
+
+      - name: Build so101-nexus
+        run: uv build --out-dir dist/
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-dists
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  pypi-publish:
+    name: pypi-publish
+    runs-on: ubuntu-latest
+    needs: build
+    timeout-minutes: 15
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Download all distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: dist/
+          attestations: true

so101_nexus-0.4.0/.github/workflows/release-smoke.yml

@@ -0,0 +1,95 @@
+name: Release Smoke Test
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Package version to install (e.g. 0.1.0 or v0.1.0). Empty = latest."
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-smoke-${{ github.event.release.tag_name || github.event.inputs.version || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  smoke-test:
+    name: smoke-test (${{ matrix.backend }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - backend: mujoco
+            package: so101-nexus
+            env_id: MuJoCoReach-v1
+            apt_packages: "xvfb libgl1 libglx-mesa0 libegl1-mesa-dev libosmesa6-dev"
+          - backend: warp
+            package: "so101-nexus[warp]"
+            env_id: WarpReach-v1
+            apt_packages: "xvfb libgl1 libglx-mesa0 libegl1-mesa-dev libosmesa6-dev"
+
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ${{ matrix.apt_packages }}
+
+      - name: Install package from PyPI (with retries)
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+          PACKAGE: ${{ matrix.package }}
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+
+          VERSION="${INPUT_VERSION:-}"
+          if [ -z "$VERSION" ]; then
+            VERSION="${RELEASE_TAG:-}"
+          fi
+          VERSION="${VERSION#v}"
+
+          if [ -n "$VERSION" ]; then
+            SPEC="${PACKAGE}==${VERSION}"
+          else
+            SPEC="${PACKAGE}"
+          fi
+
+          echo "Installing ${SPEC}"
+          for i in {1..10}; do
+            if python -m pip install "${SPEC}"; then
+              exit 0
+            fi
+            echo "Install attempt ${i}/10 failed; retrying in 30s..."
+            sleep 30
+          done
+
+          echo "Failed to install ${SPEC} from PyPI after retries."
+          exit 1
+
+      - name: Install smoke-check harness deps
+        run: python -m pip install tyro
+
+      - name: Run backend smoke check
+        env:
+          MUJOCO_GL: egl
+        run: |
+          python .github/scripts/pypi_smoke_check.py \
+            --backend "${{ matrix.backend }}" \
+            --env-id "${{ matrix.env_id }}"