.env.example

# =============================================================================
# Red Hat Lightspeed Agent for Google Cloud Configuration
# Copy this file to .env and fill in the values
# =============================================================================

# -----------------------------------------------------------------------------
# Google AI / Gemini Configuration
# -----------------------------------------------------------------------------
# Set to FALSE to use Google AI Studio, TRUE for Vertex AI
GOOGLE_GENAI_USE_VERTEXAI=FALSE

# Google AI Studio API Key (required if GOOGLE_GENAI_USE_VERTEXAI=FALSE)
# Get your API key from: https://aistudio.google.com/apikey
GOOGLE_API_KEY=your_google_api_key_here

# Vertex AI Configuration (required if GOOGLE_GENAI_USE_VERTEXAI=TRUE)
GOOGLE_CLOUD_PROJECT=your_gcp_project_id
GOOGLE_CLOUD_LOCATION=global

# Model to use (default: gemini-2.5-flash)
GEMINI_MODEL=gemini-2.5-flash

# Gemini HTTP retries (google-genai SDK: exponential backoff + jitter for 429/408/5xx)
# See: https://cloud.google.com/vertex-ai/generative-ai/docs/retry-strategy
# GEMINI_HTTP_RETRY_ATTEMPTS=5
# GEMINI_HTTP_RETRY_INITIAL_DELAY=1.0
# GEMINI_HTTP_RETRY_MAX_DELAY=60.0
# GEMINI_HTTP_RETRY_EXP_BASE=2.0
# GEMINI_HTTP_RETRY_JITTER=1.0

# -----------------------------------------------------------------------------
# Red Hat SSO / OAuth 2.0 Configuration
# -----------------------------------------------------------------------------
# Red Hat SSO (sso.redhat.com) OAuth settings
RED_HAT_SSO_ISSUER=https://sso.redhat.com/auth/realms/redhat-external
RED_HAT_SSO_CLIENT_ID=your_client_id
RED_HAT_SSO_CLIENT_SECRET=your_client_secret

# Required scopes for token introspection (comma-separated, default: api.console,api.ocm)
AGENT_REQUIRED_SCOPE=api.console,api.ocm

# Allowed scopes allowlist (comma-separated, default: openid,profile,email,api.console,api.ocm)
# Tokens carrying scopes outside this list are rejected (HTTP 403).
AGENT_ALLOWED_SCOPES=openid,profile,email,api.console,api.ocm

# GMA SSO API credentials (for DCR tenant creation when DCR_ENABLED=true)
# Used to create OAuth tenant clients via the GMA API
GMA_CLIENT_ID=your_gma_client_id
GMA_CLIENT_SECRET=your_gma_client_secret
# GMA_API_BASE_URL=https://sso.redhat.com/auth/realms/redhat-external/apis/beta/acs/v1/

# -----------------------------------------------------------------------------
# Red Hat Lightspeed MCP Server Configuration
# -----------------------------------------------------------------------------
# The MCP server provides tools to access Red Hat Insights APIs.
# It runs as a sidecar container. The agent forwards the caller's JWT token
# to the MCP server, which uses it to authenticate with console.redhat.com
# on behalf of the calling user.
#
# The MCP server can access:
#   - Advisor (recommendations)
#   - Inventory (registered systems)
#   - Vulnerability (CVE data)
#   - Remediations (playbooks)
#   - Patch (system updates)
#   - Image Builder (custom images)
#

# MCP server transport mode:
#   - stdio: Agent spawns MCP server as subprocess (development)
#   - http: Agent connects to MCP server via HTTP (production, recommended)
#   - sse: Agent uses Server-Sent Events for streaming
MCP_TRANSPORT_MODE=http

# MCP server URL (for http/sse modes)
# In Podman deployments, the MCP server runs as a sidecar on localhost:8081
# (port 8081 avoids conflict with A2A Inspector which uses 8080)
MCP_SERVER_URL=http://localhost:8081

# Enable read-only mode for MCP tools (recommended for production)
# When true, write operations (create remediation, etc.) are disabled
MCP_READ_ONLY=true

# -----------------------------------------------------------------------------
# Agent Configuration
# -----------------------------------------------------------------------------
# Agent base URL (where the A2A agent can be reached)
AGENT_PROVIDER_URL=https://your-agent-domain.com
# Agent provider's organization website URL
# Used in AgentCard provider.url and as the expected JWT audience for Google DCR
# AGENT_PROVIDER_ORGANIZATION_URL=https://www.redhat.com

# Agent name and description
AGENT_NAME=lightspeed_agent
AGENT_DESCRIPTION="Red Hat Lightspeed Agent for Google Cloud"

# Server configuration
AGENT_HOST=0.0.0.0
AGENT_PORT=8000
AGENT_PROBE_PORT=8002
# Marketplace handler probe port (health/readiness checks)
HANDLER_PROBE_PORT=8003

# -----------------------------------------------------------------------------
# Database Configuration
# -----------------------------------------------------------------------------
# Database URL for storing client registrations, usage data, etc.
# SQLite for development, PostgreSQL recommended for production
DATABASE_URL=sqlite+aiosqlite:///./lightspeed_agent.db

# For PostgreSQL in production:
# DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/lightspeed_agent

# -----------------------------------------------------------------------------
# Session Configuration
# -----------------------------------------------------------------------------
# Session storage backend: "memory" (default) or "database"
# "memory": Sessions stored in-memory (lost on restart, suitable for dev)
# "database": Sessions persisted to PostgreSQL (requires SESSION_DATABASE_URL)
SESSION_BACKEND=memory

# Session database URL (required when SESSION_BACKEND=database)
# Use a SEPARATE database from DATABASE_URL for security isolation.
# SESSION_DATABASE_URL=postgresql+asyncpg://sessions:password@localhost:5433/agent_sessions

# -----------------------------------------------------------------------------
# Google Cloud Service Control (for usage reporting)
# -----------------------------------------------------------------------------
# Service name registered with Google Cloud Marketplace
SERVICE_CONTROL_SERVICE_NAME=your-service-name.endpoints.your-project.cloud.goog

# Path to service account key file (for local development)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

# -----------------------------------------------------------------------------
# Rate Limiting Configuration (Redis-backed)
# -----------------------------------------------------------------------------
# Redis connection string for distributed rate limiting
RATE_LIMIT_REDIS_URL=redis://localhost:6379/0

# Redis operation timeout in milliseconds
RATE_LIMIT_REDIS_TIMEOUT_MS=200

# Redis key prefix used for throttling keys
RATE_LIMIT_KEY_PREFIX=lightspeed:ratelimit

# Global rate limits
RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_REQUESTS_PER_HOUR=1000

# -----------------------------------------------------------------------------
# Usage Reporting Configuration
# -----------------------------------------------------------------------------
# How often to report usage to Google Cloud (in seconds)
USAGE_REPORT_INTERVAL_SECONDS=3600

# -----------------------------------------------------------------------------
# Logging Configuration
# -----------------------------------------------------------------------------
LOG_LEVEL=INFO
LOG_FORMAT=json

# Agent execution logging detail level:
#   basic    - Logs tool names, token counts, and lifecycle events
#   detailed - Also logs tool arguments and truncated results (may contain user data)
AGENT_LOGGING_DETAIL=basic

# Maximum character length for MCP tool results sent to the LLM.
# Oversized results are replaced with a message advising the user to
# narrow down their query or use pagination. Set to 0 to disable.
TOOL_RESULT_MAX_CHARS=51200

# Audit logging (automatic when LOG_FORMAT=json):
# JSON log records automatically include user_id, org_id, order_id, and
# request_id fields for every log entry.  These fields are populated from
# the authenticated user's JWT token and provide a full audit trail of
# data lineage — proving that information shown to the user was authorized
# and retrieved from a verified Red Hat source.
#
# Each agent lifecycle event is tagged with an event_type:
#   request_authenticated, agent_run_started, agent_run_completed,
#   llm_call_started, llm_call_completed, tool_call_started,
#   tool_call_completed, mcp_jwt_forwarded
#
# Tool calls include a data_source field identifying the Red Hat Insights
# MCP tool that retrieved the data.  No additional configuration is required.

# -----------------------------------------------------------------------------
# Development/Debug Settings
# -----------------------------------------------------------------------------
# Enable debug mode (DO NOT use in production)
DEBUG=false

# Skip JWT validation (for local development only)
SKIP_JWT_VALIDATION=false

# CORS allowed origins (comma-separated).
# In debug mode, defaults to "*" (all origins, no credentials).
# In production, CORS is disabled when empty (server-to-server only).
# Example: CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
CORS_ALLOWED_ORIGINS=

# -----------------------------------------------------------------------------
# OpenTelemetry Configuration
# -----------------------------------------------------------------------------
# Enable OpenTelemetry distributed tracing
OTEL_ENABLED=false

# Service name for traces
OTEL_SERVICE_NAME=lightspeed_agent

# Exporter type: otlp, otlp-http, jaeger, zipkin, console
OTEL_EXPORTER_TYPE=otlp

# OTLP exporter endpoints
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_HTTP_ENDPOINT=http://localhost:4318

# Sampling strategy: always_on, always_off, traceidratio,
# parentbased_always_on, parentbased_always_off, parentbased_traceidratio
OTEL_TRACES_SAMPLER=always_on

# Sampler argument (e.g., 0.1 for 10% sampling with traceidratio)
OTEL_TRACES_SAMPLER_ARG=1.0