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, use Pixi to manage the environment:

pixi install
pre-commit install

Directory Structure

ProjectHephaestus/
├── pixi.toml          # Pixi configuration
├── pyproject.toml     # Python package configuration
├── hephaestus/        # Main package
│   ├── __init__.py
│   ├── agents/        # Agent frontmatter + loader + runtime
│   ├── automation/    # Issue planning / implementation / PR review pipeline
│   ├── benchmarks/    # Benchmark comparison utilities
│   ├── ci/            # CI helpers (precommit, workflows, docker timing)
│   ├── cli/           # CLI helpers (argument parsing, output formatting)
│   ├── config/        # Configuration utilities (YAML, JSON, env vars)
│   ├── datasets/      # Dataset downloading utilities
│   ├── discovery/     # Discovery of agents, skills, and code blocks
│   ├── forensics/     # Coredump capture + gdb post-mortem runner
│   ├── github/        # GitHub automation (PR merging, fleet sync, tidy, stats)
│   ├── io/            # I/O utilities (read, write, safe_write, load/save data)
│   ├── logging/       # Logging utilities (ContextLogger, setup_logging)
│   ├── markdown/      # Markdown linting and link fixing
│   ├── nats/          # NATS JetStream subscriber (event-driven workflows)
│   ├── resilience/    # Circuit breaker + retry + subprocess resilience primitives
│   ├── system/        # System information collection
│   ├── utils/         # General utility functions (slugify, retry, subprocess)
│   ├── validation/    # README, schema, and structural validation
│   └── version/       # Version management (hatch-vcs + consistency checks)
├── 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.

Platform note: The pixi developer environment is Linux-64 only (see platforms in pixi.toml). On macOS or Windows, install the published wheel into a plain virtualenv instead — see From PyPI above. The full comparison table (install paths, supported platforms, Python versions) lives in CONTRIBUTING.md#platform-support.

Prerequisites

Install Pixi by following the official installation guide.

Setup Development Environment

# Install dependencies and create environment
pixi install