ProjectHephaestus

ProjectHephaestus

Shared utilities and tooling for the HomericIntelligence ecosystem, powered by Pixi for environment management.

Overview

ProjectHephaestus provides standardized utility functions and tools that can be shared across all HomericIntelligence repositories. Following the principles in CLAUDE.md, this project emphasizes:

• Modularity: Well-defined, reusable components
• Simplicity: KISS (Keep It Simple, Stupid) principle
• Consistency: Standardized interfaces and patterns
• Reliability: Comprehensive testing and error handling

Directory Structure

ProjectHephaestus/
├── pixi.toml          # Pixi configuration
├── pyproject.toml     # Python package configuration
├── hephaestus/        # Main package
│   ├── __init__.py
│   ├── utils/         # General utility functions (slugify, retry, subprocess)
│   ├── config/        # Configuration utilities (YAML, JSON, env vars)
│   ├── io/            # I/O utilities (read, write, safe_write, load/save data)
│   ├── cli/           # CLI helpers (argument parsing, output formatting)
│   ├── logging/       # Logging utilities (ContextLogger, setup_logging)
│   ├── system/        # System information collection
│   ├── git/           # Git utilities (changelog generation)
│   ├── github/        # GitHub automation (PR merging)
│   ├── datasets/      # Dataset downloading utilities
│   ├── markdown/      # Markdown linting and link fixing
│   ├── benchmarks/    # Benchmark comparison utilities
│   ├── version/       # Version management
│   └── validation/    # README and config validation
├── tests/             # Unit tests
├── docs/              # Documentation
├── scripts/           # Utility scripts
└── README.md          # This file

Getting Started with Pixi

This project uses Pixi for environment management, which automatically handles dependencies and creates isolated environments.

Prerequisites

Install Pixi by following the official installation guide.

Setup Development Environment

# Install dependencies and create environment
pixi install

# Activate the environment (optional, as pixi runs commands in the environment automatically)
pixi shell

Running Tests

# Run tests using the test feature
pixi run test

# Or run tests directly with pytest
pixi run pytest

Development Commands

# Format code with ruff
pixi run format

# Lint code with ruff
pixi run lint

Usage

As a Package

After installing with Pixi:

from hephaestus import slugify, human_readable_size, retry_with_backoff

# Convert text to URL-friendly slug
project_slug = slugify("My Project Name")
print(project_slug)  # Output: my-project-name

# Convert bytes to human readable size
size_str = human_readable_size(1048576)
print(size_str)  # Output: 1.0 MB

As a Claude Code Plugin

ProjectHephaestus also ships as a Claude Code plugin, providing slash commands for repository auditing, agent orchestration, and knowledge management.

claude plugin install HomericIntelligence/ProjectHephaestus

Then enable it in your project's .claude/settings.json:

{
  "enabledPlugins": {
    "hephaestus@ProjectHephaestus": true
  }
}

See docs/plugin-installation.md for the full installation guide and skill reference.

Installing in Another Project

ProjectHephaestus is published to PyPI as homericintelligence-hephaestus.

Using pip:

pip install homericintelligence-hephaestus

Using Pixi:

Add to pyproject.toml:

[project]
dependencies = [
    "homericintelligence-hephaestus>=0.6.0,<1",
]

Or add a PyPI entry to pixi.toml:

[pypi-dependencies]
homericintelligence-hephaestus = ">=0.6.0,<1"

Then run pixi install to resolve the dependency.

For local development (path dependency):

[pypi-dependencies]
homericintelligence-hephaestus = { path = "../ProjectHephaestus", editable = true }

Key Features

General Utilities (hephaestus.utils)

• slugify(text): Convert text to URL-friendly slug
• retry_with_backoff(func): Decorator for exponential backoff retries
• human_readable_size(bytes): Convert bytes to human readable format
• flatten_dict(dict): Flatten nested dictionaries
• run_subprocess(cmd): Execute shell commands with error handling
• get_setting(config, key_path): Get nested dict values with dot notation

Configuration (hephaestus.config)

• load_config(path): Load YAML or JSON configuration files
• get_setting(config, key_path): Dot-notation config access
• merge_configs(*configs): Deep-merge multiple configuration dicts
• merge_with_env(config, prefix): Overlay environment variables onto config

Environment Variable Convention