docs(agent): add comprehensive module docstring and inline comments

psagentai_agent.py

@@ -1,7 +1,27 @@
 #!/usr/bin/env python3
 """
-PsAgentAI - Personal Conversational AI Agent
-Personal Conversational AI Agent system via Telegram
+PsAgentAI - Personal Conversational AI Agent.
+
+A Telegram-based conversational AI agent that acts as a personal companion.
+It maintains long-term memory through user/agent profiles, manages daily routines,
+supports file uploads/workspace editing, performs web searches, analyzes images,
+and sends proactive messages based on configured schedules.
+
+Main components:
+- Telegram bot handlers (commands, messages, voice, photos, documents)
+- AI provider abstraction (OpenRouter, StepFun, QwenCloud, llama.cpp)
+- Profile management (user and agent) with auto-enrichment
+- Conversation context storage organized by date
+- Workspace file creation/editing via AI
+- Web search integration via DuckDuckGo HTML
+- Vision/image analysis support
+- Proactive messaging loop with schedule awareness
+- System auto-improvement based on conversation analysis
+
+Typical usage:
+    python3 psagentai_agent.py
+
+Environment variables are loaded from .env via python-dotenv.
 """
 
 __version__ = "1.0.0"
@@ -52,15 +72,24 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 # ===================== CONFIGURATION =====================
+# Environment variables loaded from .env. Defaults are provided for optional
+# settings; required values must be set before running the agent.
 
+# --- Telegram ---
+# Bot token from @BotFather and target chat ID for proactive messages.
 TELEGRAM_BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN", "")
 TELEGRAM_CHAT_ID = os.getenv("TELEGRAM_CHAT_ID", "")
 TELEGRAM_CHAT_ID_FILE = "telegram_chat_id.json"
+
+# --- AI provider ---
+# Primary model and provider. Provider can be forced via AI_PROVIDER env var.
 DEFAULT_MODEL = os.getenv("DEFAULT_MODEL", "poolside/laguna-s-2.1:free")
 AI_PROVIDER = os.getenv("AI_PROVIDER", "").strip().lower()
 
+# Fallback chain used when the primary model/provider fails.
 FALLBACK_MODELS = os.getenv("FALLBACK_MODELS", "poolside/laguna-s-2.1:free,google/gemini-2.0-flash-lite-preview-02-05:free").split(",")
 
+# Provider-specific API keys and base URLs.
 OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY", "")
 OPENROUTER_API_URL = os.getenv("OPENROUTER_API_URL", "https://openrouter.ai/api/v1")
 
@@ -72,12 +101,20 @@ QWENCLOUD_API_URL = os.getenv("QWENCLOUD_API_URL", "https://dashscope.aliyuncs.c
 
 LLAMA_CPP_API_URL = os.getenv("LLAMA_CPP_API_URL", "http://localhost:8080/v1")
 
+# --- Behavior tuning ---
+# Proactive message interval bounds (minutes).
 MIN_INTERVAL_MINUTES = int(os.getenv("MIN_INTERVAL_MINUTES", "3"))
 MAX_INTERVAL_MINUTES = int(os.getenv("MAX_INTERVAL_MINUTES", "30"))
+
+# Context/history limits.
 MAX_HISTORY_LENGTH = int(os.getenv("MAX_HISTORY_LENGTH", "50"))
 UPLOAD_CONTEXT_MAX_CHARS = int(os.getenv("UPLOAD_CONTEXT_MAX_CHARS", "8000"))
+
+# Web search toggle and result cap.
 WEB_SEARCH_ENABLED = os.getenv("WEB_SEARCH_ENABLED", "true").lower() in ("true", "1", "yes")
 WEB_SEARCH_MAX_RESULTS = int(os.getenv("WEB_SEARCH_MAX_RESULTS", "5"))
+
+# --- Vision / image analysis ---
 VISION_MODEL = os.getenv("VISION_MODEL", "meta-llama/llama-4-maverick-17b-128e-instruct")
 VISION_PROVIDER = os.getenv("VISION_PROVIDER", "").strip().lower()
 if not VISION_PROVIDER:
@@ -86,10 +123,16 @@ if not VISION_PROVIDER:
     except Exception:
         VISION_PROVIDER = "openrouter"
 
+# --- Persistence ---
 USER_PROFILE_FILE = os.getenv("USER_PROFILE_FILE", "user_profile.json")
 AGENT_PROFILE_FILE = os.getenv("AGENT_PROFILE_FILE", "agent_profile.json")
 CONTEXTS_DIR = os.getenv("CONTEXTS_DIR", "contexts")
+
+# --- Agent behavior ---
+# Minimum lines the agent should produce per response.
 MIN_MESSAGE_LINES = int(os.getenv("MIN_MESSAGE_LINES", "3"))
+
+# Auto-improvement system toggle and frequency.
 AUTO_IMPROVE_ENABLED = os.getenv("AUTO_IMPROVE_ENABLED", "true").lower() in ("true", "1", "yes")
 AUTO_IMPROVE_EVERY = int(os.getenv("AUTO_IMPROVE_EVERY", "20"))