`femic.release_packaging` Module

The femic.release_packaging module owns FEMIC’s student-facing release bundle assembly path. It validates the minimum artifact set, copies bundle, Patchworks, optional Woodstock, and selected log/manifest outputs into one versioned release directory, and writes the manifest/handoff-note payloads that make the package auditable.

If you are debugging why a release package is missing a required artifact, what strict mode actually enforces, or how FEMIC decides which logs/manifests are included in the handoff bundle, this is the first module to read. In practice it owns:

required release-artifact validation
versioned release-id and output-directory creation
package file copying and hashing
release manifest and handoff-note generation

Start Here If…

Use this page first if you are trying to:

build or audit a student-facing release bundle
understand the contract for required model-input and Patchworks artifacts
inspect what logs/manifests FEMIC copies into a release package

Typical maintenance path:

Start with build_release_package() for the end-to-end release flow.
Inspect ReleasePackageResult for the returned package metadata.
Read the required-file constants when changing release minimums.

Typical Usage

The common operator-facing call is:

femic export release --instance-root external/femic-k3z-instance --case-id k3z --run-id k3z_docs_example

The matching Python entrypoint is:

from pathlib import Path
from femic.release_packaging import build_release_package

result = build_release_package(
    case_id="k3z",
    output_root=Path("output/releases"),
    model_input_bundle_dir=Path("data/model_input_bundle"),
    patchworks_output_dir=Path("output/patchworks"),
    woodstock_output_dir=Path("output/woodstock"),
    logs_dir=Path("runtime/logs"),
    run_id="docs_example",
    strict=True,
)

How This Fits Into The Pipeline

This module sits after pipeline/export work has already finished:

FEMIC produces bundle tables, Patchworks outputs, optional Woodstock exports, and run logs
this module validates/copies the selected artifacts into a versioned release directory
maintainers review and distribute that release package

That means this module owns the release-bundle contract, not the upstream scientific or export logic itself.

Key Entry Surfaces

The highest-value entrypoints in this module are:

build_release_package()
ReleasePackageResult

The main minimum-artifact constant is also useful:

REQUIRED_MODEL_INPUT_FILES
REQUIRED_PATCHWORKS_EXPORT_FILES

Core Contracts

The most important runtime contracts in this module are:

model-input bundle releases require the canonical three bundle CSVs
Patchworks export-bundle releases require forestmodel.xml plus the full fragments shapefile sidecar set: fragments.shp, fragments.dbf, fragments.shx, fragments.prj, and fragments.cpg
that export-bundle minimum is intentionally narrower than the published standalone runtime contract for a full Patchworks instance, which also requires shipped blocks/topology, compiled tracks, and analysis/PIN launch surfaces
release IDs combine normalized case ID with an explicit run ID or UTC stamp
copied files are hashed into a machine-readable manifest
only selected manifest/log families are copied from the logs directory

Failure Seams To Watch

The common failure boundaries in this module are:

strict-mode surprises strict packaging raises immediately on missing required artifacts instead of silently skipping them
release-directory collisions release IDs must be unique or packaging will fail
partial optional outputs Woodstock or logs content may be absent without invalidating the whole package, depending on requested strictness and available artifacts

Cross-References

Guides and references that pair especially closely with this module:

Related API pages:

Student-facing release packaging helpers.

class femic.release_packaging.ReleasePackageResult(release_id, release_dir, manifest_path, handoff_notes_path)[source]

Bases: object

Metadata for a generated release package.

Parameters:

release_id (str)
release_dir (Path)
manifest_path (Path)
handoff_notes_path (Path)

handoff_notes_path: Path

manifest_path: Path

release_dir: Path

release_id: str

femic.release_packaging.build_release_package(*, case_id, output_root, model_input_bundle_dir, patchworks_output_dir, woodstock_output_dir, logs_dir, run_id, strict)[source]

Create a versioned release bundle with core artifacts and notes.