Hydra Forge Engine (Internal)#

⚠️ Internal System – Do Not Import

This page documents the internal Hydra Forge engine for transparency, debugging, and auditing purposes only.

There are: - No API stability guarantees - No backward compatibility promises - No support for direct imports

Client code must never depend on these modules.

Hydra Forge - Engine Overview#

High-performance scientific library infrastructure

What is Hydra Forge?#

Hydra Forge is the internal engineering engine that powers this library.

It is a production-grade build, documentation, and diagnostics system designed for scientific and engineering Python libraries that require:

  • Native C++ / Fortran acceleration

  • Reproducible environments

  • Deterministic project structure

  • High-quality documentation

  • Robust diagnostics across Python and native layers

Hydra Forge is not application code. It is infrastructure.

This project was generated and is maintained using Hydra Forge to ensure long-term stability, performance, and maintainability.

—

Design Philosophy#

Hydra Forge is built around a few non-negotiable principles:

Single Source of Truth#

  • Python APIs are derived from the actual source code

  • Native APIs are derived from runtime-exposed symbols

  • Documentation reflects what actually runs, not what is inferred

Explicit Separation of Concerns#

  • Client code lives in src/<package_name>/

  • Engine logic lives in hydra_forge/

  • Native code is isolated under _native/

There is no ambiguity about ownership or responsibility.

Automation Over Convention#

Anything that can drift over time is automated: * Native builds * Symbol exposure (__all__) * Documentation generation * Diagnostics * Environment bootstrapping

—

Engine Structure#

The hydra_forge/ directory is intentionally included in the repository so that advanced users can inspect how the system works.

However, not all engine modules are meant to be used directly.

Hydra Forge scripts are divided into two categories:

—

Primary Engine Scripts#

(Public entry points - safe to run)

These scripts are designed to be executed directly, typically via:

python -m hydra_forge.<script_name>

They provide stable, supported workflows.

Primary scripts include:#

  • `update_docs` - Regenerates the complete project documentation (Python + native)

  • `native_smithery` - Rebuilds all native C++ / Rust / Fortran extensions

  • `update_namespace` - Recomputes public Python symbol tables

  • `doctor` - Performs environment and project sanity checks

  • `clear_pycache` - Removes cached Python artifacts

  • `map_folder_structure` - Generates a canonical project layout

If you are unsure what to run, only use these.

—

Secondary Engine Modules#

(Internal - do not call directly)

All other modules inside hydra_forge/ are internal implementation details.

They include: * AST scanners * Inventory builders * Documentation renderers * Native inspection utilities * Diagnostics collectors * Bootstrap and environment logic

These modules are: * Documented for transparency * Structured for maintainability * Not stable APIs

You should not import or call them directly unless you are extending Hydra Forge itself.

—

Native Code Integration#

Hydra Forge treats native code as a first-class citizen.

Key guarantees:

  • Native functions are exposed only via runtime inspection

  • Python wrappers do not lie about availability

  • Docstrings are extracted directly from native bindings (pbdoc)

  • Missing documentation is detected and reported

This ensures that the Python API, documentation, and compiled binaries never drift apart.

—

Documentation Pipeline#

Documentation is generated automatically from:

  • Python AST analysis

  • Runtime-inspected native modules

  • Native pbdoc blocks

  • Engine diagnostics

No handwritten API docs. No stale references.

If it appears in the documentation, it exists at runtime.

—

Ownership & Maintenance Model#

  • Hydra Forge is an engineering engine developed and maintained separately

  • The generated library belongs entirely to the client

  • Engine updates can be applied without modifying client code

  • Engine internals are isolated from domain logic

—

When Not to Touch Hydra Forge#

You generally do not need to modify anything inside hydra_forge/ if you are:

  • Adding new Python modules

  • Adding new native functions

  • Updating documentation

  • Running tests

  • Rebuilding native extensions

Hydra Forge is designed so that normal development never requires engine changes.

—

Summary#

Hydra Forge exists so that this library can focus on science and engineering, not infrastructure maintenance.

It provides: * Reproducibility * Performance * Clarity * Safety

Treat it as you would a compiler or build system: visible, trustworthy, and rarely modified.

Hydra Forge - Internal Package Initialization#

This package contains the internal tooling required by Hydra Forge: bootstrap, environment helpers, documentation system, native utilities, path mapping, namespace regeneration, etc.

Client projects MUST NOT modify this package.

Generated and maintained by Nord & Ferreira Consulting Lda.

Hydra Forge - Internal Package Initialization#

This package contains the internal tooling required by Hydra Forge: bootstrap, environment helpers, documentation system, native utilities, path mapping, namespace regeneration, etc.

Client projects MUST NOT modify this package.

Generated and maintained by Nord & Ferreira Consulting Lda.

Hydra Forge - Internal Package Initialization#

This package contains the internal tooling required by Hydra Forge: bootstrap, environment helpers, documentation system, native utilities, path mapping, namespace regeneration, etc.

Client projects MUST NOT modify this package.

Generated and maintained by Nord & Ferreira Consulting Lda.

Hydra Forge - Version Management (Bootstrap Edition)#

Centralized semantic version control for all Hydra Forge tools.

Exposes:

  • __version__ Public semantic version

  • __commit__ Short Git commit hash (if available)

  • get_version_info() Structured metadata dictionary

Supports optional override for controlled deployments:

set HYDRA_FORGE_VERSION_OVERRIDE=1.2.3

This file is part of the Hydra Forge engine. Clients must not modify it.

Hydra Forge - Bootstrap System (2025 Option C Edition)#

Responsible for:

  • Discovering the project root

  • Determining package name

  • Detecting active virtual environment

  • Auto-switching ONLY for developer/documentation tools

  • Setting import paths and environment variables

  • Guaranteeing safe, reproducible imports everywhere

This file MUST work even when called from:

  • Batch scripts

  • Python -m hydra_forge.*

  • CMake custom commands

  • IDEs (PyCharm, VSCode, Spyder)

  • Arbitrary working directories

Hydra Forge - AST Documentation Scanner (Canonical)#

Builds a DocumentationInventory from: • AST for Python code • Runtime inspection for portal exposed functions

Hydra Forge - CMakeLists Generator (Bootstrap Edition)#

Automatically detects native C++ modules for the active Hydra Forge client package and generates a CMakeLists.txt for the native layer.

Supports: • C++ pybind11 modules • Fortran backend (OBJECT library) [experimental - not included in this version] • scikit-build-core • Windows / Linux

Clients must NOT edit the generated CMakeLists.txt manually.

Hydra Forge - Native Build Mapping Management of native_categories.json and native_build_map.json. This module is the single source of truth for:

Client-defined module organization (via native_categories.json) Automated incremental rebuild metadata (native_build_map.json) Design principles: native_categories.json is authoritative for API hierarchy (client-controlled) native_build_map.json is fully regenerated each run (automated, ephemeral) Pure functions - no side effects, easy to test

hydra_pre_docs._native.native_util#

Utilities for managing compiled native extensions.

This module intentionally performs no sys.path manipulation. All path isolation is handled externally by hydra_forge.bootstrap.initialize(project_root, pkg_name)

Functions provided#

  • generate_doc_stubs() Virtual modules exposing C++ docstrings to Sphinx and IDEs.

  • safe_load_module(name) Direct .pyd loader for emergency fallback when imports fail.

Design rules#

  • No global state mutations except sys.modules injection for stub packages.

  • No import path hacks.

  • Must not leak environment assumptions.

  • Always safe in multi-library client setups.

Hydra Forge - Utilities#

Centralized runtime branding and helper utilities for all Hydra Forge tools.

IMPORTANT:

  • This file must remain pure - no sys.path manipulation, no environment changes, and no dynamic imports outside version metadata.

  • Clients must never modify this file.

  • All environment isolation is handled by bootstrap.initialize().

Generated and maintained by Nord & Ferreira Consulting Lda.

On this page