mirror of https://github.com/BerriAI/litellm.git synced 2025-12-06 11:33:26 +08:00

Files

Cesar Garcia 5b0729034c docs: cleanup README and improve agent guides (#17003 )

* docs: cleanup README and improve AI agent guides

- Remove obsolete version warnings (openai>=1.0.0, pydantic>=2.0.0)
- Add note about Responses API in README
- Add GitHub templates section to CLAUDE.md, GEMINI.md, and AGENTS.md
- Remove temporary test file test_pydantic_fields.py

* update files

* update Gemini file

2025-11-23 21:53:53 -08:00

4.2 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) 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

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

Running Scripts

poetry 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