Environment Variables Reference

Complete reference for all IntellyWeave environment variables in backend/.env.

Quick Start

cd backend
cp .env.example .env
nano .env

---

Weaviate Configuration

Option 1: Weaviate Cloud (Production)

WCD_URL=https://your-cluster.weaviate.cloud
WCD_API_KEY=your-weaviate-api-key

Variable	Required	Description
WCD_URL	Yes	Weaviate Cloud cluster URL
WCD_API_KEY	Yes	Weaviate Cloud API key

Option 2: Local Docker (Development)

WEAVIATE_IS_LOCAL=True
LOCAL_WEAVIATE_PORT=8080
LOCAL_WEAVIATE_GRPC_PORT=50051

Variable	Default	Description
WEAVIATE_IS_LOCAL	False	Enable local Weaviate
LOCAL_WEAVIATE_PORT	8080	HTTP port
LOCAL_WEAVIATE_GRPC_PORT	50051	gRPC port

Option 3: Custom Instance

WEAVIATE_IS_CUSTOM=True
CUSTOM_HTTP_HOST=your.weaviate.host
CUSTOM_HTTP_PORT=443
CUSTOM_HTTP_SECURE=True
CUSTOM_GRPC_HOST=your.weaviate.host
CUSTOM_GRPC_PORT=443
CUSTOM_GRPC_SECURE=True

Variable	Description
WEAVIATE_IS_CUSTOM	Enable custom Weaviate
CUSTOM_HTTP_HOST	HTTP hostname
CUSTOM_HTTP_PORT	HTTP port
CUSTOM_HTTP_SECURE	Use HTTPS (True/False)
CUSTOM_GRPC_HOST	gRPC hostname
CUSTOM_GRPC_PORT	gRPC port
CUSTOM_GRPC_SECURE	Use secure gRPC

---

LLM Provider API Keys

Primary Providers

# OpenAI (Required for GPT models)
OPENAI_API_KEY=sk-proj-...

# Anthropic (Required for Claude models)
ANTHROPIC_API_KEY=sk-ant-...

# OpenRouter (Multi-provider gateway)
OPENROUTER_API_KEY=sk-or-...

Variable	Provider	Models
OPENAI_API_KEY	OpenAI	GPT-4o, GPT-4o-mini, GPT-5
ANTHROPIC_API_KEY	Anthropic	Claude Sonnet, Claude Haiku
OPENROUTER_API_KEY	OpenRouter	100+ models

Google AI

GEMINI_API_KEY=...
VERTEX_API_KEY=...
STUDIO_API_KEY=...

Other Providers

COHERE_API_KEY=...
MISTRAL_API_KEY=...
HUGGINGFACE_API_KEY=hf_...
ANYSCALE_API_KEY=...
JINAAI_API_KEY=jina_...
NVIDIA_API_KEY=...
XAI_API_KEY=...
VOYAGE_API_KEY=...
VOYAGEAI_API_KEY=...
FRIENDLI_TOKEN=...
DATABRICKS_TOKEN=...

Cloud Providers

AWS_ACCESS_KEY=AKIA...
AWS_SECRET_KEY=...
AZURE_API_KEY=...

---

Quartermaster & Case Officer Tools

These services power the Archive Research workflow.

Multi-Provider Search Cascade (Sofia Service)

Used by Quartermaster to discover archive sources and by Case Officer to expand investigations. Providers are tried in order until results are found.

# Perplexity AI - AI-powered search with reasoning (recommended)
PERPLEXITY_API_KEY=pplx-...

# SearXNG - Self-hosted metasearch engine (for privacy)
SEARXNG_API_URL=http://localhost:8081

# Serper - Google Search API wrapper
SERPER_API_KEY=...

# Tavily - AI search optimized for LLM agents
TAVILY_API_KEY=tvly-...

Variable	Provider	Best For
PERPLEXITY_API_KEY	Perplexity	AI research with domain filtering
SEARXNG_API_URL	SearXNG	Privacy-focused self-hosted
SERPER_API_KEY	Serper	Google Search results
TAVILY_API_KEY	Tavily	AI-optimized search

📖 Full Guide: See Sofia Search Service

Document Reader Cascade

Used by Case Officer to read and extract content from web sources. Readers are tried in order until content is extracted.

# Perplexity - AI extraction, no size limits (recommended)
PERPLEXITY_API_KEY=pplx-...

# Jina Reader - Converts web pages to clean markdown
JINA_API_KEY=jina_...

# AgentQL - AI-powered web content extraction (JS-heavy sites)
AGENTQL_API_KEY=...

Variable	Reader	Best For
PERPLEXITY_API_KEY	Perplexity	Large documents, intelligent extraction
JINA_API_KEY	Jina	Articles, web pages
AGENTQL_API_KEY	AgentQL	JavaScript-heavy sites

Falls back to simple HTTP if none configured.

📖 Full Guide: See Document Reader Service

Aryn PDF Reader

AI-powered PDF partitioning with context-aware schema extraction. Provides intelligent PDF preview with investigation-relevant metadata.

# Get your API key at https://console.aryn.ai/
ARYN_API_KEY=...

When configured, Aryn provides:

• Context-aware extraction: Uses investigation query and research domain
• AI-inferred schema: Structured metadata tailored to research
• OCR language support: Optimized for non-English documents
• Content hypotheses: Relevance assessments for each PDF

📖 Full Guide: See Archive Domains Configuration

---

Model Configuration

BASE_MODEL=gpt-4o-mini
COMPLEX_MODEL=gpt-4o
BASE_PROVIDER=openai
COMPLEX_PROVIDER=openai
MODEL_API_BASE=https://api.openai.com/v1

Variable	Default	Description
BASE_MODEL	gpt-4o-mini	Model for simple queries
COMPLEX_MODEL	gpt-4o	Model for complex analysis
BASE_PROVIDER	(auto)	Provider for BASE_MODEL
COMPLEX_PROVIDER	(auto)	Provider for COMPLEX_MODEL
MODEL_API_BASE	(provider default)	Custom API base URL

GPT-5 Specific

GPT5_REASONING_EFFORT=medium
GPT5_TEXT_VERBOSITY=low

Variable	Values	Default	Description
GPT5_REASONING_EFFORT	minimal, low, medium, high	medium	Reasoning depth
GPT5_TEXT_VERBOSITY	low, medium, high	medium	Output verbosity

---

Application Configuration

Logging

LOGGING_LEVEL=INFO

Value	Description
DEBUG	Verbose debugging
INFO	Standard logging (recommended)
WARNING	Warnings only
ERROR	Errors only

Timeouts

CLIENT_TIMEOUT=60
TREE_TIMEOUT=300
USER_TIMEOUT=600

Variable	Default	Description
CLIENT_TIMEOUT	60	LLM client timeout (seconds)
TREE_TIMEOUT	300	Decision tree timeout (seconds)
USER_TIMEOUT	600	User session timeout (seconds)

Environment

ENVIRONMENT=development
NODE_ENV=development

Value	Description
development	Dev mode with hot reload
production	Production optimizations

Frontend

NEXTJS_DEV_URL=http://localhost:3000

---

Pipeline & Ingestion

PIPELINE_DATA_DIR=/app/data
PIPELINE_USER_ID=your-user-id
BATCH_WAIT_SECONDS=4
PIPELINE_AUTO_PREPROCESS=true
PIPELINE_AUTO_GEOCODE=false

Variable	Default	Description
PIPELINE_DATA_DIR	/app/data	Directory to watch for files
PIPELINE_USER_ID	(required)	User ID for uploads
BATCH_WAIT_SECONDS	4	Wait time before batch processing
PIPELINE_AUTO_PREPROCESS	true	Auto-preprocess documents
PIPELINE_AUTO_GEOCODE	false	Auto-geocode locations

Unstructured API (Optional)

UNSTRUCTURED_API_URL=https://api.unstructuredapp.io
UNSTRUCTURED_API_KEY=...

---

Geospatial Services

MAPBOX_ACCESS_TOKEN=pk.eyJ...

Variable	Required	Description
MAPBOX_ACCESS_TOKEN	For maps	Mapbox API token

Get a token at account.mapbox.com/access-tokens

---

Security

FERNET_KEY=your-fernet-key-for-encryption

Variable	Description
FERNET_KEY	Encryption key for sensitive data

Generate a key:

from cryptography.fernet import Fernet
print(Fernet.generate_key().decode())

---

Testing

TESTING_WCD_URL=https://your-test-cluster.weaviate.cloud
TESTING_WCD_API_KEY=your-test-weaviate-api-key
HF_TOKEN=hf_...

Variable	Description
TESTING_WCD_URL	Separate Weaviate for tests
TESTING_WCD_API_KEY	Test cluster API key
HF_TOKEN	HuggingFace token for model downloads

---

Minimal Configuration

For quick development setup:

# Weaviate (local Docker)
WEAVIATE_IS_LOCAL=True
LOCAL_WEAVIATE_PORT=8080
LOCAL_WEAVIATE_GRPC_PORT=50051

# LLM Provider (at least one)
OPENAI_API_KEY=sk-proj-your-key-here

# Models
BASE_MODEL=gpt-4o-mini
COMPLEX_MODEL=gpt-4o

# Logging
LOGGING_LEVEL=INFO

---

Production Configuration

Recommended production settings:

# Weaviate Cloud
WCD_URL=https://production.weaviate.cloud
WCD_API_KEY=prod-api-key

# Models
BASE_MODEL=gpt-4o-mini
COMPLEX_MODEL=gpt-4o

# OpenAI
OPENAI_API_KEY=sk-proj-production-key

# Anthropic (for location enrichment)
ANTHROPIC_API_KEY=sk-ant-production-key

# Mapbox (for maps)
MAPBOX_ACCESS_TOKEN=pk.production-token

# Logging
LOGGING_LEVEL=WARNING

# Environment
ENVIRONMENT=production

# Security
FERNET_KEY=production-fernet-key

# Timeouts (longer for production)
CLIENT_TIMEOUT=120
TREE_TIMEOUT=600

---

Troubleshooting

Check Environment

# Print all set variables
grep -v '^#' backend/.env | grep -v '^$'

# Verify specific variable
echo $OPENAI_API_KEY

Common Issues

Issue	Cause	Solution
"API key not set"	Missing key	Add to .env
"Connection refused"	Wrong Weaviate URL	Check WEAVIATE settings
"Model not found"	Invalid model name	Check model spelling
"Timeout"	Settings too low	Increase timeout values

---

See Also

• Getting Started - Setup guide
• LLM Configuration - Model details
• Document Processing - Pipeline setup