.env.example

# ==============================================================================
# ||        LLM API Key Proxy - Environment Variable Configuration        ||
# ==============================================================================
#
# This file provides an example configuration for the proxy server.
# Copy this file to a new file named '.env' in the same directory
# and replace the placeholder values with your actual credentials and settings.
#

# ------------------------------------------------------------------------------
# | [REQUIRED] Proxy Server Settings                                           |
# ------------------------------------------------------------------------------

# A secret key used to authenticate requests to THIS proxy server.
# This can be any string. Your client application must send this key in the
# 'Authorization' header as a Bearer token (e.g., "Authorization: Bearer YOUR_PROXY_API_KEY").
#PROXY_API_KEY="YOUR_PROXY_API_KEY"


# ------------------------------------------------------------------------------
# | [API KEYS] Provider API Keys                                               |
# ------------------------------------------------------------------------------
#
# The proxy automatically discovers API keys from environment variables.
# To add multiple keys for a single provider, increment the number at the end
# of the variable name (e.g., GEMINI_API_KEY_1, GEMINI_API_KEY_2).
#
# The provider name is derived from the part of the variable name before "_API_KEY".
# For example, 'GEMINI_API_KEY_1' configures the 'gemini' provider.
#

# --- Google Gemini ---
#GEMINI_API_KEY_1="YOUR_GEMINI_API_KEY_1"
#GEMINI_API_KEY_2="YOUR_GEMINI_API_KEY_2"

# --- OpenAI / Azure OpenAI ---
# For Azure, ensure your key has access to the desired models.
#OPENAI_API_KEY_1="YOUR_OPENAI_OR_AZURE_API_KEY"

# --- Anthropic (Claude) ---
#ANTHROPIC_API_KEY_1="YOUR_ANTHROPIC_API_KEY"

# --- OpenRouter ---
#OPENROUTER_API_KEY_1="YOUR_OPENROUTER_API_KEY"

# --- Mistral AI ---
#MISTRAL_API_KEY_1="YOUR_MISTRAL_API_KEY"

# --- NVIDIA NIM ---
#NVIDIA_NIM_API_KEY_1="YOUR_NVIDIA_API_KEY"

# --- Chutes ---
#CHUTES_API_KEY_1="YOUR_CHUTES_API_KEY"

# ------------------------------------------------------------------------------
# | [OAUTH] Provider OAuth 2.0 Credentials                                     |
# ------------------------------------------------------------------------------
#
# The proxy now uses a "local-first" approach for OAuth credentials.
# All OAuth credentials are managed within the 'oauth_creds/' directory.
#
# HOW IT WORKS:
# 1. On the first run, if you provide a path to an existing credential file
#    (e.g., from ~/.gemini/), the proxy will COPY it into the local
#    'oauth_creds/' directory with a standardized name (e.g., 'gemini_cli_oauth_1.json').
# 2. On all subsequent runs, the proxy will ONLY use the files found inside
#    'oauth_creds/'. It will no longer scan system-wide directories.
# 3. To add a new account, either use the '--add-credential' tool or manually
#    place a new, valid credential file in the 'oauth_creds/' directory.
#
# Use the variables below for the ONE-TIME setup to import existing credentials.
# After the first successful run, you can clear these paths.
#

# --- Google Gemini (gcloud CLI) ---
# Path to your gcloud ADC file (e.g., ~/.config/gcloud/application_default_credentials.json)
# or a credential file from the official 'gemini' CLI (e.g., ~/.gemini/credentials.json).
#GEMINI_CLI_OAUTH_1=""

# ------------------------------------------------------------------------------
# | [ADVANCED] Provider-Specific Settings                                      |
# ------------------------------------------------------------------------------

# --- Gemini CLI Project ID ---
# Required if you are using the Gemini CLI OAuth provider and the proxy
# cannot automatically determine your Google Cloud Project ID.
#GEMINI_CLI_PROJECT_ID=""

# --- Model Ignore Lists ---
# Specify a comma-separated list of model names to exclude from a provider's
# available models. This is useful for filtering out models you don't want to use.
#
# Format: IGNORE_MODELS_<PROVIDER_NAME>="model-1,model-2,model-3"
#
# Example:
# IGNORE_MODELS_GEMINI="gemini-1.0-pro-vision-latest,gemini-1.0-pro-latest"
# IGNORE_MODELS_OPENAI="gpt-4-turbo,gpt-3.5-turbo-instruct"
#IGNORE_MODELS_GEMINI=""
#IGNORE_MODELS_OPENAI=""

# --- Model Whitelists (Overrides Blacklists) ---
# Specify a comma-separated list of model names to ALWAYS include from a
# provider's list. This acts as an override for the ignore list.
#
# HOW IT WORKS:
# 1. A model on a whitelist will ALWAYS be available, even if it's also on an
#    ignore list (or if the ignore list is set to "*").
# 2. For any models NOT on the whitelist, the standard ignore list logic applies.
#
# This allows for two main use cases:
# - "Pure Whitelist" Mode: Set IGNORE_MODELS_<PROVIDER>="*" and then specify
#   only the models you want in WHITELIST_MODELS_<PROVIDER>.
# - "Exemption" Mode: Blacklist a broad range of models (e.g., "*-preview*")
#   and then use the whitelist to exempt specific preview models you want to test.
#
# Format: WHITELIST_MODELS_<PROVIDER_NAME>="model-1,model-2"
#
# Example of a pure whitelist for Gemini:
# IGNORE_MODELS_GEMINI="*"
# WHITELIST_MODELS_GEMINI="gemini-1.5-pro-latest,gemini-1.5-flash-latest"
#WHITELIST_MODELS_GEMINI=""
#WHITELIST_MODELS_OPENAI=""

# --- Concurrent Requests Per Key ---
# MAX is the hard safety ceiling. A key at max will not be selected.
# Default max is unlimited unless a provider overrides it.
# OPTIMAL is the soft rotation target. Balanced mode prefers keys below optimal
# before stacking; sequential mode defaults to unlimited/sticky.
# Set 0 or any negative value for unlimited concurrency.
#
# Format: MAX_CONCURRENT_REQUESTS_PER_KEY_<PROVIDER_NAME>=<number>
# Format: OPTIMAL_CONCURRENT_REQUESTS_PER_KEY_<PROVIDER_NAME>=<number>
# Format: MAX_CONCURRENT_REQUESTS_PER_KEY_<PROVIDER_NAME>_BALANCED=<number>
# Format: OPTIMAL_CONCURRENT_REQUESTS_PER_KEY_<PROVIDER_NAME>_BALANCED=<number>
# Format: MAX_CONCURRENT_REQUESTS_PER_KEY_<PROVIDER_NAME>_SEQUENTIAL=<number>
# Format: OPTIMAL_CONCURRENT_REQUESTS_PER_KEY_<PROVIDER_NAME>_SEQUENTIAL=<number>
#
# The provider-only forms apply regardless of rotation mode. Mode-specific forms
# override only that mode. Most deployments only need the provider-only forms.
#
# Example:
# MAX_CONCURRENT_REQUESTS_PER_KEY_OPENAI=-1  # No hard cap
# OPTIMAL_CONCURRENT_REQUESTS_PER_KEY_OPENAI=1  # Spread before stacking in balanced mode
# MAX_CONCURRENT_REQUESTS_PER_KEY_GEMINI_CLI=1  # Hard cap constrained providers
# OPTIMAL_CONCURRENT_REQUESTS_PER_KEY_GEMINI_CLI_BALANCED=1
# MAX_CONCURRENT_REQUESTS_PER_KEY_GEMINI_CLI_SEQUENTIAL=1
#
#MAX_CONCURRENT_REQUESTS_PER_KEY_OPENAI=-1
#OPTIMAL_CONCURRENT_REQUESTS_PER_KEY_OPENAI=1

# --- Credential Rotation Mode ---
# Controls how credentials are rotated when multiple are available for a provider.
# This affects how the proxy selects the next credential to use for requests.
#
# Available modes:
#   balanced   - (Default) Rotate credentials evenly across requests to distribute load.
#                Best for API keys with per-minute rate limits.
#   sequential - Use one credential until it's exhausted (429 error), then switch to next.
#                Best for credentials with daily/weekly quotas (e.g., free tier accounts).
#                When a credential hits quota, it's put on cooldown based on the reset time
#                parsed from the provider's error response.
#
# Format: ROTATION_MODE_<PROVIDER_NAME>=<mode>
#
# Provider Defaults:
#   - Default: sequential unless a provider overrides it
#
# Example:
# ROTATION_MODE_GEMINI=sequential    # Use Gemini keys until quota exhausted
# ROTATION_MODE_OPENAI=balanced      # Opt in to distributing load across OpenAI keys
#
# ROTATION_MODE_GEMINI=balanced

# --- Priority-Based Concurrency Multipliers ---
# Credentials can be assigned to priority tiers (1=highest, 2, 3, etc.).
# Each tier can have a concurrency multiplier that increases the effective
# hard concurrent request limit for credentials in that tier.
#
# How it works:
#   effective_max_concurrent = MAX_CONCURRENT_REQUESTS_PER_KEY * tier_multiplier
#
# This allows paid/premium credentials to handle more concurrent requests than
# free tier credentials, regardless of rotation mode.
#
# Provider Defaults (built into provider classes):
#   Gemini CLI:
#     Priority 1: 2x
#     Priority 2: 1x
#     Others: 1x (all modes)
#
# Format: CONCURRENCY_MULTIPLIER_<PROVIDER>_PRIORITY_<N>=<multiplier>
#
# Mode-specific overrides (optional):
# Format: CONCURRENCY_MULTIPLIER_<PROVIDER>_PRIORITY_<N>_<MODE>=<multiplier>
#
# Examples:
# CONCURRENCY_MULTIPLIER_GEMINI_CLI_PRIORITY_1=5   # Override P1 to 5x
# CONCURRENCY_MULTIPLIER_GEMINI_CLI_PRIORITY_2_BALANCED=1  # P2 = 1x in balanced mode only

# --- Model Quota Groups ---
# Models that share quota/cooldown timing. When one model in a group hits
# quota exhausted (429), all models in the group receive the same cooldown timestamp.
# They also reset (archive stats) together when the quota period expires.
#
# This is useful for providers where multiple model variants share the same
# underlying quota.
#
# Format: QUOTA_GROUPS_<PROVIDER>_<GROUP>="model1,model2,model3"
#
# Examples:
# QUOTA_GROUPS_GEMINI_CLI_PRO="gemini-2.5-pro,gemini-3-pro-preview"

# ------------------------------------------------------------------------------
# | [ADVANCED] Fair Cycle Rotation                                              |
# ------------------------------------------------------------------------------
#
# Ensures each credential exhausts at least once before any can be reused.
# Prevents one credential from being repeatedly used while others sit idle.
#
# Provider Defaults (see src/rotator_library/config/defaults.py):
#   - Enabled: sequential rotation mode only (balanced mode = disabled)
#   - Tracking Mode: model_group (track per quota group)
#   - Cross-Tier: false (each priority tier cycles independently)
#   - Cycle Duration: 86400 seconds (24 hours)
#   - Exhaustion Threshold: 300 seconds (5 minutes)
#
# Format: FAIR_CYCLE_{PROVIDER}=true/false
# Example:
# FAIR_CYCLE_GEMINI_CLI=false

# Tracking mode: "model_group" (per quota group) or "credential" (global per key)
# FAIR_CYCLE_TRACKING_MODE_GEMINI_CLI=model_group

# Cross-tier: true = ALL credentials must exhaust regardless of tier
# FAIR_CYCLE_CROSS_TIER_GEMINI_CLI=false

# Cycle duration in seconds
# FAIR_CYCLE_DURATION_GEMINI_CLI=86400

# Exhaustion threshold - cooldown must exceed this to count as "exhausted"
# EXHAUSTION_COOLDOWN_THRESHOLD_GEMINI_CLI=300
# EXHAUSTION_COOLDOWN_THRESHOLD=300  # Global fallback for all providers

# ------------------------------------------------------------------------------
# | [ADVANCED] Custom Caps                                                      |
# ------------------------------------------------------------------------------
#
# Set custom usage limits per tier, per model/group that are MORE restrictive
# than actual API limits. When the cap is reached, credential goes on cooldown
# BEFORE hitting the actual API limit.
#
# Cap values: absolute number (100) or percentage ("80%")
# Cooldown modes: quota_reset | offset:<seconds> | fixed:<seconds>
#
# Format: CUSTOM_CAP_{PROVIDER}_T{TIER}_{MODEL_OR_GROUP}=<value>
# Format: CUSTOM_CAP_COOLDOWN_{PROVIDER}_T{TIER}_{MODEL_OR_GROUP}=<mode>:<value>
#
# Name transformations for env vars:
#   - Dashes (-) -> Underscores (_)
#   - Dots (.) -> Underscores (_)
#   - All UPPERCASE
#   Example: claude-opus-4.5 -> CLAUDE_OPUS_4_5
#
# Tier syntax:
#   - Single tier: T2 (tier 2)
#   - Multi-tier: T2_3 (tiers 2 and 3 share config)
#   - Default: TDEFAULT (fallback for unlisted tiers)
#
# Examples:
# CUSTOM_CAP_GEMINI_CLI_T2_PRO=100
# CUSTOM_CAP_COOLDOWN_GEMINI_CLI_T2_PRO=quota_reset

# ------------------------------------------------------------------------------
# | [ADVANCED] Proxy Configuration                                             |
# ------------------------------------------------------------------------------

# --- OAuth Refresh Interval ---
# How often, in seconds, the background refresher should check and refresh
# expired OAuth tokens.
# Default: 600 (10 minutes)
# OAUTH_REFRESH_INTERVAL=600

# --- Skip OAuth Initialization ---
# Set to "true" to prevent the proxy from performing the interactive OAuth
# setup/validation flow on startup. This is highly recommended for non-interactive
# environments like Docker containers or automated scripts.
# Ensure your credentials in 'oauth_creds/' are valid before enabling this.
#SKIP_OAUTH_INIT_CHECK=false

# --- Global Request Timeout ---
# Maximum time (in seconds) a request can wait for an available credential.
# If all credentials are on cooldown and none will become available within
# this timeout, the request fails fast with a clear error message.
# Increase this value if you have limited credentials and want to wait
# longer for capacity (e.g., when credentials hit rate limits).
# Default: 30 seconds
# GLOBAL_TIMEOUT=30

# --- Transient Retry Pacing ---
# Short delay before retrying transient 5xx/connection errors or rotating to
# another credential. Jitter is added to avoid all credentials retrying at once.
# Defaults: 1.0 second base delay, up to 0.5 seconds jitter
# TRANSIENT_RETRY_DELAY=1.0
# TRANSIENT_RETRY_JITTER=0.5

# Allow retry/rotation after a stream error only when the last emitted stream
# chunk was clearly reasoning/thinking-only. Keep disabled for coding agents or
# any consumer where replaying streamed output could duplicate or diverge.
# Default: false
# STREAM_RETRY_ON_REASONING_ONLY=false

# ------------------------------------------------------------------------------
# | [ADVANCED] HTTP Timeout Configuration                                       |
# ------------------------------------------------------------------------------
#
# Controls timeouts for HTTP requests to provider APIs.
# All values are in seconds.
#

# Connection establishment timeout (default: 30)
# TIMEOUT_CONNECT=30

# Request body send timeout (default: 30)
# TIMEOUT_WRITE=30

# Connection pool acquisition timeout (default: 60)
# TIMEOUT_POOL=60

# Read timeout between streaming chunks (default: 300 = 5 minutes)
# If no data arrives for this duration, the connection is considered stalled.
# TIMEOUT_READ_STREAMING=300

# Read timeout for non-streaming responses (default: 600 = 10 minutes)
# Some LLM responses take significant time to generate.
# TIMEOUT_READ_NON_STREAMING=600

# ------------------------------------------------------------------------------
# | [ADVANCED] Gemini CLI Provider Configuration                                |
# ------------------------------------------------------------------------------
#
# Configuration for the Gemini CLI (Google Code Assist) provider.
#

# OAuth callback port for interactive re-authentication.
# Default: 8085
# GEMINI_CLI_OAUTH_PORT=8085

# ------------------------------------------------------------------------------
# | [ADVANCED] Debugging / Logging                                              |
# ------------------------------------------------------------------------------

# --- LiteLLM Pydantic Warning Suppression ---
# LiteLLM produces harmless Pydantic serialization warnings during streaming
# due to a known issue with response types (Message, StreamingChoices) having
# mismatched field counts. These warnings don't affect functionality.
# See: https://github.com/BerriAI/litellm/issues/11759
#
# NOTE: This is a workaround. Remove once litellm patches the issue above.
#
# Set to "0" to show these warnings (useful for debugging).
# Default: "1" (suppress warnings)
# SUPPRESS_LITELLM_SERIALIZATION_WARNINGS=1