Skip to content

setup.md

Latest commit

 

History

History
605 lines (432 loc) · 14.4 KB

setup.md

File metadata and controls

605 lines (432 loc) · 14.4 KB

🚀 Codomyrmex Setup Guide

This guide covers all aspects of setting up Codomyrmex, from initial installation to advanced configuration and development environment setup.

🎯 Quick Start Setup

Option 1: UV-Optimized Setup (Recommended)

# 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 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

Option 3: Alternative Setup (if uv not available)

# 1. Clone and setup virtual environment
git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. Install dependencies
uv pip install -e .

# 3. Verify installation
codomyrmex check

Note: Using uv is strongly recommended over traditional pip for faster, more reliable dependency management.

✅ Installation Verification

After installation, verify everything is working:

# Check system health
codomyrmex check

# View project information
codomyrmex info

# Run basic tests
pytest src/codomyrmex/tests/unit/ -x

# Try interactive exploration
./start_here.sh
# Choose option 7: Interactive Shell

📋 Prerequisites

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!')"

🧪 Testing & Verification

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
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
pytest src/codomyrmex/tests/ --cov=src/codomyrmex --cov-report=html

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

# Run integration tests
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
python -m ruff check src/codomyrmex/

# Format code (if needed)
python -m black src/codomyrmex/

# Type checking (if configured)
python -m mypy src/codomyrmex/

🚨 Troubleshooting Guide

This section provides solutions for the most common installation and setup issues.

🔍 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
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
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}')
"

🚀 Advanced Setup

Development Environment Setup

For contributors, see the complete development environment setup in Development Setup Guide.

Production Deployment

For production deployment, see Production Deployment Guide.

CI/CD Integration

For integrating with CI/CD systems, see External Systems Integration.

Advanced Configuration

📞 Getting Help

Community Support

  • 📖 Documentation Issues: GitHub Issues - Report documentation problems
  • 💬 General Questions: GitHub Discussions - Ask questions and share ideas
  • 🐛 Bug Reports: Use the issue tracker for bugs and feature requests

When Reporting Issues

Include:

  1. System Information: python --version, uname -a
  2. Codomyrmex Information: codomyrmex check, pip list | grep codomyrmex
  3. Error Details: Complete error messages, steps to reproduce
  4. Environment: Virtual environment status, API keys configured, Docker version

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

Next Steps:

  1. 🎮 Try Interactive Examples: Examples Documentation
  2. 📚 Explore Documentation: docs/README.md
  3. 🏗️ Understand Architecture: docs/project/architecture.md
  4. 🤝 Join Development: docs/project/contributing.md

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

Navigation Links