feature: unified agent launch script

python/scripts/launch.py

@@ -0,0 +1,128 @@
+"""
+Interactive agent launcher script.
+Allows users to select an agent from available options and launch it using uv.
+"""
+
+import os
+from pathlib import Path
+import subprocess
+from datetime import datetime
+from typing import Dict
+
+import questionary
+
+# Mapping from agent name to analyst key (for ai-hedge-fund agents)
+MAP_NAME_ANALYST: Dict[str, str] = {
+    "AswathDamodaranAgent": "aswath_damodaran",
+    "BenGrahamAgent": "ben_graham",
+    "BillAckmanAgent": "bill_ackman",
+    "CathieWoodAgent": "cathie_wood",
+    "CharlieMungerAgent": "charlie_munger",
+    "FundamentalsAnalystAgent": "fundamentals_analyst",
+    "MichaelBurryAgent": "michael_burry",
+    "MohnishPabraiAgent": "mohnish_pabrai",
+    "PeterLynchAgent": "peter_lynch",
+    "PhilFisherAgent": "phil_fisher",
+    "RakeshJhunjhunwalaAgent": "rakesh_jhunjhunwala",
+    "SentimentAnalystAgent": "sentiment_analyst",
+    "StanleyDruckenmillerAgent": "stanley_druckenmiller",
+    "TechnicalAnalystAgent": "technical_analyst",
+    "ValuationAnalystAgent": "valuation_analyst",
+    "WarrenBuffettAgent": "warren_buffett",
+}
+SEC_AGENT_NAME = "SecAgent"
+TRADING_AGENTS_NAME = "TradingAgentsAdapter"
+AGENTS = list(MAP_NAME_ANALYST.keys()) + [SEC_AGENT_NAME, TRADING_AGENTS_NAME]
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent.parent
+PYTHON_DIR = PROJECT_DIR / "python"
+ENV_PATH = PROJECT_DIR / ".env"
+ENV_PATH_STR = str(ENV_PATH.resolve())
+
+# Mapping from agent name to launch command
+MAP_NAME_COMMAND: Dict[str, str] = {}
+for name, analyst in MAP_NAME_ANALYST.items():
+    MAP_NAME_COMMAND[name] = (
+        f"cd {PYTHON_DIR}/third_party/ai-hedge-fund && uv run --env-file {ENV_PATH} -m adapter --analyst {analyst}"
+    )
+MAP_NAME_COMMAND[SEC_AGENT_NAME] = (
+    f"uv run --env-file {ENV_PATH} -m valuecell.agents.sec_agent"
+)
+MAP_NAME_COMMAND[TRADING_AGENTS_NAME] = (
+    f"cd {PYTHON_DIR}/third_party/TradingAgents && uv run --env-file {ENV_PATH} -m adapter"
+)
+BACKEND_COMMAND = (
+    f"cd {PYTHON_DIR} && uv run --env-file {ENV_PATH} -m valuecell.server.main"
+)
+FRONTEND_URL = "http://localhost:1420"
+
+
+def check_envfile_is_set():
+    if not ENV_PATH.exists():
+        print(
+            f".env file not found at {ENV_PATH}. Please create it with necessary environment variables. "
+            "check python/.env.example for reference."
+        )
+        exit(1)
+
+
+def main():
+    check_envfile_is_set()
+    timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+    log_dir = f"{PROJECT_DIR}/logs/{timestamp}"
+
+    # Use questionary multi-select to allow choosing multiple agents
+    selected_agents = questionary.checkbox(
+        "Choose agents to launch (use space to select, enter to confirm):",
+        choices=AGENTS,
+    ).ask()
+
+    if not selected_agents:
+        print("No agents selected.")
+        exit(1)
+
+    os.makedirs(log_dir, exist_ok=True)
+    print(f"Logs will be saved to {log_dir}/")
+
+    processes = []
+    logfiles = []
+    for selected_agent in selected_agents:
+        logfile_path = f"{log_dir}/{selected_agent}.log"
+        print(f"Starting agent: {selected_agent} - output to {logfile_path}")
+
+        # Open logfile for writing
+        logfile = open(logfile_path, "w")
+        logfiles.append(logfile)
+
+        # Launch command using Popen with output redirected to logfile
+        process = subprocess.Popen(
+            MAP_NAME_COMMAND[selected_agent], shell=True, stdout=logfile, stderr=logfile
+        )
+        processes.append(process)
+    print("All agents launched. Waiting for tasks...")
+
+    for selected_agent in selected_agents:
+        print(
+            f"You can monitor {selected_agent} logs at {log_dir}/{selected_agent}.log or chat on: {FRONTEND_URL}/agent/{selected_agent}"
+        )
+
+    # Launch backend
+    logfile_path = f"{log_dir}/backend.log"
+    print(f"Starting backend - output to {logfile_path}")
+    print(f"Frontend available at {FRONTEND_URL}")
+    logfile = open(logfile_path, "w")
+    logfiles.append(logfile)
+    process = subprocess.Popen(
+        BACKEND_COMMAND, shell=True, stdout=logfile, stderr=logfile
+    )
+    processes.append(process)
+
+    for process in processes:
+        process.wait()
+    for logfile in logfiles:
+        logfile.close()
+    print(f"All agents finished. Check {log_dir}/ for output.")
+
+
+if __name__ == "__main__":
+    main()

python/scripts/prepare_envs.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+
+# Color codes for output highlighting
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'  # No Color
+
+# Function to print highlighted command
+highlight_command() {
+    echo -e "${BLUE}Running: $1${NC}"
+}
+
+# Check current directory and switch to python if needed
+if [ -d "python" ] && [ -f "python/pyproject.toml" ] && [ -f ".gitignore" ]; then
+    echo -e "${YELLOW}Detected project root. Switching to python directory...${NC}"
+    cd python
+elif [ ! -f "pyproject.toml" ] || [ ! -d "third_party" ]; then
+    echo -e "${RED}Error: This script must be run from the project python directory or project root. You are in $(pwd)${NC}"
+    exit 1
+fi
+
+# Final check if in python directory
+if [ ! -f "pyproject.toml" ] || [ ! -d "third_party" ]; then
+    echo -e "${RED}Error: Failed to switch to python directory. You are in $(pwd)${NC}"
+    exit 1
+fi
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo -e "${RED}Error: 'uv' command not found. Please install 'uv' (e.g., brew install uv).${NC}"
+    exit 1
+fi
+
+echo -e "${BLUE}==========================================${NC}"
+echo -e "${BLUE}Starting environment preparation...${NC}"
+echo -e "${BLUE}==========================================${NC}"
+
+# Prepare environments
+echo -e "${GREEN}Project root confirmed. Preparing environments...${NC}"
+
+echo -e "${YELLOW}Setting up main Python environment...${NC}"
+if [ ! -d ".venv" ]; then
+    highlight_command "uv venv --python 3.12"
+    uv venv --python 3.12
+else
+    echo -e "${YELLOW}.venv already exists, skipping venv creation.${NC}"
+fi
+highlight_command "uv sync --group dev"
+uv sync --group dev
+echo -e "${GREEN}Main environment setup complete.${NC}"
+
+echo -e "${BLUE}==========================================${NC}"
+echo -e "${BLUE}Setting up third-party environments...${NC}"
+echo -e "${BLUE}==========================================${NC}"
+echo -e "${YELLOW}Setting up ai-hedge-fund environment...${NC}"
+pushd ./third_party/ai-hedge-fund
+if [ ! -d ".venv" ]; then
+    highlight_command "uv venv --python 3.12"
+    uv venv --python 3.12
+else
+    echo -e "${YELLOW}.venv already exists, skipping venv creation.${NC}"
+fi
+highlight_command "uv sync"
+uv sync
+popd
+echo -e "${GREEN}ai-hedge-fund environment setup complete.${NC}"
+
+echo -e "${YELLOW}------------------------------------------${NC}"
+echo -e "${YELLOW}Setting up TradingAgents environment...${NC}"
+echo -e "${YELLOW}------------------------------------------${NC}"
+pushd ./third_party/TradingAgents
+if [ ! -d ".venv" ]; then
+    highlight_command "uv venv --python 3.12"
+    uv venv --python 3.12
+else
+    echo -e "${YELLOW}.venv already exists, skipping venv creation.${NC}"
+fi
+highlight_command "uv sync"
+uv sync
+popd
+echo -e "${GREEN}TradingAgents environment setup complete.${NC}"
+
+echo -e "${GREEN}==========================================${NC}"
+echo -e "${GREEN}All environments are set up.${NC}"
+echo -e "${GREEN}==========================================${NC}"

python/valuecell/agents/__init__.py

@@ -1,61 +0,0 @@
-"""
-Auto-import all agents to ensure they are registered with the AgentRegistry.
-This module dynamically discovers and imports all agent classes.
-"""
-
-import importlib
-import inspect
-import pkgutil
-from pathlib import Path
-from typing import List
-
-from valuecell.core.types import BaseAgent
-
-
-def _discover_and_import_agents() -> List[str]:
-    """
-    Dynamically discover and import all agent modules in this package.
-
-    Returns:
-        List of agent class names that were imported
-    """
-    imported_agents = []
-    current_package = __name__
-    current_path = Path(__file__).parent
-
-    # Iterate through all Python files in the current directory
-    for _, module_name, _ in pkgutil.iter_modules([str(current_path)]):
-        if module_name.startswith("_"):
-            # Skip private modules
-            continue
-
-        try:
-            # Import the module
-            module = importlib.import_module(f"{current_package}.{module_name}")
-
-            # Find all classes in the module that inherit from BaseAgent
-            for name, obj in inspect.getmembers(module, inspect.isclass):
-                if (
-                    obj.__module__ == module.__name__
-                    and issubclass(obj, BaseAgent)
-                    and obj != BaseAgent
-                ):
-                    imported_agents.append(name)
-                    # Make the class available at package level
-                    globals()[name] = obj
-
-        except Exception as e:
-            # Log import errors but continue with other modules
-            import logging
-
-            logger = logging.getLogger(__name__)
-            logger.warning(f"Failed to import module {module_name}: {e}")
-
-    return imported_agents
-
-
-# Auto-import all agents
-_imported_agent_names = _discover_and_import_agents()
-
-# Export all discovered agents for convenient access
-__all__ = _imported_agent_names

python/valuecell/core/agent/client.py

@@ -60,7 +60,13 @@ async def _setup_client(self):
 
         client_factory = ClientFactory(config)
         card_resolver = A2ACardResolver(self._httpx_client, self.agent_url)
-        self.agent_card = await card_resolver.get_agent_card()
+        try:
+            self.agent_card = await card_resolver.get_agent_card()
+        except Exception as e:
+            raise RuntimeError(
+                "Failed to resolve agent card. Maybe the agent URL is incorrect or the agent is unreachable."
+                " Agents could be launched via `scripts/launch_agent.py`."
+            ) from e
         self._client = client_factory.create(self.agent_card)
 
     async def send_message(