Client SDK

The Nydus class is the main entry point for using PyNydus programmatically. It mirrors CLI behavior, but Typer entry points call the same engines directly rather than delegating to this class.

Example

from pathlib import Path
from pynydus import Nydus

ny = Nydus()

# Spawn
egg = ny.spawn()                         # reads ./Nydusfile
egg = ny.spawn(nydusfile="other/Nydusfile")

# Save / load
path = ny.save(egg, Path("agent.egg"))
path = ny.save(egg, Path("agent.egg"), sign=True)

# Load and inspect (includes raw/ and spawn log)
egg = ny.load(Path("agent.egg"))
egg.skills.skills       # list of AgentSkill
egg.mcp.configs         # dict of MCP server configs
egg.memory.memory       # list of MemoryRecord
egg.inspect_secrets()
report = ny.validate(egg)
diff = ny.diff(egg_a, egg_b)

# Hatch (rebuild mode, the default)
result = ny.hatch(
    egg,
    target="letta",
    output_dir=Path("out"),
    secrets="agent.env",
)
print(result.output_dir, result.files_created, result.warnings)

Notes:

  • spawn() fills egg.raw_artifacts and egg.spawn_log. save() writes them to the archive by default.

  • hatch() defaults to rebuild mode (regenerate files from structured Egg modules). Set mode="passthrough" to replay the egg’s redacted raw/ snapshot verbatim. Passthrough requires egg.raw_artifacts to be non-empty, which it is after spawn() or load() with the default include_raw=True.

  • If you loaded with load(..., include_raw=False), raw_artifacts is empty. Either reload with include_raw=True or pass raw_artifacts= from pynydus.engine.packager.read_raw_artifacts(path).

  • Configure LLM and registry via environment variables (NYDUS_LLM_TYPE, NYDUS_LLM_API_KEY, NYDUS_REGISTRY_URL, etc.). See Configuration.

  • Registry pull() defaults version to "latest" if omitted. The nydus pull CLI still requires --version. See Nest Registry.

Nydus

class Nydus

Main SDK entry point (mirrors CLI behavior).

Initialization

Load LLM and registry settings from environment variables.

Set NYDUS_LLM_TYPE and NYDUS_LLM_API_KEY for refinement. Set NYDUS_REGISTRY_URL (and optionally NYDUS_REGISTRY_AUTHOR) for registry operations. See :mod:pynydus.config.

spawn(nydusfile: pathlib.Path | str | None = None) → pynydus.api.schemas.Egg

Spawn an Egg from a Nydusfile.

Args: nydusfile: Path to a Nydusfile. If None, resolves one in the current working directory.

Returns: Egg with raw_artifacts and spawn_log populated from the pipeline. Use :meth:save to write a .egg file.

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

Hatch an Egg into a target runtime.

Args: egg: Loaded Egg to render. target: Destination platform. output_dir: Directory for output files (connector default if omitted). secrets: Path to .env for placeholder substitution. mode: rebuild (structured modules) or passthrough (raw snapshot). spawn_log: Spawn pipeline log for the hatch LLM. defaults to egg.spawn_log. raw_artifacts: Redacted raw/ snapshot. defaults to egg.raw_artifacts. required for passthrough when empty on the egg.

Returns: HatchResult with paths and written files.

save(egg: pynydus.api.schemas.Egg, output: pathlib.Path, *, raw_artifacts: dict[str, str] | None = None, spawn_log: list[dict] | None = None, nydusfile_text: str | None = None, sign: bool = False) → pathlib.Path

Write an Egg to a .egg archive.

Args: egg: The Egg to save. output: Destination file path (gets .egg suffix). raw_artifacts: Override egg.raw_artifacts for the archive. spawn_log: Override egg.spawn_log for the archive. nydusfile_text: Embed Nydusfile text in the archive. sign: If True, sign with the user’s Ed25519 private key.

Returns: Path to the written .egg file.

load(egg_path: pathlib.Path, *, include_raw: bool = True) → pynydus.api.schemas.Egg

Load a .egg archive into a fully populated :class:~pynydus.api.schemas.Egg.

Args: egg_path: Path to the .egg file. include_raw: If False, raw/ is not read into egg.raw_artifacts (empty dict). Use for large eggs when only structured modules are needed. for passthrough hatch, load with include_raw=True or pass read_raw_artifacts(egg_path) to :meth:hatch.

Returns: Fully populated Egg with spawn_log, raw_artifacts, and nydusfile.

validate(egg: pynydus.api.schemas.Egg) → pynydus.api.schemas.ValidationReport

Validate structural integrity of an Egg.

Args: egg: Egg to check.

Returns: Report with errors and warnings.

diff(egg_a: pynydus.api.schemas.Egg, egg_b: pynydus.api.schemas.Egg) → pynydus.api.schemas.DiffReport

Compare two Eggs.

Args: egg_a: First Egg. egg_b: Second Egg.

Returns: Structured diff report.

push(egg_path: pathlib.Path, *, name: str, version: str | None = None, author: str | None = None) → dict

Push a packed .egg to the Nest registry.

Args: egg_path: Packed archive path. name: Registry name (e.g. user/my-agent). version: Semver. if None, taken from egg.manifest.egg_version. author: Optional author override.

Returns: Server JSON response body.

pull(name: str, *, version: str = 'latest', output: pathlib.Path = Path('pulled.egg')) → pathlib.Path

Pull an Egg from the Nest registry.

Args: name: Registry name (e.g. user/my-agent). version: Semver tag. default latest. output: Destination path for the downloaded .egg.

Returns: Path written on disk.

list_versions(name: str) → list[dict]

List published versions for name.

Args: name: Registry-qualified egg name.

Returns: List of version metadata dicts from the server.

_get_registry_client()

Build a NestClient from NYDUS_REGISTRY_URL.

See the full auto-generated reference with all method signatures: pynydus.client.client.Nydus