build: migrate packaging, CI, and Docker from Poetry to uv (#25007 )

* build: migrate packaging metadata to uv

* ci: move automation and local tooling to uv

* docker: migrate image builds and runtime setup to uv

* docs: update install and deployment guidance for uv

* chore: align auxiliary scripts and tests with uv

* test: harden test_litellm isolation

* fix: keep release and health check images self-contained

* build: pin uv tooling and health check deps

* test: isolate bedrock image request formatting from suite state

* test: cover sandbox executor requirements flow

* ci: fix circleci no-op command steps

* ci: fix circleci publish workflow parsing

* fix: stabilize remaining uv migration CI checks

* ci: increase matrix test timeout headroom

* fix: restore published docker and license coverage

* fix: restore proxy runtime build parity

* fix: restore proxy extras parity and venv migrations

* ci: persist uv path across circleci steps

* fix: keep psycopg binary in default test env

* docker: preserve prisma cache across stages

* test: run local proxy checks through uv python

* build: restore runtime deps moved into ci

* build: refresh uv lock after upstream merge

* fix: restore module import in test_check_migration after merge

The conflict resolution imported only the function but the test body
references check_migration as a module throughout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: revert dependency promotions, remove nodejs-wheel-binaries, fix Docker layer caching

- Move google-generativeai, Pillow, tenacity back to ci group (they are
  lazily imported and bloat the base SDK install needlessly)
- Remove nodejs-wheel-binaries from extra_proxy and proxy-dev (redundant
  in Docker where system Node.js is already installed via apk)
- Remove all nodejs-wheel node replacement and venv npm patching blocks
  from Dockerfiles since the wheel is no longer installed
- Add --no-default-groups to CodSpeed benchmark workflow so the benchmark
  environment matches the old minimal pip install footprint
- Apply standard uv two-phase Docker pattern: copy metadata first, install
  deps (cached layer), then copy source and install project
- Replace CircleCI enterprise no-op with proper uv sync command

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: regenerate uv.lock after removing nodejs-wheel-binaries

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): use cache/restore instead of cache to prevent cache poisoning

The old workflow used actions/cache/restore (read-only). The uv migration
changed it to actions/cache (read-write), which zizmor flags as a cache
poisoning risk. Restore the safer read-only variant.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): disable setup-uv built-in cache to silence cache-poisoning alert

The setup-uv action enables caching by default, which zizmor flags as a
cache poisoning risk. Disable it since we already use a read-only
cache/restore step.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): disable setup-uv cache in publish workflow

Silences zizmor cache-poisoning alert. Publishing workflow runs
infrequently on protected branches so caching adds no real benefit.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(test): remove duplicate verbose_logger mock in test_check_migration

The logger was patched twice — first via mocker.patch() then via
mocker.patch.object(autospec=True). The second call fails because
autospec cannot inspect an already-mocked attribute. Remove the
redundant first patch.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): free disk space before Docker build in test-server-root-path

The Dockerfile.non_root build ran out of disk on the CI runner. Remove
Android SDK, .NET, Boost, and GHC toolchains (~12GB) to free space.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-09 11:46:23 -07:00

4.2 KiB

Raw Blame History

GEMINI.md

This file provides guidance to Gemini when working with code in this repository.

Development Commands

Installation

make install-dev - Install core development dependencies
make install-proxy-dev - Install proxy development dependencies with full feature set
make install-test-deps - Install all test dependencies

Testing

make test - Run all tests
make test-unit - Run unit tests (tests/test_litellm) with 4 parallel workers
make test-integration - Run integration tests (excludes unit tests)
pytest tests/ - Direct pytest execution

Code Quality

make lint - Run all linting (Ruff, MyPy, Black, circular imports, import safety)
make format - Apply Black code formatting
make lint-ruff - Run Ruff linting only
make lint-mypy - Run MyPy type checking only

Single Test Files

uv run pytest tests/path/to/test_file.py -v - Run specific test file
uv run pytest tests/path/to/test_file.py::test_function -v - Run specific test

Running Scripts

uv run python script.py - Run Python scripts (use for non-test files)

GitHub Issue & PR Templates

When contributing to the project, use the appropriate templates:

Bug Reports (.github/ISSUE_TEMPLATE/bug_report.yml):

Describe what happened vs. what you expected
Include relevant log output
Specify your LiteLLM version

Feature Requests (.github/ISSUE_TEMPLATE/feature_request.yml):

Describe the feature clearly
Explain the motivation and use case

Pull Requests (.github/pull_request_template.md):

Add at least 1 test in tests/litellm/
Ensure make test-unit passes

Architecture Overview

LiteLLM is a unified interface for 100+ LLM providers with two main components:

Core Library (`litellm/`)

Main entry point: litellm/main.py - Contains core completion() function
Provider implementations: litellm/llms/ - Each provider has its own subdirectory
Router system: litellm/router.py + litellm/router_utils/ - Load balancing and fallback logic
Type definitions: litellm/types/ - Pydantic models and type hints
Integrations: litellm/integrations/ - Third-party observability, caching, logging
Caching: litellm/caching/ - Multiple cache backends (Redis, in-memory, S3, etc.)

Proxy Server (`litellm/proxy/`)

Main server: proxy_server.py - FastAPI application
Authentication: auth/ - API key management, JWT, OAuth2
Database: db/ - Prisma ORM with PostgreSQL/SQLite support
Management endpoints: management_endpoints/ - Admin APIs for keys, teams, models
Pass-through endpoints: pass_through_endpoints/ - Provider-specific API forwarding
Guardrails: guardrails/ - Safety and content filtering hooks
UI Dashboard: Served from _experimental/out/ (Next.js build)

Key Patterns

Provider Implementation

Providers inherit from base classes in litellm/llms/base.py
Each provider has transformation functions for input/output formatting
Support both sync and async operations
Handle streaming responses and function calling

Error Handling

Provider-specific exceptions mapped to OpenAI-compatible errors
Fallback logic handled by Router system
Comprehensive logging through litellm/_logging.py

Configuration

YAML config files for proxy server (see proxy/example_config_yaml/)
Environment variables for API keys and settings
Database schema managed via Prisma (proxy/schema.prisma)

Development Notes

Code Style

Uses Black formatter, Ruff linter, MyPy type checker
Pydantic v2 for data validation
Async/await patterns throughout
Type hints required for all public APIs

Testing Strategy

Unit tests in tests/test_litellm/
Integration tests for each provider in tests/llm_translation/
Proxy tests in tests/proxy_unit_tests/
Load tests in tests/load_tests/

Database Migrations

Prisma handles schema migrations
Migration files auto-generated with prisma migrate dev
Always test migrations against both PostgreSQL and SQLite

Enterprise Features

Enterprise-specific code in enterprise/ directory
Optional features enabled via environment variables
Separate licensing and authentication for enterprise features

4.2 KiB Raw Blame History