⚠️ MOVED: Codomyrmex Installation Guide

The comprehensive installation guide has been moved to a dedicated setup documentation file for better organization.

👉 New Location: setup.md

This file now serves as a redirect to the complete setup guide that includes:

Installation instructions for all platforms
Configuration and environment setup
Troubleshooting and common issues
Advanced setup options
Development environment configuration

📦 Go to Complete Setup Guide - Everything you need to get Codomyrmex running

🎯 Quick Start (Recommended)

Option 1: UV-Optimized Setup (Fastest & Most Reliable)

# Clone and setup everything automatically with uv
git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex
./start_here.sh

Option 2: Manual UV Setup

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone the repository
git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex

# 3. Create virtual environment and install
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

# 4. Verify installation
codomyrmex check

📋 Prerequisites

Before installing Codomyrmex, ensure you have:

Required

Python 3.10+ (latest versions recommended for best package compatibility)
```
python3 --version  # Should be 3.10 or higher
```

uv (package manager used across Codomyrmex)

uv --version || curl -LsSf https://astral.sh/uv/install.sh | sh

git (version control)
```
git --version
```

Optional (for specific modules)

Node.js 18+ (for documentation generation)

node --version  # Should be 18.0 or higher
npm --version

Docker (for code execution sandbox)

docker --version
docker run hello-world  # Test Docker installation

Graphviz (for dependency visualization)

# macOS
brew install graphviz
# Ubuntu/Debian
sudo apt-get install graphviz
# Windows
# Download from https://graphviz.org/download/

🛠️ Detailed Installation Options

Using uv (Recommended)

uv is a fast Python package manager that's more reliable than pip:

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone repository
git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex

# 3. Create virtual environment and install
uv venv .venv
source .venv/bin/activate
uv sync

# 4. Verify installation
codomyrmex check

Development Installation

For contributors or developers who want to modify Codomyrmex:

# 1. Clone your fork
git clone https://github.com/YOUR_USERNAME/codomyrmex.git
cd codomyrmex

# 2. Setup development environment
bash src/codomyrmex/environment_setup/scripts/setup_dev_env.sh

# 3. Install development dependencies
uv sync --dev

# 4. Setup pre-commit hooks (optional but recommended)
pre-commit install

# 5. Run tests to verify everything works
uv run pytest src/codomyrmex/tests/ -v

⚙️ Configuration

Environment Variables (Optional)

For AI-powered features, create a .env file in the project root:

# Create .env file
cat > .env << EOF
# LLM API Keys (optional - only needed for AI features)
OPENAI_API_KEY="sk-..."
ANTHROPIC_API_KEY="sk-ant-..."
GOOGLE_API_KEY="AIzaSy..."

# Logging Configuration (optional)
CODOMYRMEX_LOG_LEVEL="INFO"
CODOMYRMEX_LOG_FILE="codomyrmex.log"

# Other Configuration (optional)
CODOMYRMEX_DEBUG="false"
EOF

Security Note: Never commit the .env file to version control. It's already included in .gitignore.

Module-Specific Setup

Some modules may require additional setup:

Documentation Module

# Install Node.js dependencies for documentation generation
cd src/codomyrmex/documentation
npm install
cd ../../..

Docker for Code Execution

# Test Docker setup
docker run --rm python:3.11-slim python -c "print('Docker works!')"

✅ Verification & Testing

Step 1: Basic System Check

# Verify Codomyrmex is working correctly
codomyrmex check

# Expected output shows all systems operational
# ✅ Python 3.13.7
# ✅ Logging & Monitoring module
# ✅ Environment Setup module
# ✅ Data visualization
# ✅ Testing framework

Step 2: Interactive Exploration

# Launch the interactive shell for hands-on exploration
./start_here.sh
# Choose option 7: Interactive Shell

# Or launch directly
uv run python -c "
from codomyrmex.terminal_interface import InteractiveShell
InteractiveShell().run()
"

Try these commands in the interactive shell:

🐜 codomyrmex> explore                    # Overview of all modules
🐜 codomyrmex> forage visualization       # Find visualization capabilities
🐜 codomyrmex> demo data_visualization    # Run live demo
🐜 codomyrmex> dive agents       # Deep dive into AI module
🐜 codomyrmex> status                     # System health check
🐜 codomyrmex> export                     # Generate system inventory

Step 3: Test Core Functionality

Test the main features to ensure everything works:

# Test data visualization (should create PNG files)
from codomyrmex.data_visualization import create_line_plot
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)
result = create_line_plot(x, y, title="Test Plot", output_path="test_plot.png")
print(f"✅ Visualization test: {result is not None}")

# Test AI code generation (requires API key)
from codomyrmex.agents import generate_code_snippet

try:
    ai_result = generate_code_snippet("Create a hello world function", "python")
    print(f"✅ AI test: {ai_result['status'] == 'success'}")
except Exception as e:
    print(f"⚠️ AI test skipped (no API key): {e}")

# Test code execution sandbox
from codomyrmex.coding import execute_code

sandbox_result = execute_code("python", "print('Hello from sandbox!')")
print(f"✅ Sandbox test: {sandbox_result['success']}")

Step 4: Run Comprehensive Tests

# Run all tests with coverage reporting
uv run pytest src/codomyrmex/tests/ --cov=src/codomyrmex --cov-report=html

# Run specific module tests
uv run pytest src/codomyrmex/tests/unit/test_data_visualization.py -v

# Run integration tests
uv run pytest src/codomyrmex/tests/integration/ -v

# Check test coverage
open src/codomyrmex/tests/htmlcov/index.html  # View coverage report

Step 5: Code Quality Check

# Run linting on the main codebase
uv run ruff check src/codomyrmex/

# Format code (if needed)
uv run black src/codomyrmex/

# Type checking (if configured)
uv run ty check src/codomyrmex/

🐛 Troubleshooting Guide

This section provides solutions for the most common installation and setup issues. If you encounter problems, work through these solutions systematically.

🔍 Quick Diagnostic Commands

First, run these commands to identify the issue:

# 1. Check your environment
python3 --version
which python3
pwd

# 2. Verify virtual environment
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
which python

# 3. Check Codomyrmex installation
uv run python -c "import codomyrmex; print('✅ Import successful')"

# 4. Run system check
codomyrmex check

# 5. Check dependencies
uv pip list | grep -E "(matplotlib|numpy|pytest|docker)"

🚨 Common Issues & Solutions

❌ "Module not found" Errors

# Problem: ImportError when trying to use Codomyrmex
# Solution: Ensure virtual environment is activated and installation is correct

# 1. Check you're in the right directory
cd /path/to/codomyrmex

# 2. Activate virtual environment
source .venv/bin/activate

# 3. Verify Python path
which python  # Should show .venv/bin/python

# 4. Reinstall if needed
uv sync

# 5. Test import
uv run python -c "import codomyrmex; print('Success!')"

❌ Python Version Too Old

# Problem: Python 3.9 or older detected
# Solution: Upgrade to Python 3.10+

# macOS with Homebrew
brew install python@3.11
brew link python@3.11

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.11 python3.11-venv

# Windows: Download from python.org
# Install Python 3.10+ and add to PATH

❌ Virtual Environment Problems

# Problem: Virtual environment not working properly
# Solution: Recreate the environment

# Remove old environment
rm -rf .venv

# Create fresh environment
uv venv .venv

# Activate and install
source .venv/bin/activate
uv sync

# Verify
codomyrmex check

❌ Permission Errors

# Problem: Permission denied when installing packages
# Solution: Don't use sudo in virtual environments

# Correct approach:
source .venv/bin/activate
uv pip install package_name

# If you accidentally used sudo:
sudo rm -rf .venv
uv venv .venv
source .venv/bin/activate
uv sync

❌ "No module named 'codomyrmex'" After Installation

# Problem: Module not found despite installation
# Solution: Check installation and Python path

# 1. Check installation location
uv pip show codomyrmex

# 2. Verify PYTHONPATH includes the right directories
echo $PYTHONPATH

# 3. Try reinstalling
uv pip uninstall codomyrmex
uv sync

# 4. Test in fresh shell
source .venv/bin/activate
uv run python -c "import codomyrmex; print('Fixed!')"

🔧 Module-Specific Issues

🤖 AI Features Not Working

# Problem: AI code generation fails
# Solution: Check API keys and connectivity

# 1. Check API keys are set
echo "OpenAI: ${OPENAI_API_KEY:+SET}"
echo "Anthropic: ${ANTHROPIC_API_KEY:+SET}"

# 2. Create .env file if missing
cat > .env << EOF
OPENAI_API_KEY="your-openai-key-here"
ANTHROPIC_API_KEY="your-anthropic-key-here"
GOOGLE_API_KEY="your-google-key-here"
EOF

# 3. Test API connectivity
uv run python -c "
import os
from codomyrmex.agents import validate_api_keys
print('API Keys:', validate_api_keys())
"

🐳 Docker/Code Execution Issues

# Problem: Code execution sandbox fails
# Solution: Check Docker installation and permissions

# 1. Verify Docker is installed and running
docker --version
docker run hello-world

# 2. On Linux, add user to docker group
sudo usermod -aG docker $USER
# Logout and login again

# 3. Test sandbox functionality
uv run python -c "
from codomyrmex.coding import execute_code
result = execute_code('python', 'print(\"Hello\")')
print('Sandbox test:', result['success'])
"

📊 Visualization Issues

# Problem: Can't create plots or display images
# Solution: Check matplotlib backend and dependencies

# 1. Check matplotlib installation
uv run python -c "import matplotlib; print('Matplotlib version:', matplotlib.__version__)"

# 2. Set non-interactive backend for saving files
export MPLBACKEND=Agg

# 3. Test plot creation
uv run python -c "
from codomyrmex.data_visualization import create_line_plot
import numpy as np
x = np.linspace(0, 10, 50)
y = np.sin(x)
result = create_line_plot(x, y, output_path='test.png')
print('Plot test:', result is not None)
"

📚 Documentation Build Issues

# Problem: Documentation website build fails
# Solution: Check Node.js and dependencies

# 1. Verify Node.js version
node --version  # Should be 18.0+

# 2. Install dependencies
cd src/codomyrmex/documentation
npm install

# 3. Test build
npm run build

# 4. If issues persist, clear cache
rm -rf node_modules package-lock.json
npm install

🔍 Advanced Debugging

Check System Dependencies

# Verify all required system packages
uv run python -c "
import sys
required_modules = ['matplotlib', 'numpy', 'pytest', 'docker']
for module in required_modules:
    try:
        __import__(module)
        print(f'✅ {module}')
    except ImportError as e:
        print(f'❌ {module}: {e}')
"

# Check optional dependencies
optional_modules = ['openai', 'anthropic', 'google.genai']
for module in optional_modules:
    try:
        __import__(module)
        print(f'✅ {module} (optional)')
    except ImportError:
        print(f'⚠️  {module} (optional - not installed)')
"

Environment Variable Issues

# Check if .env file is being loaded
uv run python -c "
import os
from pathlib import Path

# Check if .env exists and is readable
env_file = Path('.env')
if env_file.exists():
    print('✅ .env file exists')
    print('📄 Contents preview:')
    with open(env_file) as f:
        lines = f.readlines()[:3]  # Show first 3 lines
        for line in lines:
            if '=' in line and not line.startswith('#'):
                key = line.split('=')[0]
                print(f'  {key}: {os.getenv(key, \"NOT SET\")}')
else:
    print('⚠️  .env file not found')
"

🚀 Getting Additional Help

If these solutions don't resolve your issue:

Check the logs: Look for detailed error messages
```
codomyrmex check --verbose
```

Review the documentation: Check module-specific guides

# See available documentation
find docs/ -name "*.md" | head -10

Search existing issues: GitHub Issues
Ask the community: GitHub Discussions
Create a bug report: Include your system info and exact error messages

🚀 Next Steps

Once installed successfully:

Try the Quick Start: Follow the Quick Start Guide
Explore modules: Use the Interactive Shell
Read tutorials: Check out Tutorials for specific use cases
Join development: See Contributing Guide

Installation complete! You're ready to start using Codomyrmex's powerful modular toolkit for code analysis, generation, and workflow automation.

📝 Documentation Status: ✅ Verified & Signed | Last reviewed: March 2026 | Maintained by: Codomyrmex Documentation Team | Version: v1.2.3

Navigation Links

Parent: Project Overview
Module Index: All Agents
Documentation: Reference Guides
Home: Repository Root

FilesExpand file tree

installation.md

Latest commit

History