freesolo-flash-dev 1.4.9__tar.gz → 1.4.11__tar.gz

freesolo_flash_dev-1.4.11/.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.11/.github/workflows/deploy-modal-dev.yml

@@ -0,0 +1,353 @@
+name: Deploy development serving Modal app
+
+on:
+  push:
+    branches:
+      - dev
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Deploy development serving Modal app
+    if: github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    # same bound as the production deploy: its own readiness polls plus the remote image build fit
+    # well inside this, and a wedged job releases the runner instead of holding it for 6 hours.
+    timeout-minutes: 30
+    # github can replace a pending run even though a running deploy is preserved. compare against the
+    # sha reported by the deployed app so the replacement repeats every change not actually deployed.
+    concurrency:
+      group: deploy-modal-dev-serving
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    defaults:
+      run:
+        # every step runs from the repo root: modal_app.py imports `flash.serving.src...`, which only
+        # resolves with the repo root on sys.path. it derives its own paths from __file__, so cwd is
+        # free. (in freesolo the app WAS the root of its own tree and used cwd-relative imports.)
+        working-directory: .
+    env:
+      MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+      MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+      HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      FLASH_ARTIFACT_BLOB_ACCOUNT_URL: https://freesoloenvs.blob.core.windows.net
+      FLASH_ARTIFACT_BLOB_CONTAINER: artifacts-dev
+      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID_DEV }}
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID_DEV }}
+      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET_DEV }}
+      FREESOLO_INTERNAL_KEY: ${{ secrets.FREESOLO_INTERNAL_KEY }}
+      SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY_DEV }}
+      SUPABASE_PROJECT_REF: ${{ secrets.SUPABASE_PROJECT_REF }}
+      SUPABASE_PROJECT_REF_DEV: ${{ secrets.SUPABASE_PROJECT_REF_DEV }}
+      PLATFORM_BACKEND_URL: https://api-dev.freesolo.co
+      SERVING_DEPLOYMENT_MODE: development
+      SERVING_CUSTOM_DOMAIN: serve-dev.freesolo.co
+      FREESOLO_DEPLOYMENT_SHA: ${{ github.sha }}
+      FREESOLO_DEPLOYMENT_ID: ${{ github.run_id }}-${{ github.run_attempt }}
+      EXPECTED_MODAL_URL: https://freesolo-dev--freesolo-lora-serving.us-east.modal.run
+      EXPECTED_SERVING_URL: https://serve-dev.freesolo.co
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Decide whether to deploy development serving
+        id: gate
+        working-directory: .
+        env:
+          EVENT: ${{ github.event_name }}
+          CURRENT_SHA: ${{ github.sha }}
+          DEPLOYED_HEALTH_URL: https://serve-dev.freesolo.co/healthz
+        run: |
+          set -euo pipefail
+          deploy=false
+          if [ "$EVENT" = "workflow_dispatch" ]; then
+            deploy=true
+          elif ! last_deployed_sha="$(python3 - <<'PY'
+          import json
+          import os
+          import re
+          import urllib.request
+
+
+          request = urllib.request.Request(
+              os.environ["DEPLOYED_HEALTH_URL"],
+              headers={"Accept": "application/json"},
+          )
+          with urllib.request.urlopen(request, timeout=15) as response:
+              payload = json.load(response)
+          revision = payload.get("deployment_sha") if isinstance(payload, dict) else None
+          if not isinstance(revision, str) or re.fullmatch(r"[0-9a-fA-F]{40}", revision) is None:
+              raise ValueError("deployed app returned no valid source revision")
+          print(revision.lower())
+          PY
+          )"; then
+            # a missing deployment or any health, network, or parsing failure must deploy safely.
+            deploy=true
+          elif ! git merge-base --is-ancestor "$last_deployed_sha" "$CURRENT_SHA" 2>/dev/null; then
+            # a missing or rewritten deployed revision cannot safely bound the undeployed changes.
+            deploy=true
+          elif ! changed="$(git diff --name-only "$last_deployed_sha" "$CURRENT_SHA" 2>/dev/null)"; then
+            deploy=true
+          # the build-time vllm repair lives outside flash/, so name its exact image input path.
+          elif grep -qE '^(flash/|docker/patch_vllm_moe_lora\.py$|pyproject\.toml$|uv\.lock$|\.github/workflows/deploy-modal-dev\.yml$)' <<<"$changed"; then
+            deploy=true
+          fi
+          echo "deploy=$deploy" >> "$GITHUB_OUTPUT"
+          echo "Deploy development serving: $deploy"
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        if: steps.gate.outputs.deploy == 'true'
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        if: steps.gate.outputs.deploy == 'true'
+        with:
+          # pin the installed binary as well as the action implementation.
+          version: "0.12.5"
+
+      - name: Install Modal client
+        if: steps.gate.outputs.deploy == 'true'
+        working-directory: .
+        run: |
+          # deploy-time deps only; the app image is built remotely by Modal. flash is deliberately
+          # not installed - modal's CLI puts the working directory on sys.path before importing the
+          # app file, so running from the repo root is what resolves `from flash.serving.src...`.
+          # pinned to the exact client pyproject declares; see deploy-modal.yml for why an
+          # unbounded range is unsafe for the deploy path.
+          # exact pins keep the deploy client bootstrap reproducible across runner image changes.
+          uv pip install --system "modal==1.6.2" "python-dotenv==1.2.3"
+
+      - name: Verify development deployment inputs
+        if: steps.gate.outputs.deploy == 'true'
+        working-directory: .
+        run: |
+          set -euo pipefail
+          missing=""
+          for name in MODAL_TOKEN_ID MODAL_TOKEN_SECRET HF_TOKEN AZURE_TENANT_ID AZURE_CLIENT_ID AZURE_CLIENT_SECRET FREESOLO_INTERNAL_KEY SUPABASE_SERVICE_ROLE_KEY SUPABASE_PROJECT_REF SUPABASE_PROJECT_REF_DEV; do
+            if [ -z "${!name}" ]; then
+              missing="$missing $name"
+            fi
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::Refusing to deploy development serving: missing required secret(s):${missing}."
+            exit 1
+          fi
+          if [ "$SUPABASE_PROJECT_REF" = "$SUPABASE_PROJECT_REF_DEV" ]; then
+            echo "::error::Refusing to deploy development serving: production and development Supabase refs are equal."
+            exit 1
+          fi
+          if [[ "$SUPABASE_SERVICE_ROLE_KEY" != sb_secret_* ]]; then
+            echo "::error::SUPABASE_SERVICE_ROLE_KEY must use the sb_secret_ format."
+            exit 1
+          fi
+          printf 'SUPABASE_URL=https://%s.supabase.co\n' "$SUPABASE_PROJECT_REF_DEV" >> "$GITHUB_ENV"
+
+      - name: Ensure development Modal environment
+        if: steps.gate.outputs.deploy == 'true'
+        working-directory: .
+        run: |
+          set -euo pipefail
+          environments_file="$(mktemp)"
+          trap 'rm -f "$environments_file"' EXIT
+          modal environment list --json > "$environments_file"
+          environment_status="$(python3 - "$environments_file" <<'PY'
+          import json
+          import sys
+
+
+          with open(sys.argv[1], encoding="utf-8") as source:
+              environments = json.load(source)
+          if not isinstance(environments, list):
+              raise SystemExit("Modal environment list returned an invalid payload")
+          dev = next(
+              (
+                  item
+                  for item in environments
+                  if isinstance(item, dict) and item.get("name") == "dev"
+              ),
+              None,
+          )
+          if dev is None:
+              print("missing")
+          else:
+              print("ready" if dev.get("web_suffix") == "dev" else "wrong-suffix")
+          PY
+          )"
+          # create and update need workspace manage access, which the deploy token lacks. skip both in
+          # steady state so a ready environment does not fail every deploy.
+          case "$environment_status" in
+            ready)
+              ;;
+            wrong-suffix)
+              modal environment update dev --set-web-suffix dev
+              ;;
+            missing)
+              modal environment create dev
+              modal environment update dev --set-web-suffix dev
+              ;;
+            *)
+              echo "::error::Could not determine the state of the development Modal environment."
+              exit 1
+              ;;
+          esac
+
+      - name: Verify development adapter schema readiness
+        if: steps.gate.outputs.deploy == 'true'
+        working-directory: .
+        run: |
+          set -euo pipefail
+          # probe the columns the runtime actually reads, not `id` -- which is not even among them.
+          # selecting only `id` proved the TABLE exists while a schema still missing, say,
+          # `deployment_generation` passed this gate and then failed on every read after deploy.
+          # this is the same check the production workflow applies; dev kept the weaker one, so a
+          # pending serving migration could deploy a development router that cannot hydrate its
+          # registry and only fails later at readiness.
+          # import the constants module, not persistence.py: this job installs only modal and
+          # python-dotenv, while persistence.py imports httpx at module scope, so importing it
+          # would raise ModuleNotFoundError and the guard below would block every dev deploy.
+          if ! columns="$(python -c 'from flash.serving.src.store.persisted_columns import PERSISTED_COLUMNS; print(PERSISTED_COLUMNS)')" || [ -z "$columns" ]; then
+            # failing closed matters here: an empty list would degrade the query back to a bare
+            # existence check and this gate would pass while proving nothing.
+            echo "::error::Could not read PERSISTED_COLUMNS; refusing to deploy against an unverified schema."
+            exit 1
+          fi
+          endpoint="${SUPABASE_URL%/}/rest/v1/hosted_lora_adapters?select=${columns}&limit=1"
+          headers=(
+            --header "apikey: $SUPABASE_SERVICE_ROLE_KEY"
+            --header "Accept-Profile: flash"
+          )
+          status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
+            --connect-timeout 5 \
+            --max-time 15 \
+            "${headers[@]}" \
+            "$endpoint")"
+          if [ "$status" != "200" ]; then
+            echo "::error::Development Supabase flash.hosted_lora_adapters is not queryable (HTTP ${status})."
+            exit 1
+          fi
+          echo "Development Supabase flash.hosted_lora_adapters is queryable."
+
+      - name: Deploy development serving
+        if: steps.gate.outputs.deploy == 'true'
+        run: modal deploy --env dev flash/serving/app/modal_app.py
+
+      - name: Verify development serving URL
+        if: steps.gate.outputs.deploy == 'true'
+        working-directory: .
+        run: |
+          set -euo pipefail
+          resolved_url="$(python3 - <<'PY'
+          import modal
+
+
+          print(
+              modal.Function.from_name(
+                  "freesolo-lora-serving",
+                  "router",
+                  environment_name="dev",
+              ).get_web_url()
+          )
+          PY
+          )"
+          if [ "$resolved_url" != "$EXPECTED_MODAL_URL" ]; then
+            echo "::error::Development serving resolved to an unexpected generated Modal URL."
+            exit 1
+          fi
+          if [[ "$resolved_url" != *"-dev--"* ]]; then
+            echo "::error::Development serving URL does not carry the development Modal suffix."
+            exit 1
+          fi
+          echo "Development serving URL is isolated in the dev Modal environment."
+
+      - name: Wait for development serving readiness
+        if: steps.gate.outputs.deploy == 'true'
+        working-directory: .
+        run: |
+          set -euo pipefail
+          endpoint="${EXPECTED_SERVING_URL}/healthz"
+          expected_deployment_id="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          response_file="$(mktemp)"
+          trap 'rm -f "$response_file"' EXIT
+          deadline=$((SECONDS + 300))
+
+          while true; do
+            remaining=$((deadline - SECONDS))
+            if (( remaining <= 0 )); then
+              echo "::error::Development serving custom domain did not become DNS-, TLS-, and health-ready within 300 seconds."
+              exit 1
+            fi
+
+            request_timeout=10
+            if (( remaining < request_timeout )); then
+              request_timeout=$remaining
+            fi
+
+            response_status=""
+            if response_status="$(curl --silent --show-error --output "$response_file" --write-out '%{http_code}' \
+              --connect-timeout 5 \
+              --max-time "$request_timeout" \
+              "$endpoint")"; then
+              curl_exit=0
+            else
+              curl_exit=$?
+            fi
+
+            status="000"
+            if (( curl_exit == 0 )); then
+              status="$response_status"
+            fi
+
+            if [[ "$status" = "200" ]]; then
+              if python3 - "$response_file" "$GITHUB_SHA" "$expected_deployment_id" <<'PY'
+          import json
+          import sys
+
+
+          def reject_constant(_value: str) -> None:
+              raise ValueError
+
+
+          try:
+              with open(sys.argv[1], encoding="utf-8") as response:
+                  payload = json.load(response, parse_constant=reject_constant)
+          except (OSError, UnicodeDecodeError, ValueError):
+              sys.exit(1)
+
+          ready = (
+              isinstance(payload, dict)
+              and payload.get("ok") is True
+              and payload.get("deployment_sha") == sys.argv[2]
+              and payload.get("deployment_id") == sys.argv[3]
+          )
+          sys.exit(0 if ready else 1)
+          PY
+              then
+                echo "Development serving router is ready for deployment ${GITHUB_SHA} (${expected_deployment_id})."
+                break
+              fi
+              echo "Development serving health check returned malformed, unhealthy, or stale deployment JSON; retrying."
+            elif [[ "$status" = "000" ]]; then
+              echo "Development serving health check had a transport error; retrying."
+            else
+              echo "Development serving health check returned HTTP ${status}; retrying."
+            fi
+
+            remaining=$((deadline - SECONDS))
+            if (( remaining <= 0 )); then
+              continue
+            fi
+            sleep_seconds=10
+            if (( remaining < sleep_seconds )); then
+              sleep_seconds=$remaining
+            fi
+            sleep "$sleep_seconds"
+          done
+
+      - name: Nothing to deploy
+        if: steps.gate.outputs.deploy != 'true'
+        working-directory: .
+        run: echo "No development serving changes detected."