env.example

# Application Settings
APP_NAME=Anthropic-Bedrock API Proxy
APP_VERSION=1.0.0
ENVIRONMENT=development
DEBUG=True
LOG_LEVEL=INFO

# Server Settings
HOST=0.0.0.0
PORT=8000
WORKERS=1
RELOAD=False

# API Settings
API_PREFIX=/v1
DOCS_URL=/docs
OPENAPI_URL=/openapi.json
CORS_ORIGINS=*

# AWS Settings
AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=
# AWS_SECRET_ACCESS_KEY=
# AWS_SESSION_TOKEN=
# BEDROCK_ENDPOINT_URL=
# DYNAMODB_ENDPOINT_URL=

# DynamoDB Tables
DYNAMODB_API_KEYS_TABLE=anthropic-proxy-api-keys
DYNAMODB_USAGE_TABLE=anthropic-proxy-usage
DYNAMODB_MODEL_MAPPING_TABLE=anthropic-proxy-model-mapping
DYNAMODB_MODEL_PRICING_TABLE=anthropic-proxy-model-pricing
DYNAMODB_USAGE_STATS_TABLE=anthropic-proxy-usage-stats
# Usage records TTL in days (0 to disable TTL)
USAGE_TTL_DAYS=30

# Authentication
API_KEY_HEADER=x-api-key
REQUIRE_API_KEY=True
MASTER_API_KEY=sk-your-master-key
# In-process API key validation cache TTL in seconds (0 to disable).
# Key changes (including per-key access_policy) take up to this long to apply
# under healthy reads. Already admitted requests/streams are not force-stopped.
# Not prompt-cache TTL. Master keys and REQUIRE_API_KEY=False bypass policies.
# Configure per-key restrictions in Admin > API Keys, not with a global allowlist.
# Deploy enforcement to ALL workers before enabling; old-binary rollback is unsafe.
API_KEY_CACHE_TTL_SECONDS=60

# Source-IP policy trust. Always launch Uvicorn with --no-proxy-headers.
# Direct/local: leave both defaults; X-Forwarded-For is ignored.
CLIENT_IP_TRUSTED_PROXY_CIDRS=
CLIENT_IP_TRUSTED_PROXY_HOPS=0
# ALB: exact ALB subnet CIDRs, hops=1; task ingress from ALB SG only.
# CloudFront+ALB: same CIDRs, hops=2 ONLY with secret-protected ALB listener.
# Example (replace with actual ingress subnet CIDRs):
# CLIENT_IP_TRUSTED_PROXY_CIDRS=10.0.0.0/24,10.0.1.0/24
# CLIENT_IP_TRUSTED_PROXY_HOPS=1
# Both hops must append XFF; ALB XFF client-port preservation must be off.
# No wildcard trust, mixed-length ingress, or pre-rewritten ASGI client allowed.
# Trusted ingress may set one X-Forwarded-Proto=http/https for redirect scheme.
# See README "Source-IP policy deployment checklist" before enabling policies.

# In-process model mapping cache TTL in seconds (0 to disable).
# Mapping changes made in the admin portal take up to this long to apply.
MODEL_MAPPING_CACHE_TTL_SECONDS=300

# ===========================================
# Default Model Mapping Sync (remote JSON)
# Default Anthropic -> Bedrock model ID mappings are pulled from
# github.com/xiehust/bedrock-api-proxy-model-mappings (model_mappings.json) at
# startup and every MODEL_MAPPING_SYNC_INTERVAL_SECONDS, by both the proxy and
# the admin portal. The model-mappings/ git submodule is the offline snapshot
# used until the first fetch succeeds (or when sync is disabled). A failed or
# invalid fetch never clears the active mapping. Manual refresh: admin portal
# "Refresh defaults", POST /api/model-mapping/sync, scripts/sync_model_mappings.py.
# ===========================================
# MODEL_MAPPING_SYNC_ENABLED=True
# MODEL_MAPPING_SYNC_URL=https://raw.githubusercontent.com/xiehust/bedrock-api-proxy-model-mappings/main/model_mappings.json
# MODEL_MAPPING_SYNC_INTERVAL_SECONDS=3600
# MODEL_MAPPING_SYNC_TIMEOUT_SECONDS=15
# Per-deployment additions layered on top of the remote defaults (JSON object):
# DEFAULT_MODEL_MAPPING={"my-alias":"global.anthropic.claude-sonnet-4-5-20250929-v1:0"}

# Rate Limiting
RATE_LIMIT_ENABLED=True
RATE_LIMIT_REQUESTS=1000
RATE_LIMIT_WINDOW=60

# Bedrock Prompt Caching
PROMPT_CACHING_ENABLED=True
# Default Cache TTL: '5m' or '1h' (optional, unset = Anthropic default 5m)
# DEFAULT_CACHE_TTL=1h

# Timeouts
BEDROCK_TIMEOUT=1800
DYNAMODB_TIMEOUT=10
STREAMING_TIMEOUT=300

# Bedrock Concurrency
BEDROCK_THREAD_POOL_SIZE=15
BEDROCK_SEMAPHORE_SIZE=15

# Feature Flags
ENABLE_TOOL_USE=True
ENABLE_EXTENDED_THINKING=True
ENABLE_DOCUMENT_SUPPORT=True
ENABLE_PROGRAMMATIC_TOOL_CALLING=False
ENABLE_WEB_SEARCH=False
ENABLE_WEB_FETCH=True

# Bedrock Service Tier: 'default', 'flex', 'priority', 'reserved'
DEFAULT_SERVICE_TIER=default

# ===========================================
# Programmatic Tool Calling (PTC) - requires Docker
# ===========================================
# PTC_SANDBOX_IMAGE=python:3.11-slim
# PTC_SESSION_TIMEOUT=270
# PTC_EXECUTION_TIMEOUT=60
# PTC_MEMORY_LIMIT=256m
# PTC_NETWORK_DISABLED=true

# ===========================================
# Web Search Configuration
# ===========================================
# WEB_SEARCH_PROVIDER=tavily          # 'tavily', 'brave', or 'agentcore'
# WEB_SEARCH_API_KEY=tvly-your-key    # Required for Tavily or Brave; not used for agentcore
# AGENTCORE_GATEWAY_URL=https://your-gateway.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
# AGENTCORE_GATEWAY_REGION=us-east-1  # AgentCore Web Search is currently us-east-1 only
# WEB_SEARCH_MAX_RESULTS=5
# WEB_SEARCH_DEFAULT_MAX_USES=10

# ===========================================
# Web Fetch Configuration (enabled by default, no API key needed)
# ===========================================
# WEB_FETCH_DEFAULT_MAX_USES=20
# WEB_FETCH_DEFAULT_MAX_CONTENT_TOKENS=100000

# ===========================================
# Image URL Sources (for ImageContent with source.type="url")
# Proxy fetches the URL and forwards bytes to Bedrock.
# ===========================================
# IMAGE_URL_FETCH_TIMEOUT_S=30.0
# IMAGE_URL_FETCH_MAX_BYTES=20971520   # 20 MB; Bedrock enforces stricter per-model limits

# ===========================================
# OpenAI-Compatible APIs - for non-Claude models
# Scoped IDs (global., us., eu., apac., us-gov., etc.) use Runtime Responses
# by default, independently of ENABLE_OPENAI_COMPAT. Model aliases are resolved first.
# Uses BEDROCK_API_KEY / OPENAI_API_KEY, or AWS credentials via SigV4 if no key.
# Set ENABLE_BEDROCK_RESPONSES=False to restore the previous routing.
# ENABLE_BEDROCK_RESPONSES=True
# OPENAI_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1
#
# For unscoped IDs, ENABLE_OPENAI_COMPAT selects OpenAI Chat Completions
# via bedrock-mantle endpoint instead of Bedrock Converse API.
# Claude models still use InvokeModel API.
# MANTLE_ENDPOINT_URL takes precedence over OPENAI_BASE_URL when both are set.
# ===========================================
# ENABLE_OPENAI_COMPAT=False
# BEDROCK_API_KEY=your-bedrock-api-key
# MANTLE_ENDPOINT_URL=https://bedrock-mantle.us-east-1.api.aws/v1
# OPENAI_COMPAT_THINKING_HIGH_THRESHOLD=10000
# OPENAI_COMPAT_THINKING_MEDIUM_THRESHOLD=4000

# ===========================================
# OpenAI Passthrough — mount /openai/v1/* endpoints accepting native OpenAI
# Chat Completions and Responses API requests. Scoped non-Claude model IDs
# default to Runtime Responses; unscoped IDs retain their configured endpoint.
# Independent of ENABLE_OPENAI_COMPAT (the two flags can be enabled together).
# Reuses BEDROCK_API_KEY and MANTLE_ENDPOINT_URL.
# ===========================================
# ENABLE_OPENAI_PASSTHROUGH=False

# Proxy-managed Responses API web_search state for previous_response_id.
# CDK creates and injects DYNAMODB_RESPONSE_CONTEXT_TABLE automatically.
# Context is gzip-compressed, sharded into DynamoDB items, API-key scoped,
# and expired by TTL. The same table/TTL holds metadata-only Responses attribution.
# Model-restricted keys cannot use unknown/pre-upgrade/expired/unverifiable IDs
# (404; owned forbidden models: 403); start a new request after expiry, even if
# upstream retains the response. Default 3600s = 1 hour. Unrestricted/master
# response-ID behavior is unchanged; not universal unrestricted tenant isolation.
# DYNAMODB_RESPONSE_CONTEXT_TABLE=anthropic-proxy-response-context
# RESPONSE_CONTEXT_TTL_SECONDS=3600
# RESPONSE_CONTEXT_CHUNK_SIZE_BYTES=262144
# RESPONSE_CONTEXT_MAX_BYTES=1048576
# RESPONSE_CONTEXT_MAX_CHUNKS=8

# ===========================================
# Model Pricing Sync (LiteLLM)
# Pulls model pricing from the LiteLLM price table into the pricing table.
# Periodic sync runs as a background task in the admin portal; manual sync via
# POST /api/pricing/sync or scripts/sync_model_pricing.py (--dry-run to preview).
# Rows created by the sync (pricing_source="litellm") are kept up to date;
# manually created or portal-edited rows are never overwritten unless
# PRICING_SYNC_OVERWRITE_MANUAL=True. Rows are never deleted.
# ===========================================
# PRICING_SYNC_ENABLED=False
# PRICING_SYNC_URL=https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
# PRICING_SYNC_INTERVAL_HOURS=24
# PRICING_SYNC_PROVIDERS=bedrock,bedrock_converse,bedrock_mantle
# PRICING_SYNC_CREATE_MISSING=True
# PRICING_SYNC_OVERWRITE_MANUAL=False

# ===========================================
# Admin portal model speed test
# The admin portal's Model Mapping page can run a streaming request per
# Bedrock model ID through the proxy (POST {PROXY_BASE_URL}/v1/messages with
# thinking disabled) and record TTFT / output tokens per second. Results are
# stored in DYNAMODB_SPEED_TESTS_TABLE (TTL 90 days). The admin backend
# auto-provisions an API key named "admin-speedtest" for these requests.
# Behind CloudFront set PROXY_BASE_URL to the https:// distribution URL.
# ===========================================
# PROXY_BASE_URL=http://localhost:8000
# DYNAMODB_SPEED_TESTS_TABLE=anthropic-proxy-speed-tests
# SPEED_TEST_MAX_TOKENS=600
# SPEED_TEST_TIMEOUT_SECONDS=90

# ===========================================
# Admin portal authentication
# The admin API (/api/*) requires a Cognito JWT. If COGNITO_USER_POOL_ID /
# COGNITO_CLIENT_ID are unset the portal fails closed (503). For LOCAL
# development only, set ADMIN_PORTAL_DEV_AUTH_BYPASS=true to allow
# unauthenticated access; never set it on a network-reachable deployment.
# `python admin_portal/backend/main.py` binds 127.0.0.1 unless
# ADMIN_PORTAL_HOST is set.
# ===========================================
# COGNITO_USER_POOL_ID=
# COGNITO_CLIENT_ID=
# ADMIN_PORTAL_DEV_AUTH_BYPASS=false
# ADMIN_PORTAL_HOST=127.0.0.1

# ===========================================
# OpenTelemetry Tracing
# ===========================================
# ENABLE_TRACING=false
# OTEL_EXPORTER_OTLP_ENDPOINT=https://us.cloud.langfuse.com/api/public/otel
# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
# OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic <base64(publicKey:secretKey)>
# OTEL_SERVICE_NAME=anthropic-bedrock-proxy
# OTEL_TRACE_CONTENT=false
# OTEL_TRACE_SAMPLING_RATIO=1.0

# Monitoring
ENABLE_METRICS=True
# SENTRY_DSN=