From f44dde6b5febf1bc4cf90440e87e5054dc2c4bd2 Mon Sep 17 00:00:00 2001 From: hazeone <709547807@qq.com> Date: Thu, 20 Nov 2025 18:41:21 +0800 Subject: [PATCH 1/5] remove launch.py and refact doc --- docs/CONTRIBUTE_AN_AGENT.md | 64 +++++------ docs/OKX_SETUP.md | 50 -------- python/scripts/launch.py | 217 ----------------------------------- python/valuecell/__init__.py | 10 +- start.ps1 | 9 +- start.sh | 9 +- 6 files changed, 49 insertions(+), 310 deletions(-) delete mode 100644 docs/OKX_SETUP.md delete mode 100644 python/scripts/launch.py diff --git a/docs/CONTRIBUTE_AN_AGENT.md b/docs/CONTRIBUTE_AN_AGENT.md index 6d5cd53c6..53a97189e 100644 --- a/docs/CONTRIBUTE_AN_AGENT.md +++ b/docs/CONTRIBUTE_AN_AGENT.md @@ -14,7 +14,7 @@ The AI will read through this documentation and generate all necessary files: - Agent module (`core.py`, `__main__.py`, `__init__.py`) - Configuration files (YAML and JSON) -- Launch script registration +- Agent card registration (JSON) This is the fastest way to get started and learn the agent structure hands-on! @@ -23,7 +23,7 @@ This is the fastest way to get started and learn the agent structure hands-on! - [Architecture Overview](#architecture-overview) - [Create a New Agent](#create-a-new-agent) - [Add an Agent Configuration](#add-an-agent-configuration-required) -- [Register Agent in Launch Script](#register-agent-in-launch-script) +- [Run Your Agent](#run-your-agent) - [Use Models and Tools](#use-models-and-tools-inside-an-agent) - [Event System](#event-system-contracts) - [Launch Backend](#launch-backend) @@ -127,7 +127,7 @@ if __name__ == "__main__": > Always place the wrap and serve logic in `__main__.py`. This pattern enables: > > - Consistent agent launching via `uv run -m valuecell.agents.your_agent` -> - Integration with the ValueCell launch script +> - Automatic discovery by the ValueCell backend server > - Standardized transport and event emission Run your agent: @@ -243,50 +243,46 @@ The `name` must match your agent class name (e.g., `HelloAgent`). The `url` deci > - Change the `url` port if it's occupied. The wrapper reads host/port from this URL when serving > - If you see "No agent configuration found … in agent cards", check the `name` and the JSON location -## Register Agent in Launch Script +## Run Your Agent -To enable your agent to be launched via the project's launch script, register it in `python/scripts/launch.py`. +### Local Development -### Add Agent to Launch Script +For local web development, simply start the backend server which will automatically load all agents: -Open `python/scripts/launch.py` and add your agent: +```bash +# Start the full stack (frontend + backend with all agents) +bash start.sh -```python -# Define agent name constant -HELLO_AGENT_NAME = "HelloAgent" - -# Add to AGENTS list -AGENTS = [ - RESEARCH_AGENT_NAME, - AUTO_TRADING_AGENT_NAME, - HELLO_AGENT_NAME, # Add your agent here -] - -# Add launch command mapping -MAP_NAME_COMMAND[HELLO_AGENT_NAME] = ( - f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.hello_agent" -) +# Or start backend only +bash start.sh --no-frontend ``` -Now you can launch your agent using the project's start script. The `start.sh` (or `start.ps1` on Windows) script automatically invokes `launch.py`: +The backend will automatically discover and initialize your agent based on the agent card configuration. -```bash -# Launch all registered agents including yours -bash start.sh +### Direct Agent Execution + +You can also run your agent directly using Python module syntax: -# Or manually run the launch script +```bash cd python -python scripts/launch.py +uv run python -m valuecell.agents.hello_agent ``` -The launch script will: +### Client Application -- Start your agent as a background service -- Create log files in `logs/{timestamp}/HelloAgent.log` -- Display the agent's URL for monitoring +For the packaged client application (Tauri): +1. The agent will be automatically included in the build +2. No additional registration is required +3. Test using workflow builds: `.github/workflows/mac_build.yml` -> [!NOTE] -> The current launch script implementation will be optimized in future releases with automatic agent discovery and registration. For now, manual registration is required. +> [!TIP] +> Environment variables are loaded from system application directory: +> - **macOS**: `~/Library/Application Support/ValueCell/.env` +> - **Linux**: `~/.config/valuecell/.env` +> - **Windows**: `%APPDATA%\ValueCell\.env` +> +> The `.env` file will be auto-created from `.env.example` on first run if it doesn't exist. +> Both local development and packaged client use the same location. ## Use Models and Tools Inside an Agent diff --git a/docs/OKX_SETUP.md b/docs/OKX_SETUP.md deleted file mode 100644 index 59cb0d087..000000000 --- a/docs/OKX_SETUP.md +++ /dev/null @@ -1,50 +0,0 @@ -# OKX Setup Guide - -Use this checklist to enable the Auto Trading agent to route spot orders through OKX. Start with the paper environment before touching mainnet funds. - -## 1. Create API Credentials -- Log in to the OKX console → *API* → *Create V5 API key*. -- Enable **Trade** permission. Withdrawals are not required for trading. -- Record the **API Key**, **Secret Key**, and **Passphrase** immediately; you will not be able to view the secret again. -- For paper trading, toggle the **Demo trading** switch when generating the key (or set `flag=0` by using the paper environment). - -## 2. Configure Environment Variables -Add the following entries to `.env` (or export them before launching): - -```bash -AUTO_TRADING_EXCHANGE=okx -OKX_NETWORK=paper # change to mainnet after validation -OKX_API_KEY=your_api_key -OKX_API_SECRET=your_secret -OKX_API_PASSPHRASE=your_passphrase -OKX_ALLOW_LIVE_TRADING=false -OKX_MARGIN_MODE=cash # use cross / isolated for margin derivatives -OKX_USE_SERVER_TIME=false # set true if you see timestamp drift errors -``` - -## 3. Launch the Stack -- Install dependencies: `uv sync --group dev` and `bun install --cwd frontend` (first run only). -- Start services with paper overrides: - - ```bash - ./start.sh --exchange okx --network paper - ``` - -- This propagates the environment into `python/scripts/launch.py`, ensuring the Auto Trading agent connects with paper credentials. - -## 4. Validate Paper Trading -1. Trigger the Auto Trading agent via the UI (http://localhost:1420) or CLI and request trades such as “Trade BTC-USD with 5000 USD on OKX”. -2. Watch the logs under `logs//AutoTradingAgent.log` for entries like `exchange=okx` and `status=filled`. -3. Open https://www.okx.com/paper/account/trade to confirm the orders appear in the simulated environment. -4. Run the OKX unit tests locally: `uv run python -m pytest valuecell/agents/auto_trading_agent/tests/test_okx_exchange.py`. - -## 5. Promote to Mainnet (Optional and High Risk) -- Flip `OKX_NETWORK=mainnet` and `OKX_ALLOW_LIVE_TRADING=true` only after paper validation and formal approval. -- Restart with `./start.sh --exchange okx --network mainnet --allow-live-trading`. -- Monitor fills and balances continuously; revert the toggle if behaviour is unexpected. - -## 6. Safety Best Practices -- Store secrets in a vault (1Password, AWS Secrets Manager, etc.) and inject them at runtime instead of committing to disk. -- Rotate keys periodically and whenever you suspect compromise. -- Set conservative order sizes (`risk_per_trade`) and verify instrument availability (`BTC-USDT`, `ETH-USDT`, etc.) before relying on automation. -- Archive trading logs for audit purposes and switch the system back to paper mode when not actively monitoring. diff --git a/python/scripts/launch.py b/python/scripts/launch.py deleted file mode 100644 index cb8d921c4..000000000 --- a/python/scripts/launch.py +++ /dev/null @@ -1,217 +0,0 @@ -""" -Interactive agent launcher script. -Allows users to select an agent from available options and launch it using uv. -""" - -import os -import shlex -import signal -import subprocess -from datetime import datetime -from pathlib import Path -from typing import Dict - -from valuecell.utils.env import ensure_system_env_dir, get_system_env_path - -# 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", -} -TRADING_AGENTS_NAME = "TradingAgents" -RESEARCH_AGENT_NAME = "ResearchAgent" -AUTO_TRADING_AGENT_NAME = "AutoTradingAgent" -NEWS_AGENT_NAME = "NewsAgent" -STRATEGY_AGENT_NAME = "StrategyAgent" -# AGENTS = list(MAP_NAME_ANALYST.keys()) + [ -# TRADING_AGENTS_NAME, -# RESEARCH_AGENT_NAME, -# AUTO_TRADING_AGENT_NAME, -# ] -AGENTS = [ - RESEARCH_AGENT_NAME, - AUTO_TRADING_AGENT_NAME, - NEWS_AGENT_NAME, - STRATEGY_AGENT_NAME, -] - -PROJECT_DIR = Path(__file__).resolve().parent.parent.parent -PYTHON_DIR = PROJECT_DIR / "python" -ENV_PATH = get_system_env_path() - -# Convert paths to POSIX format (forward slashes) for cross-platform compatibility -# as_posix() works on both Windows and Unix systems -PROJECT_DIR_STR = PROJECT_DIR.as_posix() -PYTHON_DIR_STR = PYTHON_DIR.as_posix() -# Quote path to handle spaces (e.g., macOS Application Support) -ENV_PATH_STR = f'"{ENV_PATH.as_posix()}"' - -AUTO_TRADING_ENV_OVERRIDES = { - "AUTO_TRADING_EXCHANGE": os.getenv("AUTO_TRADING_EXCHANGE"), -} -AUTO_TRADING_ENV_PREFIX = " ".join( - f"{key}={value}" - for key, value in AUTO_TRADING_ENV_OVERRIDES.items() - if value not in (None, "") -) -if AUTO_TRADING_ENV_PREFIX: - AUTO_TRADING_ENV_PREFIX = f"{AUTO_TRADING_ENV_PREFIX} " - -# Mapping from agent name to launch command -MAP_NAME_COMMAND: Dict[str, str] = {} -# Remove external agent entries -# for name, analyst in MAP_NAME_ANALYST.items(): -# MAP_NAME_COMMAND[name] = ( -# f"uv run --env-file {ENV_PATH_STR} -m adapter --analyst {analyst}" -# ) -# MAP_NAME_COMMAND[TRADING_AGENTS_NAME] = ( -# f"uv run --env-file {ENV_PATH_STR} -m adapter" -# ) -# Keep only first-party agents -MAP_NAME_COMMAND[RESEARCH_AGENT_NAME] = ( - f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.research_agent" -) -MAP_NAME_COMMAND[AUTO_TRADING_AGENT_NAME] = ( - f"{AUTO_TRADING_ENV_PREFIX}uv run --env-file {ENV_PATH_STR} -m valuecell.agents.auto_trading_agent" -) -MAP_NAME_COMMAND[NEWS_AGENT_NAME] = ( - f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.news_agent" -) -MAP_NAME_COMMAND[STRATEGY_AGENT_NAME] = ( - f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.strategy_agent" -) -BACKEND_COMMAND = f"uv run --env-file {ENV_PATH_STR} -m valuecell.server.main" -FRONTEND_URL = "http://localhost:1420" - - -def check_envfile_is_set(): - if not ENV_PATH.exists(): - # Attempt to create system .env from repository example - example = PROJECT_DIR / ".env.example" - if example.exists(): - try: - import shutil - - ensure_system_env_dir() - shutil.copy(example, ENV_PATH) - print(f"Created system .env from example: {ENV_PATH}") - except Exception as e: - print(f"Failed to create system .env from example: {e}") - # Re-check after attempt - if not ENV_PATH.exists(): - print( - f"System .env not found at {ENV_PATH}. Please create it with necessary environment variables. " - "System paths — macOS: ~/Library/Application Support/ValueCell/.env; Linux: ~/.config/valuecell/.env; Windows: %APPDATA%\\ValueCell\\.env." - ) - exit(1) - - -def main(): - check_envfile_is_set() - timestamp = datetime.now().strftime("%Y%m%d%H%M%S") - log_dir = f"{PROJECT_DIR_STR}/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() - selected_agents = AGENTS - - 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 = [] - - print( - "Agents are now managed in-process by RemoteConnections; external processes are no longer started." - ) - - # 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) - # Start the backend in a new process group so we can terminate children. - # On Windows use CREATE_NEW_PROCESS_GROUP; on POSIX use start_new_session. - process = subprocess.Popen( - shlex.split(BACKEND_COMMAND), - shell=False, - stdout=logfile, - stderr=logfile, - cwd=PYTHON_DIR_STR, - creationflags=(subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0), - start_new_session=(os.name == "posix"), - ) - # processes.append(process) - # for process in processes: - # process.wait() - print(f"Backend (and agents) started with PID: {process.pid}") - - try: - process.wait() - except KeyboardInterrupt: - print("\nStopping backend...") - - # Attempt graceful termination of the whole process group. - try: - if os.name == "posix": - # send SIGTERM to the process group - os.killpg(process.pid, signal.SIGTERM) - else: - # Windows: try to send CTRL_BREAK to the process group - try: - process.send_signal(signal.CTRL_BREAK_EVENT) - except Exception: - process.terminate() - except Exception: - # Fallback to terminating the parent process - try: - process.terminate() - except Exception: - pass - - # Wait briefly for graceful shutdown - try: - process.wait(timeout=5) - except subprocess.TimeoutExpired: - # Force kill the whole group if still alive - try: - if os.name == "posix": - os.killpg(process.pid, signal.SIGKILL) - else: - process.kill() - except Exception: - try: - process.kill() - except Exception: - pass - print("Backend forced killed.") - - for logfile in logfiles: - logfile.close() - print(f"All agents finished. Check {log_dir}/ for output.") - - -if __name__ == "__main__": - main() diff --git a/python/valuecell/__init__.py b/python/valuecell/__init__.py index 240fcb311..25a65b03d 100644 --- a/python/valuecell/__init__.py +++ b/python/valuecell/__init__.py @@ -22,12 +22,12 @@ def load_env_file_early() -> None: - """Load environment variables using only the system `.env` file. + """Load environment variables from system application directory. Behavior: - - If the system `.env` exists, load it with `override=True`. - - If it does not exist and the repository has `.env.example`, copy it to the system path and then load. - - Do not create or use the repository root `.env`. + - Loads from system path (e.g., ~/Library/Application Support/ValueCell/.env on macOS) + - Auto-creates from .env.example if not exists + - Used by both local development and packaged client """ try: from dotenv import load_dotenv @@ -76,7 +76,7 @@ def load_env_file_early() -> None: def _load_env_file_manual() -> None: - """Fallback manual parsing: use only the system `.env`; create from example if needed.""" + """Fallback manual parsing for system .env file.""" try: current_dir = Path(__file__).parent project_root = current_dir.parent.parent.parent diff --git a/start.ps1 b/start.ps1 index 66117e89d..a9f365b27 100644 --- a/start.ps1 +++ b/start.ps1 @@ -161,10 +161,10 @@ function Start-Backend { return } - Write-Info "Starting backend (uv run scripts/launch.py)..." + Write-Info "Starting backend (uv run python -m valuecell.server.main)..." Push-Location $PY_DIR try { - & uv run --with questionary --with colorama scripts/launch.py + & uv run python -m valuecell.server.main } catch { Write-Err "Failed to start backend: $_" } finally { @@ -247,6 +247,11 @@ Usage: .\start.ps1 [options] Description: - Checks whether bun and uv are installed; missing tools will be auto-installed via PowerShell scripts. - Then installs backend and frontend dependencies and starts services. + - Environment variables are loaded from system path: + * macOS: ~/Library/Application Support/ValueCell/.env + * Linux: ~/.config/valuecell/.env + * Windows: %APPDATA%\ValueCell\.env + - The .env file will be auto-created from .env.example on first run. Options: -NoFrontend Start backend only diff --git a/start.sh b/start.sh index 5618160fd..5d234ddf7 100755 --- a/start.sh +++ b/start.sh @@ -101,8 +101,8 @@ start_backend() { warn "Backend directory not found; skipping backend start" return 0 fi - info "Starting backend (uv run scripts/launch.py)..." - cd "$PY_DIR" && uv run --with questionary scripts/launch.py + info "Starting backend (uv run python -m valuecell.server.main)..." + cd "$PY_DIR" && uv run python -m valuecell.server.main } start_frontend() { @@ -138,6 +138,11 @@ Usage: ./start.sh [options] Description: - Checks whether bun and uv are installed; on macOS, missing tools will be auto-installed via Homebrew. - Then installs backend and frontend dependencies and starts services. + - Environment variables are loaded from system path: + * macOS: ~/Library/Application Support/ValueCell/.env + * Linux: ~/.config/valuecell/.env + * Windows: %APPDATA%\ValueCell\.env + - The .env file will be auto-created from .env.example on first run. Options: --no-frontend Start backend only From 9db37d14dc8e040ebf38dbabd89b07742568b505 Mon Sep 17 00:00:00 2001 From: hazeone <709547807@qq.com> Date: Thu, 20 Nov 2025 18:41:31 +0800 Subject: [PATCH 2/5] remove VALUECELL_DEBUG setting --- python/valuecell/__init__.py | 10 +++++----- python/valuecell/utils/env.py | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/python/valuecell/__init__.py b/python/valuecell/__init__.py index 25a65b03d..8b14aa4db 100644 --- a/python/valuecell/__init__.py +++ b/python/valuecell/__init__.py @@ -44,10 +44,10 @@ def load_env_file_early() -> None: if not sys_env.exists() and example_file.exists(): ensure_system_env_dir() shutil.copy(example_file, sys_env) - if os.getenv("VALUECELL_DEBUG", "false").lower() == "true": + if os.getenv("AGENT_DEBUG_MODE", "false").lower() == "true": logger.info(f"✓ Created system .env from example: {sys_env}") except Exception as e: - if os.getenv("VALUECELL_DEBUG", "false").lower() == "true": + if os.getenv("AGENT_DEBUG_MODE", "false").lower() == "true": logger.info(f"⚠️ Failed to prepare system .env: {e}") if sys_env.exists(): @@ -56,13 +56,13 @@ def load_env_file_early() -> None: load_dotenv(sys_env, override=True) # Optional: Log successful loading if DEBUG is enabled - if os.getenv("VALUECELL_DEBUG", "false").lower() == "true": + if os.getenv("AGENT_DEBUG_MODE", "false").lower() == "true": logger.info(f"✓ Environment variables loaded from {sys_env}") logger.info(f" LANG: {os.environ.get('LANG', 'not set')}") logger.info(f" TIMEZONE: {os.environ.get('TIMEZONE', 'not set')}") else: # Only log if debug mode is enabled - if os.getenv("VALUECELL_DEBUG", "false").lower() == "true": + if os.getenv("AGENT_DEBUG_MODE", "false").lower() == "true": logger.info(f"ℹ️ No system .env file found at {sys_env}") except ImportError: @@ -71,7 +71,7 @@ def load_env_file_early() -> None: _load_env_file_manual() except Exception as e: # Only log errors if debug mode is enabled - if os.getenv("VALUECELL_DEBUG", "false").lower() == "true": + if os.getenv("AGENT_DEBUG_MODE", "false").lower() == "true": logger.info(f"⚠️ Error loading .env file: {e}") diff --git a/python/valuecell/utils/env.py b/python/valuecell/utils/env.py index 96e5376d9..eb81a68f8 100644 --- a/python/valuecell/utils/env.py +++ b/python/valuecell/utils/env.py @@ -55,7 +55,7 @@ def sys_platform_is_darwin() -> bool: def agent_debug_mode_enabled() -> bool: """Return whether agent debug mode is enabled via environment. - Checks `AGENT_DEBUG_MODE` first; falls back to `VALUECELL_DEBUG`. + Checks `AGENT_DEBUG_MODE`. """ - flag = os.getenv("AGENT_DEBUG_MODE", os.getenv("VALUECELL_DEBUG", "false")) + flag = os.getenv("AGENT_DEBUG_MODE", "false") return str(flag).lower() == "true" From f4f83b1f92bdc2deca9b20f19fd74ad08f7fef78 Mon Sep 17 00:00:00 2001 From: hazeone <709547807@qq.com> Date: Thu, 20 Nov 2025 18:45:44 +0800 Subject: [PATCH 3/5] add debug model for run --- start.ps1 | 5 ++++- start.sh | 5 +++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/start.ps1 b/start.ps1 index a9f365b27..b27bf3132 100644 --- a/start.ps1 +++ b/start.ps1 @@ -161,9 +161,11 @@ function Start-Backend { return } - Write-Info "Starting backend (uv run python -m valuecell.server.main)..." + Write-Info "Starting backend in debug mode (AGENT_DEBUG_MODE=true)..." Push-Location $PY_DIR try { + # Set debug mode for local development + $env:AGENT_DEBUG_MODE = "true" & uv run python -m valuecell.server.main } catch { Write-Err "Failed to start backend: $_" @@ -252,6 +254,7 @@ Description: * Linux: ~/.config/valuecell/.env * Windows: %APPDATA%\ValueCell\.env - The .env file will be auto-created from .env.example on first run. + - Debug mode is automatically enabled (AGENT_DEBUG_MODE=true) for local development. Options: -NoFrontend Start backend only diff --git a/start.sh b/start.sh index 5d234ddf7..04af90de4 100755 --- a/start.sh +++ b/start.sh @@ -101,8 +101,8 @@ start_backend() { warn "Backend directory not found; skipping backend start" return 0 fi - info "Starting backend (uv run python -m valuecell.server.main)..." - cd "$PY_DIR" && uv run python -m valuecell.server.main + info "Starting backend in debug mode (AGENT_DEBUG_MODE=true)..." + cd "$PY_DIR" && AGENT_DEBUG_MODE=true uv run python -m valuecell.server.main } start_frontend() { @@ -143,6 +143,7 @@ Description: * Linux: ~/.config/valuecell/.env * Windows: %APPDATA%\ValueCell\.env - The .env file will be auto-created from .env.example on first run. + - Debug mode is automatically enabled (AGENT_DEBUG_MODE=true) for local development. Options: --no-frontend Start backend only From 93d49150fd3612888e5bd03a3a50fb8b17eda72a Mon Sep 17 00:00:00 2001 From: hazeone <709547807@qq.com> Date: Thu, 20 Nov 2025 18:48:46 +0800 Subject: [PATCH 4/5] fix warning prob --- python/valuecell/utils/env.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/valuecell/utils/env.py b/python/valuecell/utils/env.py index eb81a68f8..eb10da29d 100644 --- a/python/valuecell/utils/env.py +++ b/python/valuecell/utils/env.py @@ -14,7 +14,7 @@ def get_system_env_dir() -> Path: - macOS: ~/Library/Application Support/ValueCell - Linux: ~/.config/valuecell - - Windows: %APPDATA%\ValueCell + - Windows: %APPDATA%\\ValueCell """ home = Path.home() # Windows From 978a4324b0802b0b3400190e427658344a4547e1 Mon Sep 17 00:00:00 2001 From: hazeone <709547807@qq.com> Date: Thu, 20 Nov 2025 19:05:02 +0800 Subject: [PATCH 5/5] fix contributing doc --- .github/CONTRIBUTING.md | 47 ++++++++++------------------------------- 1 file changed, 11 insertions(+), 36 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b144bbd18..2db7029e5 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -43,7 +43,7 @@ We welcome code contributions! See the [Development Setup](#development-setup) s > Multi-agent system architecture: [CORE_ARCHITECTURE](../docs/CORE_ARCHITECTURE.md) > Configuration documentation: [CONFIGURATION_GUIDE](../docs/CONFIGURATION_GUIDE.md) -> Agent development guide: [CONTRIBUTING_AN_AGENT](../docs/CONTRIBUTING_AN_AGENT.md) +> Agent development guide: [CONTRIBUTING_AN_AGENT](../docs/CONTRIBUTE_AN_AGENT.md) ## Development Setup @@ -63,15 +63,18 @@ We welcome code contributions! See the [Development Setup](#development-setup) s cd valuecell ``` -2. **Configure environment variables** +2. **First run** ```bash - cp .env.example .env - # Edit .env with your API keys + sh start.sh # MacOS, Linux + .\start.ps1 # Windows ``` +3. **Configuration** + The project will automatically create a config file (.env) in your system ValueCell directory. + You can configure your API key via the GUI settings tab. + Refer to [Configuration Guide](../docs/CONFIGURATION_GUIDE.md) for details. -Refer to [Configuration Guide](../docs/CONFIGURATION_GUIDE.md) for details. - +### Development Run **Install backend dependencies:** ```bash @@ -92,7 +95,7 @@ cd frontend bun install ``` -### Backend and Agents +### Backend For detailed information on building and contributing agents, see the [Agent Development Guide](../docs/CONTRIBUTING_AN_AGENT.md). @@ -105,15 +108,6 @@ cd python python -m valuecell.server.main ``` -**Run the Research Agent:** - -```bash -cd python -python -m valuecell.agents.research_agent -``` - -> [!TIP] -> Set your environment first. At minimum, configure `OPENROUTER_API_KEY` (or `GOOGLE_API_KEY`) and `SEC_EMAIL`. See [Configuration Guide](../docs/CONFIGURATION_GUIDE.md). ### Code Style @@ -128,26 +122,6 @@ This section shows how to run the backend locally and build new agents. - Core contracts: `valuecell.core.types` define response events and data shapes. - Streaming helpers: `valuecell.core.agent.responses.streaming` for emitting events. -#### Launch backend - -Run the API server (from the `python/` folder): - -```bash -cd python -python -m valuecell.server.main -``` - -Run the built‑in Research Agent as a standalone service: - -```bash -cd python -python -m valuecell.agents.research_agent -``` - -> [!TIP] -> Set your environment first. At minimum, configure `OPENROUTER_API_KEY` (or `GOOGLE_API_KEY`) and `SEC_EMAIL`. See `docs/CONFIGURATION_GUIDE.md`. -> Optional: set `AGENT_DEBUG_MODE=true` to trace model behavior locally. - #### Create a new Agent 1. Subclass `BaseAgent` and implement `stream()` @@ -326,6 +300,7 @@ We use **Biome** for linting and formatting. ```bash cd frontend bun run check:fix # Auto-fix all issues +bun run format:fix # Auto lint code ``` **Key style rules:**