.env.example

## =============================================================================
## ROBOSYSTEMS ENVIRONMENT CONFIGURATION
## =============================================================================
##
## Configuration organized by management location:
##
##   LOCAL/DOCKER    → Development-only settings (not used in prod)
##   SECRETS         → AWS Secrets Manager in prod (credentials, API keys)
##   FEATURES        → SSM Parameter Store /features/ (boolean flags)
##   TUNING          → SSM Parameter Store /tuning/ (runtime tunables)
##   SERVICES        → Service endpoints and configuration
##
## Override Priority: Environment Variable > SSM Parameter Store > Default
##
## SETUP: cp .env.example .env
##
## =============================================================================


## =============================================================================
## LOCAL / DOCKER DEVELOPMENT
## =============================================================================
## These settings are for local development only.
## In production, infrastructure is managed by CloudFormation/ECS.

## Environment Identity
ENVIRONMENT=dev
LOG_LEVEL=INFO
# DEBUG=false
# HOST=0.0.0.0
# PORT=8000

## Docker Image Configuration
## Keep these to run the published images as released. Comment a pair out to
## build that image locally instead; a locally built backend also runs the
## checkout's source, so an edit applies on `just restart`. Images cache after
## first pull — `just upgrade` fetches newer ones.
ROBOSYSTEMS_IMAGE=robofinsystems/robosystems:latest
ROBOSYSTEMS_PULL_POLICY=if_not_present

ROBOSYSTEMS_APP_IMAGE=robofinsystems/robosystems-app:latest
ROBOSYSTEMS_APP_PULL_POLICY=if_not_present

ROBOLEDGER_APP_IMAGE=robofinsystems/roboledger-app:latest
ROBOLEDGER_APP_PULL_POLICY=if_not_present

ROBOINVESTOR_APP_IMAGE=robofinsystems/roboinvestor-app:latest
ROBOINVESTOR_APP_PULL_POLICY=if_not_present

## Local Service URLs
ROBOSYSTEMS_API_URL=http://localhost:8000
ROBOSYSTEMS_URL=http://localhost:3000
ROBOLEDGER_URL=http://localhost:3001
ROBOINVESTOR_URL=http://localhost:3002
# Which app hosts the interactive auth surface ("login home")
# LOGIN_HOME_APP=robosystems

## OpenTelemetry (local collector - primarily used in prod/staging)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
# OTEL_SERVICE_NAME=robosystems-service
# OTEL_RESOURCE_ATTRIBUTES=
# OTEL_CONSOLE_EXPORT=false


## =============================================================================
## SECRETS (AWS Secrets Manager in prod)
## =============================================================================
## In production, these are stored in AWS Secrets Manager.
## For local development, set placeholder or real values here.
##
## Secrets Manager paths:
##   robosystems/{env}          → Main application secrets
##   robosystems/{env}/postgres → Database credentials
##   robosystems/{env}/valkey   → Cache credentials
##
## See: bin/setup/aws.sh for the full secret structure

## Encryption Keys
CONNECTION_CREDENTIALS_KEY=your-random-32-byte-connection-key-here
JWT_SECRET_KEY=your-random-32-byte-jwt-secret-key-here
ADMIN_API_KEY=dev-admin-key-for-testing-only

## Database Credentials
POSTGRES_PASSWORD=postgres
DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@pg:5432/robosystems
EXTENSIONS_DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@pg:5432/extensions
# Echo all SQL to logs (noisy — handy for local query debugging)
# DATABASE_ECHO=false

## Dagster Database Credentials
DAGSTER_HOST=dagster-webserver
DAGSTER_PORT=8002
DAGSTER_HOME=/app/dagster_home
DAGSTER_POSTGRES_HOST=pg
DAGSTER_POSTGRES_PORT=5432
DAGSTER_POSTGRES_USER=postgres
DAGSTER_POSTGRES_DB=dagster
DAGSTER_POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

## Cache Credentials
VALKEY_AUTH_TOKEN=valkey
VALKEY_URL=redis://:${VALKEY_AUTH_TOKEN}@valkey:6379

## OpenSearch
OPENSEARCH_URL=http://robosystems-opensearch:9200
# OPENSEARCH_INDEX=documents

## JWT Configuration (deployment-specific, in Secrets Manager for prod)
## Note: In prod, JWT_ISSUER/JWT_AUDIENCE are set based on API_ACCESS_MODE
# JWT_ISSUER=api.robosystems.ai
# JWT_AUDIENCE=robosystems.ai,roboledger.ai,roboinvestor.ai

## Email Configuration (deployment-specific identity)
# EMAIL_FROM_ADDRESS=noreply@robosystems.ai
# EMAIL_FROM_NAME=RoboSystems

## QuickBooks/Intuit
INTUIT_CLIENT_ID=your-intuit-client-id-here
INTUIT_CLIENT_SECRET=your-intuit-client-secret-here
INTUIT_ENVIRONMENT=sandbox
INTUIT_REDIRECT_URI=http://localhost:3001/connections/qb-callback

## Mercury bank feed — the partner OAuth client (sandbox or production).
## Needs CONNECTION_MERCURY_ENABLED=true below. Self-hosted and local
## deployments may instead turn on MERCURY_API_KEY_CONNECTIONS_ENABLED and
## paste a personal read-only token at connect time — never in hosted prod.
# MERCURY_CLIENT_ID=your-mercury-client-id-here
# MERCURY_CLIENT_SECRET=your-mercury-client-secret-here
# MERCURY_ENVIRONMENT=sandbox

## Plaid bank feed — client id + secret from the Plaid dashboard (Team
## Settings → Keys). Needs CONNECTION_PLAID_ENABLED=true below.
# PLAID_CLIENT_ID=your-plaid-client-id-here
# PLAID_SECRET=your-plaid-sandbox-secret-here
# PLAID_ENVIRONMENT=sandbox

## CORS — extra origins for dev (e.g., ngrok tunnels for OAuth callbacks).
## Comma-separated. Dev only — staging/prod derive origins from the app URLs
## (ROBOLEDGER_URL / ROBOINVESTOR_URL / ROBOSYSTEMS_URL / VIEWER_URL, plus
## HOLON_URL for the viewer's original host, served as an alias).
# EXTRA_CORS_ORIGINS=https://your-tunnel.ngrok-free.dev
# VIEWER_URL=
# HOLON_URL=

## Stripe
# STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key-here
# STRIPE_PUBLISHABLE_KEY=pk_test_your-stripe-publishable-key-here
# STRIPE_WEBHOOK_SECRET=whsec_your-stripe-webhook-secret-here

## Cloudflare Turnstile
# TURNSTILE_SECRET_KEY=
# TURNSTILE_SITE_KEY=

## Enterprise SSO (OIDC + SCIM) — dedicated deployments only
## Connection to the customer IdP; enable via SSO_OIDC_ENABLED / SCIM_ENABLED
## in FEATURE FLAGS. Issuer is the org authorization server
## (e.g. https://<org>.okta.com, not /oauth2/default).
## Env vars here are the LOCAL-DEV path; deployed environments carry this
## whole block in the robosystems/{env} base secret (JWT_ISSUER precedent).
# SSO_OIDC_ISSUER=
# SSO_OIDC_CLIENT_ID=
# SSO_OIDC_CLIENT_SECRET=
# SSO_OIDC_PROVIDER_LABEL=SSO
# SSO_DEFAULT_ROLE=member
## Pin the deployment's single enterprise org (set AFTER the first
## `scim bootstrap` mints it); scopes SCIM tokens, bootstrap, and OIDC linking.
# ENTERPRISE_ORG_ID=
## ID-token claim compared to the SCIM externalId at first-login linking.
## Okta: sub (default). Entra: oid.
# SSO_OIDC_BINDING_CLAIM=sub

## Cloudflare R2 (zero-egress downloads)
# R2_ACCESS_KEY_ID=
# R2_SECRET_ACCESS_KEY=
# R2_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
# R2_BUCKET_NAME=robosystems-downloads
R2_PUBLIC_BUCKET_NAME=robosystems-public
R2_PUBLIC_URL=https://pub-d1753a082ea941e38d5a696fae8248f5.r2.dev

## Hugging Face (public SEC dataset publish — manual Dagster job; write token also runs HF Jobs)
# HF_TOKEN=
# HF_SEC_DATASET_REPO=robosystems/sec-xbrl-knowledge-graphs

## OpenFIGI
# OPENFIGI_API_KEY=

## SEC.gov (user agent for API access)
# SEC_GOV_USER_AGENT="YourCompany your-email@example.com"

## LocalStack Credentials (local development only - emulates S3, DynamoDB)
## In prod, IAM roles provide credentials via instance metadata
AWS_REGION=us-east-1
AWS_ENDPOINT_URL=http://localstack:4566
# Browser-reachable endpoint for presigned URLs (the host can't resolve the
# "localstack" docker hostname). Dev only — unset in staging/prod.
AWS_S3_PRESIGN_ENDPOINT_URL=http://localhost:4566
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_S3_ACCESS_KEY_ID=test
AWS_S3_SECRET_ACCESS_KEY=test

## AWS Bedrock Credentials (local development only - for AI agent features)
## In prod, IAM roles provide credentials via instance metadata
AWS_BEDROCK_REGION=us-east-1
AWS_BEDROCK_ACCESS_KEY_ID=your-bedrock-access-key
AWS_BEDROCK_SECRET_ACCESS_KEY=your-bedrock-secret-key

## Self-hosted model (optional) — run the operators on open weights through any
## OpenAI-compatible server (vLLM, Ollama, LM Studio, a hosted API catalog)
## instead of Bedrock. Needs OPENAI_COMPAT_ENABLED=true below. Map a tier to it
## with OPERATOR_PROFILE_*; unmapped tiers stay on Bedrock. From inside Docker, a
## server on the host is host.docker.internal (Ollama:
## http://host.docker.internal:11434/v1). Endpoints, tested models and caveats:
## Self-Hosted AI Models in the technical docs.
# OPENAI_COMPAT_BASE_URL=https://integrate.api.nvidia.com/v1
# OPENAI_COMPAT_MODEL=z-ai/glm-5.3-flash
# OPENAI_COMPAT_API_KEY=
# OPENAI_COMPAT_MAX_OUTPUT_TOKENS=0
# OPENAI_COMPAT_TIMEOUT_SECONDS=300
# OPENAI_COMPAT_CREDITS_PER_1K_INPUT=0
# OPENAI_COMPAT_CREDITS_PER_1K_OUTPUT=0
# OPERATOR_PROFILE_ECONOMY=openai-compat
# OPERATOR_PROFILE_BALANCED=openai-compat
# OPERATOR_PROFILE_QUALITY=openai-compat


## =============================================================================
## FEATURE FLAGS (SSM /features/ in prod)
## =============================================================================
## Boolean flags that enable/disable features.
## In staging/prod, managed via SSM Parameter Store: /robosystems/{env}/features/
##
## Override priority: Environment Variable > SSM > Default (usually false)
## Env var name: Same as below (e.g., USER_REGISTRATION_ENABLED)

## Extensions — RoboLedger & RoboInvestor product surfaces
## EXTENSIONS_GRAPHQL_ENABLED is the GraphQL endpoint kill switch.
# ROBOLEDGER_ENABLED=true
# ROBOINVESTOR_ENABLED=true
# EXTENSIONS_GRAPHQL_ENABLED=true
# Period-close autopilot: sensor drafts the closing entry when a schedule matures
# EXTENSIONS_PROMOTION_AUTO_DISPATCH=false

## Platform Operations
USER_REGISTRATION_ENABLED=true
BILLING_ENABLED=false
RATE_LIMIT_ENABLED=false
LOAD_SHEDDING_ENABLED=false
OTEL_ENABLED=false
# OTEL_TRACES_ENABLED=false

## Security & Authentication
SECURITY_AUDIT_ENABLED=false
# EMAIL_VERIFICATION_ENABLED=false
# CAPTCHA_ENABLED=false
## Auth posture (GET /v1/auth/providers). SSO/SCIM connection config is in SECRETS.
# PASSWORD_AUTH_ENABLED=true
# SSO_OIDC_ENABLED=false
# SCIM_ENABLED=false
# PASSKEYS_ENABLED=false
## MCP OAuth 2.1: the /v1/oauth authorization server, the OAuth carriage on
## /v1/graphs/{g}/mcp, and the OAuth-only /v1/mcp route (SSM: features/)
# MCP_OAUTH_ENABLED=false
## Hard MFA gate for org owner/admin password logins (requires PASSKEYS_ENABLED;
## flip after an adoption window)
# MFA_ENFORCEMENT_ENABLED=false
## WebAuthn RP overrides — normally derived from ROBOSYSTEMS_URL (deployed) or
## localhost (dev); set only to pin them explicitly
# PASSKEY_RP_ID=
# PASSKEY_ORIGIN=

## Organization
# ORG_MEMBER_INVITATIONS_ENABLED=false
# Test-support only (dev/staging): returns the raw org-invite token in the create
# response so the tenant-isolation harness can provision a multi-user org. Ignored
# in production (fail-closed). Do not enable in prod.
# AUTH_INVITE_TOKEN_IN_RESPONSE=false

## Graph Operations
# DIRECT_GRAPH_MATERIALIZATION_ENABLED=true
# SUBGRAPH_CREATION_ENABLED=true
# BACKUP_CREATION_ENABLED=true
# OPERATOR_POST_ENABLED=true
# Self-hosted model for the operators (connection settings are in SECRETS above)
# OPENAI_COMPAT_ENABLED=false
# FACT_GRID_ENABLED=true
# MCP_AUTO_LIMIT_ENABLED=true
# MCP_WORKSPACE_ENABLED=true
# MCP_GRAPHQL_ENABLED=true
# Subgraph write/DDL MCP tools (write-graph-cypher, add-node-table, add-relationship-table)
# MCP_SUBGRAPH_OPS_ENABLED=true
# Days of operation_mutation_audit rows to keep (one row per mutating call,
# from the REST API, MCP clients and in-app operators).
# 396 = 13 months; a dedicated deployment can keep more.
# OPERATION_AUDIT_RETENTION_DAYS=396
# MCP_SEMANTIC_MEMORY_ENABLED=false
# AI semantic memory (LanceDB) master gate; MCP_SEMANTIC_MEMORY_ENABLED is the MCP sub-gate
# SEMANTIC_MEMORY_ENABLED=false
# Tenant framework authoring (taxonomy blocks). On in dev/test, off in prod/staging
# TAXONOMY_AUTHORING_ENABLED=true

## Shared Repository Operations
# SHARED_MASTER_READS_ENABLED=true
# SHARED_MASTER_PARKING_ENABLED=true
# SEMANTIC_SEARCH_ENABLED=true

## Connection Providers
# CONNECTIONS_ENABLED=true
# CONNECTION_QUICKBOOKS_ENABLED=true
# CONNECTION_EXTERNAL_ENABLED=true
# CONNECTION_MERCURY_ENABLED=false
# MERCURY_API_KEY_CONNECTIONS_ENABLED=false
# CONNECTION_PLAID_ENABLED=false
# The hourly sweep that syncs every connection once its last sync is older
# than the cadence (SSM feature flag in hosted environments)
# CONNECTION_SCHEDULED_SYNC_ENABLED=true
# CONNECTION_SYNC_INTERVAL_HOURS=24

## Adapter Pipelines
# SEC_PIPELINE_ENABLED=true
# Local control experiments only: keep text-block values in the graph as well as on S3.
# Never in a real environment — text blocks are most of a filing's bytes.
# XBRL_KEEP_TEXTBLOCKS_INLINE=false
# Publish each filing's holon, Tavi model, primary document and manifest to the
# public data bucket at process time, and the per-filer catalog after staging.
# SEC_FILING_ARTIFACTS_ENABLED=true



## =============================================================================
## TUNING PARAMETERS (SSM /tuning/ in prod)
## =============================================================================
## Runtime tunables that can be adjusted without redeployment.
## In staging/prod, managed via SSM Parameter Store: /robosystems/{env}/tuning/
##
## Override priority: Environment Variable > SSM > Default
## Env var name: TUNING_{CATEGORY}_{KEY} (e.g., TUNING_CACHE_BALANCE_TTL)
##
## Manage with: just ssm-tuning-list {env}
##              just ssm-tuning-set {env} {path} {value}

## Limits
# TUNING_LIMITS_ORG_GRAPHS_DEFAULT=10

## Materialization cadence (seconds) - raised on dedicated deployments
# TUNING_MATERIALIZATION_MIN_STALE_AGE=30
# TUNING_MATERIALIZATION_MAX_STALE_WAIT=300
# TUNING_MATERIALIZATION_STAGE_TIMEOUT=120
# TUNING_MATERIALIZATION_COPY_TIMEOUT=300
# TUNING_MATERIALIZATION_ENGINE_COPY_TIMEOUT=3600
# TUNING_TIMEOUTS_GRAPH_ENGINE_QUERY=120

## Cache TTLs (seconds)
# TUNING_CACHE_BALANCE_TTL=300
# TUNING_CACHE_SUMMARY_TTL=600
# TUNING_CACHE_JWT_TTL=1800
# TUNING_CACHE_API_KEY_TTL=300
# TUNING_CACHE_SCHEMA_TTL=300

## Database Connection Pool (tune based on RDS instance size and ECS task count)
## max connections per task = POOL_SIZE + MAX_OVERFLOW
# TUNING_DATABASE_POOL_SIZE=5
# TUNING_DATABASE_MAX_OVERFLOW=10
# TUNING_DATABASE_POOL_TIMEOUT=30
# TUNING_DATABASE_POOL_RECYCLE=3600

## Admission Control - Main API (percentages 0-100)
# TUNING_ADMISSION_MEMORY_THRESHOLD=85.0
# TUNING_ADMISSION_CPU_THRESHOLD=90.0
# TUNING_ADMISSION_QUEUE_THRESHOLD=80.0

## Admission Control - Graph API (percentages 0-100)
# TUNING_LBUG_ADMISSION_MEMORY_THRESHOLD=85.0
# TUNING_LBUG_ADMISSION_CPU_THRESHOLD=90.0

## Load Shedding (percentages 0-100)
# TUNING_LOAD_SHEDDING_START_PRESSURE=80.0
# TUNING_LOAD_SHEDDING_STOP_PRESSURE=60.0

## Queue Configuration
# TUNING_QUEUES_MAX_SIZE=1000
# TUNING_QUEUES_MAX_CONCURRENT=50
# TUNING_QUEUES_MAX_PER_USER=10
# TUNING_QUEUES_TIMEOUT=300

## Extensions GraphQL query bounds — guard the OLTP pool from deep / alias-heavy
## / oversized queries (introspection unaffected).
## SSM: /tuning/graphql/{MAX_DEPTH,MAX_ALIASES,MAX_TOKENS}.
# TUNING_GRAPHQL_MAX_DEPTH=15
# TUNING_GRAPHQL_MAX_ALIASES=30
# TUNING_GRAPHQL_MAX_TOKENS=2000

## Circuit Breakers
# TUNING_CIRCUITS_THRESHOLD=5
# TUNING_CIRCUITS_TIMEOUT=60

## MCP Limits
# TUNING_MCP_MAX_RESULT_ROWS=1000
# TUNING_MCP_MAX_RESULT_SIZE_MB=5.0
# TUNING_MCP_POOL_IDLE_TIMEOUT=300
# TUNING_MCP_POOL_MAX_LIFETIME=3600

## Timeouts (seconds)
# TUNING_TIMEOUTS_GRAPH_HTTP=30
# TUNING_TIMEOUTS_GRAPH_QUERY=30

## SSE Configuration
# TUNING_SSE_MAX_CONNECTIONS_PER_USER=5
# TUNING_SSE_QUEUE_SIZE=100

## Workers
# TUNING_WORKERS_MAX_WORKERS=10


## =============================================================================
## GRAPH CONFIGURATION
## =============================================================================
## Graph database backend selection and operational settings.

## Graph Backend Selection
GRAPH_BACKEND_TYPE=ladybug
GRAPH_SHARED_REPOSITORY_BACKEND=ladybug
GRAPH_API_URL=http://graph-api:8001
# GRAPH_API_KEY=your-graph-api-key-here

## LadybugDB Configuration
LBUG_DATABASE_PATH=./data/lbug-dbs
LBUG_ACCESS_PATTERN=api_auto
LBUG_NODE_TYPE=writer

## DuckDB Configuration
DUCKDB_STAGING_PATH=./data/staging

## Artifact Storage (precomputed Parquet for enrichment refinement)
# ARTIFACT_PATH=./data/artifacts

## LanceDB Vector Search Index
# LANCE_INDEX_PATH=./data/lance

## Arelle (XBRL) runtime cache directory
# ARELLE_CACHE_DIR=

## Shared Repository Configuration
# SHARED_REPLICA_ALB_URL=http://internal-robosystems-shared-prod-xxx.region.elb.amazonaws.com:8001

## Graph Resiliency
# GRAPH_CIRCUIT_BREAKERS_ENABLED=true
# GRAPH_REDIS_CACHE_ENABLED=true
# GRAPH_RETRY_LOGIC_ENABLED=true
# GRAPH_HEALTH_CHECKS_ENABLED=true