refactor(lens)!: rename internal engine code and API by moe-berri · Pull Request #44034 · BerriAI/litellm

moe-berri · 2026-10-01T16:52:18Z

TLDR

Problem this solves:

Lens still uses another product's name internally
Deployment files include unrelated QA screenshots

How it solves it:

Rename Lens code, APIs, worker imports, and database tables
Preserve saved data with a rerunnable schema-only migration
Block unsafe db-push upgrades until the rename is applied
Update split-backend routing and CI test selection
Remove eight deployment screenshots

Intentional product change: Lens APIs move from /engine to /lens; list responses use lenses, and worker claims use lens_id. Existing API clients and workers must upgrade with the proxy

User Flow

Before: Lens API clients use the old product name

Open /ui/lens/ and connect a worker
API clients call /engine to manage investigations

After: Lens uses its own name throughout setup and execution

Open /ui/lens/ and connect the matching worker
API clients call /lens to manage investigations
Existing db-push installations apply the rename SQL before restarting

Validation

Full local make check passes after the review fixes. All 16 Postgres migration/repository checks pass, covering all three db-push entrypoints, each legacy table, fresh setup, restart, and replay of the migration. The combined migration and extras suite passes 90 tests, and all 10 component-allowlist tests pass. The two added search-path cases fail on the previous SQL and pass with the fix, retaining saved run associations through migration replay. A clean environment installing only the extras package receives its database driver automatically and passes both fresh-schema and legacy-schema safety checks. uv lock --check passes. Earlier validation passed all 100 existing Lens unit tests and 26 dashboard tests. All four HTTP billing/privacy cases also pass, including disconnect cancellation. Existing test assertions were preserved while updating names; one new regression verifies saved findings, history, worker credentials, and billing assignments survive the actual migration

The published worker image is pinned by digest in setup and Compose, and was pulled successfully. The standalone Docker image passes non-root/read-only imports and temporary-storage recovery. A real Docker investigation completed against local request logs, screening one selected request and returning a finding. This is a naming/transport check, not a claim of large-scale analysis quality

Screenshots / Proof of Fix

Use a disposable PostgreSQL schema with the legacy Lens tables and a saved run. Put another empty schema first in search_path, then execute the rename SQL and query SELECT id, lens_id FROM "LiteLLM_LensRun"

Before (`ed19330`)

Execute that revision's migration with the empty schema first
Querying the saved run fails: ERROR: column lens_id does not exist

After (`17a97f8`)

Execute the updated migration with the same search path
Querying the saved run returns ('saved-run', 'saved-lens')
Execute the migration again and query: the same saved run association remains intact

The proxy's earlier real-inference validation returned HTTP 200 through /lens/worker/{lens_id}/{job_id}/model, with matching Lens and virtual-key spend, and rejected blocked, exhausted, model-restricted, and deleted keys. A published worker completed a one-request investigation. Those inference checks predate this commit; the latest checks exercise migration and dependency fixes against real PostgreSQL

Caveats

Severe

Coordinate proxy, worker, and API-client upgrades
Stop workers after scans finish; upgrade proxy instances together
Old worker images and /engine clients cannot use renamed APIs
Existing db-push installations must apply the rename SQL first

Low

CI and automated reviews are pending
One initial scan hit local ClickHouse memory limits
Historical migration names remain unchanged to preserve migration checksums

The docs guide was updated in merged BerriAI/litellm-docs#1971. The db-push upgrade instructions are in deploy/lens/README.md

Note

High Risk
Breaking API and database rename requires coordinated proxy, worker, and client upgrades; incorrect migration order or mixed versions can block startups or strand scans, though db-push guards and in-place SQL mitigate data loss.

Overview
Breaking rename: Lens moves off the internal “engine” name end-to-end—HTTP surface /engine → /lens, list payloads use lenses, worker claims use lens_id, and the Python package is litellm/proxy/lens (worker module lens.worker). Proxy routing, backend allowlists, OpenAPI snapshot, and dashboard (lensData, LensView, etc.) follow the same paths and field names.

Data and deploy: Prisma/Postgres objects become LiteLLM_Lens, LiteLLM_LensRun (engine_id → lens_id), and LiteLLM_LensWorker, with migration 20261001100000_rename_lens renaming legacy tables in place. prisma db push now calls raise_if_lens_rename_pending() (proxy + extras) so existing LiteLLM_Engine* data is not dropped; litellm-proxy-extras adds psycopg for that check. Lens worker Docker/Compose images and CI path filters point at the new package; upgrade notes are in deploy/lens/README.md.

Tests and integration suites are retargeted to /lens and the new table names, with added coverage for migration replay and db-push refusal on legacy schemas.

^{Reviewed by Cursor Bugbot for commit 17a97f8. Bugbot is set up for automated code reviews on this repo. Configure here.}

codecov · 2026-10-01T17:04:36Z

Codecov Report

❌ Patch coverage is 91.25000% with 14 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/lens/endpoints.py	86.59%	13 Missing ⚠️
litellm/proxy/lens/worker.py	80.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

moe-berri · 2026-10-01T17:16:59Z

@greptileai

moe-berri · 2026-10-01T17:17:03Z

@veria-ai

moe-berri · 2026-10-01T17:17:06Z

bugbot run

cursor

Stale Bugbot comment from a previous run.

greptile-apps · 2026-10-01T17:21:03Z

Confidence Score: 5/5

[Critical risk] Renames database tables and API routes for the Lens feature.

The PR appears safe to merge based on the changes since the previous review.

Summary

The PR renames Lens’s internal code, API, worker, and database tables, and adds an in-place migration with a guard against unsafe database pushes.

The latest changes adjust the migration’s column lookup, make its database driver a package dependency, and extend migration coverage.

_{Reviews (3) · Last reviewed commit: "fix(lens): resolve migration tables acro..."}

codspeed · 2026-10-01T17:32:00Z

Merging this PR will not alter performance

✅ 31 untouched benchmarks

_{Comparing litellm_lens_remove_deploy_screenshots (17a97f8) with main (d9f7324)¹}

No successful run was found on main (6ca90b9) during the generation of this report, so d9f7324 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

moe-berri · 2026-10-01T17:38:09Z

@greptileai

moe-berri · 2026-10-01T17:38:13Z

@veria-ai

moe-berri · 2026-10-01T17:38:18Z

bugbot run

moe-berri · 2026-10-01T17:42:21Z

@greptileai

cursor

Stale Bugbot comment from a previous run.

…se driver

moe-berri · 2026-10-01T17:50:12Z

@greptileai @veria-ai

moe-berri · 2026-10-01T17:50:16Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 17a97f8. Configure here.}

…ase URL (#44073) The Lens rename check added in #44034 refuses prisma db push when it cannot reach the database. This test pointed DATABASE_URL at a dead port to keep the real CI database out of the run, so it now trips that check before the push timeout it exists to cover. Unsetting DATABASE_URL skips every database probe and keeps the test focused on the timeout hint.

chore(lens): remove deployment screenshots

ba16857

moe-berri mentioned this pull request Oct 1, 2026

docs(lens): align setup and API guide with investigation controls BerriAI/litellm-docs#1971

Merged

refactor(lens)!: rename internal engine package and API

b972bfb

moe-berri had a problem deploying to e2e-changed October 1, 2026 17:13 — with GitHub Actions Error

moe-berri changed the title ~~chore(lens): remove deployment screenshots~~ refactor(lens)!: rename internal engine code and API Oct 1, 2026

fix(lens): pin worker image for renamed API

c06866d

moe-berri had a problem deploying to e2e-changed October 1, 2026 17:15 — with GitHub Actions Error

test(lens): cover fresh and populated rename migrations

2d89ace

moe-berri had a problem deploying to e2e-changed October 1, 2026 17:18 — with GitHub Actions Error

cursor Bot reviewed Oct 1, 2026

View reviewed changes

greptile-apps Bot reviewed Oct 1, 2026

View reviewed changes

Comment thread schema.prisma

Comment thread litellm/proxy/lens/endpoints.py

Comment thread tests/unit/proxy/lens/test_analysis.py

fix(lens): protect db-push upgrades and restore routing and CI

ed19330

moe-berri had a problem deploying to e2e-changed October 1, 2026 17:37 — with GitHub Actions Error

tin-berri approved these changes Oct 1, 2026

View reviewed changes

moe-berri marked this pull request as ready for review October 1, 2026 17:39

moe-berri requested a review from a team October 1, 2026 17:39

cursor Bot reviewed Oct 1, 2026

View reviewed changes

Comment thread litellm-proxy-extras/litellm_proxy_extras/migrations/20261001100000_rename_lens/migration.sql

greptile-apps Bot reviewed Oct 1, 2026

View reviewed changes

Comment thread litellm-proxy-extras/litellm_proxy_extras/utils.py

Comment thread litellm/proxy/lens/endpoints.py

fix(lens): resolve migration tables across schemas and include databa…

17a97f8

…se driver

moe-berri requested a deployment to e2e-changed October 1, 2026 17:50 — with GitHub Actions Waiting

cursor Bot reviewed Oct 1, 2026

View reviewed changes

moe-berri merged commit 259c166 into main Oct 1, 2026
117 of 123 checks passed

moe-berri deleted the litellm_lens_remove_deploy_screenshots branch October 1, 2026 18:02

yuneng-berri mentioned this pull request Oct 1, 2026

test(proxy-extras): run the db push timeout hint test without a database URL #44073

Merged

3 of 5 tasks

timrsmith mentioned this pull request Oct 1, 2026

fix(proxy): make the per-reload credential sync linear in the number of credentials #43929

Open

3 of 5 tasks

mateo-berri mentioned this pull request Oct 1, 2026

feat(interactions): durable cross-pod settlement for background interaction billing #41955

Merged

7 tasks done

Conversation

moe-berri commented Oct 1, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TLDR

User Flow

Validation

Screenshots / Proof of Fix

Before (ed19330)

After (17a97f8)

Caveats

Severe

Low

Uh oh!

codecov Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

cursor 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!

greptile-apps Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codspeed Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

cursor 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!

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

moe-berri commented Oct 1, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch is waiting to be deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

moe-berri commented Oct 1, 2026 •

edited by cursor Bot

Loading

Before (`ed19330`)

After (`17a97f8`)

codecov Bot commented Oct 1, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

greptile-apps Bot commented Oct 1, 2026 •

edited

Loading

codspeed Bot commented Oct 1, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading