.env.example

# HAppy VErtical (HAVE) SDK - Environment Variables Reference
# ===========================================================
# This file documents all environment variables supported across the SDK packages.
# Copy this file to .env and configure as needed for your application.
#
# Precedence: User-provided options > Environment variables > Package defaults
# All HAVE_* variables use the pattern: HAVE_{PACKAGE}_{FIELD}

# ===========================================================
# @have/utils - Utility Functions
# ===========================================================
# No environment variables (foundation package with no config)

# ===========================================================
# @have/logger - Structured Logging
# ===========================================================
# Logging configuration
HAVE_LOGGER_LEVEL=info
# Options: debug, info, warn, error

# ===========================================================
# @have/ai - Multi-Provider AI Client
# ===========================================================
# General AI configuration (applies to all providers)
HAVE_AI_PROVIDER=openai
# Options: openai, anthropic, gemini, claude-cli, huggingface, bedrock
HAVE_AI_MODEL=gpt-4o
# Provider-specific model name
HAVE_AI_TIMEOUT=30000
# Request timeout in milliseconds
HAVE_AI_MAX_RETRIES=3
# Maximum number of retry attempts
HAVE_AI_API_KEY=
# Fallback API key (used if provider-specific key not set)
HAVE_AI_BASE_URL=
# Custom base URL for API requests (useful for proxies)

# Provider-Specific API Keys
OPENAI_API_KEY=
# OpenAI API key (https://platform.openai.com/api-keys)
ANTHROPIC_API_KEY=
# Anthropic Claude API key (https://console.anthropic.com/)
GEMINI_API_KEY=
# Google Gemini API key (https://ai.google.dev/)
GOOGLE_API_KEY=
# Alternative Google API key
HF_TOKEN=
# Hugging Face API token (https://huggingface.co/settings/tokens)

# AWS Bedrock (for AWS-hosted AI models)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1

# ===========================================================
# @have/sql - Database Operations
# ===========================================================
# Database configuration
HAVE_SQL_TYPE=sqlite
# Options: sqlite, postgres, duckdb, json
HAVE_SQL_URL=:memory:
# Connection string (takes precedence over individual options)
# Examples:
#   SQLite: file:database.db or :memory:
#   Postgres: postgresql://user:pass@localhost:5432/dbname
#   Turso: libsql://your-database.turso.io

# PostgreSQL/connection options (used when URL not provided)
HAVE_SQL_HOST=localhost
HAVE_SQL_PORT=5432
HAVE_SQL_DATABASE=mydb
HAVE_SQL_USER=username
HAVE_SQL_PASSWORD=

# Backward compatibility with SQLOO_* variables (PostgreSQL only)
# These are deprecated - use HAVE_SQL_* instead
# SQLOO_URL=
# SQLOO_DATABASE=
# SQLOO_HOST=
# SQLOO_USER=
# SQLOO_PASSWORD=
# SQLOO_PORT=

# ===========================================================
# @have/ocr - Optical Character Recognition
# ===========================================================
# OCR configuration
HAVE_OCR_PROVIDER=auto
# Options: auto, tesseract, onnx, web-ocr
HAVE_OCR_LANGUAGE=eng
# Language codes (e.g., 'eng', 'eng+chi_sim', 'fra')
HAVE_OCR_CONFIDENCE_THRESHOLD=75
# Minimum confidence threshold (0-100)
HAVE_OCR_TIMEOUT=30000
# Processing timeout in milliseconds

# ===========================================================
# @have/pdf - PDF Processing
# ===========================================================
# PDF processing configuration
HAVE_PDF_ENABLE_OCR=true
# Enable OCR fallback for image-based PDFs (boolean: true/false/1/0/yes/no)
HAVE_PDF_TIMEOUT=30000
# Processing timeout in milliseconds
HAVE_PDF_PROVIDER=auto
# Options: unpdf, pdfjs, auto
HAVE_PDF_MAX_FILE_SIZE=52428800
# Maximum file size in bytes (default: 50MB)

# ===========================================================
# @have/cache - Caching Utilities
# ===========================================================
# Common cache settings (all providers)
HAVE_CACHE_PROVIDER=memory
# Options: memory, file, redis
HAVE_CACHE_NAMESPACE=
# Logical grouping prefix for cache keys
HAVE_CACHE_DEFAULT_TTL=3600
# Default time-to-live in seconds

# Memory provider settings
HAVE_CACHE_MAX_SIZE=104857600
# Maximum cache size in bytes (default: 100MB)
HAVE_CACHE_MAX_ENTRIES=10000
# Maximum number of cache entries
HAVE_CACHE_EVICTION_POLICY=lru
# Options: lru (least recently used), lfu (least frequently used), fifo
HAVE_CACHE_CHECK_PERIOD=60000
# Cleanup interval in milliseconds

# File provider settings
HAVE_CACHE_CACHE_DIR=./.cache
# Directory path for file-based cache
HAVE_CACHE_COMPRESSION=true
# Enable compression for cached files (boolean)
HAVE_CACHE_FILE_EXTENSION=.cache
# File extension for cache files

# Redis provider settings
HAVE_CACHE_HOST=localhost
# Redis server hostname
HAVE_CACHE_PORT=6379
# Redis server port
HAVE_CACHE_PASSWORD=
# Redis authentication password
HAVE_CACHE_DB=0
# Redis database number (0-15)
HAVE_CACHE_KEY_PREFIX=cache:
# Additional prefix for Redis keys
HAVE_CACHE_ENABLE_COMPRESSION=true
# Enable compression for large values
HAVE_CACHE_COMPRESSION_THRESHOLD=1024
# Compress values larger than this (bytes)
HAVE_CACHE_CONNECT_TIMEOUT=5000
# Connection timeout in milliseconds
HAVE_CACHE_COMMAND_TIMEOUT=1000
# Command timeout in milliseconds

# ===========================================================
# @have/translator - Translation Services
# ===========================================================
# Translation configuration
HAVE_TRANSLATOR_PROVIDER=google
# Options: google, deepl, libretranslate
HAVE_TRANSLATOR_TIMEOUT=30000
# Request timeout in milliseconds
HAVE_TRANSLATOR_MAX_RETRIES=3
# Maximum number of retry attempts

# Provider-specific API keys
GOOGLE_TRANSLATE_API_KEY=
# Google Cloud Translation API key
DEEPL_API_KEY=
# DeepL API key (https://www.deepl.com/pro-api)

# ===========================================================
# @have/geo - Geographic Services
# ===========================================================
# Geographic service configuration
HAVE_GEO_PROVIDER=openstreetmap
# Options: google, openstreetmap
HAVE_GEO_TIMEOUT=15000
# Request timeout in milliseconds
HAVE_GEO_MAX_RESULTS=5
# Maximum number of results to return
HAVE_GEO_RATE_LIMIT_DELAY=2000
# OpenStreetMap rate limit delay in milliseconds
HAVE_GEO_USER_AGENT=
# Custom User-Agent for OpenStreetMap requests

# Provider-specific API keys
GOOGLE_MAPS_API_KEY=
# Google Maps API key (https://developers.google.com/maps)

# ===========================================================
# @have/spider - Web Crawling
# ===========================================================
# Web crawling configuration
HAVE_SPIDER_TIMEOUT=30000
# Request timeout in milliseconds
HAVE_SPIDER_USER_AGENT=
# Custom user agent string
# Default: Mozilla/5.0 (compatible; HappyVertical Spider/2.0; +https://happyvertical.com/bot)
HAVE_SPIDER_MAX_REQUESTS=
# Maximum number of requests (unlimited if not set)

# ===========================================================
# Additional Notes
# ===========================================================
# 1. Boolean values support multiple formats:
#    - true/false
#    - 1/0
#    - yes/no
#
# 2. Number values are automatically converted from strings
#
# 3. All environment variables are optional - packages provide sensible defaults
#
# 4. User-provided options in code always override environment variables
#
# 5. For production deployments:
#    - Store sensitive credentials in secure secret management systems
#    - Use .env files only for local development
#    - Never commit .env files to version control
#
# 6. For more information on each package, see:
#    - packages/{package-name}/CLAUDE.md
#    - packages/{package-name}/README.md