From 0411ca188099379218841a7c63e2fb552373e0f5 Mon Sep 17 00:00:00 2001 From: teknium Date: Wed, 1 Oct 2025 09:54:17 +0000 Subject: [PATCH] Add environment configuration file, restructure tool imports, and enhance README setup instructions --- .env.example | 49 ++++++++++++++ README.md | 48 +++++++++++-- model_tools.py | 10 +-- requirements.txt | 4 +- run_agent.py | 12 ++++ tools/__init__.py | 67 +++++++++++++++++++ .../image_generation_tool.py | 0 .../mixture_of_agents_tool.py | 0 terminal_tool.py => tools/terminal_tool.py | 0 vision_tools.py => tools/vision_tools.py | 0 web_tools.py => tools/web_tools.py | 0 11 files changed, 178 insertions(+), 12 deletions(-) create mode 100644 .env.example create mode 100644 tools/__init__.py rename image_generation_tool.py => tools/image_generation_tool.py (100%) rename mixture_of_agents_tool.py => tools/mixture_of_agents_tool.py (100%) rename terminal_tool.py => tools/terminal_tool.py (100%) rename vision_tools.py => tools/vision_tools.py (100%) rename web_tools.py => tools/web_tools.py (100%) diff --git a/.env.example b/.env.example new file mode 100644 index 000000000..bae4ec14f --- /dev/null +++ b/.env.example @@ -0,0 +1,49 @@ +# Hermes Agent Environment Configuration +# Copy this file to .env and fill in your API keys +# Get API keys from the URLs listed below + +# ============================================================================= +# REQUIRED API KEYS +# ============================================================================= + +# Anthropic API Key - Main agent model +# Get at: https://console.anthropic.com/ +ANTHROPIC_API_KEY= + +# Firecrawl API Key - Web search, extract, and crawl +# Get at: https://firecrawl.dev/ +FIRECRAWL_API_KEY= + +# Nous Research API Key - Vision analysis and multi-model reasoning +# Get at: https://inference-api.nousresearch.com/ +NOUS_API_KEY= + +# Morph API Key - Terminal/command execution tools +# Get at: https://morph.so/ +MORPH_API_KEY= + +# FAL.ai API Key - Image generation +# Get at: https://fal.ai/ +FAL_KEY= + +# ============================================================================= +# OPTIONAL API KEYS +# ============================================================================= + +# OpenAI API Key - Optional, for enhanced Hecate features +# Get at: https://platform.openai.com/ +OPENAI_API_KEY= + +# ============================================================================= +# OPTIONAL CONFIGURATION +# ============================================================================= + +# Terminal Tool Settings +HECATE_VM_LIFETIME_SECONDS=300 +HECATE_DEFAULT_SNAPSHOT_ID=snapshot_p5294qxt + +# Debug Logging (set to "true" to enable, logs saved to ./logs/) +WEB_TOOLS_DEBUG=false +VISION_TOOLS_DEBUG=false +MOA_TOOLS_DEBUG=false +IMAGE_TOOLS_DEBUG=false diff --git a/README.md b/README.md index 541a01a24..bd5d7f920 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,42 @@ An AI agent with advanced tool-calling capabilities, featuring a flexible toolse - **Toolsets System**: Organize tools into logical groups for different scenarios ## Setup + +### 1. Install Dependencies ```bash +# Create and activate virtual environment (recommended) +python3 -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate + +# Install required packages pip install -r requirements.txt + +# Install Hecate for terminal tools git clone git@github.com:NousResearch/hecate.git cd hecate pip install -e . +cd .. ``` +### 2. Configure Environment Variables +```bash +# Copy the example environment file +cp .env.example .env + +# Edit .env and add your API keys +nano .env # or use your preferred editor +``` + +**Required API Keys:** +- `ANTHROPIC_API_KEY` - Main agent model (get at: https://console.anthropic.com/) +- `FIRECRAWL_API_KEY` - Web tools (get at: https://firecrawl.dev/) +- `NOUS_API_KEY` - Vision & reasoning tools (get at: https://inference-api.nousresearch.com/) +- `MORPH_API_KEY` - Terminal tools (get at: https://morph.so/) +- `FAL_KEY` - Image generation (get at: https://fal.ai/) +- `OPENAI_API_KEY` - Optional, for some Hecate features + +See `.env.example` for all available configuration options including debug settings and terminal tool configuration. + ## Toolsets System The agent uses a toolsets system for organizing and managing tools. All tools must be part of a toolset to be accessible - individual tool selection is not supported. This ensures consistent and logical grouping of capabilities. @@ -115,13 +144,20 @@ agent = AIAgent(enabled_toolsets=["my_tools"]) ## Environment Variables -Set these environment variables to enable different tools: +All environment variables can be configured in the `.env` file (copy from `.env.example`). -- `FIRECRAWL_API_KEY`: For web tools (search, extract, crawl) -- `MORPH_API_KEY`: For terminal tools -- `NOUS_API_KEY`: For vision and reasoning tools -- `FAL_KEY`: For image generation tools -- `ANTHROPIC_API_KEY`: For the main agent model +**Core API Keys:** +- `ANTHROPIC_API_KEY`: Main agent model +- `FIRECRAWL_API_KEY`: Web tools (search, extract, crawl) +- `NOUS_API_KEY`: Vision and reasoning tools +- `MORPH_API_KEY`: Terminal tools +- `FAL_KEY`: Image generation tools +- `OPENAI_API_KEY`: Optional, for some Hecate features + +**Configuration Options:** +- `HECATE_VM_LIFETIME_SECONDS`: VM lifetime (default: 300) +- `HECATE_DEFAULT_SNAPSHOT_ID`: Default snapshot (default: snapshot_p5294qxt) +- `WEB_TOOLS_DEBUG`, `VISION_TOOLS_DEBUG`, `MOA_TOOLS_DEBUG`, `IMAGE_TOOLS_DEBUG`: Enable debug logging ## Documentation diff --git a/model_tools.py b/model_tools.py index 42f068604..cf0bf74b4 100644 --- a/model_tools.py +++ b/model_tools.py @@ -30,11 +30,11 @@ import json import asyncio from typing import Dict, Any, List -from web_tools import web_search_tool, web_extract_tool, web_crawl_tool, check_firecrawl_api_key -from terminal_tool import terminal_tool, check_hecate_requirements, TERMINAL_TOOL_DESCRIPTION -from vision_tools import vision_analyze_tool, check_vision_requirements -from mixture_of_agents_tool import mixture_of_agents_tool, check_moa_requirements -from image_generation_tool import image_generate_tool, check_image_generation_requirements +from tools.web_tools import web_search_tool, web_extract_tool, web_crawl_tool, check_firecrawl_api_key +from tools.terminal_tool import terminal_tool, check_hecate_requirements, TERMINAL_TOOL_DESCRIPTION +from tools.vision_tools import vision_analyze_tool, check_vision_requirements +from tools.mixture_of_agents_tool import mixture_of_agents_tool, check_moa_requirements +from tools.image_generation_tool import image_generate_tool, check_image_generation_requirements from toolsets import ( get_toolset, resolve_toolset, resolve_multiple_toolsets, get_all_toolsets, get_toolset_names, validate_toolset, diff --git a/requirements.txt b/requirements.txt index 1a12b5845..50ca44210 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,5 @@ firecrawl-py openai -fal-client \ No newline at end of file +fal-client +python-dotenv +fire \ No newline at end of file diff --git a/run_agent.py b/run_agent.py index 5fabfe078..26ee3c49d 100644 --- a/run_agent.py +++ b/run_agent.py @@ -28,6 +28,18 @@ from typing import List, Dict, Any, Optional from openai import OpenAI import fire from datetime import datetime +from pathlib import Path + +# Load environment variables from .env file +from dotenv import load_dotenv + +# Load .env file if it exists +env_path = Path(__file__).parent / '.env' +if env_path.exists(): + load_dotenv(dotenv_path=env_path) + print(f"✅ Loaded environment variables from {env_path}") +else: + print(f"ℹ️ No .env file found at {env_path}. Using system environment variables.") # Import our tool system from model_tools import get_tool_definitions, handle_function_call, check_toolset_requirements diff --git a/tools/__init__.py b/tools/__init__.py new file mode 100644 index 000000000..9843e757e --- /dev/null +++ b/tools/__init__.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +""" +Tools Package + +This package contains all the specific tool implementations for the Hermes Agent. +Each module provides specialized functionality for different capabilities: + +- web_tools: Web search, content extraction, and crawling +- terminal_tool: Command execution on virtual machines +- vision_tools: Image analysis and understanding +- mixture_of_agents_tool: Multi-model collaborative reasoning +- image_generation_tool: Text-to-image generation with upscaling + +The tools are imported into model_tools.py which provides a unified interface +for the AI agent to access all capabilities. +""" + +# Export all tools for easy importing +from .web_tools import ( + web_search_tool, + web_extract_tool, + web_crawl_tool, + check_firecrawl_api_key +) + +from .terminal_tool import ( + terminal_tool, + check_hecate_requirements, + TERMINAL_TOOL_DESCRIPTION +) + +from .vision_tools import ( + vision_analyze_tool, + check_vision_requirements +) + +from .mixture_of_agents_tool import ( + mixture_of_agents_tool, + check_moa_requirements +) + +from .image_generation_tool import ( + image_generate_tool, + check_image_generation_requirements +) + +__all__ = [ + # Web tools + 'web_search_tool', + 'web_extract_tool', + 'web_crawl_tool', + 'check_firecrawl_api_key', + # Terminal tools + 'terminal_tool', + 'check_hecate_requirements', + 'TERMINAL_TOOL_DESCRIPTION', + # Vision tools + 'vision_analyze_tool', + 'check_vision_requirements', + # MoA tools + 'mixture_of_agents_tool', + 'check_moa_requirements', + # Image generation tools + 'image_generate_tool', + 'check_image_generation_requirements', +] + diff --git a/image_generation_tool.py b/tools/image_generation_tool.py similarity index 100% rename from image_generation_tool.py rename to tools/image_generation_tool.py diff --git a/mixture_of_agents_tool.py b/tools/mixture_of_agents_tool.py similarity index 100% rename from mixture_of_agents_tool.py rename to tools/mixture_of_agents_tool.py diff --git a/terminal_tool.py b/tools/terminal_tool.py similarity index 100% rename from terminal_tool.py rename to tools/terminal_tool.py diff --git a/vision_tools.py b/tools/vision_tools.py similarity index 100% rename from vision_tools.py rename to tools/vision_tools.py diff --git a/web_tools.py b/tools/web_tools.py similarity index 100% rename from web_tools.py rename to tools/web_tools.py