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

iniciar.sh

@@ -1,85 +1,128 @@
 #!/bin/bash
-set -e
+# =============================================================================
+# PsAgentAI - Setup and Run Script
+# =============================================================================
+# Purpose: Create Python virtual environment, install dependencies,
+#          validate .env configuration, and start the agent.
+# Usage:   ./iniciar.sh
+# =============================================================================
 
+set -e  # Exit immediately on any command failure
+
+# -----------------------------------------------------------------------------
+# Banner
+# -----------------------------------------------------------------------------
 echo "=========================================="
 echo "   PsAgentAI - Personal Agent AI Conversacional"
 echo "=========================================="
 echo ""
 
-# Check Python 3
+# -----------------------------------------------------------------------------
+# Preflight: verify Python 3 is available
+# -----------------------------------------------------------------------------
+# Check if python3 exists in PATH. If not, instruct the user to install it.
 if ! command -v python3 &> /dev/null; then
-    echo "❌ Python 3 não encontrado. Instale com: sudo apt install python3 python3-venv python3-pip"
+    echo "❌ Python 3 not found. Install with: sudo apt install python3 python3-venv python3-pip"
     exit 1
 fi
 
 PYTHON_VERSION=$(python3 --version | cut -d' ' -f2)
-echo "✅ Python $PYTHON_VERSION encontrado"
+echo "✅ Python $PYTHON_VERSION found"
 
-# Create virtual environment
+# -----------------------------------------------------------------------------
+# Virtual environment setup
+# -----------------------------------------------------------------------------
+# Create an isolated venv under ./venv if it doesn't already exist, then
+# activate it so pip/python resolve inside the environment.
 VENV_DIR="venv"
 if [ ! -d "$VENV_DIR" ]; then
     echo ""
-    echo "📦 Criando ambiente virtual Python..."
+    echo "📦 Creating Python virtual environment..."
     python3 -m venv "$VENV_DIR"
-    echo "✅ Ambiente virtual criado em ./$VENV_DIR"
+    echo "✅ Virtual environment created at ./$VENV_DIR"
 else
-    echo "✅ Ambiente virtual já existe em ./$VENV_DIR"
+    echo "✅ Virtual environment already exists at ./$VENV_DIR"
 fi
 
-# Activate virtual environment
+# Activate virtual environment for the current shell session
 echo ""
-echo "🔄 Ativando ambiente virtual..."
+echo "🔄 Activating virtual environment..."
 source "$VENV_DIR/bin/activate"
 
-# Upgrade pip
+# -----------------------------------------------------------------------------
+# pip upgrade
+# -----------------------------------------------------------------------------
+# Ensure pip itself is up to date inside the venv before installing deps.
 echo ""
-echo "⬆️  Atualizando pip..."
+echo "⬆️  Upgrading pip..."
 pip install --upgrade pip -q
 
-# Install dependencies
+# -----------------------------------------------------------------------------
+# Dependencies installation
+# -----------------------------------------------------------------------------
+# Install all Python dependencies from requirements.txt quietly.
 echo ""
-echo "📥 Instalando dependências..."
+echo "📥 Installing dependencies..."
 pip install -r requirements.txt -q
-echo "✅ Dependências instaladas"
+echo "✅ Dependencies installed"
 
-# Check .env file
+# -----------------------------------------------------------------------------
+# .env validation
+# -----------------------------------------------------------------------------
+# If .env is missing, try to copy from .env.example. If neither exists,
+# abort with instructions.
 echo ""
 if [ ! -f ".env" ]; then
-    echo "⚠️  Arquivo .env não encontrado!"
-    echo "📝 Copie o arquivo .env.example para .env e configure suas chaves API."
+    echo "⚠️  .env file not found!"
+    echo "📝 Copy .env.example to .env and configure your API keys."
     if [ -f ".env.example" ]; then
         cp .env.example .env
-        echo "✅ Arquivo .env criado a partir de .env.example"
-        echo "⚠️  Por favor, edite o arquivo .env com suas configurações antes de continuar."
+        echo "✅ .env created from .env.example"
+        echo "⚠️  Please edit .env with your configuration before continuing."
     else
-        echo "❌ Arquivo .env.example não encontrado. Crie o arquivo .env manualmente."
+        echo "❌ .env.example not found. Create .env manually."
         exit 1
     fi
 else
-    echo "✅ Arquivo .env encontrado"
+    echo "✅ .env file found"
 fi
 
-# Check required env vars
+# -----------------------------------------------------------------------------
+# Required environment variables check
+# -----------------------------------------------------------------------------
+# Verify that essential variables are populated. Warn if missing, but
+# continue so the user can see all warnings at once.
 echo ""
-echo "🔍 Verificando configurações..."
+echo "🔍 Checking configuration..."
 
+# Helper: check a single env var value and print status
 check_env_var() {
-    if [ -z "$1" ] || [ "$1" = " " ]; then
-        echo "⚠️  $2 não configurado no .env"
+    local value="$1"
+    local label="$2"
+    if [ -z "$value" ] || [ "$value" = " " ]; then
+        echo "⚠️  $label not configured in .env"
     else
-        echo "✅ $2 configurado"
+        echo "✅ $label configured"
     fi
 }
 
+# Telegram bot token (required to receive messages)
 check_env_var "$(grep -E '^TELEGRAM_BOT_TOKEN=' .env | cut -d'=' -f2-)" "TELEGRAM_BOT_TOKEN"
+
+# Telegram chat ID (required for auto-detection / proactive messages)
 check_env_var "$(grep -E '^TELEGRAM_CHAT_ID=' .env | cut -d'=' -f2-)" "TELEGRAM_CHAT_ID"
-check_env_var "$(grep -E '^(OPENROUTER_API_KEY|STEPFUN_API_KEY|QWENCLOUD_API_KEY)=' .env | cut -d'=' -f2- | head -1)" "Pelo menos uma chave de API de IA"
+
+# At least one AI provider key (OpenRouter, StepFun, or QwenCloud)
+check_env_var "$(grep -E '^(OPENROUTER_API_KEY|STEPFUN_API_KEY|QWENCLOUD_API_KEY)=' .env | cut -d'=' -f2- | head -1)" "At least one AI API key"
 
 echo ""
 echo "=========================================="
-echo "   Iniciando PsAgentAI..."
+echo "   Starting PsAgentAI..."
 echo "=========================================="
 echo ""
 
+# -----------------------------------------------------------------------------
 # Run the agent
+# -----------------------------------------------------------------------------
+# Execute the main Python script inside the activated virtual environment.
 python3 psagentai_agent.py