Skip to main content

Environment Setup - Usage Examples

This document provides usage examples for the environment_setup module, primarily focusing on the env_checker.py script and its functions.

Example 1: Running env_checker.py as a Standalone Script​

This is the most common way to quickly validate your project environment.

# Navigate to the Codomyrmex project root directory
# cd /path/to/codomyrmex

# Execute the env_checker.py script
python environment_setup/env_checker.py

Expected Outcome​

  • The script will first attempt to import essential Python dependencies (e.g., cased, dotenv).
    • If any are missing, it will print an error message to stderr instructing you to install them (usually via uv sync) and then exit.
  • If dependencies are present, it will then check for the .env file in the project root.
    • If .env is found, it will print a confirmation message and attempt to load it.
    • If .env is missing, it will print a detailed message to stdout guiding you on how to create it, including a template with common API key placeholders (e.g., OPENAI_API_KEY), and then exit.
  • If both checks pass, you should see messages indicating success.

Example 2: Importing and Using env_checker.py Functions in Another Script​

Modules or utility scripts within Codomyrmex can programmatically use the functions from env_checker.py to perform environment validation at runtime.

# In your_module/your_script.py

import os
import sys

# Determine the project root path (adjust if your script is nested differently)
# This example assumes your_script.py is one level inside a module directory, 
# and the module directory is at the project root.
# For example: codomyrmex/your_module/your_script.py
# then project_root should be codomyrmex/

# A more robust way to find project root might be needed depending on script location
# This is a basic example assuming a known structure.
try:
    current_dir = os.path.dirname(os.path.realpath(__file__))
    project_root = os.path.abspath(os.path.join(current_dir, '..', '..')) # Adjust '..', '..' based on actual depth
    # Verify a known marker for project root, e.g., the presence of 'pyproject.toml' or '.git'
    if not os.path.exists(os.path.join(project_root, 'pyproject.toml')):
        # Fallback or raise error if heuristic fails
        print("Error: Could not reliably determine project root for env_checker.py. Please ensure your script correctly identifies it.", file=sys.stderr)
        # As a simple fallback, assuming script is run from somewhere within project:
        project_root = os.getcwd() 
        print(f"Attempting to use current working directory as project root: {project_root}", file=sys.stderr)

except NameError: # __file__ is not defined (e.g. in an interactive session)
    project_root = os.getcwd()
    print(f"Warning: __file__ not defined. Using current working directory as project root for env_checker: {project_root}", file=sys.stderr)


# Import the functions
# Ensure environment_setup is in PYTHONPATH or script is run in a way that allows the import
try:
    from environment_setup.env_checker import ensure_dependencies_installed, check_and_setup_env_vars
except ImportError:
    print("Error: Could not import from environment_setup.env_checker. Make sure PYTHONPATH is set correctly or run from project root.", file=sys.stderr)
    # Potentially add environment_setup to sys.path if a known relative path exists
    # For example, if this script is in codomyrmex/some_module/script.py:
    # sys.path.append(os.path.join(project_root, 'environment_setup'))
    # from env_checker import ensure_dependencies_installed, check_and_setup_env_vars
    sys.exit(1) # Exit if import fails

print("Performing environment checks...")

# Check 1: Ensure core Python dependencies are installed
ensure_dependencies_installed()
print("Core Python dependencies seem to be installed.")

# Check 2: Ensure .env file is present and set up
# The check_and_setup_env_vars function expects the absolute path to the repository root.
check_and_setup_env_vars(repo_root_path=project_root)
print(f".env file check completed. API keys should now be loaded if .env exists at {project_root}.")

# Now you can safely access environment variables, e.g.:
# my_api_key = os.getenv("OPENAI_API_KEY")
# if my_api_key:
#     print("Successfully retrieved OPENAI_API_KEY.")
# else:
#     print("OPENAI_API_KEY not found in environment.")

print("Environment checks passed. Proceeding with script execution.")
# ... rest of your script's logic ...

Expected Outcome​

  • Similar to Example 1, the imported functions will perform their respective checks.
  • If ensure_dependencies_installed() fails, the script will exit with a message.
  • If check_and_setup_env_vars() finds the .env file missing (after being provided the project root), it will print guidance and exit.
  • If both checks pass, messages indicating success will be printed, and the calling script can proceed, assuming necessary environment variables are loaded.

Example 3: Shell Scripts for General Environment Setup​

For examples of shell commands and step-by-step instructions for setting up the broader project environment (including Python virtual environments, uv sync, Node.js setup for the documentation module, etc.), please refer to:

  • The environment_setup/README.md file: Specifically, the section "I. General Project Development Environment Setup".
  • The main project README.md: This may also contain or be the primary source for these instructions once reorganized as suggested.

These READMEs provide the command sequences for initial setup.

Common Pitfalls & Troubleshooting​

  • Issue: ImportError: No module named environment_setup.env_checker (or similar) when trying to import functions in your own script.

    • Solution:
      • Ensure your script is run from a context where Python can find the environment_setup module. This usually means running your script from the project root directory (codomyrmex/).
      • If running from a subdirectory, ensure the codomyrmex/ directory (which contains environment_setup/) is in your PYTHONPATH environment variable, or modify sys.path dynamically in your script (see commented example in the Python script above, but use with caution).
      • Activate your Python virtual environment (source .venv/bin/activate) where project dependencies are installed.

  • Issue: env_checker.py (or imported functions) cannot find .env even if it exists, or suggests creating it in the wrong place.

    • Solution: The check_and_setup_env_vars() function relies on the repo_root_path argument being correctly passed to it. Ensure this path accurately points to the directory where your .env file is (or should be) located, which is typically the main codomyrmex/ project root.

  • Issue: "Essential dependencies are missing" for packages you believe are installed.

    • Solution:
      • Double-check you are in the correct Python virtual environment (source .venv/bin/activate).
      • Run uv pip list to see installed packages in the current environment.
      • Ensure pyproject.toml in the project root is up-to-date and re-run uv sync.

Example 4: First-Time Full Project Setup Checklist (Conceptual Example)​

This scenario walks through the typical commands a developer would run for a first-time setup, as primarily documented in environment_setup/README.md (Part I) or the main project README.md.

Goal: To get the Codomyrmex project cloned, Python environment set up, dependencies installed, and basic configuration (like .env) in place.

# 1. Ensure Prerequisites are Met (Manual Check):
#    - Python 3.10+ installed?
#    - pip available?
#    - git installed?
#    - Node.js 18.0+ and npm/yarn (if working on documentation module)?
#    (Refer to system-specific guides for installing these if missing)

echo "Step 1: Prerequisites - Assumed to be met by the developer."

# 2. Clone the Repository:
git clone https://github.com/your-username/codomyrmex.git # Replace with actual URL
cd codomyrmex
echo "Step 2: Repository cloned and current directory changed to codomyrmex/"

# 3. Create and Activate a Python Virtual Environment:
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
echo "Step 3: Python virtual environment .venv created and activated."

# 4. Install Root Python Dependencies:
uv sync
echo "Step 4: Root Python dependencies installed from pyproject.toml."

# 5. Run `env_checker.py` to verify dependencies and .env setup:
python environment_setup/env_checker.py
# This script will guide you if `.env` is missing or if essential packages from pyproject.toml
# were not installed correctly (e.g., due to pip issues).
# If it prompts to create `.env`, follow its instructions and add your API keys.
echo "Step 5: env_checker.py executed. Follow its guidance if any issues reported."

# 6. (Optional) Setup for the `documentation` Module (Docusaurus):
# If you need to work on or build the documentation website:
read -p "Do you need to set up the documentation module (Docusaurus)? (y/n): " setup_docs
if [[ "$setup_docs" == "y" || "$setup_docs" == "Y" ]]; then
  cd documentation
  echo "Installing Node.js dependencies for Docusaurus... (This might take a moment)"
  npm install # or yarn install
  echo "Docusaurus dependencies installed. You can now run 'npm run start' here."
  cd .. # Return to project root
else
  echo "Skipping documentation module setup."
fi

echo "Step 6: Documentation module setup (if chosen) complete or skipped."

echo "Basic Codomyrmex development environment setup is complete!"

Expected Outcome:

  • The project is cloned.
  • A Python virtual environment is active with necessary packages.
  • env_checker.py has confirmed dependencies and guided .env creation.
  • (If chosen) Docusaurus dependencies are installed.
  • The developer is ready to start working on the project.

Example 5: Setting Up for a Specific Module with Unique Needs (Conceptual)​

While Codomyrmex aims for a unified base setup, a specific module might have an additional, unique setup step not covered by the global pyproject.toml (e.g., installing a specific system library or a tool not manageable by uv).

Scenario: Imagine a hypothetical special_hardware_interface module needs a system driver and a special Python package installed directly from a Git URL.

Instructions for this would typically be in special_hardware_interface/README.md:

# special_hardware_interface - README

## Prerequisites

- Ensure the main Codomyrmex project environment is set up (see `environment_setup/README.md`).

## Module-Specific Setup

1.  **Install System Driver**: 
    ```bash
    # (Instructions for installing the XYZ driver for your OS)
    # sudo apt-get install xyz-driver # Example for Debian/Ubuntu
  1. Install Special Python Package (within your active .venv): 
    uv pip install git+https://example.com/vendor/special_xyz_python_lib.git#egg=special_xyz
  2. Verify: Run the module's verification script (if provided): 
    python special_hardware_interface/verify_setup.py

**Key Takeaway**: For module-specific setup steps beyond the common environment:

1. Always check that module's `README.md` first.
2. Perform these steps *after* the main project setup and *within* the activated project virtual environment (`.venv`).

This `environment_setup` module primarily focuses on the *common* baseline. Individual modules are responsible for documenting their *additional unique* setup requirements.

## Navigation Links

- **Parent**: [Project Overview](../README.md)
- **Module Index**: [All Agents](../../AGENTS.md)
- **Documentation**: [Reference Guides](../../../docs/README.md)
- **Home**: [Root README](../../../README.md)