Hephaestus

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

Overview

Hephaestus provides standardized utility functions and tools that can be shared across all HomericIntelligence repositories. Following the principles in AGENTS.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

Project Status: See docs/ROADMAP.md for the public roadmap and current focus areas.

Installation

From PyPI

Hephaestus is published to PyPI under the ecosystem-branded distribution name HomericIntelligence-Hephaestus. The import name, however, is the short lowercase hephaestus:

pip install HomericIntelligence-Hephaestus

import hephaestus
print(hephaestus.__version__)

Upgrading? When moving across a major version, read the migration guide for required consumer changes.

Note on naming. pip install hephaestus will not find this package — the bare name is unowned on PyPI. The HomericIntelligence-<Name> prefix is the deliberate naming convention shared across the HomericIntelligence ecosystem (Keystone, Odyssey, etc.) to avoid PyPI namespace collisions; the distribution is HomericIntelligence-Hephaestus. Wheel filenames are PEP 625 normalized to lowercase, so you will see homericintelligence_hephaestus-<version>-py3-none-any.whl on disk and in release assets.

Optional dependencies

pyproject.toml defines several extras groups. [all] is a runtime aggregator and intentionally excludes [dev] (which carries test/lint tooling such as pytest, ruff, and mypy):

• pip install HomericIntelligence-Hephaestus[all] — installs all runtime extras: automation, github, nats, toml, xml, schema. Note that automation is the product layer (hephaestus.automation) and pulls in pydantic; see ADR 0001.
• uv sync — installs the editable project plus its default development and automation dependency groups for contributors.
• uv sync --all-groups --all-extras --locked — installs the complete locked dependency surface used by CI dependency and license checks.
• Individual extras (e.g. [github], [schema]) are available for users who only need one integration.

Development setup

For local development, install uv and just, then bootstrap the project (installs deps, the editable package, and pre-commit hooks in one step):

just bootstrap

See CONTRIBUTING.md → Development Setup for the full workflow, including the manual fallback if you do not have just.

Library vs product layer

Hephaestus ships two layers from one distribution:

• Library — hephaestus.{utils, io, config, logging, cli, system, github, validation, resilience, markdown, ci, benchmarks, datasets, discovery, forensics, nats, version, agents}. Loaded lazily by import hephaestus.
• Product — hephaestus.automation. Opt-in via pip install HomericIntelligence-Hephaestus[automation]. Implements the Claude/Codex automation pipeline (Planner, Implementer, CIDriver, reviewers, loop runner, curses TUI).

import hephaestus does not load hephaestus.automation, curses, fcntl, or pydantic, and a base pip install no longer pulls pydantic (it ships only in the [automation] extra). The boundary is enforced by tests/unit/validation/test_import_surface.py and tests/unit/validation/test_automation_boundary.py. See docs/adr/0001-automation-library-boundary.md.

Repository navigation

This index covers every tracked top-level path except README.md itself and the legacy compatibility pointer. The navigation guard in tests/unit/validation/test_readme_subpackage_tree.py requires new tracked root entries to be added here. Checkout-only state and ignored generated output such as .git/, .venv/, .pytest_cache/, and build/ are intentionally outside this index.

Source and supporting material

Project and policy documents

Build and dependency metadata

Repository tool configuration

Getting Started with uv

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

Platform note: uv supports this project's Python 3.13 development environment on Linux, macOS, and Windows. The required GitHub Actions jobs currently run on Linux; POSIX-specific tests are marked to skip on native Windows. See CONTRIBUTING.md#platform-support.

Prerequisites

Install uv by following the official installation guide.

Setup Development Environment

Bootstrap the project in one step (see CONTRIBUTING.md → Development Setup for the full workflow and the no-just fallback):

just bootstrap

Running Tests

# Run all tests (unit + integration)
just test
uv run pytest

# Run only unit tests (coverage-gated in CI)
just test-unit
uv run pytest tests/unit

# Run only integration tests
just test-integration
uv run pytest tests/integration

# Run all tests except integration
uv run pytest -m "not integration"

All integration tests carry pytest.mark.integration (module-level pytestmark), so marker-based selection is reliable.

Development Commands

# Format code with ruff
just format
uv run ruff format hephaestus scripts tests

# Lint code with ruff
just lint
uv run ruff check hephaestus scripts tests

Usage

As a Package

After installing with uv:

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

Installing in Another Project

Hephaestus is published to PyPI as homericintelligence-hephaestus. The wheel is pure-Python and installs on Linux, macOS, and Windows (see requires-python in pyproject.toml). This is the supported install path for non-Linux platforms.

Using pip:

pip install homericintelligence-hephaestus

Using uv:

Add to pyproject.toml:

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

Then run uv sync to resolve the dependency.

After 1.0 ships, bump these constraints to >=1.0,<2.

For local development (path dependency):

uv add --editable ../Hephaestus

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
• run_git(args, retries=None): Execute Git commands through the shared subprocess adapter with bounded timeout and network retry protection
• 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

merge_with_env maps environment variables to config keys using double underscore (__) as the nesting delimiter. Single underscores are preserved as part of the key name.

Numeric strings are automatically converted to int or float. To also convert boolean-like strings (true/false/yes/no/on/off) to Python bool, pass convert_bools=True:

from hephaestus.config.utils import merge_with_env

# HEPHAESTUS_DEBUG=true → {"debug": True} (not the string "true")
config = merge_with_env({}, convert_bools=True)

I/O Utilities (hephaestus.io)

• read_file(path) / write_file(path, content): Simple file I/O
• load_data(path) / save_data(path, data): Structured data (JSON/YAML)

CLI Commands

Run any command with --help to see full usage.

The package currently installs 56 console scripts from [project.scripts].

Automation

hephaestus-plan-issues exits 75 when open-issue discovery is deferred by a GitHub rate limit. This is a retryable temporary failure, not success. With --json, reset_epoch is the known reset epoch or null, affected_issues is null when discovery could not enumerate them, and incomplete_issue_scope identifies the affected repository selection. Retry without --force; issues already at or past state:plan-go remain completed and are not planned again.

Private Pi provider setup

Pi uses operator-local provider configuration only. Do not commit Pi provider config, endpoint URLs, hostnames, checkpoint names, model identifiers, or local aliases. Configure the OpenAI-compatible provider in the local Pi config, set HEPH_PI_PROVIDER=<operator-local-provider-alias> and HEPH_PI_MODEL=<operator-local-alias> for the explicit smoke sentinel, and see docs/pi-private-provider.md for the sanitized setup and denylist guard. That smoke seam does not yet select those values through Pi's native provider/model contract. Pi is not yet admitted to normal Hephaestus automation: --agent pi fails closed until #2516 verifies the required packages and #2518 enforces native selection, lifecycle, and tool scopes. The local setup is for the explicit adapter-smoke seam only.

Running the automation loop from a source checkout (macOS / Codex)

When hephaestus-automation-loop is not installed on PATH (fresh source checkout) and Claude is not installed, invoke the loop through uv and pin Codex as the agent:

# Prerequisites
command -v uv             # uv installed
command -v codex && codex login status   # Codex authenticated
command -v gh && gh auth status          # gh authenticated

# Title-scoped loop over open "nitpick" / "minor" issues
issues=$(
  gh issue list --state open --limit 500 --json number,title \
    --jq '.[] | select((.title | ascii_downcase) | test("(^|[^a-z0-9_])(nitpick|minor)([^a-z0-9_]|$)")) | .number' \
  | sort -n -u | paste -sd, -
)

test -n "$issues" \
  && uv run hephaestus-automation-loop --issues "$issues" --agent codex \
  || echo "No open nitpick/minor title issues found"

If the pre-loop git fetch is denied (e.g. macOS sandboxing returns error: cannot open .git/FETCH_HEAD: Operation not permitted) the loop now logs a WARNING and renders the trunk line as [Repo] trunk=<sha> (stale) so the refresh failure is visible rather than silently treated as a clean sync (#993).

GitHub

hephaestus-merge-prs exits 0 only when every discovered PR was merged, successfully queued, or intentionally skipped by --dry-run. It exits 1 when any requested PR is blocked, fails, or is unexpectedly left unprocessed, and exits 130 when interrupted. With --json, every outcome—including failure or interruption before PR discovery—contains results, totals, requested, and processed; pre-discovery outcomes use an empty result list, zero totals, and zero requested/processed counts.

System & Data

Debugging & Forensics

Validation

Markdown

CI / Pre-commit

Development Utilities

Configuration & Dependencies

Version Management

Examples

# Collect system info (JSON output)
hephaestus-system-info --json

# Collect system info without tool version checks
hephaestus-system-info --no-tools

# Download a dataset
hephaestus-download-dataset --help

# Merge open PRs
hephaestus-merge-prs --help

# Run all validation checks
hephaestus-check-coverage --help
hephaestus-check-complexity --help

Development Guidelines

1. Follow the principles in AGENTS.md
2. Write comprehensive unit tests for all new functionality
3. Document all public functions with Google-style docstrings
4. Use type hints for all function parameters and return values
5. Keep functions small and focused (single responsibility principle)

Contributing

The main branch is protected; all changes go through a pull request. The active ruleset requires signed commits, while pr-policy checks issue references, Conventional Commit subjects, and DCO trailers. The loop runs $athena:pr-review; its prose and grade are audit evidence, not authorization. pr_review writes state:implementation-go only when a structural audit and fresh live GitHub head, thread, and exclusive-label facts permit that transition. The GitHub label is the loop's sole durable implementation-state authority. merge_wait revalidates the current-process proof and conditionally squash-merges that exact head; it does not create, disable, adopt, or poll an auto-merge request. Normal review may collect CI/CD evidence as context, but the loop does not change CI/CD. Required CI/CD checks are the merge contract.

1. Create a feature branch named <issue-number>-description (git checkout -b 123-amazing-feature).
2. Commit your changes with both attestations (git commit -s -S -m "feat(scope): add amazing feature"), using conventional commit messages.
3. Push the branch (git push -u origin 123-amazing-feature).
4. Open a pull request titled type(scope): concise description whose body contains the literal line Closes #123 (capital C, no colon, on its own line — Fixes/Resolves are not accepted). The title becomes the squash-merge subject on main.
5. Do not enable auto-merge manually. The automation loop's review, label, and merge_wait preserves the head-bound approval boundary with a SHA-conditional normal merge and never mutates native auto-merge.

See CONTRIBUTING.md for the full process.

uv Environment

uv sync creates this checkout's .venv and installs the project in editable mode. The default dependency groups include the development and automation tools; run repository commands with uv run <command> so they use that locked environment. Use uv sync --all-groups --all-extras --locked when a workflow or local check must exercise the complete dependency surface represented by uv.lock.

Adding New Dependencies

Use uv to add a runtime dependency, then refresh the environment:

uv add requests
uv sync

License

BSD 3-Clause License — see LICENSE for the full text, and NOTICE for third-party dependency licenses and compatibility notes.