.env.example

# gh-social-ml Environment Variables
# Copy this file to .env and fill in your values.

# GitHub Personal Access Token (required for acquisition)
GITHUB_TOKEN=your_github_token_here

# Bounded, resumable corpus acquisition
CORPUS_TARGET_COUNT=50000
ACQUISITION_MAX_CYCLES=1
ACQUISITION_CHECKPOINT_PATH=.cache/acquisition_checkpoint.json
# Per-request metadata aliases, independent of --batch-size scheduler chunks.
# Application safety range: 1..10. Keep the conservative existing default.
GITHUB_METADATA_BATCH_SIZE=10
# Shared across acquisition batches; 1 gives serial README fetching.
GITHUB_README_WORKERS=4

# Qdrant repository indexing. Keep the embedding model aligned with the
# embedding/Qdrant contract published by the embedding owner.
QDRANT_URL=http://localhost:6333
# QDRANT_API_KEY=your-qdrant-api-key
QDRANT_COLLECTION_NAME=osiris_research_corpus_v2_20260722_r1
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_MODEL_REVISION=c9745ed1d9f207416be6d2e6f8de32d1f16199bf

# Optional README restructuring; acquisition continues when this is omitted.
# OPENROUTER_API_KEY=your-openrouter-api-key

# V2 discovery-card summary generation. The provider receives only a bounded,
# derived copy; canonical README Markdown remains unchanged in backend storage.
SUMMARY_PROVIDER=openrouter
SUMMARY_API_URL=https://openrouter.ai/api/v1/chat/completions
# SUMMARY_API_KEY=replace-with-summary-provider-key
SUMMARY_MODEL_ID=meta-llama/llama-3.3-70b-instruct
SUMMARY_PROMPT_VERSION=repo-card-summary-v1
SUMMARY_FORMAT_VERSION=repo-card-summary-json-v1
SUMMARY_INPUT_MAX_CHARS=12000
SUMMARY_TEMPERATURE=0.1
SUMMARY_MAX_OUTPUT_TOKENS=240
SUMMARY_REQUEST_TIMEOUT_SECONDS=30
SUMMARY_RPM_LIMIT=60
SUMMARY_TPM_LIMIT=120000
SUMMARY_FAILURE_THRESHOLD=3
SUMMARY_COOLDOWN_SECONDS=30
SUMMARY_MAX_RETRIES=2
SUMMARY_RETRY_BASE_SECONDS=1

# PostgreSQL Database URL
# ──────────────────────────────────────────────────────────────
# Local PostgreSQL (Homebrew / native):
#   DATABASE_URL=postgresql://your_username@localhost:5432/gh_social
#
# Supabase (cloud):
#   DATABASE_URL=postgresql://postgres.xxxx:your-password@aws-0-region.pooler.supabase.com:6543/postgres
#
# SSL is auto-detected for Supabase hosts. No extra config needed.

# ──────────────────────────────────────────────────────────────
# Trending Repository Ingestion Configuration
# ──────────────────────────────────────────────────────────────

# Number of trending repositories to fetch per refresh cycle
TRENDING_REPO_LIMIT=30

# Refresh interval in hours (default: 24 hours)
TRENDING_REFRESH_HOURS=24

# Trending snapshots are delivered only to the backend. The backend outbox and
# ML refresh pipeline own all Qdrant updates; the trending worker never does.

# PostgreSQL table names for trending repositories
TRENDING_TABLE_NAME=trending_repositories
TRENDING_METADATA_TABLE_NAME=trending_metadata

# Request timeout in seconds (for HTTP requests to GitHub Trending page)
GITHUB_TIMEOUT_SECONDS=30.0

# Maximum retry attempts for failed requests
GITHUB_MAX_RETRIES=4

# Log level for trending service
TRENDING_LOG_LEVEL=INFO

# Log file path (if not set, logs to stdout)
# TRENDING_LOG_FILE=/var/log/trending_service.log

# Whether to continue processing on individual repository failures
CONTINUE_ON_ERROR=true

# Maximum number of consecutive failures before stopping the pipeline
MAX_CONSECUTIVE_FAILURES=10
DATABASE_URL=postgresql://your_username@localhost:5432/gh_social

# Migration / Sync settings (used by sync_local_to_supabase.py)
# ──────────────────────────────────────────────────────────────
# LOCAL_DATABASE_URL=postgresql://your_username@localhost:5432/gh_social
# SUPABASE_DATABASE_URL=postgresql://postgres.xxxx:your-password@aws-0-region.pooler.supabase.com:6543/postgres

# ──────────────────────────────────────────────────────────────
# Backend Integration
# ──────────────────────────────────────────────────────────────

# URL of the gh-social backend (used when pushing recommendations)
BACKEND_URL=http://localhost:5000

# Shared secret sent in X-Internal-Secret header when calling /api/internal/recommendations
# Must match the backend environment. Production requires exactly 64 lowercase
# hexadecimal characters; generate it with: openssl rand -hex 32
INTERNAL_API_SECRET=replace-with-64-lowercase-hex-characters

# Online ML API and feedback worker (Redis + Qdrant only). These are local
# development values. Production must use deploy/production.env.example as its
# schema and must not copy DATABASE_URL/GITHUB_TOKEN into the container env.
APP_ENV=development
V2_FEEDBACK_CONSUMER_REQUIRED=true
INTERNAL_API_HEADER=x-internal-secret
REDIS_URL=redis://localhost:6379/0
FEEDBACK_ALLOW_MEMORY_FALLBACK=false
FEEDBACK_STREAM_NAME=ml:feedback:v2
FEEDBACK_STREAM_MAXLEN=100000
FEEDBACK_CONSUMER_GROUP=ml-feedback-v2
FEEDBACK_CONSUMER_PREFIX=feedback-worker
FEEDBACK_CONSUMER_HEARTBEAT_KEY=ml:feedback:v2:consumer-heartbeat
FEEDBACK_CONSUMER_HEARTBEAT_TTL_SECONDS=15
FEEDBACK_READ_BATCH_SIZE=20
FEEDBACK_CONSUMER_WORKERS=4
FEEDBACK_READ_BLOCK_MS=1000
FEEDBACK_RECLAIM_IDLE_MS=30000
FEEDBACK_IDEMPOTENCY_TTL_SECONDS=2592000
FEEDBACK_USER_LOCK_PREFIX=ml:user-vector-lock
FEEDBACK_USER_LOCK_TTL_SECONDS=30
FEEDBACK_USER_LOCK_WAIT_SECONDS=2
FEEDBACK_USER_LOCK_RENEW_INTERVAL_SECONDS=10
FEEDBACK_MAX_DELIVERY_ATTEMPTS=5
FEEDBACK_DEAD_LETTER_STREAM=ml:feedback:v2:dead
FEEDBACK_DEAD_LETTER_MAXLEN=10000
FEEDBACK_REJECTION_HISTORY_SIZE=64
FEEDBACK_MAX_TRACKED_REPOSITORIES=256
FEEDBACK_MAX_USER_STATE_BYTES=1000000
FEEDBACK_QDRANT_TIMEOUT_SECONDS=10
FEEDBACK_DWELL_MIN_SECONDS=3
FEEDBACK_DWELL_FULL_CREDIT_SECONDS=300
FEEDBACK_DWELL_MAX_ALPHA=0.15
FEEDBACK_HEALTH_WARN_PENDING=1000
FEEDBACK_HEALTH_MAX_PENDING=10000
FEEDBACK_HEALTH_WARN_LAG=10000
FEEDBACK_HEALTH_MAX_LAG=50000
FEEDBACK_HEALTH_WARN_STREAM_LENGTH=80000
FEEDBACK_HEALTH_MAX_STREAM_LENGTH=100000
FEEDBACK_HEALTH_WARN_DEAD_LETTER=1
FEEDBACK_HEALTH_MAX_DEAD_LETTER=1000
# Finite 1-120 seconds; online RPC timeout floors min(cap, request budget).
QDRANT_TIMEOUT_SECONDS=10
QDRANT_DISTANCE=Cosine
QDRANT_VECTOR_NAME=repo_embedding
# Token-aware candidate: repo-embedding-v3-token-sections-v1.
# Keep v2 until corpus/ranker qualification; see docs/README_EMBEDDING_AGGREGATION.md.
REPOSITORY_EMBEDDING_VERSION=repo-embedding-v2
REPOSITORY_FEATURE_SPEC_VERSION=v2
USER_PROFILES_COLLECTION=user_profiles
# The current user collection uses an unnamed vector.
# USER_PROFILE_VECTOR_NAME=
VECTOR_DIMENSION=384
V2_USER_COLLECTION_REQUIRED=true
V2_COMPATIBLE_EMBEDDING_VERSIONS=repo-embedding-v2
V2_REQUIRED_CONTENT_VERSION=1
V2_REQUIRED_FEATURE_SPEC_VERSION=v2
V2_ALLOW_MISSING_EMBEDDING_REVISION=false
MIN_ELIGIBLE_REPOSITORIES=0
README_CHUNK_CHARS=2500
README_CHUNK_OVERLAP_CHARS=250
EMBEDDING_WARMUP_ON_STARTUP=false
# Real encoder/ranker inference must finish before production readiness.
INFERENCE_WARMUP_TIMEOUT_SECONDS=120
EMBEDDING_TIMEOUT_SECONDS=30
EMBEDDING_MAX_CONCURRENCY=1
EMBEDDING_EXECUTOR_WORKERS=1
EMBEDDING_MAX_OUTSTANDING_JOBS=4
EMBEDDING_CPU_THREADS=1

# V2 uses the manually qualified checked-in ranker at full traffic. Its
# manifest still truthfully records that it was trained on synthetic data.
V2_HEAVY_RANKER_ENABLED=true
# auto retains current CUDA preference; select hardware only after qualification.
V2_HEAVY_RANKER_DEVICE=auto
V2_HEAVY_RANKER_REQUIRED=true
V2_HEAVY_RANKER_TRAFFIC_PERCENT=100
V2_ALLOW_UNQUALIFIED_HEAVY_RANKER=false
V2_HEAVY_RANKER_CANARY_SALT=v2-heavy-ranker-2026
ML_MODEL_VERSION=qdrant-hybrid-v2
V2_EXPLORATION_FRACTION=0.333333
V2_MAX_SAME_LANGUAGE=5
V2_RECOMMENDATION_TIMEOUT_SECONDS=12
V2_HEALTH_TIMEOUT_SECONDS=5
# Routine probes read cached diagnostics. Failed/stale snapshots fail readiness.
# Max age must cover refresh interval plus two diagnostic timeouts.
V2_HEALTH_REFRESH_SECONDS=15
V2_HEALTH_MAX_AGE_SECONDS=45
V2_RECOMMENDATION_EXECUTOR_WORKERS=4
V2_RECOMMENDATION_MAX_OUTSTANDING=8
# Shared recommendation/search Qdrant I/O. Includes queued and running child calls.
V2_RETRIEVAL_IO_WORKERS=4
V2_RETRIEVAL_IO_MAX_OUTSTANDING=8
# Reserved pools prevent mutation, Redis, and health work from consuming the
# event loop or recommendation executor. Capacity includes running + queued.
V2_FEEDBACK_EXECUTOR_WORKERS=2
V2_FEEDBACK_MAX_OUTSTANDING=8
V2_FEEDBACK_TIMEOUT_SECONDS=8
V2_REFRESH_EXECUTOR_WORKERS=2
V2_REFRESH_MAX_OUTSTANDING=4
V2_REFRESH_TIMEOUT_SECONDS=45
# Query embedding has a reserved queue, separate from slow summary generation.
# It still uses the process-shared, concurrency-bounded frozen encoder.
V2_SEARCH_EXECUTOR_WORKERS=1
V2_SEARCH_MAX_OUTSTANDING=4
V2_SEARCH_TIMEOUT_SECONDS=4
V2_HEALTH_EXECUTOR_WORKERS=2
V2_HEALTH_MAX_OUTSTANDING=4
REPOSITORY_JOB_LOCK_TTL_MS=600000
REPOSITORY_JOB_LOCK_WAIT_SECONDS=30

# Opt in only when disposable local Redis and Qdrant services are available.
RUN_FEEDBACK_INTEGRATION=false
RUN_V2_FEEDBACK_INTEGRATION=false

# ──────────────────────────────────────────────────────────────
# Deployment Optimizations (Render, Railway, etc.)
# ──────────────────────────────────────────────────────────────

# Force pip to download the CPU-only version of PyTorch to save massive amounts of RAM
# PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu

# Limit PyTorch and its math libraries to 1 thread. These are defaults in the
# production image and may be overridden only after latency/resource testing.
# OMP_NUM_THREADS=1
# OPENBLAS_NUM_THREADS=1
# MKL_NUM_THREADS=1
# VECLIB_MAXIMUM_THREADS=1
# NUMEXPR_NUM_THREADS=1

# Restrict Linux memory arenas to save idle RAM
# MALLOC_ARENA_MAX=2

# Experimental backend-sourced social candidate channel; no live activation by default.
# Enable only after the paired visibility projection and quality acceptance.
V2_SOCIAL_CANDIDATE_MODE=disabled
V2_SOCIAL_CANDIDATE_TRAFFIC_PERCENT=0

# Keep false until the backend lineage persistence/outbox contract is deployed.
# Enables only bounded observed ancestry in the existing GraphQL quota path.
ACQUISITION_LINEAGE_ENABLED=false
# Requires complete observed owner/fork-family metadata and strict-heavy vectors.
V2_DIVERSITY_MODE=disabled
V2_DIVERSITY_TRAFFIC_PERCENT=0
V2_DIVERSITY_RELEVANCE_WEIGHT=0.7
V2_DIVERSITY_DUPLICATE_COSINE=0.98
V2_DIVERSITY_MAX_PER_OWNER=2
V2_DIVERSITY_MAX_PER_TOPIC=5
V2_DIVERSITY_MAX_PER_CATEGORY=8
V2_DIVERSITY_MAX_PER_FAMILY=1
V2_DIVERSITY_MIN_EXPLORATION=2