Forge API#

The Forge API is the only client-facing interface to the Hydra Forge engine.

All commands exposed under forge are: - Stable - Documented - Safe to call directly - Intended for automation, CI, and developer tooling

Everything else in the Hydra Forge package is internal.

Hydra Forge - clear_pycache#

Safely remove all Python cache artifacts from a Hydra Forge project.

Windows-safe, idempotent, and resilient to read-only files.

Hydra Forge - doctor#

Read-only diagnostic tool for inspecting the runtime and environment state of a Hydra Forge project.

Doctor Spec: v1.2 (pip + uv aware)

Modes#

analyze (default)

Collects and reports environment, runtime, and native state.

heal (reserved)

Explicitly not implemented.

This tool NEVER modifies project state.

Hydra Forge — Native Exposure Tree Generator#

This script materializes the authoritative native exposure tree under:

_native/compiled/exposed/

The exposure tree defines the entire public native API surface available through {pkg}.portal. Nothing outside this tree is importable by client code.

Purpose#

The generator establishes a deterministic, explicit contract between:

  • what native artifacts exist (build reality), and

  • what native functionality is exposed to Python (API intent).

It produces both:

  • a concrete filesystem layout used for imports, and

  • a machine-readable manifest (exposed_api.json) consumed by documentation, diagnostics, and tooling.

Inputs#

The exposure tree is derived exclusively from the following sources:

  • native_build_map.json

    Ground truth describing what native modules exist, how they were built, and where their compiled artifacts are located.

  • native_categories.json (optional)

    Declarative specification of stable, structured import paths forming the public Python API. Modules not listed here are exposed provisionally under a flat namespace.

No filesystem scanning, heuristics, or runtime discovery is performed beyond these explicit inputs.

Exposure model#

Two exposure modes are supported:

  1. Structured exposure Modules declared in native_categories.json are exposed under stable, hierarchical import paths, e.g.:

    {pkg}.portal.io.csv.ascii_csv_reader

    This is the preferred and production-ready API form.

  2. Flat exposure Compiled modules not yet declared in categories are exposed under:

    {pkg}.portal.flat.<module>

    Flat exposure is fully functional but explicitly provisional; paths may change once the module is categorized.

Guarantees#

This script provides the following hard guarantees:

  • It NEVER compiles native code

  • It NEVER modifies native_build_map.json

  • It NEVER copies artifacts outside _native/

  • It NEVER invents or infers API surface

If a native function appears in the generated API, it is:

  • backed by a real compiled artifact,

  • explicitly exposed, and

  • documented exactly as exposed.

If it does not appear here, it does not exist for client code.

Outputs#

  • _native/compiled/exposed/

    Materialized import tree used by portal

  • exposed_api.json
    Canonical manifest describing:

    • exposed modules

    • category paths

    • exposure mode (structured / flat)

    • native binaries

    • extracted function metadata

This manifest is the single source of truth for native API documentation and inspection.

Intended usage#

This script is executed as a build-time / generation-time step, typically after native compilation and before documentation generation.

It is safe to run repeatedly and is fully idempotent.

Hydra Forge - Project Structure Mapper (Bootstrap Edition)#

Generate a clean, human-readable folder tree of a Hydra-generated project.

Features#

  • Bulletproof project-root detection using Hydra Forge env vars

  • Optional –full mode (include ALL files except names containing “OLD”)

  • Optional –include-files (normally folders only)

  • Pretends .venv/ contains only {user, dev, docs} unless –full

  • Saves timestamped <project>_structure_*.md into the project root

This tool belongs to Hydra Forge. Clients should not modify it. Generated and maintained by Nord & Ferreira Consulting Lda.

native_exposure_check.py

Hydra Forge - Native Smithery#

The Native Smithery is the single, authoritative build-time engine utility responsible for forging native extension artifacts used by a Hydra Forge library.

It is part of the ``hydra_forge`` engine package and is intended to be executed by library developers and CI systems whenever the native layer changes.

The Native Smithery is never invoked at runtime, during import, or as part of normal package usage.

When to run#

The Native Smithery must be run whenever any change occurs in the native layer, including:

  • Modifications to _native/src (C++ or Rust sources)

  • Addition, removal, or renaming of native units

  • Changes to generated wrappers

  • Changes to compiled native artifacts

  • Cleanup of stale or orphaned native files

Running the Native Smithery reconciles the entire native layer and guarantees that all derived artifacts reflect the current filesystem state.

Purpose#

The Native Smithery answers exactly one question:

Given the current native source tree, what native artifacts should exist - and do they exist correctly?

All answers are derived directly and exclusively from the filesystem.

Core principles#

The Native Smithery is intentionally mechanical, deterministic, and policy-free.

The following invariants define its behavior:

  • A native module exists if and only if a non-hidden source directory exists in _native/src.

  • Wrappers, compiled artifacts, exposure trees, and documentation inputs are derived artifacts and may be regenerated or removed freely.

  • Rebuild decisions are based only on filesystem state and timestamps.

  • native_build_map.json records what was built, never what should be built.

  • The filesystem is the sole source of truth and is rediscovered on every run.

Responsibilities#

The Native Smithery performs the following tasks:

  • Detect native modules that require rebuilding (pure filesystem discovery + timestamp comparison)

  • Build native extensions:

    • C++ modules via CMake

    • Rust modules via maturin

  • Normalize compiled artifacts (stable filenames, consistent placement, tag removal)

  • Remove stale or orphaned artifacts with no corresponding source

  • Regenerate native_build_map.json as a descriptive snapshot of the current native build state

  • Refresh downstream systems that depend on native artifacts:

    • update_namespace (Python-side exposure)

    • generate_exposed_tree (public native API surface)

Non-responsibilities#

By design, the Native Smithery explicitly does not:

  • Define or interpret API categories

  • Decide which modules are public

  • Expose or validate import paths

  • Modify native_categories.json

  • Perform runtime discovery

  • Apply policy, heuristics, or inference

  • Execute during package runtime or import

These concerns belong to separate layers of Hydra Forge.

Execution model#

  • Safe to run repeatedly (idempotent)

  • Incremental by default

  • Language-aware (C++, Rust)

  • Deterministic given the filesystem state

  • Automatically skipped in packaging contexts

Pipeline position#

The Native Smithery occupies the following position in the Hydra Forge pipeline:

native sources
      ↓
Native Smithery
      ↓
native_build_map.json   (descriptive snapshot)
      ↓
generate_exposed_tree
      ↓
portal + exposed_api.json
      ↓
documentation / client imports

If a native artifact does not pass through the Native Smithery, it does not exist.

Fortran support is intentionally disabled in Hydra Forge v1. Experimental Fortran tooling may exist internally but is not part of the supported native contract.

Intended audience#

This module is intended for:

  • Library developers

  • CI systems

  • Native toolchain workflows

It is a developer-facing engine tool, not a public runtime API.

Hydra Forge - update_docs#

Generate full project documentation using the Hydra Forge documentation engine.

This command orchestrates the entire documentation pipeline, including inventory scanning, diagnostics, RST generation, and Sphinx builds.

Usage#

Run from the project root:

python -m hydra_forge.update_docs –flags

Flags#

--no-color

Disable ANSI colors and progress redraws (CI / installers)

--quiet

Reduce Sphinx verbosity

Pipeline#

  1. Bootstrap project environment (DOCS mode)

  2. Clean previous documentation artifacts

  3. Scan project into DocumentationInventory

  4. Collect Python and native diagnostics

  5. Generate RST files

  6. Optionally enforce quality gates

  7. Build Sphinx HTML documentation

Behavior#

  • Fully automated

  • Deterministic output

  • No manual edits required

Environment Variables#

HYDRA_SKIP_SPHINX=1

Skip Sphinx build (useful for CI tests)

Typical Use Cases#

  • Generating client-facing documentation

  • CI documentation checks

  • Verifying native doc coverage

  • Producing release artifacts

This is a primary engine script intended for direct client use.

Hydra Forge - update_namespace#

Regenerate __all__ exports for the client package and its subpackages.

This command ensures a clean, explicit, SciPy-style public API by rebuilding all __init__.py export lists based on actual source content.

Usage#

Run from the project root:

python -m forge.namespace python -m forge.namespace –dry-run python -m forge.namespace –verbose

Behavior#

  • Detects public functions and classes

  • Skips protected packages (_native, portal)

  • Updates subpackage __init__.py files

  • Updates top-level package __init__.py

Options#

--dry-run

Show changes without writing files

--verbose

Print additional diagnostic output

Typical Use Cases#

  • After adding or removing public APIs

  • Before releasing a new version

  • Before generating documentation

This is a primary engine script intended for direct client use.

On this page