.env.example

# AI Studio Proxy API Configuration Template
# Copy this file to .env and modify as needed

# =============================================================================
# 1. Server Port Configuration
# =============================================================================

# FastAPI Main Service Port
# The port where the OpenAI-compatible API will listen.
PORT=2048

# Streaming Proxy Service Port
# Set to 0 to disable the streaming proxy service.
STREAM_PORT=3120

# GUI Launcher Default Port Configuration
# These are only used for default suggestions in the launcher.
DEFAULT_FASTAPI_PORT=2048
DEFAULT_CAMOUFOX_PORT=9222

# =============================================================================
# 2. Proxy Configuration
# =============================================================================

# Unified Proxy Configuration (Recommended)
# High priority; configures HTTP_PROXY, HTTPS_PROXY, and internal browser proxy.
UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890

# Legacy Proxy Settings (Only used if UNIFIED_PROXY_CONFIG is not set)
# HTTP_PROXY=http://127.0.0.1:7890
# HTTPS_PROXY=http://127.0.0.1:7890

# Proxy Bypass List (Separated by semicolons)
# NO_PROXY=localhost;127.0.0.1;*.local

# =============================================================================
# 3. Logging & Debugging
# =============================================================================

# Server Log Level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
SERVER_LOG_LEVEL=INFO

# Whether to redirect print output to logs
SERVER_REDIRECT_PRINT=false

# Enable Debug and Trace Logs
DEBUG_LOGS_ENABLED=false
TRACE_LOGS_ENABLED=false

# JSON Structured Logging
JSON_LOGS=false

# Log Rotation Configuration
LOG_FILE_MAX_BYTES=10485760
LOG_FILE_BACKUP_COUNT=5

# =============================================================================
# 4. Authentication Configuration
# =============================================================================

# Auto-save Authentication Information
# Set to true to automatically save auth status (cookies/localStorage) after login.
AUTO_SAVE_AUTH=false

# Auth Save Timeout (seconds)
# Timeout while waiting for user to provide a filename for the saved auth.
AUTH_SAVE_TIMEOUT=30

# Auto Rotate Auth Profile (true/false)
# Automatically switch to a different auth profile when quota is exceeded or issues occur.
AUTO_ROTATE_AUTH_PROFILE=true

# Auto Auth Rotation on Startup (true/false)
# Automatically select an available auth profile when starting.
AUTO_AUTH_ROTATION_ON_STARTUP=false

# Auto Confirm Login
AUTO_CONFIRM_LOGIN=true

# Quota Rotation Thresholds (Graceful Rotation)
# Soft Limit: Triggers "Rotation Pending". Current stream finishes, then rotates.
QUOTA_SOFT_LIMIT=850000
# Hard Limit: Triggers immediate "Kill Signal" to prevent hard bans.
QUOTA_HARD_LIMIT=950000

# -----------------------------------------------------------------------------
# Cookie Refresh Configuration
# -----------------------------------------------------------------------------
# Automatically refresh and persist browser cookies to keep auth profiles fresh.
# This helps prevent cookie expiration issues during long-running sessions.

# Enable automatic cookie refresh (default: true)
COOKIE_REFRESH_ENABLED=true

# Periodic refresh interval in seconds (default: 1800 = 30 minutes)
COOKIE_REFRESH_INTERVAL_SECONDS=1800

# Enable cookie save after successful API requests (default: true)
COOKIE_REFRESH_ON_REQUEST_ENABLED=true

# Number of successful requests between cookie saves (default: 10)
COOKIE_REFRESH_REQUEST_INTERVAL=10

# Enable cookie save on graceful shutdown (default: true)
COOKIE_REFRESH_ON_SHUTDOWN=true

# =============================================================================
# 5. Browser & Model Configuration
# =============================================================================

# Launch Mode (normal, debug, headless, virtual_display, direct_debug_no_browser)
LAUNCH_MODE=normal

# Camoufox WebSocket Endpoint
# For connecting to existing external Camoufox/Chrome instance.
# CAMOUFOX_WS_ENDPOINT=ws://127.0.0.1:9222

# Quick Launch (Direct Launch)
# Skip launcher menu and use .env configuration directly.
DIRECT_LAUNCH=false

# Only collect attachments from the current user's message (true/false)
ONLY_COLLECT_CURRENT_USER_ATTACHMENTS=false

# Camoufox WebSocket Capture Timeout (seconds)
ENDPOINT_CAPTURE_TIMEOUT=45

# =============================================================================
# 6. API Default Parameter Configuration
# =============================================================================

# Default Sampling Parameters
DEFAULT_TEMPERATURE=1.0
DEFAULT_MAX_OUTPUT_TOKENS=65536
DEFAULT_TOP_P=0.95
DEFAULT_STOP_SEQUENCES=["User:"]

# Thinking Model Configuration (e.g., gemini-2.0-flash-thinking)
ENABLE_THINKING_BUDGET=true
DEFAULT_THINKING_BUDGET=8192

# Thinking Budget Level Values (tokens) - Used for "low", "medium", "high" presets
THINKING_BUDGET_LOW=10923
THINKING_BUDGET_MEDIUM=21845
THINKING_BUDGET_HIGH=32768

# Gemini 3 Default Thinking Levels
DEFAULT_THINKING_LEVEL_PRO=high
DEFAULT_THINKING_LEVEL_FLASH=high

# Control if disabling streaming also disables thinking budget (default behavior: false)
DISABLE_THINKING_BUDGET_ON_STREAMING_DISABLE=false

# Feature Toggles (Google Search, URL Context)
ENABLE_GOOGLE_SEARCH=false
ENABLE_URL_CONTEXT=false

# =============================================================================
# Function Calling Configuration (Native vs Emulated)
# =============================================================================
# This configures how OpenAI-compatible tool calls (tools parameter) are handled.
# NOTE: XML-based tools in prompts are NOT affected - they pass through as plain text.

# Function Calling Mode: "auto" | "native" | "emulated"
# - "auto": (RECOMMENDED) Tries native first, auto-fallback to emulated on failure
# - "native": AI Studio UI-driven function calling (best reliability)
# - "emulated": Text-based prompt injection (legacy, backwards compatible)
#
# When to use each:
# - "auto": Best for most users - resilient with automatic fallback
# - "native": When you need maximum reliability and your models support it
# - "emulated": For older setups or if native mode causes issues
FUNCTION_CALLING_MODE=auto

# Enable automatic fallback to emulated mode when native mode fails
# Only applies when FUNCTION_CALLING_MODE=native (auto mode always has fallback)
FUNCTION_CALLING_NATIVE_FALLBACK=true

# Timeout for function calling UI operations (milliseconds)
FUNCTION_CALLING_UI_TIMEOUT=10000

# Native mode retry attempts before fallback
FUNCTION_CALLING_NATIVE_RETRY_COUNT=3

# Clear function definitions between requests (stateless behavior)
# Set to false if you want to reuse tool definitions across requests
FUNCTION_CALLING_CLEAR_BETWEEN_REQUESTS=true

# -----------------------------------------------------------------------------
# Function Calling Debug Logging (Master Switch)
# -----------------------------------------------------------------------------
# When false, ALL function calling logs (console & modular) are disabled.
# Useful for production to minimize noise and disk I/O.
FUNCTION_CALLING_DEBUG=false

# Enable function calling state caching for performance
# Reduces UI operations when same tools are used in subsequent requests
FUNCTION_CALLING_CACHE_ENABLED=true

# Cache TTL in seconds (0 = no expiration within session)
FUNCTION_CALLING_CACHE_TTL=0

# -----------------------------------------------------------------------------
# Function Calling Improvements (FC-001 to FC-004)
# -----------------------------------------------------------------------------
# These settings control advanced function calling compatibility features.
# See docs/architecture/FUNCTION_CALLING_IMPROVEMENTS.md for details.

# FC-001: thoughtSignature Support for Gemini 3
# Add thoughtSignature to functionCall parts for Gemini 3 model compatibility.
# When replaying conversation history with tool calls, Gemini 3 may require
# this field for validation. Safe for older models (ignored if not needed).
FUNCTION_CALLING_THOUGHT_SIGNATURE=true

# FC-004: Type Case Normalization (UPPERCASE types)
# Convert JSON Schema types to UPPERCASE (e.g., "string" -> "STRING").
# The iBUHub/AIStudioToAPI project uses UPPERCASE types.
# WARNING: Set to false by default - requires UI verification before enabling.
# Only enable after confirming AI Studio UI accepts UPPERCASE types.
FUNCTION_CALLING_UPPERCASE_TYPES=false

# -----------------------------------------------------------------------------
# Modular Per-Component Logging (Active only if FUNCTION_CALLING_DEBUG=true)
# -----------------------------------------------------------------------------
# Fine-grained logging with separate log files in logs/fc_debug/<module>.log
# See docs/architecture/FC_DEBUG_LOGGING_DESIGN.md for full documentation.

# Enable individual modules for targeted debugging. Only enabled modules
# will create log files. All default to false to minimize disk I/O.
#
# ORCHESTRATOR: Mode selection, fallback logic, high-level flow
# UI:           Browser UI automation (toggle, dialog, paste)
# CACHE:        Cache hits/misses/invalidation
# WIRE:         Wire format parsing from network responses
# DOM:          DOM-based function call extraction
# SCHEMA:       Tool schema conversion and validation
# RESPONSE:     Response formatting for OpenAI compatibility

FC_DEBUG_ORCHESTRATOR=false
FC_DEBUG_UI=false
FC_DEBUG_CACHE=false
FC_DEBUG_WIRE=false
FC_DEBUG_DOM=false
FC_DEBUG_SCHEMA=false
FC_DEBUG_RESPONSE=false

# -----------------------------------------------------------------------------
# Per-Module Log Levels
# -----------------------------------------------------------------------------
# Available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
# Only affects modules that are enabled above.
# Recommendation: Use DEBUG for troubleshooting, INFO for general monitoring.

FC_DEBUG_LEVEL_ORCHESTRATOR=DEBUG
FC_DEBUG_LEVEL_UI=DEBUG
FC_DEBUG_LEVEL_CACHE=DEBUG
FC_DEBUG_LEVEL_WIRE=DEBUG
FC_DEBUG_LEVEL_DOM=DEBUG
FC_DEBUG_LEVEL_SCHEMA=DEBUG
FC_DEBUG_LEVEL_RESPONSE=DEBUG

# -----------------------------------------------------------------------------
# Log File Rotation
# -----------------------------------------------------------------------------
# Configure rotation to prevent unbounded disk usage.
# Max file size in bytes (default: 5MB = 5242880)
# Backup count determines how many rotated files to keep.

FC_DEBUG_LOG_MAX_BYTES=5242880
FC_DEBUG_LOG_BACKUP_COUNT=3

# -----------------------------------------------------------------------------
# Payload Truncation
# -----------------------------------------------------------------------------
# Large payloads (tool definitions, arguments) can clutter logs.
# Enable truncation to keep logs readable while preserving key info.

# Master switch for truncation
FC_DEBUG_TRUNCATE_ENABLED=true

# Maximum characters for different payload types:
# - TOOL_DEF: Tool/function schema definitions (often 10KB+)
# - ARGS: Function call arguments
# - RESPONSE: Response bodies

FC_DEBUG_TRUNCATE_MAX_TOOL_DEF=500
FC_DEBUG_TRUNCATE_MAX_ARGS=1000
FC_DEBUG_TRUNCATE_MAX_RESPONSE=2000

# -----------------------------------------------------------------------------
# Combined Log (Optional)
# -----------------------------------------------------------------------------
# Additionally write all FC debug logs to a single combined file.
# Useful for seeing cross-module request flow in one place.
# File: logs/fc_debug/fc_combined.log

FC_DEBUG_COMBINED_LOG=false

# =============================================================================
# Quick Start Examples:
# =============================================================================
#
# Example 1: Debug cache issues only
#   FUNCTION_CALLING_DEBUG=true
#   FC_DEBUG_CACHE=true
#
# Example 2: Full FC debugging with combined log
#   FUNCTION_CALLING_DEBUG=true
#   FC_DEBUG_ORCHESTRATOR=true
#   FC_DEBUG_UI=true
#   FC_DEBUG_CACHE=true
#   FC_DEBUG_WIRE=true
#   FC_DEBUG_DOM=true
#   FC_DEBUG_SCHEMA=true
#   FC_DEBUG_RESPONSE=true
#   FC_DEBUG_COMBINED_LOG=true
#
# Example 3: Production monitoring (errors only)
#   FUNCTION_CALLING_DEBUG=true
#   FC_DEBUG_ORCHESTRATOR=true
#   FC_DEBUG_LEVEL_ORCHESTRATOR=ERROR
# =============================================================================


# =============================================================================
# 7. Advanced Timeout Configuration (milliseconds)
# =============================================================================

# Response Completion Total Timeout
# Default: 600000 (10 minutes)
RESPONSE_COMPLETION_TIMEOUT=600000

# Initial Wait Time Before Polling
INITIAL_WAIT_MS_BEFORE_POLLING=500

# Polling Interval
POLLING_INTERVAL=300
POLLING_INTERVAL_STREAM=180

# Silence Timeout (Base threshold for inactivity detection)
SILENCE_TIMEOUT_MS=60000

# Page Action Timeouts
POST_SPINNER_CHECK_DELAY_MS=500
FINAL_STATE_CHECK_TIMEOUT_MS=1500
POST_COMPLETION_BUFFER=700

# UI Generation Wait Configuration
UI_GENERATION_WAIT_TIMEOUT_MS=5000
UI_GENERATION_CHECK_INTERVAL_MS=500
UI_STABILIZATION_BUFFER_MS=500

# Clear Chat Related Timeouts
CLEAR_CHAT_VERIFY_TIMEOUT_MS=4000
CLEAR_CHAT_VERIFY_INTERVAL_MS=4000

# Interaction Timeouts
CLICK_TIMEOUT_MS=3000
CLIPBOARD_READ_TIMEOUT_MS=3000
WAIT_FOR_ELEMENT_TIMEOUT_MS=10000

# Stream Related Configuration
PSEUDO_STREAM_DELAY=0.01

# =============================================================================
# 8. GUI Launcher Configuration
# =============================================================================

# GUI Default Proxy and Port settings
GUI_DEFAULT_PROXY_ADDRESS=http://127.0.0.1:7890
GUI_DEFAULT_STREAM_PORT=3120
GUI_DEFAULT_HELPER_ENDPOINT=

# =============================================================================
# 9. Script Injection Configuration
# =============================================================================

# Whether to enable Tampermonkey script injection (Deprecated)
ENABLE_SCRIPT_INJECTION=false

# Tampermonkey script file path (relative to project root)
USERSCRIPT_PATH=browser_utils/more_models.js

# =============================================================================
# 10. Miscellaneous System Config
# =============================================================================

# Model Metadata
MODEL_NAME=AI-Studio_Proxy_API
CHAT_COMPLETION_ID_PREFIX=chatcmpl-
AI_STUDIO_URL_PATTERN=aistudio.google.com/
EXCLUDED_MODELS_FILENAME=excluded_models.txt

# Internal URL Markers and Fallbacks
DEFAULT_FALLBACK_MODEL_ID=no model list
MODELS_ENDPOINT_URL_CONTAINS=MakerSuiteService/ListModels
USER_INPUT_START_MARKER_SERVER=__USER_INPUT_START__
USER_INPUT_END_MARKER_SERVER=__USER_INPUT_END__

# =============================================================================
# 11. Stream State and Error Suppression
# =============================================================================

# Stream Timeout Log State Configuration
STREAM_MAX_INITIAL_ERRORS=3
STREAM_WARNING_INTERVAL_AFTER_SUPPRESS=60.0
STREAM_SUPPRESS_DURATION_AFTER_INITIAL_BURST=400.0

# =============================================================================
# 12. Frontend Build Configuration
# =============================================================================

# Skip frontend build check (for environments without Node.js/npm)
SKIP_FRONTEND_BUILD=false