From 429d2ac7bc6892abfa48bf8c50d9fafce168f41b Mon Sep 17 00:00:00 2001
From: furyhawk <furyx@hotmail.com>
Date: Sun, 14 Jun 2026 19:01:58 +0800
Subject: [PATCH] feat: Update .env.example with structured configuration
 sections for better clarity

---
 .env.example | 48 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 40 insertions(+), 8 deletions(-)

diff --git a/.env.example b/.env.example
index 14dac78..c053faf 100644
--- a/.env.example
+++ b/.env.example
@@ -1,21 +1,53 @@
-# Set to true to enable debug logging and SQL echo
+# ── Debugging ──────────────────────────────────────────────────────────────
+# Set to true to enable debug logging and SQLAlchemy echo
 DEBUG=false
 
-# OpenAI-compatible API configuration
+# ── LLM (OpenAI-compatible) ────────────────────────────────────────────────
 LLM_BASE_URL=http://host.docker.internal:11434/v1
 LLM_MODEL=llama
+# Leave empty for local servers like Ollama / llama.cpp
+LLM_API_KEY=
 
+# ── AI Agent ────────────────────────────────────────────────────────────────
+# Model used by pydantic-ai for agent reasoning (e.g. gpt-4o, claude-sonnet-4)
+AI_MODEL=gpt-4o
+
+# ── Embeddings ─────────────────────────────────────────────────────────────
+# If EMBEDDING_BASE_URL is empty, the LLM base URL is used instead
 EMBEDDING_BASE_URL=http://host.docker.internal:11434/v1
 EMBEDDING_API_KEY=
 
-# API key for the LLM provider (leave empty for local servers like Ollama)
-LLM_API_KEY=
-
-# Logfire observability (set your token to enable)
+# ── Observability ──────────────────────────────────────────────────────────
+# Set LOGFIRE_TOKEN to enable Logfire telemetry; omit to disable
 LOGFIRE_TOKEN=
 
-# PostgreSQL (asyncpg connection string)
+# ── PostgreSQL ─────────────────────────────────────────────────────────────
 DATABASE_URL=postgresql+asyncpg://agent_alpha:agent_alpha@postgres:5432/agent_alpha
 
-# Valkey / Redis
+# ── Valkey / Redis (cache + chat persistence) ──────────────────────────────
 VALKEY_URL=redis://valkey:6379/0
+
+# ── Redis pub/sub (separate connection for RAG status SSE) ─────────────────
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+
+# ── Milvus (vector database for RAG) ───────────────────────────────────────
+MILVUS_URI=http://localhost:19530
+MILVUS_TOKEN=
+
+# ── File / Media Storage ──────────────────────────────────────────────────
+MEDIA_DIR=media
+MAX_UPLOAD_SIZE_MB=50
+
+# ── RAG Parser ─────────────────────────────────────────────────────────────
+PDF_PARSER=pymupdf
+
+# ── Cross-Encoder Reranker ─────────────────────────────────────────────────
+CROSS_ENCODER_MODEL=cross-encoder/ms-marco-MiniLM-L6-v2
+HF_TOKEN=
+MODELS_CACHE_DIR=~/.cache/agent-alpha/models
+
+# ── RAG Image Description ──────────────────────────────────────────────────
+# Model to use for describing images in RAG documents (empty = disabled)
+RAG_IMAGE_DESCRIPTION_MODEL=