Skip to content

Installation Guide

This guide will walk you through installing LEGIONHERCULES and its dependencies.

Prerequisites

System Requirements

  • Operating System: Linux, macOS, or Windows with WSL
  • Python: 3.9 or higher
  • Memory: 8GB RAM minimum (16GB recommended)
  • Storage: 5GB free space for models

Required Software

  1. Python 3.9+

Check your Python version: 

python --version
# or
python3 --version

  1. Ollama

Ollama is required for running LLMs locally.

macOS/Linux: 

curl -fsSL https://ollama.com/install.sh | sh

Windows: Download from ollama.com

Installation Methods

pip install legionhercules

Method 2: Install with Development Dependencies

pip install "legionhercules[dev]"

Method 3: Install from Source

git clone https://github.com/deathlegion/legionhercules.git
cd legionhercules
pip install -e ".[dev]"

Post-Installation Setup

1. Start Ollama

Ensure Ollama is running:

ollama serve

You should see output like: 

2024/01/15 10:30:00 routes.go:1000: Listening on 127.0.0.1:11434

2. Download a Model

Pull your first model:

ollama pull llama3.2

Or use LEGIONHERCULES:

legionhercules models --pull llama3.2

Recommended Models:

Model Size Best For
llama3.2 2GB Fast, general purpose
llama3.1:8b 4.7GB Balanced speed/quality
codellama 3.8GB Code tasks
mistral 4.1GB Strong reasoning
phi3 2.3GB Efficient, good quality

3. Verify Installation

Test your installation:

# Check CLI is installed
legionhercules --version

# Test Ollama connection
legionhercules models --list

# Start a chat
legionhercules chat "Hello!"

Configuration

Initialize Config

Create a configuration file:

legionhercules config --init

This creates ~/.legionhercules/config.yaml.

Environment Variables

You can override config with environment variables:

export LEGIONHERCULES_LLM_MODEL=llama3.1:8b
export LEGIONHERCULES_LLM_BASE_URL=http://localhost:11434

Troubleshooting

Ollama Connection Issues

Problem: Cannot connect to Ollama

Solution: 1. Check if Ollama is running: 

curl http://localhost:11434/api/tags

  1. Start Ollama if not running: 

    ollama serve

  2. Check firewall settings for port 11434

Model Download Issues

Problem: Model download fails or is slow

Solution: 1. Check your internet connection 2. Try a smaller model first (llama3.2) 3. Use a download manager for large models

Python Import Errors

Problem: ModuleNotFoundError

Solution: 1. Ensure you're in the correct virtual environment 2. Reinstall: pip install --force-reinstall legionhercules

Permission Issues

Problem: Permission denied when writing files

Solution: 1. Check directory permissions 2. Run with appropriate user permissions 3. Ensure ~/.legionhercules directory is writable

Uninstallation

To remove LEGIONHERCULES:

pip uninstall legionhercules

To remove configuration:

rm -rf ~/.legionhercules

Next Steps