.env.example

# =============================================================================
# StoryForge — Environment Variables Reference
# Copy this file to .env and fill in your values.
# =============================================================================


# -----------------------------------------------------------------------------
# LLM Backend
# -----------------------------------------------------------------------------

# API key for the LLM provider (OpenAI-compatible)
STORYFORGE_API_KEY=your-api-key-here

# Base URL of the LLM API endpoint
STORYFORGE_BASE_URL=https://api.openai.com/v1

# Model name to use for story generation
STORYFORGE_MODEL=gpt-4o-mini

# Backend mode: "api" (OpenAI-compatible) or "local" (Ollama / LM Studio)
STORYFORGE_BACKEND=api

# Sampling temperature for generation (0.0 – 2.0)
STORYFORGE_TEMPERATURE=0.8


# -----------------------------------------------------------------------------
# Image Generation
# -----------------------------------------------------------------------------

# Image provider: "openai", "hf", "replicate", "seedream", or "none"
STORYFORGE_IMAGE_PROVIDER=none

# OpenAI-compatible API key for image generation
IMAGE_API_KEY=

# Base URL for the image API (defaults to OpenAI)
IMAGE_API_URL=https://api.openai.com/v1

# Hugging Face access token (for HF Inference API / Diffusers)
HF_TOKEN=

# Replicate API key (for IP-Adapter and other Replicate models)
REPLICATE_API_KEY=

# SeedDream API key
SEEDREAM_API_KEY=


# -----------------------------------------------------------------------------
# Security
# -----------------------------------------------------------------------------

# HMAC signing key — generate with: openssl rand -hex 32
STORYFORGE_SECRET_KEY=change-me-in-production

# Block prompt-injection attempts; set to "false" to log-only without blocking
STORYFORGE_BLOCK_INJECTION=true

# Comma-separated allowed CORS origins (empty = allow all, not safe for prod)
# Example: https://myapp.com,https://staging.myapp.com
STORYFORGE_ALLOWED_ORIGINS=localhost:7860

# Comma-separated trusted reverse-proxy IPs for X-Forwarded-For handling
# Example: 10.0.0.1,10.0.0.2
TRUSTED_PROXY_IPS=


# -----------------------------------------------------------------------------
# Database
# -----------------------------------------------------------------------------

# SQLAlchemy database URL
# SQLite  (dev):    sqlite:///./data/storyforge.db
# Postgres (prod):  postgresql+asyncpg://user:pass@localhost:5432/storyforge
DATABASE_URL=sqlite:///./data/storyforge.db

# Connection pool settings (ignored for SQLite)
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# Echo all SQL statements to stdout ("1" or "true" for dev debugging only)
DB_ECHO=false


# -----------------------------------------------------------------------------
# Redis
# -----------------------------------------------------------------------------

# Redis connection URL — enables rate-limiting, progress tracking, LLM caching,
# and JWT revocation. Leave blank to fall back to in-process / no-op stubs.
# Example: redis://localhost:6379/0  or  redis://:password@host:6379/0
REDIS_URL=

# Refuse to start when Redis is unavailable ("1" or "true" for prod deployments)
STORYFORGE_REDIS_REQUIRED=false


# -----------------------------------------------------------------------------
# Workers / Concurrency
# -----------------------------------------------------------------------------

# Number of Gunicorn/Uvicorn worker processes (blank = auto from CPU count)
NUM_WORKERS=1

# Alternative recognised by Gunicorn; NUM_WORKERS takes precedence when set
WEB_CONCURRENCY=

# Server port
PORT=7860


# -----------------------------------------------------------------------------
# Auth / JWT  (leave blank if running open-source without auth)
# -----------------------------------------------------------------------------

# Directory where JWT signing keys are stored
STORYFORGE_JWT_KEY_DIR=data/jwt_keys

# Key ID used to select the active signing key
STORYFORGE_JWT_KEY_ID=default

# Access token TTL in seconds (default 86400 = 24 h)
STORYFORGE_JWT_TTL_SECONDS=86400

# How often the JWT signing key rotates, in days
JWT_KEY_ROTATION_DAYS=1

# Check token revocation on every request ("false" to disable for performance)
JWT_REVOCATION_CHECK=true

# Maximum token lifetime in days regardless of TTL
JWT_MAX_TOKEN_AGE_DAYS=7

# Superadmin user ID (grants elevated permissions; leave blank to disable)
STORYFORGE_SUPERADMIN_ID=


# -----------------------------------------------------------------------------
# Logging
# -----------------------------------------------------------------------------

# Log output format: "text" (human-friendly) or "json" (structured, for prod)
LOG_FORMAT=text

# How many days to retain audit log entries
AUDIT_LOG_RETENTION_DAYS=90


# -----------------------------------------------------------------------------
# Pipeline / Quality Gate
# -----------------------------------------------------------------------------

# Maximum total retries across all pipeline stages (blank = 3× per-stage default)
STORYFORGE_MAX_TOTAL_RETRIES=

# Enable lite (faster / cheaper) generation mode ("1" or "true")
STORYFORGE_LITE_MODE=false


# -----------------------------------------------------------------------------
# Storage / Paths
# -----------------------------------------------------------------------------

# Directory where user feedback JSON files are written
STORYFORGE_FEEDBACK_DIR=data/feedback

# File path for persisting token-cost logs (blank = disabled)
STORYFORGE_COST_LOG=

# Custom token pricing overrides as a JSON string (see docs for schema)
STORYFORGE_TOKEN_PRICING=

# Path to the active prompts YAML file (blank = bundled default)
STORYFORGE_PROMPTS_FILE=


# -----------------------------------------------------------------------------
# RAG / Knowledge Base  (optional ChromaDB integration)
# -----------------------------------------------------------------------------

# Directory where ChromaDB persists its vector store
CHROMA_PERSIST_DIR=data/chromadb

# ChromaDB collection name
CHROMA_COLLECTION_NAME=storyforge_world


# -----------------------------------------------------------------------------
# Miscellaneous
# -----------------------------------------------------------------------------

# Base URL of a running StoryForge instance (used by demo/test scripts)
STORYFORGE_URL=http://localhost:7860