hephaestus

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

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

Installation

From PyPI

ProjectHephaestus 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__)

Note on naming. pip install hephaestus and pip install project-hephaestus will not find this package — both names are unowned on PyPI. The HomericIntelligence-<Project> prefix is the deliberate naming convention shared across the HomericIntelligence ecosystem (ProjectKeystone, ProjectOdyssey, etc.) to avoid PyPI namespace collisions. 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: github, nats, toml, xml, schema.
• pip install HomericIntelligence-Hephaestus[dev] — installs development and testing dependencies. Use this for contributors and CI.
• pip install "HomericIntelligence-Hephaestus[all,dev]" — both, for a full development environment via pip (Pixi users get this automatically via pixi install).
• Individual extras (e.g. [github], [schema]) are available for users who only need one integration.

Development setup

For local development, install Pixi 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

ProjectHephaestus 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. The boundary is enforced by tests/unit/test_import_surface.py and tests/unit/test_automation_boundary.py. See docs/adr/0001-automation-library-boundary.md.

Directory Structure