flybots 1.0.0__tar.gz

flybots-1.0.0/.bandit

@@ -0,0 +1,6 @@
+[bandit]
+# S101 — assert_used. Pytest is built on assert; flagging it is noise.
+# B404/B603 — subprocess use in scripts/make_promo.py. It invokes the
+#   ffmpeg binary shipped by imageio-ffmpeg with a fixed argument list and
+#   shell=False. No part of the command line comes from user input.
+skips = S101,B404,B603

flybots-1.0.0/.gitattributes

@@ -0,0 +1,13 @@
+# The 44 simulation GIFs live in Git LFS. The docs and README link them
+# through media.githubusercontent.com -- which is the LFS media endpoint --
+# so neither the docs build nor CI ever has to check LFS out.
+src/uav_sim/simulations/**/*.gif filter=lfs diff=lfs merge=lfs -text
+
+# docs/public/ is deliberately NOT in LFS, and the rule above is scoped so it
+# stays that way. VitePress bundles these files at build time, and the README
+# links promo.gif through raw.githubusercontent.com, which serves an LFS file
+# as its pointer text rather than as the image.
+
+# Don't skew language statistics with generated or vendored content.
+docs/package-lock.json linguist-generated=true
+uv.lock                linguist-generated=true

flybots-1.0.0/.github/ISSUE_TEMPLATE/algorithm_request.yml

@@ -0,0 +1,53 @@
+name: Algorithm request
+description: Suggest an algorithm to implement
+labels: [enhancement, algorithm]
+body:
+  - type: input
+    id: algorithm
+    attributes:
+      label: Algorithm
+      placeholder: Informed RRT*
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - path planning
+        - trajectory planning
+        - path tracking
+        - trajectory tracking
+        - state estimation
+        - perception
+        - swarm
+        - vehicle model
+        - reinforcement learning
+        - other
+    validations:
+      required: true
+
+  - type: input
+    id: reference
+    attributes:
+      label: Reference
+      description: Author, title, venue, year. A DOI or arXiv link is ideal.
+      placeholder: Gammell et al., "Informed RRT*", IROS 2014
+    validations:
+      required: true
+
+  - type: textarea
+    id: rationale
+    attributes:
+      label: Why this one
+      description: What does it do that the existing implementations do not?
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would like to implement this myself

flybots-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: Something behaves incorrectly
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Physics bugs are the interesting ones. The most useful report says
+        what you started from, what you applied, what happened, and what
+        should have happened.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you observe?
+      placeholder: The fixed-wing climbs away instead of holding altitude.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      placeholder: Trimmed flight should hold altitude to within a metre.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: A short script beats a description. This is rendered as Python.
+      render: python
+      placeholder: |
+        from uav_sim.vehicles.fixed_wing import FixedWing
+
+        aircraft = FixedWing()
+        controls = aircraft.reset_trimmed(airspeed=35.0, altitude=200.0)
+        for _ in range(5000):
+            aircraft.step(controls, 0.002)
+        print(aircraft.state[2])  # expected ~200, got 812
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `flybots --version`
+    validations:
+      required: true
+
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Environment
+      description: Output of `flybots doctor`
+      render: shell

flybots-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or idea
+    url: https://github.com/guilyx/flybots/discussions
+    about: Ask how something works, or propose an algorithm to add.

flybots-1.0.0/.github/ISSUE_TEMPLATE/docs.yml

@@ -0,0 +1,22 @@
+name: Documentation issue
+description: Something in the docs is wrong, missing or unclear
+labels: [documentation]
+body:
+  - type: input
+    id: page
+    attributes:
+      label: Page
+      description: URL or file path
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong
+      description: |
+        If something was hard to understand, say what you expected it to
+        say. "I could not tell which pitch sign convention applies" is more
+        actionable than "the docs are confusing".
+    validations:
+      required: true

flybots-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## What changed
+
+<!-- One or two sentences. What does this PR do? -->
+
+## Why
+
+<!-- What problem does this solve? If it fixes a bug, describe the
+     incorrect behaviour: what did it do, and what should it have done? -->
+
+## How it was verified
+
+<!-- How do you know it works? Prefer evidence over assertion:
+     numbers, a failing-then-passing test, a before/after comparison. -->
+
+- [ ] `uv run pytest` passes
+- [ ] `pre-commit run --all-files` passes
+- [ ] New behaviour is covered by tests that would fail without this change
+
+## For new algorithms
+
+- [ ] Citation in the module docstring (author, title, venue, year)
+- [ ] Runnable simulation exposing `main()`
+- [ ] Docs page plus a sidebar entry in `docs/.vitepress/config.ts`
+- [ ] Follows the frame conventions in CONTRIBUTING.md (world ENU, body FLU)
+
+## Notes for reviewers
+
+<!-- Anything you are unsure about, or that deserves a closer look. -->

flybots-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,156 @@
+# Erwin Lejeune - 2026-02-18
+
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          version: latest
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-groups
+      - name: Run pre-commit checks
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+
+  security:
+    name: Security scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          version: latest
+          enable-cache: true
+      - run: uv python install 3.12
+
+      # Our own code. This gates the build: anything bandit flags here is
+      # something we wrote and can fix.
+      - name: Static analysis (bandit)
+        run: uvx bandit -q -r src scripts
+
+      # Producing the input gates, even though auditing it does not. An
+      # audit that cannot read its input reports nothing, which looks
+      # exactly like an audit that found nothing.
+      #
+      # --no-header matters: FORCE_COLOR is set for the whole workflow, so
+      # uv wraps its header comment in ANSI codes. The escape byte lands
+      # before the '#', pip-audit stops seeing a comment, and it rejects
+      # the entire file on line 1.
+      - name: Export the locked dependency set
+        run: |
+          uv export --all-groups --format requirements-txt \
+            --no-emit-project --no-hashes --no-header --no-annotate > deps.txt
+          test -s deps.txt
+          # Written as an `if`, not `! grep ...`: bash ignores errexit for a
+          # command whose status is inverted with `!`, so the negated form
+          # can never fail the step.
+          if grep -q $'\x1b' deps.txt; then
+            echo "deps.txt contains ANSI escapes; pip-audit will reject it" >&2
+            exit 1
+          fi
+
+      # Advisories appear against pinned versions with no warning and no fix
+      # available, so the audit itself reports rather than gates -- a red X
+      # nobody can clear teaches contributors to ignore CI.
+      - name: Python dependency audit
+        continue-on-error: true
+        run: uvx pip-audit -r deps.txt --desc
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Docs dependency audit
+        working-directory: docs
+        run: |
+          # Print the full report. Two findings survive here, both in the
+          # vite range that VitePress 1.6.4 pins, both Windows-only and
+          # dev-server-only, and neither reaching the built site. See the
+          # `overrides` note in docs/package.json.
+          npm audit || true
+          # Gate on critical alone, so this step stays green until something
+          # lands that genuinely cannot wait for an upstream release.
+          npm audit --audit-level=critical
+
+  test:
+    name: Test (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          lfs: false
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          version: latest
+          enable-cache: true
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --all-groups
+      - name: Run tests
+        run: uv run pytest -q --cov=uav_sim --cov-report=xml --cov-report=term-missing
+      - name: Upload coverage
+        if: matrix.python == '3.12'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: coverage
+          path: coverage.xml
+          if-no-files-found: warn
+
+  smoke:
+    name: CLI smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          version: latest
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-groups
+      - name: Physics self-check
+        run: uv run flybots doctor
+      - name: Catalogue is discoverable
+        run: |
+          uv run flybots list
+          uv run flybots envs
+      - name: Trim solver
+        run: uv run flybots trim skywalker_x8
+      - name: Training loop runs end to end
+        run: uv run flybots train hover --iterations 3 --directions 4 --eval-episodes 3
+
+  docs:
+    name: Docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - run: npm ci
+        working-directory: docs
+      - run: npm run build
+        working-directory: docs

flybots-1.0.0/.github/workflows/pages.yml

@@ -0,0 +1,69 @@
+# Erwin Lejeune - 2026-02-18
+#
+# Builds the VitePress site and publishes it to GitHub Pages.
+
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Let a running deploy finish rather than cancelling it half-published.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          # VitePress reads git history to show last-updated timestamps.
+          fetch-depth: 0
+          # No LFS. The simulation GIFs are the only LFS content, and the
+          # docs link them through media.githubusercontent.com rather than
+          # bundling them -- checking them out would spend LFS bandwidth on
+          # every deploy for files the build never opens. The promo video
+          # under docs/public/ is a normal git object precisely so that this
+          # stays true. CI's `Docs build` job proves it: same build, no LFS.
+          lfs: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Build site
+        run: npm run build
+        working-directory: docs
+
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

flybots-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,97 @@
+# Erwin Lejeune - 2026-08-18
+#
+# Builds the distribution and publishes it to PyPI as `flybots`.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC), so there is no API token
+# in the repository secrets. It needs a one-time setup on PyPI: on the
+# project's "Publishing" page, add a GitHub publisher for
+# guilyx/flybots, workflow `release.yml`, environment `pypi`.
+# Until that exists the publish step fails with an OIDC error rather than
+# silently uploading nothing.
+
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Build and check only, do not upload"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          # The sdist bundles the README, not the media it links to, so the
+          # 6 MB promo video is dead weight for this job.
+          lfs: false
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          version: latest
+          enable-cache: true
+      - run: uv python install 3.12
+
+      # A tag that disagrees with pyproject uploads a version nobody can
+      # reproduce from the tag. Caught here, before anything is built.
+      - name: Tag matches the packaged version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          packaged=$(uv version --short)
+          tagged="${GITHUB_REF_NAME#v}"
+          echo "pyproject: $packaged, tag: $tagged"
+          test "$packaged" = "$tagged"
+
+      - run: uv build
+
+      # twine's check is what PyPI itself runs on the long description. A
+      # README it cannot render is rejected at upload time, which is a bad
+      # place to find out.
+      - name: Metadata is valid
+        run: uvx twine check dist/*
+
+      # Proves the wheel installs and that both console scripts resolve --
+      # `flybots` and the `uav-sim` alias kept for the rename.
+      - name: Wheel installs and the commands work
+        run: |
+          uv venv /tmp/release-check
+          VIRTUAL_ENV=/tmp/release-check uv pip install dist/*.whl
+          /tmp/release-check/bin/flybots --version
+          /tmp/release-check/bin/uav-sim --version
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') && !inputs.dry-run
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/flybots/
+    permissions:
+      # Mints the OIDC token Trusted Publishing exchanges for an upload
+      # token. Nothing else in this workflow needs it.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          version: latest
+      - name: Upload
+        run: uv publish --trusted-publishing always

flybots-1.0.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff
+.ruff_cache/
+
+*.log
+*.log.gz
+*.log.gz.part
+*.log.gz.part.1
+*.log.gz.part.2
+*.log.gz.part.3
+*.log.gz.part.4
+*.log.gz.part.5
+*.log.gz.part.6
+*.log.gz.part.7
+.env
+
+# Generated simulation artifacts
+src/uav_sim/simulations/**/*_log.json
+
+# Trained policies, other than the checked-in reference ones.
+# The learning curve belongs with the policy: `scripts/make_promo.py` only
+# takes its reuse path when *both* files are present, so ignoring the curve
+# made every promo render retrain from scratch -- an hour of CPU to change a
+# line of on-screen copy.
+policies/*
+!policies/hover.npz
+!policies/hover_curve.npy
+
+# Docs build output
+docs/.vitepress/dist/
+docs/.vitepress/cache/

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

@@ -0,0 +1,37 @@
+# See https://pre-commit.com for more information
+# Run `pre-commit install` to install hooks, then `pre-commit run --all-files` to check
+repos:
+  # Conventional commits: feat:, fix:, chore:, docs:, style:, refactor:, test:, etc.
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.27.0
+    hooks:
+      # `stages` belongs on the hook, not the repo — pre-commit warns about
+      # it at the repo level and then ignores it.
+      - id: commitizen
+        stages: [commit-msg]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ["--maxkb=6000"]
+        # The promo video is the one binary deliberately committed outside
+        # LFS — it has to be a real file under docs/public/ for the site to
+        # bundle it. Exempting it by name keeps the limit meaningful for
+        # everything else, which is what the check is actually for.
+        exclude: ^docs/public/media/promo\.mp4$
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  # Keep this in step with the ruff version in pyproject's dev group.
+  # A stale pin here is worse than no pin: ruff's formatter changes between
+  # releases, so the two versions fight over the same files and every CI run
+  # reformats what the last local run just formatted.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

flybots-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12