freesolo-flash-dev 1.4.10__tar.gz → 1.4.12__tar.gz

freesolo_flash_dev-1.4.12/.env.example

@@ -0,0 +1,116 @@
+# flash control plane (operator-side). copy to .env and fill in.
+# provider credentials live only here; clients never see them and authenticate
+# with their api key.
+#
+# Everything under "required" is checked by `flash/providers/core/preflight.py` at
+# startup; `flash-server` refuses to serve if any of them is missing. Settings
+# that only DEGRADE the plane (no GITHUB_TOKEN)
+# warn at startup instead of blocking it.
+#
+# self-hosting? read the self-hosting guide first - the short version is the two lines
+# below, and it is a much smaller list than this file suggests:
+#
+#   FLASH_STANDALONE=1
+#   FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+#
+# IMPORTANT: `flash-server` does NOT read this file. It reads the process
+# environment, so copying it to .env is not by itself enough — load it:
+#
+#   set -a && . ./.env && set +a && flash-server     # shell
+#   docker run --env-file .env ...                   # docker
+
+# --- required: Modal GPU substrate ---
+MODAL_TOKEN_ID=
+MODAL_TOKEN_SECRET=
+MODAL_ENVIRONMENT=main
+# set to 1 to bypass the shared base-model weight cache.
+FLASH_WEIGHT_CACHE_DISABLED=0
+
+# --- required: Flash-owned artifacts (private Azure Blob Storage) ---
+FLASH_ARTIFACT_BLOB_ACCOUNT_URL=https://youraccount.blob.core.windows.net
+FLASH_ARTIFACT_BLOB_CONTAINER=artifacts
+# DefaultAzureCredential is used on the controller. Alternatively supply an account
+# connection string here. Account keys never reach training workers: the controller
+# issues a container SAS with read/create/write/list permissions and a 27-hour lifetime.
+# FLASH_ARTIFACT_BLOB_CONNECTION_STRING=
+# A preissued container SAS URL is also accepted (use a read-only one on serving engines).
+# FLASH_ARTIFACT_BLOB_SAS_URL=
+# Logical namespace inside the private container; independent of any upstream account.
+FLASH_ARTIFACT_NAMESPACE=Freesolo-Co
+
+# --- optional: upstream gated base-model downloads and explicit Hub exports ---
+HF_TOKEN=
+
+# --- required: control-plane auth ---
+# The plane's own auth key. On a self-hosted (FLASH_STANDALONE=1) deployment this is
+# the ONLY credential the plane accepts and is therefore the entire trust boundary -
+# generate a high-entropy value and treat it like a root password:
+#
+#   export FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+#
+# On a managed deployment it is the shared internal key that maps to a single service
+# identity without a network call, alongside per-user keys verified against
+# {FREESOLO_BASE_URL}/api/auth/verify.
+FREESOLO_INTERNAL_KEY=
+
+# --- optional: self-hosting ---
+# Run without a Freesolo backend. Off by default. With it set, the plane stops calling
+# out for project/environment/billing validation and trusts FREESOLO_INTERNAL_KEY as a
+# single-tenant operator credential; external bearer tokens are REJECTED rather than
+# accepted unverified. Single tenant - see SELF_HOSTING.md before enabling.
+# FLASH_STANDALONE=1
+
+# --- optional: deployment topology ---
+# Where Flash keeps its local state: the saved login, the SQLite database, run records, and
+# results. Defaults to ~/.flash (= /root/.flash for the container's default user, which is the
+# path the Dockerfile declares as a VOLUME). Set this for a rootless container, a Kubernetes
+# PVC, a read-only home directory, or a systemd unit with ProtectHome. Everything moves
+# together, so point it at ONE durable location and mount a volume there.
+# FLASH_DATA_DIR=/var/lib/flash
+# Log verbosity for `flash-server`: DEBUG, INFO, WARNING, ERROR, CRITICAL. The server defaults
+# to INFO -- provider resolution, capability removal, reaper startup, and degraded-config
+# warnings are all reported at INFO/WARNING. An unrecognized value falls back to the default
+# rather than blocking startup.
+# FLASH_LOG_LEVEL=INFO
+# `text` (default) or `json`. JSON emits one object per line for a structured log sink. The
+# same information is logged either way; only the punctuation differs.
+# FLASH_LOG_FORMAT=text
+# Bind address for `flash-server`. Defaults to 127.0.0.1; the container image passes 0.0.0.0
+# explicitly. The --host and --port flags win over both of these.
+# FLASH_SERVER_HOST=127.0.0.1
+# Port for `flash-server`, default 8080. Must be 1-65535: an unusable value stops startup
+# rather than silently binding the default, since a plane listening on the wrong port looks
+# healthy and is unreachable.
+# FLASH_SERVER_PORT=8080
+# How long (seconds) to wait for a SQLite lock held by another writer, default 30. Raise it on
+# networked storage, where a lock can be held far longer than on a local volume. This changes
+# only patience: journal mode, synchronous, and foreign keys are correctness settings and are
+# deliberately not configurable.
+# FLASH_SQLITE_BUSY_TIMEOUT_SECONDS=30
+
+# --- optional ---
+# Server token for the environment repository. Without it, environments hosted in a
+# private GitHub repo cannot be fetched; environments in public GitHub repos still work,
+# so this warns at startup rather than blocking it. (A local directory is never a valid
+# environment source - the GPU worker fetches the environment itself.)
+GITHUB_TOKEN=
+# Where to verify user keys. Defaults to https://api.freesolo.co when unset. Ignored
+# under FLASH_STANDALONE=1, which verifies nothing over the network.
+# FREESOLO_BASE_URL=
+# Adapter serving is delegated to a multi-LoRA serving app (a Modal app that serves
+# every adapter on one GPU per base model, scaling to zero when idle).
+# `flash deploy`/`undeploy`/`chat` register/deregister/chat against it. Defaults to the
+# hosted URL when unset; point it at your own deployment to self-host serving.
+#
+# Under FLASH_STANDALONE=1 there is NO default: those three commands error out until this
+# is set to a backend YOU operate. Every serving request carries FREESOLO_INTERNAL_KEY,
+# which on a self-hosted plane is the credential controlling that plane, so pointing it at
+# a service you do not run would hand that credential over. Training never uses this.
+#
+# A Freesolo-hosted value is refused the same way an unset one is -- assigning the hosted
+# URL here does not get you past the guard, it just produces the same error. Set it to
+# YOUR serving deployment; the managed plane gets the hosted URL from the code default.
+# FREESOLO_SERVING_URL=https://serving.example.internal
+# The worker container image is not configurable: every provider runs the published
+# ghcr.io/freesolo-co/flash-worker tags (per-GPU-arch kernel-cache variants, falling back to the
+# base :cu128), selected by GPU class in flash/providers/_lifecycle/net/worker.py.

freesolo_flash_dev-1.4.12/.github/workflows/bake-kernel-cache.yml

@@ -0,0 +1,275 @@
+name: flash worker kernel-cache (per-arch)
+
+# Builds per-SM worker images with compiled kernel caches baked in to reuse matching kernels
+# on cold workers. Each matrix leg:
+#   1. offloads the warmup to a Modal GPU of that arch (GH runners have none) -> build/kernel_cache,
+#   2. builds docker/Dockerfile.kernelcache -> ghcr.io/freesolo-co/flash-worker:cu128-<sm>,
+#   3. pushes it. After live qualification, record its immutable digest in QUALIFIED_WORKER_IMAGES
+#      (flash/providers/_lifecycle/net/worker.py); publishing a tag does not enable it for workers.
+#
+# Depends on the base ghcr.io/freesolo-co/flash-worker:cu128 image existing (worker-image.yml) — the
+# warmup runs INSIDE it so the cache matches the image's pinned torch/triton/fla/liger toolchain.
+#
+# Secrets: MODAL_TOKEN_ID + MODAL_TOKEN_SECRET (the warmup GPU sandbox) + HF_TOKEN (the temp dataset that ferries code + the
+# cache artifact) are native repo Actions secrets, synced from Infisical (prod:/flash-ci) by the
+# github-ci-flash Secret Sync; the GHCR push uses the default GITHUB_TOKEN. Heavy + paid,
+# but UNGATED: the fingerprint detection in auto-rebake.yml decides WHEN this runs (only on a real
+# kernel-toolchain change), so there is no manual approval step. Invoked by hand (workflow_dispatch)
+# OR automatically by auto-rebake.yml (workflow_call) when the kernel toolchain changed.
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_ref:
+        description: "Existing worker base image to bake (labels pin its source and fingerprints)"
+        type: string
+        default: "ghcr.io/freesolo-co/flash-worker:cu128"
+        required: false
+      sms:
+        description: "comma-separated sm list to bake; default is all validated arches"
+        default: "sm80,sm86,sm89,sm90,sm120,sm100"
+        required: false
+      deadline_minutes:
+        description: "Maximum GPU runtime per architecture (1–90 minutes)"
+        type: number
+        default: 90
+        required: false
+      target_tag_prefix:
+        description: "target image tag before the -sm suffix"
+        default: "cu128"
+        required: false
+  # auto-rebake.yml calls this for the EXPENSIVE path (the cache is invalid and must be re-warmed on a
+  # real GPU). It passes the arch subset, the fingerprints to stamp, and a digest-pinned base so the
+  # warm runs inside the exact :cu128 the per-arch tag will sit on.
+  workflow_call:
+    inputs:
+      deadline_minutes:
+        type: number
+        default: 90
+        required: false
+      sms:
+        type: string
+        required: true
+      fp_cache:
+        type: string
+        required: false
+        default: ""
+      fp_base:
+        type: string
+        required: false
+        default: ""
+      base_ref:
+        type: string
+        required: false
+        default: "ghcr.io/freesolo-co/flash-worker:cu128"
+      base_revision:
+        type: string
+        required: false
+        default: ""
+      target_tag_prefix:
+        type: string
+        required: false
+        default: "cu128"
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  # Ungated: the PAID Modal bake runs as soon as it's called/dispatched. The decision of WHEN to run
+  # lives in auto-rebake.yml's fingerprint gate (it only invokes this when fp_cache changed), so a
+  # second manual approval here would be redundant. Re-add an `approve` job with `environment: gpu-bake`
+  # (and `needs: approve`) if you ever want a human checkpoint back.
+  bake:
+    # Upstream only -- see publish.yml. "Ungated" above means no human APPROVAL step; it never meant
+    # any repository may start it. This workflow is directly dispatchable (`workflow_dispatch`), so
+    # a fork reaches it without passing auto-rebake's fingerprint gate, and it both requests the
+    # org-only `ubuntu-24.04-8core` runner (a label a fork has no runner for, so the job QUEUES
+    # instead of failing) and creates paid Modal resources. `workflow_call` from auto-rebake still
+    # satisfies this, because a called workflow evaluates `github.repository` as the CALLER's repo.
+    if: github.repository == 'freesolo-co/flash'
+    runs-on: ubuntu-24.04-8core
+    # 47min is the slowest run on record (the rest sit at 12-23min); 120 absorbs a slow provider
+    # allocation without letting a hung bake hold the runner for the 6-hour default.
+    #
+    # Modal also enforces the sandbox lifetime when the CI controller disappears.
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {
+              sm: sm80,
+              arch: "8.0",
+            }
+          - {
+              sm: sm86,
+              arch: "8.6",
+            }
+          # the controller walks ordered same-sm secure-cloud gpu types from its per-sm map.
+          # preferred datacenter cards stay first, but one empty sku cannot strand this architecture
+          # on a stale image and send ordinary starts through jit.
+          - {
+              sm: sm89,
+              arch: "8.9",
+            }
+          - {
+              sm: sm90,
+              arch: "9.0",
+            }
+          # blackwell needs cuda-13 hosts to jit its ptx (matches min_cuda_for in the provider).
+          - {
+              sm: sm120,
+              arch: "12.0",
+            }
+          # datacenter blackwell is distinct from sm120. b200 is the only validated sm100 type.
+          - {
+              sm: sm100,
+              arch: "10.0",
+            }
+    steps:
+      # Gate FIRST (no checkout needed) so skipped arches do no crane / checkout / build work.
+      - name: Should bake ${{ matrix.sm }}?
+        id: gate
+        env:
+          REQUESTED_SMS: ${{ inputs.sms || 'sm80,sm86,sm89,sm90,sm120,sm100' }}
+          BAKE_DEADLINE_MINUTES: ${{ inputs.deadline_minutes }}
+        run: |
+          # Leave 30 minutes of the 120-minute job for setup, transfer and publication.
+          if ! [[ "$BAKE_DEADLINE_MINUTES" =~ ^([1-9]|[1-8][0-9]|90)$ ]]; then
+            echo "::error::deadline_minutes must be an integer from 1 to 90"
+            exit 1
+          fi
+          req="$REQUESTED_SMS"
+          req="${req// /}"   # tolerate spaces, e.g. "sm80, sm86"
+          case ",$req," in
+            *,${{ matrix.sm }},*) echo "run=true" >> "$GITHUB_OUTPUT" ;;
+            *) echo "run=false" >> "$GITHUB_OUTPUT"; echo "skipping ${{ matrix.sm }}" ;;
+          esac
+
+      # Downloaded to disk and checksum-verified before extraction, rather than piped straight
+      # into tar: a piped stream is extracted as it arrives, so a corrupted or substituted
+      # artifact is already on PATH by the time anything could notice. Bump the version and the
+      # digest together (the vendor publishes checksums.txt alongside each release).
+      - name: Install crane
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          set -euo pipefail
+          ver=v0.20.2
+          sha=c14340087103ba9dadf61d45acd20675490fd0ccbd56ac7901fc1b502137f44b
+          curl -fsSL -o /tmp/crane.tar.gz \
+            "https://github.com/google/go-containerregistry/releases/download/${ver}/go-containerregistry_Linux_x86_64.tar.gz"
+          echo "${sha}  /tmp/crane.tar.gz" | sha256sum -c -
+          sudo tar -xz -C /usr/local/bin -f /tmp/crane.tar.gz crane
+          rm -f /tmp/crane.tar.gz
+          crane version
+
+      - name: Log in to GHCR
+        if: steps.gate.outputs.run == 'true'
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Resolve the base + fingerprints BEFORE checkout, so the checkout (hence the warmed flash code)
+      # is pinned to the EXACT commit the base was built from. auto-rebake passes everything (fast path);
+      # a manual dispatch READS the labels off the published base, so the per-arch image always matches
+      # the base it extends (same source of truth as the gate) instead of recomputing from the checkout.
+      - name: Resolve base + fingerprints
+        id: base
+        if: steps.gate.outputs.run == 'true'
+        env:
+          BASE_REF: ${{ inputs.base_ref || 'ghcr.io/freesolo-co/flash-worker:cu128' }}
+          FP_CACHE: ${{ inputs.fp_cache }}
+          FP_BASE: ${{ inputs.fp_base }}
+          BASE_REVISION: ${{ inputs.base_revision }}
+        run: |
+          if [ -n "$FP_CACHE" ]; then
+            echo "ref=$BASE_REF" >> "$GITHUB_OUTPUT"
+            echo "fp_cache=$FP_CACHE" >> "$GITHUB_OUTPUT"
+            echo "fp_base=$FP_BASE" >> "$GITHUB_OUTPUT"
+            echo "revision=$BASE_REVISION" >> "$GITHUB_OUTPUT"
+          else
+            ref=$(crane digest --full-ref "$BASE_REF")
+            cfg=$(crane config "$ref")
+            echo "ref=$ref" >> "$GITHUB_OUTPUT"
+            echo "fp_cache=$(echo "$cfg" | jq -r '.config.Labels["co.freesolo.flash.kernelcache.fp_cache"] // ""')" >> "$GITHUB_OUTPUT"
+            echo "fp_base=$(echo "$cfg" | jq -r '.config.Labels["co.freesolo.flash.kernelcache.fp_base"] // ""')" >> "$GITHUB_OUTPUT"
+            echo "revision=$(echo "$cfg" | jq -r '.config.Labels["org.opencontainers.image.revision"] // ""')" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Pin the checkout to the base's source commit so the warmed flash code matches the base exactly
+      # (the cache is content-keyed by the code that compiled it). Falls back to the event sha if the
+      # base predates the revision label.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: steps.gate.outputs.run == 'true'
+        with:
+          ref: ${{ steps.base.outputs.revision || github.sha }}
+
+      - name: Install uv
+        if: steps.gate.outputs.run == 'true'
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          # pin the installed binary as well as the action implementation.
+          version: "0.12.5"
+          # no cache: the post-run cache-prune calls `uv`, but the "Free disk space" step deletes
+          # /opt/hostedtoolcache (where setup-uv put uv), so the post step fails ("uv not found") and
+          # marks the whole job red even though the bake + push already succeeded.
+          enable-cache: false
+
+      - name: Sync bake dependencies
+        if: steps.gate.outputs.run == 'true'
+        run: uv sync --extra server
+
+      # MODAL_TOKEN_ID + MODAL_TOKEN_SECRET (the warmup GPU sandbox) + HF_TOKEN (upstream model/tokenizer downloads) are
+      # native repo Actions secrets, synced from Infisical (prod:/flash-ci) by the github-ci-flash
+      # Secret Sync. No Infisical CLI/login at job time -- Infisical stays the source of truth and
+      # rotations propagate via the sync. BASE_IMAGE
+      # is digest-pinned so the warm runs inside the EXACT base the per-arch tag will sit on.
+      - name: Warm kernels on a Modal ${{ matrix.sm }} GPU -> build/kernel_cache
+        if: steps.gate.outputs.run == 'true'
+        env:
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          BASE_IMAGE: ${{ steps.base.outputs.ref }}
+          BAKE_DEADLINE_MINUTES: ${{ inputs.deadline_minutes }}
+        run: |
+          uv run python docker/bake_kernel_cache.py \
+            --arch "${{ matrix.arch }}" --sm "${{ matrix.sm }}" \
+            --image "$BASE_IMAGE" \
+            --deadline-min "$BAKE_DEADLINE_MINUTES" \
+            --out build/kernel_cache
+
+      - name: Free disk space
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/.ghcup \
+            /usr/local/lib/android /opt/hostedtoolcache /usr/share/swift \
+            /usr/local/share/boost /usr/local/lib/node_modules \
+            /usr/local/share/powershell /usr/share/miniconda || true
+          sudo apt-get clean || true
+          sudo docker image prune -af || true
+          df -h /
+
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+        if: steps.gate.outputs.run == 'true'
+
+      # thin layer FROM the SAME base the warmup ran inside -> the cache toolchain always matches the
+      # shipped image (rebuilding the full Dockerfile.worker from the checkout could drift from the
+      # published base and bake a cache that silently won't load). GHCR auth from the login step above.
+      - name: Build + push baked per-sm image (thin layer on the warmed base)
+        if: steps.gate.outputs.run == 'true'
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile.kernelcache
+          push: true
+          tags: ghcr.io/freesolo-co/flash-worker:${{ inputs.target_tag_prefix || 'cu128' }}-${{ matrix.sm }}
+          provenance: false
+          build-args: |
+            BASE=${{ steps.base.outputs.ref }}
+            FP_CACHE=${{ steps.base.outputs.fp_cache }}
+            FP_BASE=${{ steps.base.outputs.fp_base }}
+            BASE_REVISION=${{ steps.base.outputs.revision }}