# Environment Setup - Technical Overview

This document provides a detailed technical overview of the Environment Setup module.

## 1. Introduction and Purpose

The Environment Setup module is designed to streamline the initial developer onboarding process and ensure a consistent, verifiable development environment for the Codomyrmex project. It primarily achieves this through the `env_checker.py` script, which validates critical Python dependencies (like `cased` and `python-dotenv`) and guides the setup of essential configurations such as API keys via `.env` files. Its key responsibility is to minimize environment-related issues by providing an automated check and clear guidance, thereby establishing a reliable baseline for all other development activities within Codomyrmex.

## 2. Architecture

The module's architecture is centered around the `env_checker.py` script. This script contains standalone functions that perform specific checks and can be run directly or imported by other scripts.

- **Key Components/Sub-modules**:
  - `env_checker.py`:
    - `ensure_dependencies_installed()`: This function attempts to import essential Python packages (currently `cased` and `dotenv`). If an `ImportError` occurs for any of them, it prints an instructional message to `stderr` guiding the user to install dependencies (typically via `uv sync` from the project root) and then calls `sys.exit(1)`.
    - `check_and_setup_env_vars(repo_root_path: str)`: This function checks for the existence of a `.env` file at the provided `repo_root_path`.
      - If the file is missing, it prints detailed guidance to `stdout` on how to create one, including a template with common API key placeholders (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`), and then calls `sys.exit(1)`.
      - If the file exists, it attempts to load it using `dotenv.load_dotenv()` and prints a success message.
    - `if __name__ == '__main__':` block: This allows `env_checker.py` to be executed as a standalone script. It determines the project root (assuming `env_checker.py` is in `environment_setup/` under the root) and then calls `ensure_dependencies_installed()` followed by `check_and_setup_env_vars(project_root)`.

- **Data Flow**:
  - `ensure_dependencies_installed()`:
    - Input: None (relies on Python's import mechanism).
    - Output: Messages to `stderr` upon failure. Can terminate the script via `sys.exit(1)`.
  - `check_and_setup_env_vars(repo_root_path: str)`:
    - Input: `repo_root_path` (string) - the absolute path to the project root directory.
    - Output: Messages to `stdout` (guidance for creating `.env`) or `stderr` (error messages). Can terminate the script. Modifies the current process's environment by loading variables if `.env` exists and `dotenv.load_dotenv()` is successful.

- **Core Logic**:
  - Dependency Checking: Utilizes `try-except ImportError` blocks for each specified dependency.
  - `.env` File Check: Uses `os.path.exists()` to check for the file. Prints pre-defined string templates for guidance.
  - Project Root Determination (in `__main__` block of `env_checker.py`): Calculates `os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))` based on the location of `env_checker.py`.

- **External Dependencies** (for `env_checker.py` to operate):
  - `sys`: Used for `sys.exit()` and writing to `sys.stderr`.
  - `os`: Used for path manipulations (`os.path.exists`, `os.path.join`, `os.path.abspath`, `os.path.dirname`, `os.getcwd`).
  - `dotenv` (specifically `python-dotenv`): The `dotenv.load_dotenv()` function is called. The script also checks if this library itself can be imported.
  - `cased`: The script checks if this library can be imported.

```mermaid
flowchart TD
    A[Run `python environment_setup/env_checker.py`] --> B{__main__ block};
    B --> C[Determine Project Root Path];
    C --> D[Call ensure_dependencies_installed()];
    D -- On Import Error for cased/dotenv --> E[Print Error & Exit(1)];
    D -- All Imports OK --> F[Call check_and_setup_env_vars(project_root)];
    F -- .env Missing --> G[Print .env Creation Guide & Exit(1)];
    F -- .env Exists --> H[Call dotenv.load_dotenv()];
    H --> I[Print Success Message];
    E --> Z[End Script];
    G --> Z;
    I --> Z;
```

## 3. Design Decisions and Rationale

- **Standalone Script with Importable Functions**: `env_checker.py` is designed this way for flexibility. Developers can quickly execute `python environment_setup/env_checker.py` for a comprehensive environment validation. Simultaneously, other modules or utility scripts within Codomyrmex can import and use the `ensure_dependencies_installed()` and `check_and_setup_env_vars()` functions programmatically, often as a prerequisite check at the beginning of their execution.
- **Error Handling via `sys.exit(1)`**: For critical missing components (essential Python dependencies, or the `.env` file after guidance has been provided on its necessity), the script terminates with a non-zero exit code. This is standard practice for scripts to signal failure, making it suitable for integration into automated checks or CI/CD pipelines where a script failure should halt further process.
- **Guidance via Print Statements**: When issues are found (missing dependencies or `.env` file), the script provides clear, actionable instructions to the console to help the developer rectify the situation.
- **Reliance on Root `pyproject.toml`**: The `env_checker.py` script does not maintain its own list of project-wide dependencies to check. It verifies a small, critical subset (like `cased`, `dotenv`) assuming these, and all others, are correctly listed in the main project `pyproject.toml`. The primary role of `env_checker.py` is to ensure these key bootstrapping libraries are present and that API key configuration is prompted.

## 4. Data Models

N/A. The `environment_setup` module, particularly `env_checker.py`, primarily deals with system checks (file existence, importability of modules) and string paths. It does not define or operate on complex internal data structures for its core functionality.

## 5. Configuration

N/A. The `env_checker.py` script itself is not externally configured. Its behavior is hardcoded to check for specific dependencies and the `.env` file structure. It is a tool to *check for* configurations required by other parts of the Codomyrmex project.

## 6. Scalability and Performance

N/A for this type of utility module. The checks performed by `env_checker.py` (import attempts, file existence check) are very quick, local operations and have negligible impact on performance or scalability.

## 7. Security Aspects

- The most significant security aspect is the guidance provided for creating the `.env` file for API keys. The script emphasizes the importance of these keys and guides the user to create the file with placeholders. It stresses, via documentation (`SECURITY.md`), that the `.env` file **must not** be committed to version control.
- `env_checker.py` itself does not handle or store actual API key values; it only checks for the file's existence and loads it using `python-dotenv` if present.
- The script relies on Python's `import` mechanism. It assumes that the Python environment and the packages it attempts to import (like `cased`, `dotenv`) are sourced from trusted locations, as per the project's overall dependency management strategy (e.g., using pinned versions from PyPI via `pyproject.toml`).
- Refer to the `environment_setup/SECURITY.md` file for a more detailed discussion on secure API key management and dependency handling.

## 8. Future Development / Roadmap

- **Enhanced Dependency Checks**: Could be expanded to check for specific minimum versions of critical dependencies if necessary, or even to verify the presence of system-level tools (e.g., `git`, `node`).
- **Interactive `.env` Creation**: An option could be added to interactively prompt the user for API key values and create the `.env` file, though this adds complexity and needs careful handling not to log keys.
- **Broader Environment Validation**: Could incorporate checks for Node.js, npm/yarn if these are not covered by a separate mechanism, especially for bootstrapping the `documentation` module setup.
- **Platform-Specific Guidance**: For system prerequisites, provide more platform-specific installation advice (e.g., `apt-get install python3-venv` on Debian/Ubuntu).
- **Integration into a `make setup` or `codomyrmex_cli setup` command**: Encapsulate `env_checker.py` and other setup steps into a more unified project setup command.

## Navigation Links

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