Skip to content

AGENTS.md

Latest commit

 

History

History
341 lines (252 loc) · 10.1 KB

AGENTS.md

File metadata and controls

341 lines (252 loc) · 10.1 KB
Raw

Setup Module - Agent Scaffolding

Module Overview

Purpose: Environment setup, dependency management, and system configuration for the GNN processing pipeline

Pipeline Step: Step 1: Environment setup (1_setup.py)

Category: Environment Management / Dependency Installation

Status: ✅ Production Ready

Version: 1.6.0

Last Updated: 2026-04-16

Core Functionality

Primary Responsibilities

  1. Virtual environment creation and management
  2. Dependency installation and validation via native UV commands
  3. System requirement verification
  4. UV (Python package manager) integration
  5. Environment configuration and optimization

Key Capabilities

  • Automated virtual environment setup using UV
  • Comprehensive dependency management via uv sync
  • System requirement validation
  • UV environment optimization
  • Dependency conflict resolution via uv.lock
  • Environment health monitoring
  • Native UV dependency operations (add, remove, sync, lock)

API Reference

Orchestrator Entry Point

The thin orchestrator src/1_setup.py defines:

setup_orchestrator(target_dir, output_dir, logger, **kwargs) -> bool

It wraps setup_uv_environment (default path) or setup_complete_environment (when optional groups are requested). **kwargs accepts:

  • verbose (bool) — verbose logging
  • recreate_venv (bool) — recreate .venv
  • dev (bool) — uv sync --extra dev
  • install_all_extras (bool) — uv sync --all-extras (supersedes dev)
  • setup_core_only (bool) — skip the JAX/Optax/Flax/pymdp probe
  • install_optional (bool) — install optional groups
  • optional_groups (str) — comma-separated group names (see OPTIONAL_GROUPS)

Default path: uv sync for core deps. Step 12 core backends (JAX, NumPyro, DisCoPy), interactive visualization (pandas, plotly, seaborn, h5py), and LLM clients are in [project.dependencies] and therefore installed without any --extra. PyTorch and bnlearn are still supported by render/execute code paths, but remain manual installs while the current Torch advisory has no patched release. SETUP_DEFAULT_PIPELINE_EXTRAS is empty by default because core dependencies already cover the default pipeline runtime. Step 22 (GUI) additionally needs uv sync --extra gui to pull Gradio.

Module-level Public Functions

setup_uv_environment(verbose=False, recreate=False, dev=False, extras=None, install_all_extras=False, skip_jax_test=False, output_dir=None) -> bool

Description: Set up UV virtual environment with dependencies using native UV sync

Parameters:

  • verbose: Enable verbose output
  • recreate: Recreate existing environment
  • dev: Install development optional group (--extra dev)
  • extras: Additional package groups to install (each as --extra)
  • install_all_extras: If true, uv sync --all-extras (takes precedence over dev)
  • skip_jax_test: Skip the JAX stack probe (same probe as utils.jax_stack_validation.verify_jax_pymdp_stack)
  • output_dir: Output directory for setup logs

Returns: True if setup succeeded

install_uv_dependencies(verbose=False, dev=False, extras=None, install_all_extras=False) -> bool

Description: Install UV dependencies using uv sync from pyproject.toml

Parameters:

  • verbose: Enable verbose output
  • dev: If true and install_all_extras is false, append --extra dev
  • extras: Additional package groups (--extra each)
  • install_all_extras: If true, append --all-extras (ignores dev for sync flags)

Returns: True if installation succeeded

add_uv_dependency(package: str, dev: bool = False, verbose: bool = False) -> bool

Description: Add a dependency using uv add command

Parameters:

  • package: Package name with optional version specifier
  • dev: Add as development dependency
  • verbose: Enable verbose logging

Returns: True if successful

remove_uv_dependency(package: str, verbose: bool = False) -> bool

Description: Remove a dependency using uv remove command

Parameters:

  • package: Package name to remove
  • verbose: Enable verbose logging

Returns: True if successful

update_uv_dependencies(verbose: bool = False, upgrade: bool = False) -> bool

Description: Update dependencies using uv sync command

Parameters:

  • verbose: Enable verbose logging
  • upgrade: Upgrade dependencies to latest compatible versions

Returns: True if successful

lock_uv_dependencies(verbose: bool = False) -> bool

Description: Update lock file using uv lock command

Parameters:

  • verbose: Enable verbose logging

Returns: True if successful

check_system_requirements(verbose=False) -> bool

Description: Check system requirements for GNN pipeline

Parameters:

  • verbose: Enable verbose output

Returns: True if requirements are met

Dependencies

Required Dependencies

  • uv - Python package manager (required, native commands used)
  • python - Python interpreter (>=3.9)
  • pyproject.toml - Project dependencies configuration

Optional Dependencies

  • None (UV handles all dependency management)

Internal Dependencies

  • utils.pipeline_template - Pipeline utilities

Configuration

Environment Settings

UV_CONFIG = {
    'python_version': '3.11',
    'environment_name': 'gnn-pipeline',
    'dependency_source': 'pyproject.toml',  # Primary source
    'lock_file': 'uv.lock',  # Dependency lock file
    'use_native_uv': True,  # Use native UV commands
    'dev_dependencies': True,
    'test_dependencies': True
}

System Requirements

SYSTEM_REQUIREMENTS = {
    'python_version_min': '3.9',
    'memory_min_gb': 4,
    'disk_space_min_gb': 2,
    'cpu_cores_min': 2,
    'uv_required': True
}

Usage Examples

All setup helpers are exported from the package root. Prefer from setup import ….

from setup import (
    setup_uv_environment,
    add_uv_dependency,
    remove_uv_dependency,
    update_uv_dependencies,
    lock_uv_dependencies,
    check_system_requirements,
)

setup_uv_environment(verbose=True, dev=True, extras=["llm", "visualization", "audio"])

add_uv_dependency("requests>=2.28.0", dev=False, verbose=True)
add_uv_dependency("pytest>=7.0.0", dev=True, verbose=True)
remove_uv_dependency("old-package", verbose=True)
update_uv_dependencies(verbose=True, upgrade=False)
update_uv_dependencies(verbose=True, upgrade=True)
lock_uv_dependencies(verbose=True)

if not check_system_requirements(verbose=True):
    raise SystemExit("System requirements not met")

Output Specification

Output Products

  • environment_setup_summary.json - Setup completion summary, timings, and probe results
  • installed_packages.json - Installed package inventory
  • uv.lock - Dependency lock file (updated)

Output Directory Structure

output/1_setup_output/
├── environment_setup_summary.json
└── installed_packages.json

Performance Characteristics

Latest Execution

  • Duration: ~2-5 minutes for full setup
  • Memory: ~50-100MB during installation
  • Status: ✅ Production Ready

Expected Performance

  • Environment Creation: 30-60 seconds
  • Dependency Installation: 1-3 minutes (via uv sync)
  • System Validation: < 30 seconds
  • Health Check: < 10 seconds
  • Dependency Lock: < 10 seconds

Error Handling

Setup Errors

  1. Environment Creation: Virtual environment creation failures
  2. Dependency Installation: Package installation errors via uv sync
  3. System Requirements: Insufficient system resources or missing UV
  4. Network Issues: Package download failures
  5. Permission Errors: Insufficient file permissions
  6. Lock File Conflicts: Lock file corruption or conflicts

Recovery Strategies

  • Retry Logic: Automatic retry for transient failures
  • Lock File Regeneration: Regenerate uv.lock if corrupted
  • Graceful Degradation: Continue with available packages
  • Manual Instructions: Provide manual installation guidance
  • Environment Recreate: Option to recreate environment from scratch

Integration Points

Orchestrated By

  • Script: 1_setup.py (Step 1)
  • Function: setup_uv_environment()

Imports From

  • utils.pipeline_template - Pipeline utilities

Imported By

  • main.py - Pipeline orchestration
  • tests.test_setup_* - Setup tests

Data Flow

System Check → UV Environment Creation → UV Sync (pyproject.toml → uv.lock) → Validation → Health Report

Testing

Test Files

  • src/tests/setup/test_setup_overall.py - Module-level setup tests
  • src/tests/test_uv_environment.py - UV environment behavior tests
  • src/tests/test_environment_overall.py - Environment-related integration checks

Test Coverage

Measure on demand — this file does not pin a number:

uv run --extra dev python -m pytest src/tests/test_setup*.py --cov=src/setup --cov-report=term-missing

Key Test Scenarios

  1. Environment creation and setup
  2. Dependency installation via UV sync
  3. System requirement verification
  4. Native UV command operations
  5. Error handling and recovery

MCP Integration

Tools Registered

  • setup.check_environment - Check system environment
  • setup.create_environment - Create UV environment
  • setup.install_dependencies - Install dependencies via UV sync
  • setup.validate_setup - Validate setup completion
  • setup.add_dependency - Add dependency via UV add
  • setup.remove_dependency - Remove dependency via UV remove
  • setup.update_dependencies - Update dependencies via UV sync
  • setup.lock_dependencies - Update lock file via UV lock

Tool Endpoints

@mcp_tool("setup.check_environment")
def check_environment_tool():
    """Check system environment for GNN pipeline"""
    # Implementation

@mcp_tool("setup.add_dependency")
def add_dependency_tool(package: str, dev: bool = False):
    """Add a dependency using UV add"""
    # Implementation

Documentation

  • README: Module Overview
  • AGENTS: Agentic Workflows
  • SPEC: Architectural Specification
  • SKILL: Capability API