.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"

# --- Umans ---
# OpenAI-compatible aggregation provider (api.code.umans.ai).
# Use UMANS_MODELS to map custom upstream names to canonical display names.
#UMANS_API_KEY_1="YOUR_UMANS_API_KEY"
#UMANS_API_BASE="https://api.code.umans.ai"
#UMANS_QUOTA_LIMIT=200
#UMANS_QUOTA_REFRESH_INTERVAL=300
#UMANS_MODELS='{"moonshot/kimi-k2.6": {"id": "umans-kimi-k2.6"}, "z-ai/glm-5.2": {"id": "umans-glm-5.2"}}'

# --- Ollama Cloud ---
# Free/paid inference via ollama.com. Models discovered dynamically from /api/tags.
# Dual-window quota tracking (session ~5hr reset, weekly 7-day reset) requires a
# __Secure-session cookie from your ollama.com browser session.
# Without the cookie, the provider still works but uses 429-based reactive rotation.
#OLLAMA_CLOUD_API_KEY_1="YOUR_OLLAMA_CLOUD_API_KEY"
#OLLAMA_CLOUD_SESSION_COOKIE_1="YOUR_SECURE_SESSION_COOKIE"
#OLLAMA_CLOUD_QUOTA_REFRESH_INTERVAL=300

# ------------------------------------------------------------------------------
# | [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

# --- Session Stickiness (Sequential Mode) ---
# Session tracking is in-memory by default. It uses provider/model/scope-bound
# anchors to keep related chat requests on the same credential where evidence is
# strong enough. Explicit client IDs are NOT trusted by default because many
# coding clients generate random IDs per request.
#
# Wait briefly for a session-bound credential when it is blocked only by
# concurrency. Set to 0 to rotate immediately instead of waiting.
# Format: SESSION_STICKY_WAIT_SECONDS=<seconds>
# Format: SESSION_STICKY_WAIT_SECONDS_<PROVIDER>=<seconds>
#SESSION_STICKY_WAIT_SECONDS=15
#SESSION_STICKY_WAIT_SECONDS_GEMINI_CLI=15
#
# TTL and max entries for the sequential strategy's in-memory session->credential
# sticky cache. These do not enable disk persistence.
#SESSION_STICKY_ENTRY_TTL_SECONDS=3600
#SESSION_STICKY_ENTRY_TTL_SECONDS_GEMINI_CLI=3600
#SESSION_STICKY_MAX_ENTRIES=10000
#SESSION_STICKY_MAX_ENTRIES_GEMINI_CLI=10000
#
# Optional: promote explicit request fields to trusted strong session evidence.
# Leave unset unless your clients send stable conversation IDs.
#TRUSTED_SESSION_ID_FIELDS="conversation_id,thread_id"

# --- 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"

# --- Model Fallback / Spillover ---
# Configure fallback providers for specific models. When a prefixed request
# (e.g., google/gemma-4-31b-it) exhausts all credentials on the primary
# provider due to scaling issues or errors, the proxy will automatically
# try the listed fallback providers in order.
#
# This does NOT affect unprefixed requests (those use MODEL_ALIAS instead).
# Fallback only triggers on transient provider failures (5xx, rate limits,
# connection errors). Request-level errors (400, 401, 403) are never retried.
#
# Format: MODEL_FALLBACK_<MODEL_NAME>=provider1[:model1],provider2[:model2][|retry_mode]
#
# Model name: dashes → underscores, dots → underscores, uppercased
#   gemma-4-31b-it → GEMMA_4_31B_IT
#
# If no :model is specified after a provider, the original model name is used.
#
# Retry mode (appended after |):
#   exhaust      - (Default) Try all credentials on each fallback provider
#                  before moving to the next. Gives each provider a full shot.
#   round_robin  - Try one credential per provider, cycling through.
#
# Examples:
# MODEL_FALLBACK_GEMMA_4_31B_IT="nvidia_nim,ollama_cloud"
# MODEL_FALLBACK_GEMMA_4_31B_IT="nvidia_nim:google/gemma-4-31b-it,ollama_cloud:gemma-4-31b-it|exhaust"
# MODEL_FALLBACK_DEEPSEEK_V3="nvidia_nim,google|round_robin"

# ------------------------------------------------------------------------------
# | [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

# ------------------------------------------------------------------------------
# | [CODEX] OpenAI Codex Provider Configuration                                |
# ------------------------------------------------------------------------------
#
# Codex provider uses OAuth authentication with OpenAI's ChatGPT backend API.
# Credentials are stored in oauth_creds/ directory as codex_oauth_*.json files.
#

# --- Reasoning Effort ---
# Controls how much "thinking" the model does before responding.
# Higher effort = more thorough reasoning but slower responses.
#
# Available levels (model-dependent):
#   - low: Minimal reasoning, fastest responses
#   - medium: Balanced (default)
#   - high: More thorough reasoning
#   - xhigh: Maximum reasoning (gpt-5.2, gpt-5.2-codex, gpt-5.3-codex, gpt-5.1-codex-max only)
#
# Can also be controlled per-request via:
#   1. Model suffix: codex/gpt-5.2:high
#   2. Request param: "reasoning_effort": "high"
#
# CODEX_REASONING_EFFORT=medium

# --- Reasoning Summary ---
# Controls how reasoning is summarized in responses.
# Options: auto, concise, detailed, none
# CODEX_REASONING_SUMMARY=auto

# --- Reasoning Output Format ---
# How reasoning/thinking is presented in responses.
# Options:
#   - think-tags: Wrap in <think>...</think> tags (default, matches other providers)
#   - raw: Include reasoning as-is
#   - none: Don't include reasoning in output
# CODEX_REASONING_COMPAT=think-tags

# --- Identity Override ---
# When true, injects an override that tells the model to prioritize
# user-provided system prompts over the required opencode instructions.
# CODEX_INJECT_IDENTITY_OVERRIDE=true

# --- Instruction Injection ---
# When true, injects the required opencode system instruction.
# Only disable if you know what you're doing (API may reject requests).
# CODEX_INJECT_INSTRUCTION=true

# --- Empty Response Handling ---
# Number of retry attempts when receiving empty responses.
# CODEX_EMPTY_RESPONSE_ATTEMPTS=3

# Delay (seconds) between empty response retries.
# CODEX_EMPTY_RESPONSE_RETRY_DELAY=2

# --- OAuth Configuration ---
# OAuth callback port for Codex interactive authentication.
# Default: 8086
# CODEX_OAUTH_PORT=8086


# --- GitHub Copilot ---
# GitHub Copilot provider uses Device Flow OAuth.
# The GitHub OAuth token (long-lived) is used to derive short-lived
# Copilot API tokens (~30 min expiry, refreshed automatically).
#
# Numbered credential format (recommended for multiple accounts):
#   COPILOT_1_GITHUB_TOKEN=gho_xxxxx  (first GitHub account)
#   COPILOT_2_GITHUB_TOKEN=gho_yyyyy  (second GitHub account)
#
# Legacy single-credential format:
#   COPILOT_GITHUB_TOKEN=gho_xxxxx
#
# Optional: override the default model list
#   COPILOT_MODELS=gpt-4o,claude-sonnet-4,gemini-2.5-pro
#
# To obtain a GitHub OAuth token, run the proxy with --add-credential
# and select the Copilot provider, or use the interactive Device Flow
# by starting the proxy without any COPILOT env vars.

# --- KiloCode ---
# KiloCode is configured as a custom OpenAI-compatible provider.
# API key and base URL follow the standard pattern:
#   KILO_API_BASE=https://api.kilo.ai/api/openrouter/
#   KILO_API_KEY_1="your-kilo-api-key"
#
# Optional: credit balance monitoring via the Kilo web dashboard.
# Obtain this value from the browser cookie __Secure-next-auth.session-token
# after logging in to https://app.kilo.ai/profile
# The token auto-refreshes (~30-day TTL) and the proxy keeps it alive.
# If absent or expired, requests still work — quota simply shows as unknown.
#KILO_SESSION_TOKEN=""
#KILO_QUOTA_REFRESH_INTERVAL=600

# ------------------------------------------------------------------------------
# | [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