From ac797259232e91c107381546137a287b2262f9d0 Mon Sep 17 00:00:00 2001 From: teknium Date: Sat, 7 Feb 2026 00:05:04 +0000 Subject: [PATCH] Update dependencies and enhance installation scripts - Added `prompt_toolkit` as a direct dependency for interactive CLI support. - Updated `modal` optional dependency to require `swe-rex[modal]>=1.4.0` for improved cloud execution capabilities. - Enhanced `messaging` optional dependencies to include `aiohttp>=3.9.0` for WhatsApp bridge communication. - Refined installation scripts to check for Python version requirements, emphasizing the need for Python 3.11+ for RL training tools. - Improved setup scripts to ensure proper installation of submodules and dependencies, enhancing user experience during setup. --- .gitignore | 2 + README.md | 343 ++++++++++++++++++++++++++++++++++++-- example-skill/SKILL.md | 70 -------- hermes_cli/doctor.py | 38 ++++- hermes_cli/setup.py | 90 ++++++++-- pyproject.toml | 8 +- requirements.txt | 19 +-- scripts/install.ps1 | 29 +++- scripts/install.sh | 27 ++- setup-hermes.sh | 33 ++++ tools/rl_training_tool.py | 22 ++- 11 files changed, 553 insertions(+), 128 deletions(-) delete mode 100644 example-skill/SKILL.md diff --git a/.gitignore b/.gitignore index 87617b60..dcbbb56a 100644 --- a/.gitignore +++ b/.gitignore @@ -39,6 +39,8 @@ agent-browser/ *.pem privvy* images/ +__pycache__/ +hermes_agent.egg-info/ # CLI config (may contain sensitive SSH paths) cli-config.yaml diff --git a/README.md b/README.md index a2c4bf26..aa603d64 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,9 @@ irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/ins ``` The installer will: -- Clone to `~/.hermes-agent` (with submodules: mini-swe-agent, tinker-atropos) -- Create a virtual environment -- Install all dependencies +- Clone to `~/.hermes/hermes-agent` (with submodules: mini-swe-agent, tinker-atropos) +- Create a virtual environment (Python 3.11+ recommended) +- Install all dependencies and submodule packages - Run the interactive setup wizard - Add `hermes` to your PATH @@ -179,8 +179,8 @@ hermes config set terminal.singularity_image ~/python.sif **Modal** (serverless cloud): ```bash -pip install modal boto3 -modal setup # Authenticate +pip install "swe-rex[modal]" # Installs swe-rex + modal + boto3 +modal setup # Authenticate with Modal hermes config set terminal.backend modal ``` @@ -275,16 +275,19 @@ See [docs/messaging.md](docs/messaging.md) for WhatsApp and advanced setup. Train language models with reinforcement learning using the Tinker API and Atropos framework. +> **Note:** RL training tools require **Python 3.11+** (the upstream `tinker` package has this requirement). On Python 3.10, the RL toolset will be automatically disabled — all other features work fine. + #### Requirements -1. **API Keys:** Add to `~/.hermes/.env`: +1. **Python 3.11+** (check with `python3 --version`) +2. **API Keys:** Add to `~/.hermes/.env`: ```bash TINKER_API_KEY=your-tinker-key # Get from https://tinker-console.thinkingmachines.ai/keys WANDB_API_KEY=your-wandb-key # Get from https://wandb.ai/authorize OPENROUTER_API_KEY=your-key # Optional: for rl_test_inference ``` -2. **That's it!** tinker-atropos is included as a submodule - no separate installation needed. +3. **That's it!** tinker-atropos is included as a submodule — the installer handles it automatically. #### Using RL Tools @@ -425,26 +428,332 @@ skills/ ## Manual Installation -If you prefer not to use the installer: +If you prefer full control over the installation process (or the quick-install script doesn't suit your environment), follow these steps to set everything up by hand. + +### Prerequisites + +| Requirement | Minimum Version | Check Command | Notes | +|-------------|----------------|---------------|-------| +| **Python** | 3.11+ recommended (3.10 minimum) | `python3 --version` | Required. 3.11+ needed for RL training tools | +| **Git** | Any recent | `git --version` | Required | +| **pip** | 21+ | `pip --version` | Comes with Python | +| **Node.js** | 18+ | `node --version` | Optional — needed for browser automation tools | +| **ripgrep** | Any | `rg --version` | Optional — faster file search in terminal tool (falls back to grep) | + +
+Installing prerequisites by platform + +**Ubuntu / Debian:** +```bash +sudo apt update +sudo apt install python3.11 python3.11-venv python3-pip git +# Optional: +sudo apt install ripgrep nodejs npm +``` + +**macOS (Homebrew):** +```bash +brew install python@3.11 git +# Optional: +brew install ripgrep node +``` + +**Windows (WSL recommended):** +Use the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) and follow the Ubuntu instructions above. Alternatively, use the PowerShell quick-install script at the top of this README. + +
+ +--- + +### Step 1: Clone the Repository + +Clone with `--recurse-submodules` to pull the required submodules ([mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent) for the terminal tool backend and [tinker-atropos](https://github.com/nousresearch/tinker-atropos) for RL training): ```bash -# Clone the repository (with submodules) +git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git +cd hermes-agent +``` + +If you already cloned without `--recurse-submodules`, initialize them manually: +```bash +git submodule update --init --recursive +``` + +--- + +### Step 2: Create & Activate a Virtual Environment + +A virtual environment keeps Hermes dependencies isolated from your system Python: + +```bash +python3 -m venv venv +source venv/bin/activate + +# Upgrade core packaging tools +pip install --upgrade pip wheel setuptools +``` + +> **Tip:** Every time you open a new terminal to use Hermes, activate the venv first: +> `source /path/to/hermes-agent/venv/bin/activate` + +--- + +### Step 3: Install Python Dependencies + +Install the main package in editable mode with all optional extras (messaging, cron, CLI menus): + +```bash +pip install -e ".[all]" +``` + +If you only want the core agent (no Telegram/Discord/cron support): +```bash +pip install -e "." +``` + +
+Optional extras breakdown + +| Extra | What it adds | Install command | +|-------|-------------|-----------------| +| `all` | Everything below | `pip install -e ".[all]"` | +| `messaging` | Telegram & Discord gateway | `pip install -e ".[messaging]"` | +| `cron` | Cron expression parsing for scheduled tasks | `pip install -e ".[cron]"` | +| `cli` | Terminal menu UI for setup wizard | `pip install -e ".[cli]"` | +| `modal` | Modal cloud execution backend (swe-rex + modal + boto3) | `pip install -e ".[modal]"` | +| `dev` | pytest & test utilities | `pip install -e ".[dev]"` | + +You can combine extras: `pip install -e ".[messaging,cron]"` + +
+ +--- + +### Step 4: Install Submodule Packages + +These are local packages checked out as Git submodules. Install them in editable mode: + +```bash +# Terminal tool backend (required for the terminal/command-execution tool) +pip install -e "./mini-swe-agent" + +# RL training backend (requires Python 3.11+) +pip install -e "./tinker-atropos" +``` + +Both are optional — if you skip them, the corresponding toolsets simply won't be available. + +> **Note:** `tinker-atropos` requires Python 3.11+ (the upstream `tinker` package has this constraint). On Python 3.10, skip this line — RL tools will be disabled but everything else works. + +--- + +### Step 5: Install Node.js Dependencies (Optional) + +Only needed if you plan to use the **browser automation** toolset (Browserbase-powered): + +```bash +npm install +``` + +This installs the `agent-browser` package defined in `package.json`. Skip this step if you don't need browser tools. + +--- + +### Step 6: Create the Configuration Directory + +Hermes stores all user configuration in `~/.hermes/`: + +```bash +# Create the directory structure +mkdir -p ~/.hermes/{cron,sessions,logs} + +# Copy the example config file +cp cli-config.yaml.example ~/.hermes/config.yaml + +# Create an empty .env file for API keys +touch ~/.hermes/.env +``` + +Your `~/.hermes/` directory should now look like: +``` +~/.hermes/ +├── config.yaml # Agent settings (model, terminal, toolsets, compression, etc.) +├── .env # API keys and secrets (one per line: KEY=value) +├── cron/ # Scheduled job data +├── sessions/ # Messaging gateway sessions +└── logs/ # Conversation logs +``` + +--- + +### Step 7: Add Your API Keys + +Open `~/.hermes/.env` in your editor and add at minimum an LLM provider key: + +```bash +# Required — at least one LLM provider: +OPENROUTER_API_KEY=sk-or-v1-your-key-here + +# Optional — enable additional tools: +FIRECRAWL_API_KEY=fc-your-key # Web search & scraping +BROWSERBASE_API_KEY=bb-your-key # Browser automation +BROWSERBASE_PROJECT_ID=your-project-id # Browser automation +FAL_KEY=your-fal-key # Image generation (FLUX) +TINKER_API_KEY=your-tinker-key # RL training +WANDB_API_KEY=your-wandb-key # RL training metrics + +# Optional — messaging gateway: +TELEGRAM_BOT_TOKEN=123456:ABC-DEF # From @BotFather +TELEGRAM_ALLOWED_USERS=your-user-id # Comma-separated +DISCORD_BOT_TOKEN=MTIz... # From Developer Portal +DISCORD_ALLOWED_USERS=your-user-id # Comma-separated +``` + +Or set them one at a time via the CLI: +```bash +hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here +``` + +--- + +### Step 8: Add `hermes` to Your PATH + +The `hermes` command is installed into the virtual environment's `bin/` directory. Add it to your shell PATH so you can run `hermes` from anywhere: + +**Bash** (`~/.bashrc`): +```bash +echo '' >> ~/.bashrc +echo '# Hermes Agent' >> ~/.bashrc +echo 'export PATH="$HOME/hermes-agent/venv/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +**Zsh** (`~/.zshrc`): +```bash +echo '' >> ~/.zshrc +echo '# Hermes Agent' >> ~/.zshrc +echo 'export PATH="$HOME/hermes-agent/venv/bin:$PATH"' >> ~/.zshrc +source ~/.zshrc +``` + +**Fish** (`~/.config/fish/config.fish`): +```fish +fish_add_path $HOME/hermes-agent/venv/bin +``` + +> **Note:** Adjust the path if you cloned to a different location. The key is to add the `venv/bin` directory inside your clone to your PATH. + +Alternatively, if you don't want to modify your PATH, you can create a symlink: +```bash +mkdir -p ~/.local/bin +ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes +``` +(Most distributions already have `~/.local/bin` on the PATH.) + +--- + +### Step 9: Run the Setup Wizard (Optional) + +The interactive setup wizard walks you through configuring your API keys and preferences: + +```bash +hermes setup +``` + +This is optional if you already configured `~/.hermes/.env` and `~/.hermes/config.yaml` manually in the steps above. + +--- + +### Step 10: Verify the Installation + +```bash +# Check that the command is available +hermes version + +# Run diagnostics to verify everything is working +hermes doctor + +# Check your configuration +hermes status + +# Test with a quick query +hermes chat -q "Hello! What tools do you have available?" +``` + +If `hermes doctor` reports issues, it will tell you exactly what's missing and how to fix it. + +--- + +### Quick-Reference: Manual Install (Condensed) + +For those who just want the commands without the explanations: + +```bash +# Clone & enter git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git cd hermes-agent -# Run setup script -./setup-hermes.sh - -# Or manually: +# Virtual environment python3 -m venv venv source venv/bin/activate +pip install --upgrade pip wheel setuptools + +# Install everything pip install -e ".[all]" +pip install -e "./mini-swe-agent" +pip install -e "./tinker-atropos" +npm install # optional, for browser tools -# Install submodules (required for terminal and RL tools) -pip install -e "./mini-swe-agent" # Terminal tool backend -pip install -e "./tinker-atropos" # RL training backend +# Configure +mkdir -p ~/.hermes/{cron,sessions,logs} +cp cli-config.yaml.example ~/.hermes/config.yaml +touch ~/.hermes/.env +echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env -hermes setup +# Add to PATH (adjust for your shell) +echo 'export PATH="'$(pwd)'/venv/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc + +# Verify +hermes doctor +hermes +``` + +--- + +### Updating a Manual Installation + +To update an existing manual install to the latest version: + +```bash +cd /path/to/hermes-agent +source venv/bin/activate + +# Pull latest code and submodules +git pull origin main +git submodule update --init --recursive + +# Reinstall (picks up new dependencies) +pip install -e ".[all]" +pip install -e "./mini-swe-agent" +pip install -e "./tinker-atropos" + +# Check for new config options added since your last update +hermes config check +hermes config migrate # Interactively add any missing options +``` + +### Uninstalling a Manual Installation + +```bash +# Remove the cloned repository +rm -rf /path/to/hermes-agent + +# Remove user configuration (optional — keep if you plan to reinstall) +rm -rf ~/.hermes + +# Remove the PATH line from your shell config (~/.bashrc or ~/.zshrc) +# Look for the "# Hermes Agent" comment and remove that block ``` --- diff --git a/example-skill/SKILL.md b/example-skill/SKILL.md deleted file mode 100644 index df20ff20..00000000 --- a/example-skill/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: example-skill -description: An example skill demonstrating the skill file format and structure ---- - -# Example Skill - -This is an example skill file that demonstrates how to create skills for the Hermes Agent. - -## Skill File Format - -Skills are markdown files with YAML frontmatter at the top: - -```yaml ---- -name: your-skill-name -description: A brief one-line description of what this skill does ---- -``` - -The frontmatter fields: -- **name**: The identifier used to reference this skill (lowercase, hyphens for spaces) -- **description**: A brief description shown when listing skills (keep under 200 chars) - -## Writing Effective Skills - -### 1. Be Specific and Actionable - -Good skills provide clear, actionable instructions: - -``` -When reviewing code: -1. Check for security vulnerabilities first -2. Verify error handling is comprehensive -3. Ensure tests cover edge cases -``` - -### 2. Include Examples - -Show concrete examples of what you want: - -```python -# Good: Descriptive variable names -user_authentication_token = get_token() - -# Bad: Cryptic abbreviations -uat = gt() -``` - -### 3. Define When to Use - -Help the agent understand when this skill applies: - -> Use this skill when: reviewing pull requests, auditing security, or checking code quality. - -## Skill Categories - -Consider organizing skills by purpose: - -- **Conventions**: Coding standards, API patterns, naming rules -- **Workflows**: Step-by-step processes for deployments, reviews, releases -- **Knowledge**: Domain-specific information, system architecture, gotchas -- **Templates**: Boilerplate for common tasks, response formats - -## Tips - -1. Keep the description concise - it's shown in the skills list -2. Use headers to organize longer skills -3. Include code examples where helpful -4. Reference other skills if they're related diff --git a/hermes_cli/doctor.py b/hermes_cli/doctor.py index 5e0ee39f..7c770cf8 100644 --- a/hermes_cli/doctor.py +++ b/hermes_cli/doctor.py @@ -58,8 +58,11 @@ def run_doctor(args): print(color("◆ Python Environment", Colors.CYAN, Colors.BOLD)) py_version = sys.version_info - if py_version >= (3, 10): + if py_version >= (3, 11): check_ok(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}") + elif py_version >= (3, 10): + check_ok(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}") + check_warn("Python 3.11+ recommended for RL Training tools (tinker requires >= 3.11)") elif py_version >= (3, 8): check_warn(f"Python {py_version.major}.{py_version.minor}.{py_version.micro}", "(3.10+ recommended)") else: @@ -263,6 +266,39 @@ def run_doctor(args): except Exception as e: check_warn("Anthropic API", f"({e})") + # ========================================================================= + # Check: Submodules + # ========================================================================= + print() + print(color("◆ Submodules", Colors.CYAN, Colors.BOLD)) + + # mini-swe-agent (terminal tool backend) + mini_swe_dir = PROJECT_ROOT / "mini-swe-agent" + if mini_swe_dir.exists() and (mini_swe_dir / "pyproject.toml").exists(): + try: + __import__("minisweagent") + check_ok("mini-swe-agent", "(terminal backend)") + except ImportError: + check_warn("mini-swe-agent found but not installed", "(run: pip install -e ./mini-swe-agent)") + issues.append("Install mini-swe-agent: pip install -e ./mini-swe-agent") + else: + check_warn("mini-swe-agent not found", "(run: git submodule update --init --recursive)") + + # tinker-atropos (RL training backend) + tinker_dir = PROJECT_ROOT / "tinker-atropos" + if tinker_dir.exists() and (tinker_dir / "pyproject.toml").exists(): + if py_version >= (3, 11): + try: + __import__("tinker_atropos") + check_ok("tinker-atropos", "(RL training backend)") + except ImportError: + check_warn("tinker-atropos found but not installed", "(run: pip install -e ./tinker-atropos)") + issues.append("Install tinker-atropos: pip install -e ./tinker-atropos") + else: + check_warn("tinker-atropos requires Python 3.11+", f"(current: {py_version.major}.{py_version.minor})") + else: + check_warn("tinker-atropos not found", "(run: git submodule update --init --recursive)") + # ========================================================================= # Check: Tool Availability # ========================================================================= diff --git a/hermes_cli/setup.py b/hermes_cli/setup.py index 83f42730..5f9f045a 100644 --- a/hermes_cli/setup.py +++ b/hermes_cli/setup.py @@ -652,6 +652,23 @@ def run_setup_wizard(args): print_info("Modal Cloud Configuration:") print_info("Get credentials at: https://modal.com/settings") + # Check if swe-rex[modal] is installed, install if missing + try: + from swerex.deployment.modal import ModalDeployment + print_info("swe-rex[modal] package: installed ✓") + except ImportError: + print_info("Installing required package: swe-rex[modal]...") + import subprocess + result = subprocess.run( + [sys.executable, "-m", "pip", "install", "swe-rex[modal]>=1.4.0"], + capture_output=True, text=True + ) + if result.returncode == 0: + print_success("swe-rex[modal] installed (includes modal + boto3)") + else: + print_warning("Failed to install swe-rex[modal] — install manually:") + print_info(' pip install "swe-rex[modal]>=1.4.0"') + # Always show current status and allow reconfiguration current_token = get_env_value('MODAL_TOKEN_ID') if current_token: @@ -917,6 +934,24 @@ def run_setup_wizard(args): save_env_value("BROWSERBASE_API_KEY", api_key) if project_id: save_env_value("BROWSERBASE_PROJECT_ID", project_id) + + # Check if Node.js dependencies are installed (required for browser tools) + import shutil + node_modules = PROJECT_ROOT / "node_modules" / "agent-browser" + if not node_modules.exists() and shutil.which("npm"): + print_info(" Installing Node.js dependencies for browser tools...") + import subprocess + result = subprocess.run( + ["npm", "install", "--silent"], + capture_output=True, text=True, cwd=str(PROJECT_ROOT) + ) + if result.returncode == 0: + print_success(" Node.js dependencies installed") + else: + print_warning(" npm install failed — run manually: cd ~/.hermes/hermes-agent && npm install") + elif not node_modules.exists(): + print_warning(" Node.js not found — browser tools require: npm install (in the hermes-agent directory)") + print_success(" Configured ✓") print() @@ -950,6 +985,11 @@ def run_setup_wizard(args): tinker_configured = get_env_value('TINKER_API_KEY') wandb_configured = get_env_value('WANDB_API_KEY') + # Check Python version requirement upfront + rl_python_ok = sys.version_info >= (3, 11) + if not rl_python_ok: + print_warning(f" Requires Python 3.11+ (current: {sys.version_info.major}.{sys.version_info.minor})") + if tinker_configured and wandb_configured: print_success(" Status: Configured ✓") if prompt_yes_no(" Update RL training credentials?", False): @@ -969,18 +1009,46 @@ def run_setup_wizard(args): print_warning(" Status: Not configured (tools will be disabled)") if prompt_yes_no(" Set up RL Training?", False): - print_info(" Get Tinker key at: https://tinker-console.thinkingmachines.ai/keys") - print_info(" Get WandB key at: https://wandb.ai/authorize") - api_key = prompt(" Tinker API key", password=True) - if api_key: - save_env_value("TINKER_API_KEY", api_key) - wandb_key = prompt(" WandB API key", password=True) - if wandb_key: - save_env_value("WANDB_API_KEY", wandb_key) - if api_key and wandb_key: - print_success(" Configured ✓") + # Check Python version before proceeding + if not rl_python_ok: + print_error(f" Python 3.11+ required (current: {sys.version_info.major}.{sys.version_info.minor})") + print_info(" Upgrade Python and reinstall to enable RL training tools") else: - print_warning(" Partially configured (both keys required)") + print_info(" Get Tinker key at: https://tinker-console.thinkingmachines.ai/keys") + print_info(" Get WandB key at: https://wandb.ai/authorize") + api_key = prompt(" Tinker API key", password=True) + if api_key: + save_env_value("TINKER_API_KEY", api_key) + wandb_key = prompt(" WandB API key", password=True) + if wandb_key: + save_env_value("WANDB_API_KEY", wandb_key) + + # Check if tinker-atropos submodule is installed + try: + __import__("tinker_atropos") + except ImportError: + tinker_dir = PROJECT_ROOT / "tinker-atropos" + if tinker_dir.exists() and (tinker_dir / "pyproject.toml").exists(): + print_info(" Installing tinker-atropos submodule...") + import subprocess + result = subprocess.run( + [sys.executable, "-m", "pip", "install", "-e", str(tinker_dir)], + capture_output=True, text=True + ) + if result.returncode == 0: + print_success(" tinker-atropos installed") + else: + print_warning(" tinker-atropos install failed — run manually:") + print_info(' pip install -e "./tinker-atropos"') + else: + print_warning(" tinker-atropos submodule not found — run:") + print_info(" git submodule update --init --recursive") + print_info(' pip install -e "./tinker-atropos"') + + if api_key and wandb_key: + print_success(" Configured ✓") + else: + print_warning(" Partially configured (both keys required)") # ========================================================================= # Save config and show summary diff --git a/pyproject.toml b/pyproject.toml index 0924ceaf..1af0cb2a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,8 @@ dependencies = [ "requests", "jinja2", "pydantic>=2.0", + # Interactive CLI (prompt_toolkit is used directly by cli.py) + "prompt_toolkit", # Tools "firecrawl-py", "fal-client", @@ -32,12 +34,12 @@ dependencies = [ ] [project.optional-dependencies] -modal = ["modal", "boto3"] +modal = ["swe-rex[modal]>=1.4.0"] dev = ["pytest", "pytest-asyncio"] -messaging = ["python-telegram-bot>=20.0", "discord.py>=2.0"] +messaging = ["python-telegram-bot>=20.0", "discord.py>=2.0", "aiohttp>=3.9.0"] cron = ["croniter"] cli = ["simple-term-menu"] -all = ["croniter", "python-telegram-bot>=20.0", "discord.py>=2.0", "simple-term-menu"] +all = ["croniter", "python-telegram-bot>=20.0", "discord.py>=2.0", "aiohttp>=3.9.0", "simple-term-menu"] [project.scripts] hermes = "hermes_cli.main:main" diff --git a/requirements.txt b/requirements.txt index 98db357c..d950a50b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,6 +6,10 @@ httpx rich tenacity prompt_toolkit +pyyaml +requests +jinja2 +pydantic>=2.0 # Web tools firecrawl-py @@ -15,10 +19,6 @@ fal-client # mini-swe-agent dependencies (for terminal tool) # Note: Install mini-swe-agent itself with: pip install -e ./mini-swe-agent -pyyaml -requests -jinja2 -pydantic>=2.0 litellm>=1.75.5 typer platformdirs @@ -27,18 +27,17 @@ platformdirs # Requires Docker installed and user in 'docker' group # Optional: For Modal backend (cloud execution) -# modal -# boto3 +# swe-rex[modal]>=1.4.0 # Includes modal + boto3 + swe-rex runtime # Optional: For cron expression parsing (cronjob scheduling) croniter # Optional: For messaging platform integrations (gateway) -# Telegram: pip install python-telegram-bot +# Telegram python-telegram-bot>=20.0 -# Discord: pip install discord.py +# Discord discord.py>=2.0 -# WhatsApp: Requires Node.js bridge (see docs/messaging.md) -# aiohttp # For WhatsApp bridge communication \ No newline at end of file +# WhatsApp bridge communication + general async HTTP (used by gateway) +aiohttp>=3.9.0 diff --git a/scripts/install.ps1 b/scripts/install.ps1 index 8170abba..86b914d3 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -69,7 +69,7 @@ function Write-Error { function Test-Python { Write-Info "Checking Python..." - # Try different python commands + # Try different python commands (prefer 3.11+ for full feature support) $pythonCmds = @("python3", "python", "py -3") foreach ($cmd in $pythonCmds) { @@ -79,7 +79,15 @@ function Test-Python { $major, $minor = $version.Split('.') if ([int]$major -ge 3 -and [int]$minor -ge 10) { $script:PythonCmd = $cmd + $script:PythonVersion = $version Write-Success "Python $version found" + + # Warn if < 3.11 (RL training tools require 3.11+) + if ([int]$minor -lt 11) { + Write-Warning "Python 3.11+ recommended — RL Training tools (tinker-atropos) require >= 3.11" + Write-Info "Core agent features will work fine on $version" + } + return $true } } @@ -89,7 +97,7 @@ function Test-Python { } Write-Error "Python 3.10+ not found" - Write-Info "Please install Python 3.10 or newer from:" + Write-Info "Please install Python 3.11 or newer (recommended) from:" Write-Info " https://www.python.org/downloads/" Write-Info "" Write-Info "Make sure to check 'Add Python to PATH' during installation" @@ -312,11 +320,18 @@ function Install-Dependencies { Write-Info "Installing tinker-atropos (RL training backend)..." if (Test-Path "tinker-atropos\pyproject.toml") { - try { - pip install -e ".\tinker-atropos" 2>&1 | Out-Null - Write-Success "tinker-atropos installed" - } catch { - Write-Warning "tinker-atropos install failed (RL tools may not work)" + # tinker-atropos depends on the 'tinker' package which requires Python >= 3.11 + $major, $minor = $PythonVersion.Split('.') + if ([int]$minor -ge 11) { + try { + pip install -e ".\tinker-atropos" 2>&1 | Out-Null + Write-Success "tinker-atropos installed" + } catch { + Write-Warning "tinker-atropos install failed (RL tools may not work)" + } + } else { + Write-Warning "tinker-atropos requires Python 3.11+ (skipping — RL training tools won't be available)" + Write-Info "Upgrade to Python 3.11+ to enable RL training features" } } else { Write-Warning "tinker-atropos not found (run: git submodule update --init)" diff --git a/scripts/install.sh b/scripts/install.sh index c3ff5a79..c97cbc8a 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -149,22 +149,29 @@ detect_os() { check_python() { log_info "Checking Python..." - # Try different python commands + # Try different python commands (prefer 3.11+ for full feature support) for cmd in python3.12 python3.11 python3.10 python3 python; do if command -v $cmd &> /dev/null; then PYTHON_CMD=$cmd PYTHON_VERSION=$($cmd -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")') - # Check version - if python3 -c "import sys; exit(0 if sys.version_info >= (3, 10) else 1)" 2>/dev/null; then + # Check minimum version (3.10) + if $cmd -c "import sys; exit(0 if sys.version_info >= (3, 10) else 1)" 2>/dev/null; then log_success "Python $PYTHON_VERSION found" + + # Warn if < 3.11 (RL training tools require 3.11+) + if ! $cmd -c "import sys; exit(0 if sys.version_info >= (3, 11) else 1)" 2>/dev/null; then + log_warn "Python 3.11+ recommended — RL Training tools (tinker-atropos) require >= 3.11" + log_info "Core agent features will work fine on $PYTHON_VERSION" + fi + return 0 fi fi done log_error "Python 3.10+ not found" - log_info "Please install Python 3.10 or newer:" + log_info "Please install Python 3.11 or newer (recommended):" case "$OS" in linux) @@ -179,7 +186,7 @@ check_python() { log_info " sudo pacman -S python" ;; *) - log_info " Use your package manager to install Python 3.10+" + log_info " Use your package manager to install Python 3.11+" ;; esac ;; @@ -480,8 +487,14 @@ install_deps() { log_info "Installing tinker-atropos (RL training backend)..." if [ -d "tinker-atropos" ] && [ -f "tinker-atropos/pyproject.toml" ]; then - pip install -e "./tinker-atropos" > /dev/null 2>&1 || log_warn "tinker-atropos install failed (RL tools may not work)" - log_success "tinker-atropos installed" + # tinker-atropos depends on the 'tinker' package which requires Python >= 3.11 + if $PYTHON_CMD -c "import sys; exit(0 if sys.version_info >= (3, 11) else 1)" 2>/dev/null; then + pip install -e "./tinker-atropos" > /dev/null 2>&1 || log_warn "tinker-atropos install failed (RL tools may not work)" + log_success "tinker-atropos installed" + else + log_warn "tinker-atropos requires Python 3.11+ (skipping — RL training tools won't be available)" + log_info "Upgrade to Python 3.11+ to enable RL training features" + fi else log_warn "tinker-atropos not found (run: git submodule update --init)" fi diff --git a/setup-hermes.sh b/setup-hermes.sh index e22511b3..e1a9dcb4 100755 --- a/setup-hermes.sh +++ b/setup-hermes.sh @@ -54,6 +54,11 @@ fi PYTHON_VERSION=$($PYTHON_CMD -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")') echo -e "${GREEN}✓${NC} Python $PYTHON_VERSION found" +# Warn if < 3.11 (RL training tools require 3.11+) +if ! $PYTHON_CMD -c "import sys; exit(0 if sys.version_info >= (3, 11) else 1)" 2>/dev/null; then + echo -e "${YELLOW}⚠${NC} Python 3.11+ recommended — RL Training tools (tinker-atropos) require >= 3.11" +fi + # ============================================================================ # Virtual environment # ============================================================================ @@ -80,6 +85,34 @@ pip install -e ".[all]" > /dev/null 2>&1 || pip install -e "." > /dev/null echo -e "${GREEN}✓${NC} Dependencies installed" +# ============================================================================ +# Submodules (terminal backend + RL training) +# ============================================================================ + +echo -e "${CYAN}→${NC} Installing submodules..." + +# mini-swe-agent (terminal tool backend) +if [ -d "mini-swe-agent" ] && [ -f "mini-swe-agent/pyproject.toml" ]; then + pip install -e "./mini-swe-agent" > /dev/null 2>&1 && \ + echo -e "${GREEN}✓${NC} mini-swe-agent installed" || \ + echo -e "${YELLOW}⚠${NC} mini-swe-agent install failed (terminal tools may not work)" +else + echo -e "${YELLOW}⚠${NC} mini-swe-agent not found (run: git submodule update --init --recursive)" +fi + +# tinker-atropos (RL training backend — requires Python 3.11+) +if [ -d "tinker-atropos" ] && [ -f "tinker-atropos/pyproject.toml" ]; then + if $PYTHON_CMD -c "import sys; exit(0 if sys.version_info >= (3, 11) else 1)" 2>/dev/null; then + pip install -e "./tinker-atropos" > /dev/null 2>&1 && \ + echo -e "${GREEN}✓${NC} tinker-atropos installed" || \ + echo -e "${YELLOW}⚠${NC} tinker-atropos install failed (RL tools may not work)" + else + echo -e "${YELLOW}⚠${NC} tinker-atropos requires Python 3.11+ (skipping — RL training tools won't be available)" + fi +else + echo -e "${YELLOW}⚠${NC} tinker-atropos not found (run: git submodule update --init --recursive)" +fi + # ============================================================================ # Optional: ripgrep (for faster file search) # ============================================================================ diff --git a/tools/rl_training_tool.py b/tools/rl_training_tool.py index 770c542c..8b901ad5 100644 --- a/tools/rl_training_tool.py +++ b/tools/rl_training_tool.py @@ -1300,10 +1300,26 @@ async def rl_test_inference( # Requirements Check # ============================================================================ +def check_rl_python_version() -> bool: + """ + Check if Python version meets the minimum for RL tools. + + tinker-atropos depends on the 'tinker' package which requires Python >= 3.11. + """ + return sys.version_info >= (3, 11) + + def check_rl_api_keys() -> bool: """ - Check if required API keys are available. + Check if required API keys and Python version are available. + + RL training requires: + - Python >= 3.11 (tinker package requirement) + - TINKER_API_KEY for the Tinker training API + - WANDB_API_KEY for Weights & Biases metrics """ + if not check_rl_python_version(): + return False tinker_key = os.getenv("TINKER_API_KEY") wandb_key = os.getenv("WANDB_API_KEY") return bool(tinker_key) and bool(wandb_key) @@ -1311,9 +1327,11 @@ def check_rl_api_keys() -> bool: def get_missing_keys() -> List[str]: """ - Get list of missing required API keys. + Get list of missing requirements for RL tools (API keys and Python version). """ missing = [] + if not check_rl_python_version(): + missing.append(f"Python >= 3.11 (current: {sys.version_info.major}.{sys.version_info.minor})") if not os.getenv("TINKER_API_KEY"): missing.append("TINKER_API_KEY") if not os.getenv("WANDB_API_KEY"):