# ============================================================================
# Model Configuration
# ============================================================================
# Flock supports all litellm-compatible models, including OpenAI and Azure OpenAI.
# Documentation: https://docs.litellm.ai/docs/providers
# Common models:

# AZURE OPENAI - API key authentication for "azure/{model_name}"
# LiteLLM reads AZURE_API_KEY / AZURE_API_BASE / AZURE_API_VERSION for Azure requests.
; AZURE_API_KEY=xxx
; AZURE_API_BASE=https://your-resource.openai.azure.com/
; AZURE_API_VERSION="2024-12-01-preview"
; DEFAULT_MODEL="azure/gpt-4.1"

# AZURE OPENAI - Entra ID / DefaultAzureCredential authentication
# Leave AZURE_API_KEY unset, keep DEFAULT_MODEL / AZURE_API_BASE / AZURE_API_VERSION,
# and create a token provider in code:
#   from flock.engines.auth.azure import get_default_azure_token_provider
#   DSPyEngine(lm_kwargs={"azure_ad_token_provider": get_default_azure_token_provider()})
# Install: uv sync --extra azure
# Optional for user-assigned managed identity:
; AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
# Optional for service-principal auth:
; AZURE_TENANT_ID=11111111-1111-1111-1111-111111111111
; AZURE_CLIENT_SECRET=your-app-secret

# OPENAI - "openai/{model_name}"

; OPENAI_API_KEY=xxx
; OPENAI_API_BASE=https://api.openai.com/v1/
; DEFAULT_MODEL="openai/gpt-5"

# OPENROUTER - "openrouter/{model_name}"

; OPENROUTER_API_KEY=
; OPENROUTER_API_BASE=
; DEFAULT_MODEL="openrouter/polaris-alpha"

# ============================================================================
# OpenTelemetry Tracing Configuration
# ============================================================================

# Enable auto-tracing for all agents and operations
# Set to "true" to enable OpenTelemetry distributed tracing
# Traces are stored in DuckDB for fast analytical queries
FLOCK_AUTO_TRACE=true

# Store traces in DuckDB database (recommended for production)
# Creates .flock/traces.duckdb with full input/output capture
# Set to "true" to enable DuckDB storage
FLOCK_TRACE_FILE=true

# 🆕 Unified Workflow Tracing (v0.5.0+)
# Automatically wrap operations in workflow traces for better observability
# When disabled (default), use explicit `async with flock.traced_run("name")`
# Set to "true" to enable automatic workflow trace detection
# FLOCK_AUTO_WORKFLOW_TRACE=true

# Filter: Trace only specific services (whitelist)
# Format: JSON array of service names (case-insensitive)
# If not set or empty, all services are traced
# Recommended: Trace core services, avoid streaming token overhead
# Example: FLOCK_TRACE_SERVICES=["flock", "agent", "dspyengine", "outpututilitycomponent"]
FLOCK_TRACE_SERVICES=["flock", "agent", "dspyengine", "outpututilitycomponent"]

# Filter: Ignore specific operations (blacklist)
# Format: JSON array of operation names in "Service.method" format
# Use this to exclude noisy or low-value operations from traces
# Example: FLOCK_TRACE_IGNORE=["DashboardEventCollector.set_websocket_manager"]
FLOCK_TRACE_IGNORE=["DashboardEventCollector.set_websocket_manager"]

# Trace Time-To-Live (TTL): Auto-delete old traces
# Deletes traces older than specified days on application startup
# Keeps database size manageable and removes stale debugging data
# Set to empty or comment out to keep traces forever
# Example: FLOCK_TRACE_TTL_DAYS=30
FLOCK_TRACE_TTL_DAYS=30

# ============================================================================
# Unified Tracing Usage (Code-based approach - RECOMMENDED)
# ============================================================================
#
# Instead of using FLOCK_AUTO_WORKFLOW_TRACE, use explicit traced_run():
#
#   async with flock.traced_run("workflow_name"):
#       await flock.publish(data)
#       await flock.run_until_idle()
#
# Benefits:
#   ✅ Single trace for entire workflow (all operations share trace_id)
#   ✅ Proper parent-child span hierarchy
#   ✅ Custom workflow names for better organization
#   ✅ Add custom attributes: span.set_attribute("key", "value")
#   ✅ Nested workflow support
#
# Clearing traces for fresh debug sessions:
#   result = Flock.clear_traces()  # Deletes all spans, runs VACUUM
#
# See docs/UNIFIED_TRACING.md for complete guide
# ============================================================================

OPENAI_API_KEY=xxx
