Context

What this explains: How C++/Rust code is compiled, linked, and exposed to Python through explicit orchestration.

No manual wrapper files
Stable ABI and import paths
Parity - enforced alignment between runtime availability and documentation

The architecture supports additional native languages when equivalent guarantees are upheld.

Native integration

Hydra Forge treats native code as a first-class component of a scientific Python library.

Native compilation, exposure, and verification are handled through explicit, inspectable boundaries rather than ad-hoc build logic embedded in Python code.

This document describes how native code is structured, built, exposed, and verified within a Hydra Forge–generated project.

Design goals

Native integration is designed around four goals:

Predictability - consistent behavior across machines
Transparency - explicit sources, artifacts, and interfaces
Parity - enforced agreement between Python and native layers
Longevity - maintainability over time

Native code as a dedicated layer

All native code lives under a single, well-defined location:

src/<package_name>/_native/

This directory represents the entire native surface of the library. Build orchestration is centralized; no native logic is scattered across Python modules.

src/hydra_dx/_native/
├── src/
│   ├── cpp/
│   └── rust/
├── compiled/
├── native_build_map.json
├── native_categories.json
├── version.json

Native source of truth: `_native/src/`

The _native/src/ directory contains the authoritative source code for all native components.

_native/src/
├── cpp/
└── rust/

Key principles

Source code is never generated implicitly
Multiple native languages can coexist safely
Language-specific conventions are respected
Code is organized by intent, not by build system

Compiled artifacts: `_native/compiled/`

Compiled native extensions are placed in:

_native/compiled/

Source code and build artifacts are intentionally separated. Artifacts are never modified in place by Python code.

Build orchestration and mapping

Native builds are governed by an explicit build map:

_native/native_build_map.json

This file records declared native modules, their sources, artifacts, and Python exposure.

During rebuild and verification, Hydra Forge validates (and blocks on) consistency between sources, artifacts, names, and exposed interfaces.

Python-facing interface: `portal/`

Native code is exposed to Python exclusively through the generated portal namespace.

src/<package_name>/portal/

The portal represents the entire public native API surface of the library. It is not discovered dynamically at runtime and does not rely on import-time inspection.

Python code never imports native binaries directly
All native functionality is accessed through explicit, generated import paths
The exposed structure defines what is public and what is not
Import paths are stable and versioned

The contents of portal/ are generated mechanically from compiled native artifacts and explicit exposure rules, forming a deterministic, inspectable contract between native code and Python.

If a symbol is not present in the exposed tree, it cannot be imported or documented.

Exposure generation and the exposed tree

Native exposure is a deliberate, repeatable generation step, not a runtime discovery mechanism.

Hydra Forge materializes an explicit exposure tree under:

src/<package_name>/_native/compiled/exposed/

This tree defines the complete set of native modules and symbols that are importable through portal.

Compiled native artifacts are inspected
Exposure rules are applied explicitly
Import paths are generated deterministically
A manifest of the exposed API is written and verified

Exposure generation can be re-run at any time after modifying native_categories.json, without recompiling native code.

All exposure occurs during controlled build or verification steps — never at import time.

Language-specific binding details remain internal to the engine and never leak into the public Python-facing interface.

Native docstring extraction

During exposure generation, Hydra Forge extracts verbatim runtime docstrings directly from the compiled native bindings.

These docstrings are treated as the authoritative source of truth when present for native API documentation. They are not re-authored, paraphrased, or mirrored in Python code.

Docstrings are read verbatim from the compiled native module
Extraction occurs during exposure generation and verification
The extracted text becomes the authoritative documentation source
Documentation quality is surfaced, not artificially enforced

Functions may be exposed without docstrings during development. In such cases, documentation is present but minimal or degraded. This is intentional and supports rapid prototyping.

Documentation parity

Native documentation is part of the public contract, but it is not a prerequisite for experimentation.

Native functions may exist and be exposed without docstrings
Docstrings are captured verbatim from compiled bindings during exposure generation
Documentation visibility always matches runtime availability

Functions without docstrings remain fully usable at runtime, but appear with minimal or degraded documentation. This behavior is intentional.

Hydra Forge is designed to support rapid native prototyping — you can iterate, expose, test, and benchmark native code without being forced into premature documentation work.

At the same time, the system makes documentation quality observable. With the provided exposure blueprints and binding patterns, there is no structural barrier to adding or improving native docstrings — only a conscious engineering choice.

This allows native code to move from experimental to production-grade without changing exposure paths, import structure, or documentation mechanics.

The best way to evaluate this mechanism is not through examples on this page, but by inspecting the generated library documentation directly.

Every exposed native symbol, its import path, runtime behavior, and extracted documentation can be reviewed in the generated API reference.

This documentation is produced automatically from the same build artifacts used to compile and expose the native code. There is no parallel, hand-written documentation layer.

Inspect the generated library documentation

The full, generated documentation for a Hydra Forge–produced library is available for inspection.

This documentation reflects the actual public API surface, including native modules exposed through portal, their import paths, runtime behavior, and extracted docstrings.

The only reliable way to evaluate this mechanism is by inspecting the generated library documentation itself.

Open generated library documentation ↗

This documentation is produced directly from compiled artifacts and exposure manifests. There is no hand-written or parallel documentation layer.

Verification and safety guarantees

Native integration is verified during generation and rebuild.

Artifact presence and correctness
Interface visibility
Documentation presence and alignment with runtime availability
Inventory consistency
Test execution

Failure is explicit and blocking; partially integrated native code is never delivered.

Why inline native builds are avoided

Hydra Forge intentionally avoids:

Inline setup.py compilation
Import-time builds
Implicit rebuilds
Environment-dependent heuristics

These patterns are replaced with explicit orchestration and verification.

Summary

Hydra Forge integrates native code by making boundaries explicit and verifiable.