creature-lab 0.3.0__tar.gz

creature_lab-0.3.0/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "attribution": {
+    "commit": "",
+    "pr": "",
+    "sessionUrl": false
+  }
+}

creature_lab-0.3.0/.copier-answers.launcher-kit.yml

@@ -0,0 +1,3 @@
+# Changes here will be overwritten by Copier; do not edit by hand.
+_commit: v1.1.0
+_src_path: gh:oney-erge/launcher-kit

creature_lab-0.3.0/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.github
+.venv
+.env
+.env.*
+runs
+outputs
+__pycache__
+*.pyc

creature_lab-0.3.0/.gitattributes

@@ -0,0 +1,51 @@
+# Line endings, pinned per file type rather than left to each contributor's
+# core.autocrlf setting.
+#
+# Nothing is broken today - the blobs in this repository are already LF, and a
+# clone on Linux or macOS gets LF. But nothing enforced that: a contributor on
+# Windows with core.autocrlf=false commits exactly what is in their editor, and
+# a shell script committed with CRLF fails on the first line of real work with
+#
+#     set: pipefail: invalid option name
+#
+# which reads as a broken installer rather than a line-ending problem. This file
+# makes the outcome independent of who committed it.
+
+# Anything Git decides is text gets LF in the repository.
+* text=auto
+
+# Must be LF wherever they are checked out, because they run on Linux even when
+# they were written on Windows.
+*.sh          text eol=lf
+*.command     text eol=lf
+Dockerfile    text eol=lf
+*.yml         text eol=lf
+*.yaml        text eol=lf
+
+# Windows entry points, which cmd.exe and PowerShell expect to find as CRLF.
+*.bat         text eol=crlf
+*.cmd         text eol=crlf
+*.ps1         text eol=crlf
+
+# Never touched: conversion corrupts these.
+*.png         binary
+*.gif         binary
+*.webp        binary
+*.jpg         binary
+*.ico         binary
+*.woff        binary
+*.woff2       binary
+*.ttf         binary
+*.msi         binary
+*.exe         binary
+*.pdf         binary
+
+# The front end is built into a committed bundle that CI rebuilds on Linux and compares byte for
+# byte. Its sources must be LF on every machine: Vite copies index.html's line endings, so a
+# Windows checkout with CRLF produced a bundle a few bytes different from CI's.
+web-ui/index.html  text eol=lf
+web-ui/src/**      text eol=lf
+
+# The built bundle is generated: never convert its line endings, so a Windows checkout, a Linux
+# checkout and CI's rebuild are the same bytes.
+creature_lab/web/static/**  -text

creature_lab-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a crash, incorrect run artifact, or broken CLI workflow
+title: "Bug: "
+labels: bug
+---
+
+## What happened?
+
+## Command
+
+```bash
+
+```
+
+## Expected behavior
+
+## Environment
+
+- OS:
+- Python:
+- Creature Lab version:
+- Backend: pybullet / mujoco / none
+
+## Artifacts
+
+Prefer a verified design pack—it contains the exact creature, task, controller, trace, and hashes:
+
+```bash
+creature-lab export-pack latest --out creature-lab-bug-pack
+creature-lab verify-pack creature-lab-bug-pack
+```
+
+Attach the pack, or paste `report latest --json` when a pack cannot be shared. Policy packs may
+contain serialized code; do not attach secrets or a policy you are not allowed to redistribute.

creature_lab-0.3.0/.github/ISSUE_TEMPLATE/creature_submission.md

@@ -0,0 +1,27 @@
+---
+name: Creature submission
+about: Propose a new packaged zoo creature
+title: "Zoo creature: "
+labels: zoo
+---
+
+## Creature name
+
+Use lowercase words with underscores.
+
+## What should it demonstrate?
+
+## Files
+
+- `creature.json`:
+- task JSON:
+- baseline JSON, if available:
+- GIF or report, if available:
+
+## Validation
+
+```bash
+uv run creature-lab validate path/to/creature.json --task path/to/task.json
+uv run creature-lab run path/to/creature.json --task path/to/task.json
+uv run creature-lab report latest
+```

creature_lab-0.3.0/.github/ISSUE_TEMPLATE/docs_improvement.md

@@ -0,0 +1,16 @@
+---
+name: Docs improvement
+about: Improve onboarding, examples, specs, or CLI reference docs
+title: "Docs: "
+labels: documentation
+---
+
+## Page or command
+
+## What is confusing or missing?
+
+## Suggested improvement
+
+## Verification
+
+What command should someone run to confirm the docs are accurate?

creature_lab-0.3.0/.github/ISSUE_TEMPLATE/task_proposal.md

@@ -0,0 +1,26 @@
+---
+name: Task proposal
+about: Propose a new local challenge task
+title: "Task: "
+labels: task
+---
+
+## Task goal
+
+## Existing schema features used
+
+- Terrain friction:
+- Target:
+- Damage event:
+- Impulse event:
+- Reward terms:
+
+## Candidate command
+
+```bash
+uv run creature-lab run examples/quadruped.json --task path/to/task.json
+```
+
+## Acceptance signal
+
+What score, report signal, or diagnosis result should show that the task works?

creature_lab-0.3.0/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      security-updates:
+        applies-to: security-updates
+        patterns: ["*"]
+      production-dependencies:
+        dependency-type: production
+        update-types: ["minor", "patch"]
+      development-dependencies:
+        dependency-type: development
+        update-types: ["minor", "patch"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      security-updates:
+        applies-to: security-updates
+        patterns: ["*"]
+      actions:
+        update-types: ["minor", "patch"]

creature_lab-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,238 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  launchers:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - if: runner.os != 'Windows'
+        run: bash -n run.sh run.command
+      - if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $errors = $null
+          [void][System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path run.ps1), [ref]$null, [ref]$errors)
+          if ($errors) { $errors | Format-List; exit 1 }
+      - if: runner.os == 'Windows'
+        name: Launcher helpers under Windows PowerShell 5.1
+        shell: powershell
+        run: ./scripts/test-launcher-helpers.ps1
+
+  first-launch:
+    name: first launch (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          cache-suffix: first-launch-${{ matrix.os }}
+      - name: Start the app with the real launcher and check it
+        shell: bash
+        run: |
+          # One step on purpose: on Windows a process started in an earlier step is gone by now.
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            # What run.bat does: Windows PowerShell 5.1.
+            powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File run.ps1 -NoBrowser > launch.log 2>&1 &
+          else
+            nohup ./run.sh --no-browser > launch.log 2>&1 &
+          fi
+          ready=0
+          for _ in $(seq 1 180); do
+            if curl -fsS http://127.0.0.1:8080/api/health; then ready=1; break; fi
+            sleep 2
+          done
+          if [ "$ready" != 1 ]; then
+            echo "The app did not come up within 6 minutes."
+            tail -n 120 launch.log || true
+            exit 1
+          fi
+          echo
+          # No package was compiled from source: PyBullet must stay optional.
+          uv run --no-sync python -c "import importlib.util as u; assert u.find_spec('pybullet') is None, 'PyBullet must stay optional'; import fastapi, mujoco, viser, onnxruntime"
+          curl -fsS http://127.0.0.1:8080/api/robots | python -c "import json, sys; keys = [r['key'] for r in json.load(sys.stdin)['robots']]; assert keys == ['microduck', 'unitree_g1'], keys"
+
+  quality-and-package:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          cache-suffix: quality-and-package
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Sync all local/test integrations
+        run: uv sync --all-extras
+      - name: Ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Full test suite
+        run: uv run pytest
+      - name: CLI and behavioral contracts
+        run: |
+          uv run creature-lab doctor
+          uv run creature-lab validate examples/tripod.json --task examples/crawl_forward.json
+          uv run creature-lab zoo validate-all
+          uv run creature-lab zoo check-showcases
+      - name: Build wheel and source distribution
+        run: uv build
+      - name: Smoke-test the installed wheel outside the checkout
+        run: |
+          python3 -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/pip install --quiet "$(ls dist/*.whl)[sim]"
+          mkdir -p /tmp/wheel-smoke
+          cd /tmp/wheel-smoke
+          /tmp/wheel-venv/bin/creature-lab doctor
+          /tmp/wheel-venv/bin/creature-lab zoo run quadruped --runs-dir ./runs
+
+  supported-platforms:
+    name: ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: "3.12"
+            physics-extra: sim
+          - os: windows-latest
+            python: "3.11"
+            physics-extra: sim
+          - os: windows-latest
+            python: "3.12"
+            physics-extra: sim
+          - os: macos-latest
+            python: "3.11"
+            physics-extra: mujoco
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          cache-suffix: supported-${{ matrix.os }}-${{ matrix.python }}
+      - name: Set up Python
+        run: uv python install ${{ matrix.python }}
+      - name: Sync runtime and test dependencies
+        run: uv sync --extra ${{ matrix.physics-extra }} --extra viz --extra export --extra evolve
+      - name: Platform test suite
+        run: uv run pytest -m "not optional_backend"
+      - name: Launcher and CLI smoke
+        run: |
+          uv run python scripts/start.py --dry-run
+          uv run creature-lab validate examples/tripod.json --task examples/crawl_forward.json
+
+  browser-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          cache-suffix: browser-smoke
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install editor and browser dependencies
+        run: |
+          uv sync --extra sim --extra viz --extra browser
+          uv run playwright install --with-deps chromium
+      - name: Real first-run browser journey and process cleanup
+        run: uv run python scripts/browser_smoke.py
+
+  frontend:
+    # The browser app's source (web-ui/) and the bundle committed in
+    # creature_lab/web/static must agree, so users never need Node.
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: web-ui
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web-ui/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
+      - name: Committed bundle matches the source
+        run: |
+          if [ -n "$(git status --porcelain -- ../creature_lab/web/static)" ]; then
+            git status --short -- ../creature_lab/web/static
+            echo "creature_lab/web/static is stale: run 'npm run build' in web-ui and commit it."
+            exit 1
+          fi
+
+  docker-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - run: docker compose up --detach --build
+      - run: |
+          for attempt in $(seq 1 60); do
+            curl --fail --silent http://127.0.0.1:8080 && exit 0
+            sleep 2
+          done
+          docker compose logs
+          exit 1
+      - if: always()
+        run: docker compose down --volumes
+
+  lockfile:
+    # uv sync --frozen trusts uv.lock as-is; fail when it no longer matches pyproject.toml.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv lock --check
+
+  zizmor:
+    # Workflow security audit, pinned and offline so its result changes only
+    # with this file or the workflows (settings in .github/zizmor.yml).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uvx zizmor==1.31.1 --offline --min-severity medium --config .github/zizmor.yml .github/workflows

creature_lab-0.3.0/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,39 @@
+name: Dependabot auto-merge
+
+# Merges passing Dependabot pull requests; the logic lives in
+# oney-erge/.github/.github/workflows/dependabot-automerge.yml.
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+  status:
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: Dependabot pull request number to re-evaluate
+        required: true
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write
+  checks: read
+  statuses: read
+
+# One queue per branch: a newer event for the same pull request replaces a pending
+# one, and events on other branches never cancel it.
+concurrency:
+  group: dependabot-automerge-${{ inputs.pr || github.event.workflow_run.head_branch || github.event.branches[0].name || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  merge:
+    if: >-
+      github.event_name == 'workflow_dispatch'
+      || (github.event_name == 'workflow_run' && startsWith(github.event.workflow_run.head_branch, 'dependabot/'))
+      || (github.event_name == 'status' && github.event.state == 'success'
+          && startsWith(github.event.branches[0].name, 'dependabot/'))
+    uses: oney-erge/.github/.github/workflows/dependabot-automerge.yml@main
+    with:
+      pr: ${{ inputs.pr }}
+      sha: ${{ github.event.workflow_run.head_sha || github.event.sha }}

creature_lab-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+# Publishing a GitHub release (tag vX.Y.Z) builds, tests and smoke-installs the package, attaches
+# the wheel and sdist to the release, then publishes them to PyPI through trusted publishing (the
+# protected `pypi` environment; no token in the repository). Run it by hand to build and check
+# without publishing.
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-verify:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # attach the distributions to the GitHub release
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv python install 3.11
+      - run: uv sync --all-extras
+      - run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pytest
+          uv run creature-lab zoo check-showcases
+          uv build
+      - name: Check the release tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          version=$(uv run python -c "import creature_lab; print(creature_lab.VERSION)")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match the package version $version" >&2
+            exit 1
+          fi
+      - name: Install the wheel into a clean environment
+        run: |
+          uv venv --python 3.11 "$RUNNER_TEMP/release-venv"
+          uv pip install --python "$RUNNER_TEMP/release-venv" dist/creature_lab-*.whl
+          "$RUNNER_TEMP/release-venv/bin/creature-lab" --help > /dev/null
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: creature-lab-distributions
+          path: dist/*
+          if-no-files-found: error
+      - name: Attach the distributions to the release
+        if: github.event_name == 'release'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$GITHUB_REF_NAME" dist/* --clobber --repo "$GITHUB_REPOSITORY"
+
+  publish:
+    if: github.event_name == 'release'
+    needs: build-and-verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: creature-lab-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

creature_lab-0.3.0/.github/workflows/scorecard.yml

@@ -0,0 +1,30 @@
+name: Scorecard
+
+# Publishes this repository's OpenSSF Scorecard to scorecard.dev:
+# https://scorecard.dev/viewer/?uri=github.com/oney-erge/Creature-Lab
+# Results are not uploaded as code-scanning alerts.
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "17 6 * * 1"
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  analysis:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true

creature_lab-0.3.0/.github/zizmor.yml

@@ -0,0 +1,14 @@
+# zizmor (https://docs.zizmor.sh) settings, checked in CI.
+rules:
+  # The Dependabot auto-merge caller runs on workflow_run by design: it never
+  # checks out or runs pull request code, only calls the GitHub API.
+  dangerous-triggers:
+    ignore:
+      - dependabot-automerge.yml
+  unpinned-uses:
+    config:
+      policies:
+        # Shared workflows from the owner's own .github repository track main on
+        # purpose, so a fix there applies to every repository at once.
+        "oney-erge/*": any
+        "*": hash-pin

creature_lab-0.3.0/.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+.setup/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+CLAUDE.local.md
+runs/
+outputs/
+*.mp4
+*.gif
+!docs/assets/
+!docs/assets/*.gif
+!docs/assets/**/
+!docs/assets/**/*.gif
+!docs/assets/*.mp4
+*.webm
+.DS_Store
+.idea/
+.vscode/
+MUJOCO_LOG.TXT
+*.urdf
+
+# Local assistant state
+.claude/settings.local.json
+.claude/scheduled_tasks.lock
+
+# Browser app front end (the built bundle in creature_lab/web/static is committed)
+web-ui/node_modules/