chore(backend): add uv dependency lock by Git-on-my-level · Pull Request #8038 · BasedHardware/omi

Git-on-my-level · 2026-06-19T23:30:56Z

Summary

First PR of the backend Python reproducibility rollout.

pins backend local/CI Python with backend/.python-version (3.11.15)
adds a uv pylock.toml generated from the existing backend runtime + hermetic e2e requirement inputs
adds local helper scripts:
- backend/scripts/sync-python-deps.sh
- backend/scripts/update-python-lock.sh
updates Backend Hermetic E2E CI to install via uv pip sync pylock.toml --system
updates backend agent/setup docs to point developers at the uv workflow

This deliberately leaves production Dockerfiles on the existing pip install -r requirements.txt path; that is the next PR so CI/local behavior can be proven before changing runtime image builds.

Validation

workflow yaml ok
./scripts/update-python-lock.sh
Python 3.11.15 is already installed
Resolved 262 packages in 60ms

uv venv --python 3.11.15 /tmp/omi-backend-uv-pr1-test
uv pip sync pylock.toml --python /tmp/omi-backend-uv-pr1-test/bin/python
uv sync elapsed=0:05.47 user=7.75 sys=3.09

/tmp/omi-backend-uv-pr1-test/bin/python -m pytest tests/unit/test_firestore_cache.py -q --tb=short
9 passed in 0.12s
pytest elapsed=0:01.14 user=1.04 sys=0.07

Follow-up

Next PR should move backend Docker image dependency installation to the checked-in uv lock after this PR's CI/local path is green. Tracked in #8039.

mintlify · 2026-06-19T23:31:07Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
deepeninc	🟡 Building	–	Jun 19, 2026, 11:30 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

mintlify · 2026-06-19T23:31:15Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
omi	🟢 Ready	View Preview	Jun 19, 2026, 11:31 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Git-on-my-level · 2026-06-19T23:31:36Z

Follow-up Docker/runtime-image uv migration is tracked in #8039.

cubic-dev-ai

2 issues found across 7 files

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

Git-on-my-level · 2026-06-19T23:35:30Z

Addressed cubic's review comments:

pinned the new astral-sh/setup-uv action to the immutable v7 commit SHA (37802adc94f370d6bfd71619e3f0bf239e1f3b78)
restored cross-platform setup docs with separate macOS/Linux and Windows PowerShell activation examples

Validation after the patch:

workflow yaml ok
sh -n backend/scripts/sync-python-deps.sh
sh -n backend/scripts/update-python-lock.sh

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 860d105c7a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-19T23:37:32Z

-          python -m pip install --upgrade pip
-          python -m pip install -r requirements.txt
-          python -m pip install -r testing/e2e/requirements.txt
+        run: uv pip sync pylock.toml --system


Keep e2e installs aligned with Docker dependencies

Until the backend Dockerfiles are moved to pylock.toml, this workflow no longer tests the dependency set that is actually deployed: I checked backend/Dockerfile and it still builds from backend/requirements.txt via pip install -r /tmp/requirements.txt. In any PR that changes requirements.txt without the lock, or where an open requirement resolves differently under pip, hermetic e2e can pass here while the production image uses different package versions, so either keep this CI path on the same requirements inputs as Docker for now or switch Docker/enforcement to the lock in the same rollout.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-19T23:37:32Z

-    python --version
-    python -m venv venv
+    # From backend/
+    ./scripts/sync-python-deps.sh


Install uv before running the sync script

For a fresh local setup, this is now the first command that needs uv, but the preceding platform dependency steps still only install Python/Git/FFmpeg/opus. Since backend/scripts/sync-python-deps.sh exits immediately when command -v uv fails, users following these docs hit that error before the venv is created; add uv installation to the system dependency steps or insert an explicit install step before this command.

Useful? React with 👍 / 👎.

Git-on-my-level · 2026-06-19T23:42:27Z

Follow-up Docker/runtime-image uv migration is now tracked as an ANX card: https://anx.scalingforever.com/o/david-zhang/w/omi/boards/stability?card=build-backend-install-docker-deps-from-uv-lock (GitHub issue: #8039).

Git-on-my-level · 2026-06-20T01:07:02Z

Docker smoke test + follow-up recommendation

I tried to build/test the backend Dockerfile from this PR branch.

What passed locally

The exact production base image is private from this environment, so I used public python:3.11-slim as a local stand-in by tagging it as gcr.io/based-hardware-dev/python:3.11-slim-forky and then building the existing Dockerfile:

docker build -f backend/Dockerfile -t omi-backend-uv-pr1:test .

Result: build completed successfully.

Runtime smoke checks inside the built image also passed:

python 3.11.15
runtime imports ok
main import ok

Started the container and verified HTTP responses:

/docs -> 200
/openapi.json -> 200
/ -> 404

/ returning 404 is expected because the app does not define a root route.

What could not be validated here

The actual production base image could not be pulled from this environment:

gcr.io/based-hardware-dev/python:3.11-slim-forky
failed to fetch anonymous token ... 403 Forbidden

So this validates Dockerfile mechanics and runtime smoke behavior against a close public Python 3.11 slim stand-in, but not the exact private GCR base image.

Do we need a GCR-access machine?

For the current PR as written: not strictly before merge, because this PR does not change the Docker install path; Docker still installs from backend/requirements.txt exactly as before.

For the follow-up that moves Docker to the uv lock: yes — that PR should be built on a machine/CI runner with GCR access using the real gcr.io/based-hardware-dev/python:3.11-slim-forky base image, plus a container smoke test.

Follow-up needed

The Codex review comment is valid: CI now installs from pylock.toml, while Docker still installs from requirements.txt. To avoid CI/runtime dependency drift, the safer next step is to migrate the main backend Dockerfile to a runtime-only uv lock in the same rollout or immediately after this PR, then validate that exact image with GCR access.

Suggested next implementation shape:

split lock outputs if needed:
- runtime lock from backend/requirements.txt
- e2e/dev lock including backend/testing/e2e/requirements.txt
main backend/Dockerfile installs from the runtime uv lock
CI enforces lock freshness when requirement inputs change
exact Docker build + smoke runs against the private GCR base image

chore(backend): add uv dependency lock

860d105

Git-on-my-level mentioned this pull request Jun 19, 2026

build(backend): install Docker deps from uv lock #8039

Open

mintlify Bot deployed to staging - docs June 19, 2026 23:31 View deployment

cubic-dev-ai Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread .github/workflows/backend-hermetic-e2e.yml Outdated

Comment thread docs/doc/developer/backend/Backend_Setup.mdx Outdated

fix: address uv setup review comments

e7adfbb

mintlify Bot deployed to staging - docs June 19, 2026 23:36 View deployment

chatgpt-codex-connector Bot reviewed Jun 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(backend): add uv dependency lock#8038

chore(backend): add uv dependency lock#8038
Git-on-my-level wants to merge 2 commits into
mainfrom
chore/python-versioning-audit

Git-on-my-level commented Jun 19, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Jun 19, 2026

Uh oh!

mintlify Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

Git-on-my-level commented Jun 19, 2026

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Git-on-my-level commented Jun 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 19, 2026

Uh oh!

chatgpt-codex-connector Bot Jun 19, 2026

Uh oh!

Git-on-my-level commented Jun 19, 2026

Uh oh!

Git-on-my-level commented Jun 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Git-on-my-level commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Follow-up

Uh oh!

mintlify Bot commented Jun 19, 2026

Uh oh!

mintlify Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Git-on-my-level commented Jun 19, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Git-on-my-level commented Jun 19, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

Git-on-my-level commented Jun 19, 2026

Uh oh!

Git-on-my-level commented Jun 20, 2026

Docker smoke test + follow-up recommendation

What passed locally

What could not be validated here

Do we need a GCR-access machine?

Follow-up needed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Git-on-my-level commented Jun 19, 2026 •

edited

Loading

mintlify Bot commented Jun 19, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading