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.
• The [github] extra is an empty compatibility extra. GitHub commands use the external gh command and this extra installs no Python dependency.
• Individual dependency-bearing extras (e.g. [nats], [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, observability, prompts, scripts_lib, 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 the fast pre-commit and pull-request test selection
just test

# Run the full nightly normal-test complement
just test-nightly

# Run the fast unit selection
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

Local metadata subprocesses, including the version git-tag probe, default to 10 seconds. HEPHAESTUS_SUBPROCESS_METADATA_TIMEOUT accepts integer values from 1 through 86400 seconds; malformed or out-of-range values emit a bounded warning and use the 10-second default. Terminal restoration uses a fixed 2-second cleanup timeout and has no override.

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

Explicit configuration

Hephaestus does not overlay HEPH_* or HEPHAESTUS_* environment variables onto application configuration. Load a configuration file, parse command-line options at the application boundary, and merge those explicit values:

from hephaestus.config import load_config, merge_configs

file_config = load_config("hephaestus.yml")
cli_overrides = {"database": {"host": args.database_host}}
config = merge_configs(file_config, cli_overrides)

See the environment-variable registry for the remaining narrowly approved runtime variables and the deny-by-default policy.

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 58 console scripts from [project.scripts].

Automation

Codex implementation uses the native direct runner when no isolation adapter is selected. This temporary path uses shared host state in HOME/.codex. An explicit adapter selection still requires complete, valid deployment evidence and never falls back after failure. See ADR-0043 and the production adapter issue.

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, then write a private, mode-0600 TOML alias file containing exactly provider and model strings. Pass its path with --pi-alias-config; aliases are parsed in process and are never forwarded through the parent environment, subprocess arguments, logs, or Slurm exports. See docs/pi-private-provider.md for the sanitized setup and denylist guard. Run hephaestus-install-pi-plugins --dry-run --json to inspect the exact package plan and hephaestus-install-pi-plugins --global --yes --no-approve to install the safe global defaults. Passing package preflight does not admit normal Pi automation: in a standard installation, --agent pi fails before stage or wrapper dispatch because no OS-isolation adapter is bundled. A trusted host integration must provide a named hephaestus.pi_isolation_adapters entry point, and the operator must select it with --pi-isolation-adapter ENTRY_POINT. That adapter enforces the resolved filesystem and network policy; the local setup otherwise supports only the explicit adapter-smoke seam.

Use --disable-pi-automation when a run must omit Pi. That flag leaves host-owned Athena advise and learn unchanged. See docs/runbooks/pi-rollout.md for enable, omit, and recovery steps.

For independent tool selection, literal model names, and migration from aliases, MODEL[:EFFORT] controls, and external server requirements, see docs/ifm-models.md.

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

For recovery from an older installed package, use the fixed-revision runtime procedure. Repository synchronization does not update the package that runs the coordinator. On macOS, host verification requires a virtual environment. A Conda base environment is not supported for this operation.

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

hephaestus-run-under-gdb limits gdb and RUN_UNDER_GDB=0 execution to 7200 seconds by default. Pass --timeout SECONDS before <core-dir> to select a value from 1 through 86400. On timeout, POSIX platforms kill and boundedly reap the dedicated process group; platforms without process-group support kill and boundedly reap the direct child instead. Timeouts exit 124. Lack of POSIX process-group support does not prevent normal execution.

Validation

Markdown

CI / Pre-commit

Development Utilities

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

Follow the ASD-STE100 writing standard for all English technical prose that you create or revise.

1. Follow the principles in AGENTS.md
2. Write comprehensive unit tests for all new functionality
3. Run each new or changed test and verify that it passes before you create a PR
4. Document all public functions with Google-style docstrings
5. Use type hints for all function parameters and return values
6. 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. Run each new or changed test. Verify that pytest collects it and reports success. The full suites run in required CI/CD, not in pre-commit.
4. Push the branch (git push -u origin 123-amazing-feature).
5. 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.
6. 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.