pynydus.engine.hatcher

Hatching pipeline: transforms an Egg into a target runtime. Spec 13.

Two modes: rebuild (default): render from structured egg modules via connector passthrough: replay redacted raw/ snapshot verbatim

Pipeline steps: 1. Version check: verify min_nydus_version compatibility 2. Build file dict: connector.render() (rebuild) or raw snapshot (passthrough) 3. LLM polish: adapt/polish on placeholder’d content (no real secrets) 4. Secrets IN: substitute {{SECRET_NNN}} / {{PII_NNN}} with real values 5. Write connector (agent) files to output/agent/ 6. Write standard artifacts (AGENTS.md, agent-card.json, apm.yml, mcp.json) to output root 7. Hatch log: write hatch_log.json to output/logs/

The LLM never sees real secrets: only placeholder tokens. Real values are injected as the last transformation before writing to disk.

Module Contents

Functions

hatch	Run the full hatching pipeline (see module docstring for steps).
_substitute_secrets	Replace all {{SECRET_NNN}} / {{PII_NNN}} placeholders with real values.
_write_standard_artifacts	Write egg-level standard artifacts to the output root.
_write_files	Write all file entries to disk. Returns list of created filenames.
_write_hatch_log	Write hatch_log.json to the output directory’s logs/ folder.
_get_hatcher	Return the hatcher connector for the given agent type.
_parse_env_file	Parse a .env file into a dict of key=value pairs.
_build_placeholder_map	Build placeholder -> value mapping, raising if required secrets are missing.
_check_version_compat	Reject eggs that require a newer Nydus version than we have.

Data

logger

API

pynydus.engine.hatcher.logger

‘getLogger(…)’

pynydus.engine.hatcher.hatch(egg: pynydus.api.schemas.Egg, *, target: pynydus.common.enums.AgentType, output_dir: pathlib.Path | None = None, secrets_path: pathlib.Path | None = None, mode: pynydus.common.enums.HatchMode = HatchMode.REBUILD, llm_config: pynydus.llm.LLMTierConfig | None = None, spawn_log: list[dict] | None = None, raw_artifacts: dict[str, str] | None = None) → pynydus.api.schemas.HatchResult

Run the full hatching pipeline (see module docstring for steps).

Args: egg: Egg to hatch (typically from :func:~pynydus.engine.packager.load). target: Destination runtime (openclaw, zeroclaw, letta). output_dir: Directory for output files. default ./[target]/. secrets_path: .env file for placeholder substitution (secrets IN). mode: rebuild (structured render()) or passthrough (raw snapshot). llm_config: Optional LLM tier for refinement (spawn and hatch). spawn_log: Spawn log entries forwarded to the hatch LLM. defaults to egg.spawn_log. raw_artifacts: Redacted raw/ files. defaults to egg.raw_artifacts. If the egg was loaded with include_raw=False, egg.raw_artifacts is empty. pass the result of :func:~pynydus.engine.packager.read_raw_artifacts or reload with include_raw=True for passthrough.

Returns: HatchResult with output path, files written, warnings, and hatch log.

pynydus.engine.hatcher._substitute_secrets(files: dict[str, str], placeholder_map: dict[str, str]) → dict[str, str]

Replace all {{SECRET_NNN}} / {{PII_NNN}} placeholders with real values.

pynydus.engine.hatcher._write_standard_artifacts(egg: pynydus.api.schemas.Egg, output_dir: pathlib.Path, hatch_log: list[dict]) → list[str]

Write egg-level standard artifacts to the output root.

pynydus.engine.hatcher._write_files(files: dict[str, str], output_dir: pathlib.Path) → list[str]

Write all file entries to disk. Returns list of created filenames.

pynydus.engine.hatcher._write_hatch_log(result: pynydus.api.schemas.HatchResult) → None

Write hatch_log.json to the output directory’s logs/ folder.

pynydus.engine.hatcher._get_hatcher(target: pynydus.common.enums.AgentType)

Return the hatcher connector for the given agent type.

pynydus.engine.hatcher._parse_env_file(secrets_path: pathlib.Path) → dict[str, str]

Parse a .env file into a dict of key=value pairs.

pynydus.engine.hatcher._build_placeholder_map(egg: pynydus.api.schemas.Egg, env_vars: dict[str, str], secrets_path: pathlib.Path) → dict[str, str]

Build placeholder -> value mapping, raising if required secrets are missing.

pynydus.engine.hatcher._check_version_compat(egg: pynydus.api.schemas.Egg) → None

Reject eggs that require a newer Nydus version than we have.