.env.example

# Qdrant connection
QDRANT_URL=http://localhost:6333
# QDRANT_API_KEY=

# Multi-repo mode: 0=single-repo (default), 1=multi-repo
# Single-repo: All files go into one collection (COLLECTION_NAME)
# Multi-repo: Each subdirectory gets its own collection
MULTI_REPO_MODE=0

# Logical repo reuse (experimental): 0=disabled (default), 1=enable logical_repo_id-based
# collection reuse across git worktrees / clones. When enabled, indexer, watcher, and
# upload service will try to reuse a canonical collection per logical repository and
# use (repo_id + repo_rel_path) for skip-unchanged across worktrees.
#LOGICAL_REPO_REUSE=0

# Single unified collection for seamless cross-repo search (default: "codebase")
# Leave unset or use "codebase" for unified search across all your code
COLLECTION_NAME=codebase


# Embeddings
EMBEDDING_MODEL=BAAI/bge-base-en-v1.5
EMBEDDING_PROVIDER=fastembed
# Optional repo tag attached to each payload
REPO_NAME=workspace

# Qwen3-Embedding Feature Flag (optional, experimental)
# Enable to use Qwen3-Embedding-0.6B instead of BGE-base (requires reindex)
# QWEN3_EMBEDDING_ENABLED=0
# When enabled, set EMBEDDING_MODEL to the Qwen3 model:
# EMBEDDING_MODEL=electroglyph/Qwen3-Embedding-0.6B-onnx-uint8
# Add instruction prefix to search queries (recommended for Qwen3)
# QWEN3_QUERY_INSTRUCTION=1
# Custom instruction text (default: code search instruction)
# QWEN3_INSTRUCTION_TEXT=Instruct: Given a code search query, retrieve relevant code snippets\nQuery:

# Cross-Codebase Isolation (multi-repo search scoping)
# When enabled, search results are automatically filtered to the current repo
# Disable (=0) to search all repos by default (legacy behavior)
REPO_AUTO_FILTER=1
# Explicitly set current repo (overrides auto-detection from git/directory)
# CURRENT_REPO=my-project

# MCP servers (SSE)
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8000            # search/store MCP (mcp-server-qdrant)
FASTMCP_INDEXER_PORT=8001    # companion indexer MCP (index/prune/list)
FASTMCP_SERVER_NAME=qdrant-mcp
# MCP_MAX_LOG_TAIL=4000      # Max chars for subprocess stdout/stderr tail (default: 4000)

# Logging configuration
# LOG_LEVEL controls verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO

# Transport: sse (default), http (streamable), or stdio
FASTMCP_TRANSPORT=sse


# Optional duplicate Streamable HTTP instances (run alongside SSE)
# Use these in docker-compose overrides to expose /mcp/ on separate ports.
FASTMCP_HTTP_TRANSPORT=http
FASTMCP_HTTP_PORT=8002
FASTMCP_HTTP_HEALTH_PORT=18002
FASTMCP_INDEXER_HTTP_PORT=8003
FASTMCP_INDEXER_HTTP_HEALTH_PORT=18003
# MCP_INDEXER_URL=http://localhost:8003/mcp


# Reranker settings (FastEmbed model - recommended)
# Set RERANKER_MODEL to enable cross-encoder reranking (auto-downloads ONNX model)
# Popular models: jinaai/jina-reranker-v2-base-multilingual, BAAI/bge-reranker-base
# RERANKER_MODEL=jinaai/jina-reranker-v2-base-multilingual

# Legacy: manual ONNX paths (alternative to RERANKER_MODEL)
# Use these if you have a custom ONNX model or want explicit control
# RERANKER_ONNX_PATH=/work/models/model_qint8_avx512_vnni.onnx
# RERANKER_TOKENIZER_PATH=/work/models/tokenizer.json

# Enable reranking in the indexer MCP search path
RERANKER_ENABLED=0
# Tuning knobs (effective when enabled)
RERANKER_TOPN=50
RERANKER_RETURN_M=12
RERANKER_TIMEOUT_MS=2000

# Post-rerank symbol boost: ensures exact symbol matches rank highest even when
# the neural reranker disagrees. Applied after rerank blending as a direct score addition.
# Set to 0 to disable, >1.0 to boost symbol matches more aggressively.
POST_RERANK_SYMBOL_BOOST=1.0
# Rerank blend weight: ratio of rerank score vs fusion score (0.0-1.0)
# Higher = more weight on neural reranker, lower = more weight on lexical/symbol boosts
RERANK_BLEND_WEIGHT=0.6

# Safety: minimum rerank timeout floor (ms) to avoid cold-start timeouts
RERANK_TIMEOUT_FLOOR_MS=1000

# Optional warmups (disabled by default)
EMBEDDING_WARMUP=0
RERANK_WARMUP=0


# In-process execution (faster; falls back to subprocess on failure)
HYBRID_IN_PROCESS=1
RERANK_IN_PROCESS=1

# Parallel dense query execution (for multi-query searches)
# Queries >= threshold are executed in parallel using thread pool
# Set higher to avoid thread overhead on small query counts; set 1 to always parallelize
PARALLEL_DENSE_QUERIES=1
PARALLEL_DENSE_THRESHOLD=4

# LLM query expansion (uses existing decoder infrastructure)
# Set REFRAG_RUNTIME=glm|minimax|llamacpp to choose runtime (defaults to llamacpp)
# Requires REFRAG_DECODER=1 for llama.cpp path
# EXPAND_MAX_TOKENS=512  # Max tokens for expansion response (default: 512)

# PRF (Pseudo-Relevance Feedback) - enabled by default
# Mines top terms from search results for a refined second pass
# PRF_ENABLED=1
# PRF_TOP_DOCS=8
# PRF_MAX_TERMS=6

# Semantic expansion settings (synonym/related term expansion for better recall)
SEMANTIC_EXPANSION_ENABLED=1
SEMANTIC_EXPANSION_TOP_K=5
SEMANTIC_EXPANSION_SIMILARITY_THRESHOLD=0.7
SEMANTIC_EXPANSION_MAX_TERMS=3
SEMANTIC_EXPANSION_CACHE_SIZE=1000
SEMANTIC_EXPANSION_CACHE_TTL=3600
# Hybrid search tuning
# HYBRID_EXPAND=0
# HYBRID_PER_PATH=2
# HYBRID_SYMBOL_BOOST=0.35
# HYBRID_RECENCY_WEIGHT=0.1
# RERANK_EXPAND=1

# Caching (embeddings and search results)
# MAX_EMBED_CACHE=16384
# HYBRID_RESULTS_CACHE=128
# HYBRID_RESULTS_CACHE_ENABLED=1

# Query Optimization (adaptive HNSW_EF tuning for 2x faster simple queries)
QUERY_OPTIMIZER_ADAPTIVE=1
QUERY_OPTIMIZER_MIN_EF=64
QUERY_OPTIMIZER_MAX_EF=512
QUERY_OPTIMIZER_SIMPLE_THRESHOLD=0.3
QUERY_OPTIMIZER_COMPLEX_THRESHOLD=0.7
QUERY_OPTIMIZER_SIMPLE_FACTOR=0.5
QUERY_OPTIMIZER_SEMANTIC_FACTOR=1.0
QUERY_OPTIMIZER_COMPLEX_FACTOR=2.0
QUERY_OPTIMIZER_DENSE_THRESHOLD=0.2
QUERY_OPTIMIZER_COLLECTION_SIZE=10000
QDRANT_EF_SEARCH=128

# AST-based code understanding (semantic chunking for 20-30% better precision)
USE_TREE_SITTER=1
INDEX_USE_ENHANCED_AST=1
INDEX_SEMANTIC_CHUNKS=1

# Pattern Search - structural code similarity across languages
# Enables pattern_search MCP tool and indexes 64-dim pattern vectors
# Uses WL graph kernel, CFG fingerprints, SimHash, spectral features
# PATTERN_VECTORS=1

# Indexer scaling and exclusions
# QDRANT_DEFAULT_EXCLUDES=0
# QDRANT_IGNORE_FILE=.qdrantignore
# QDRANT_EXCLUDES=tokenizer.json,*.onnx,/vendor
# INDEX_CHUNK_LINES=120
# INDEX_CHUNK_OVERLAP=20
# INDEX_BATCH_SIZE=64
# INDEX_PROGRESS_EVERY=200


# ReFRAG mode (optional): compact gating + micro-chunking
# Enable to add a 64-dim mini vector for fast gating and use token-based micro-chunks
REFRAG_MODE=0
MINI_VECTOR_NAME=mini
MINI_VEC_DIM=64
MINI_VEC_SEED=1337
HYBRID_MINI_WEIGHT=0.5
# Micro-chunking controls (token-based)
INDEX_MICRO_CHUNKS=0
MICRO_CHUNK_TOKENS=16
MICRO_CHUNK_STRIDE=8
# Optional: gate-first using mini vectors to prefilter dense search
REFRAG_GATE_FIRST=0
REFRAG_CANDIDATES=200

# Lexical vector settings (v2: multi-hash + bigrams for better keyword matching)
LEX_VECTOR_NAME=lex
LEX_VECTOR_DIM=2048
# Multi-hash: each token hashes to N buckets (more = better collision resistance, default 3)
LEX_MULTI_HASH=3
# Bigrams: enable bigram hashing for phrase matching (default on)
LEX_BIGRAMS=1
# Weight for bigram entries relative to unigrams
LEX_BIGRAM_WEIGHT=0.7
# Sparse lexical vectors: lossless exact matching (no hash collisions)
# When enabled, stores sparse vectors alongside dense for exact term matching
LEX_SPARSE_MODE=0
LEX_SPARSE_NAME=lex_sparse

# Output shaping for micro spans
# Defaults are runtime-aware: GLM uses higher values automatically
# GLM + micro chunks: 24 spans, 8192 tokens | GLM + semantic: 12 spans, 4096 tokens
# Granite/llamacpp: 3 spans, 512 tokens
# Set these to override the computed defaults:
# MICRO_OUT_MAX_SPANS=24
# MICRO_MERGE_LINES=6
# MICRO_BUDGET_TOKENS=8192
# MICRO_TOKENS_PER_LINE=32


# Decoder-path ReFRAG (feature-flagged; off by default)
REFRAG_DECODER=0
# Runtime selection: openai, glm, minimax, llamacpp (default)
# Set explicitly - no auto-detection to avoid surprise API calls
REFRAG_RUNTIME=llamacpp
REFRAG_ENCODER_MODEL=BAAI/bge-base-en-v1.5
REFRAG_PHI_PATH=/work/models/refrag_phi_768_to_dmodel.json
REFRAG_SENSE=heuristic

# Enable index-time pseudo descriptions for micro-chunks (requires REFRAG_DECODER)
REFRAG_PSEUDO_DESCRIBE=1

# Llama.cpp sidecar (optional)
# Docker CPU-only (stable): http://llamacpp:8080
# Native GPU-accelerated (fast): http://localhost:8081
LLM_PROVIDER=ollama
OLLAMA_HOST=http://host.docker.internal:11434
LLAMACPP_URL=http://llamacpp:8080
REFRAG_DECODER_MODE=prompt  # prompt|soft

# OpenAI decoder backend (GPT-4.1, GPT-4.1-mini, o1, etc.)
# OPENAI_API_KEY=sk-your-openai-api-key
# OPENAI_MODEL=gpt-4.1-mini
# OPENAI_API_BASE=https://api.openai.com/v1  # or Azure/compatible endpoint

# GLM (ZhipuAI) decoder backend
# Supports GLM-4.5, GLM-4.6, GLM-4.7 with version-specific defaults
# GLM-4.7: temp=1.0, top_p=0.95, max_output=128K, context=200K, tool_stream support
# GLM-4.6: temp=1.0, top_p=0.95, thinking support
# GLM-4.5: temp=1.0, top_p=0.95, fast model (thinking can be disabled)
# GLM_API_BASE=https://api.z.ai/api/coding/paas/v4/
# GLM_MODEL=glm-4.6
# GLM_MODEL_FAST=glm-4.5
# GLM_API_KEY=your_glm_api_key_here

# Answer shaping (enforce concise responses from context_answer)
# CTX_SUMMARY_CHARS=0
# CTX_SNIPPET_CHARS=400
# DECODER_MAX_TOKENS=4000

# Parallel pseudo-tag generation (indexing speedup)
# Set to 4 for 4x parallel GLM calls during indexing; 1 = sequential (default)
# PSEUDO_BATCH_CONCURRENCY=4

# MiniMax M2 decoder backend (OpenAI-compatible API)
# MINIMAX_API_BASE=https://api.minimax.io/v1
# MINIMAX_MODEL=MiniMax-M2
# MINIMAX_API_KEY=your_minimax_api_key_here

# GPU Performance Toggle
# Set to 1 to use native GPU-accelerated server on localhost:8081
# Set to 0 to use Docker CPU-only server (default, stable)
USE_GPU_DECODER=0

REFRAG_SOFT_SCALE=1.0

# Llama.cpp runtime tuning
LLAMACPP_USE_GPU=0           # Set to 1 to enable Metal/CLBlast acceleration
# LLAMACPP_GPU_LAYERS=-1     # Override number of layers to offload (defaults to -1 when USE_GPU=1)
# LLAMACPP_GPU_SPLIT=         # Optional tensor split for multi-GPU setups
# LLAMACPP_THREADS=           # Override number of CPU threads
# LLAMACPP_CTX_SIZE=8192      # Context tokens; higher values need more VRAM
# LLAMACPP_EXTRA_ARGS=        # Additional flags passed verbatim to llama.cpp

# Operational safeguards and timeouts
# Limit explosion of micro-chunks on huge files (0 to disable)
MAX_MICRO_CHUNKS_PER_FILE=2000
# Qdrant request timeout (seconds)
QDRANT_TIMEOUT=20
# Memory collection auto-detection cache
MEMORY_AUTODETECT=1
MEMORY_COLLECTION_TTL_SECS=300

# Smarter re-indexing for symbol cache, reuse embeddings and reduce decoder/pseudo tags to re-index
SMART_SYMBOL_REINDEXING=1
MAX_CHANGED_SYMBOLS_RATIO=0.6

# Watcher-safe defaults (recommended)
# Applied to watcher via compose; uncomment to apply globally.
# Qdrant write/read timeout (seconds)
# QDRANT_TIMEOUT=60
# Cap per-file micro-chunks (keeps upserts small)
# MAX_MICRO_CHUNKS_PER_FILE=200
# Upsert batching + retries for large payloads
# INDEX_UPSERT_BATCH=128
# INDEX_UPSERT_RETRIES=5
# INDEX_UPSERT_BACKOFF=0.5
# Debounce file events to coalesce bursts
# WATCH_DEBOUNCE_SECS=1.5
# Optional fs metadata fast-path for unchanged files (skips re-reading files
# when size/mtime match cache.json in the same workspace).
# INDEX_FS_FASTPATH=0
# Optional 2-phase pseudo/tag mode (disabled by default).
# When enabled, indexer/watcher skip inline pseudo/tag generation and a background
# backfill worker adds them asynchronously via Qdrant.
# PSEUDO_DEFER_TO_WORKER=1
# Backfill worker settings (only used when PSEUDO_DEFER_TO_WORKER=1):
# PSEUDO_BACKFILL_DEBUG=0
# PSEUDO_BACKFILL_TICK_SECS=60
# PSEUDO_BACKFILL_MAX_POINTS=256

# Development Remote Upload Configuration
# HOST_INDEX_PATH=./dev-workspace

# Remote upload git history (used by upload clients)
# Max number of commits to include per bundle (0 disables git history)
REMOTE_UPLOAD_GIT_MAX_COMMITS=500
# Optional git log since filter, e.g. '6 months ago' or '2024-01-01'
# REMOTE_UPLOAD_GIT_SINCE=
# Force full snapshot manifests instead of incremental deltas
# REMOTE_UPLOAD_GIT_FORCE=0

# Git history ingestion cleanup
# When ingesting a snapshot git history manifest, prune any older git_message points
# for the same repo that are not part of the latest snapshot run.
GIT_HISTORY_PRUNE=1
# Delete git_history_*.json manifest files under .remote-git after successful ingest.
# This prevents unbounded accumulation of manifests on the server.
GIT_HISTORY_DELETE_MANIFEST=1
# If keeping manifests, cap how many git_history_*.json files to keep per .remote-git dir
# (oldest beyond this count are deleted). Set 0 to disable.
GIT_HISTORY_MANIFEST_MAX_FILES=50

# Enable commit lineage goals for indexing
REFRAG_COMMIT_DESCRIBE=1
COMMIT_VECTOR_SEARCH=0

STRICT_MEMORY_RESTORE=1

# info_request() tool settings (simplified codebase retrieval)
# Default result limit for info_request queries
INFO_REQUEST_LIMIT=10
# Default context lines in snippets (richer than repo_search default)
INFO_REQUEST_CONTEXT_LINES=5
# Enable explanation mode by default (summary, primary_locations, related_concepts)
# INFO_REQUEST_EXPLAIN_DEFAULT=0
# Enable relationship mapping by default (imports_from, calls, related_paths)
# INFO_REQUEST_RELATIONSHIPS=0

# TOON output format (Token-Oriented Object Notation)
# When enabled, search results use compact TOON encoding to reduce token usage
# TOON_ENABLED=0


# ---------------------------------------------------------------------------
# OpenLit Observability (OFF by default)
# ---------------------------------------------------------------------------
# Self-hosted LLM/vector-DB tracing via OpenTelemetry.
#
# Dashboard: http://localhost:3000
#   Email: user@openlit.io
#   Password: openlituser
#
# To enable: set OPENLIT_ENABLED=1 and ensure openlit SDK is installed.
# Traces LLM calls (GLM, Ollama, llama.cpp) and Qdrant operations automatically.

# Master toggle for OpenLit instrumentation
OPENLIT_ENABLED=0

# OTLP endpoint for trace export (OpenLit's built-in collector)
# Port 4317 = gRPC, Port 4318 = HTTP (default)
OTEL_EXPORTER_OTLP_ENDPOINT=http://openlit:4318

# Application name shown in traces
OPENLIT_APP_NAME=context-engine

# Environment tag for filtering traces (development, staging, production)
OPENLIT_ENVIRONMENT=development

# ClickHouse backend (used by OpenLit for storing traces)
# OPENLIT_CLICKHOUSE_HOST=clickhouse
# OPENLIT_CLICKHOUSE_PORT=8123
# OPENLIT_CLICKHOUSE_USER=default
# OPENLIT_CLICKHOUSE_PASSWORD=OPENLIT
# OPENLIT_CLICKHOUSE_DATABASE=openlit



# ---------------------------------------------------------------------------
# Optional Auth & Bridge Configuration (OFF by default)
# ---------------------------------------------------------------------------

# Global auth toggle for backend services (upload_service, MCP indexer/memory).
# When set to 1, services will require a valid session for protected operations.
# When unset or 0, auth is disabled and behavior matches previous versions.
# CTXCE_AUTH_ENABLED=0

# Shared token used by /auth/login for the bridge and other service clients.
# When CTXCE_AUTH_ENABLED=1 and this is set, /auth/login will only issue
# sessions when the provided token matches this value.
# CTXCE_AUTH_SHARED_TOKEN=change-me-dev-token

# Create "open-dev" tokens when a shared token is unset, basically allows requesting a session with no real auth
# CTXCE_AUTH_ALLOW_OPEN_TOKEN_LOGIN=0

# Optional admin token for creating additional users via /auth/users once the
# first user has been bootstrapped. If unset, only the initial user can be
# created (no additional users).
# CTXCE_AUTH_ADMIN_TOKEN=change-me-admin-token

# Auth database location (default: sqlite file under WORK_DIR/.codebase).
# Use a SQLite URL for local/dev, or point to a different path.
# CTXCE_AUTH_DB_URL=sqlite:////work/.codebase/ctxce_auth.sqlite

# Session TTL (seconds) for issued auth sessions.
# 0 or negative values disable expiry (sessions do not expire). When >0,
# active sessions are extended with a sliding window whenever they are used.
# CTXCE_AUTH_SESSION_TTL_SECONDS=0

# Collection registry & ACL (only used when CTXCE_AUTH_ENABLED=1).
# When enabled, infrastructure/health checks may populate an internal SQLite
# registry of known Qdrant collections, and ACL rules can be applied by services.

# Admin collection deletion (dangerous). Set to 1 to allow the Admin UI to delete
# Qdrant collections and related server-managed workspaces. Leave 0/empty to
# completely disable collection deletion endpoints.
# CTXCE_ADMIN_COLLECTION_DELETE_ENABLED=0

# Collection registry sync behavior: when set to 1, a collection that is marked
# deleted in the auth DB (is_deleted=1) will be automatically un-deleted
# (is_deleted=0) if it reappears in Qdrant during registry discovery (e.g. via
# scripts/health_check.py). Default is OFF.
# CTXCE_COLLECTION_REGISTRY_UNDELETE_ON_DISCOVERY=0

# ACL bypass (dev/early deployments): allow all users to access all collections.
# CTXCE_ACL_ALLOW_ALL=0

# MCP boundary enforcement (OFF by default).
# When enabled, MCP servers will enforce collection ACLs using the auth DB.
# Requires CTXCE_AUTH_ENABLED=1. If CTXCE_ACL_ALLOW_ALL=1, enforcement is bypassed.
# This is intended for gradually rolling out collection-level permissions without
# changing existing client auth/session mechanisms.
# CTXCE_MCP_ACL_ENFORCE=0

# Bridge-side configuration (ctx-mcp-bridge):
# The bridge will POST to this URL for auth login and store the returned
# session id, then inject it into all MCP tool calls as the `session` field.
# CTXCE_AUTH_BACKEND_URL=http://localhost:8004

# Optional defaults for bridge CLI (env) auth:
# CTXCE_AUTH_TOKEN=dev-shared-token
# CTXCE_AUTH_USERNAME=you@example.com
# CTXCE_AUTH_PASSWORD=your-password

# Controls cloning original collection into _old collection, recreating (full reindex) of a collection
# so that search is not blocked while reindexing. Bridge can route queries to _old. Uploads go to both
# original and _old collection
# CTXCE_STAGING_ENABLED=0

# Collection copy timeout (seconds) - falls back to QDRANT_TIMEOUT if not set
# Note: Qdrant enforces its own request deadline. Bump QDRANT_TIMEOUT (and matching timeout in your Qdrant config)
# to something large (e.g. 600 seconds) so the server doesn't drop long-running scrolls.
# CTXCE_COPY_COLLECTION_TIMEOUT=1800 # 30 mins, should be compatible with QDRANT timeout value

# Collection copy batching and verification
# CTXCE_COPY_COLLECTION_BATCH=128
# CTXCE_COPY_VERIFY_RETRIES=3
# CTXCE_COPY_VERIFY_DELAY=2         # Delay in seconds between verification retries

# Admin UI refresh interval for staging status (milliseconds)
# CTXCE_ADMIN_COLLECTION_REFRESH_MS=30000 # 30s

# Snapshot refresh dry-run mode - preview snapshot refresh operations without executing
# CTXCE_SNAPSHOT_REFRESH_DRY_RUN=0

# Force collection name - ingest_code subprocess flag for admin-driven runs (staging rebuild).
# When set to 1, forces ingest_code to honor explicit COLLECTION_NAME even in multi-repo mode.
# This is primarily used by admin subprocess runs that supply per-repo indexing_env overrides.
# Normal watcher and indexer flows do not set this.
# CTXCE_FORCE_COLLECTION_NAME=0

# Collection mapping cache TTL - seconds to cache collection mapping index lookups
# CTXCE_COLLECTION_MAPPING_INDEX_TTL_SECS=5

# Bridge state token - optional shared token for bridge state validation
# CTXCE_BRIDGE_STATE_TOKEN=

# ---------------------------------------------------------------------------
# End of Auth & Bridge Configuration
# ---------------------------------------------------------------------------