pynydus.client.client

Python SDK: mirrors the CLI 1:1. Spec §19.

Usage::

from pynydus import Nydus

ny = Nydus()
egg = ny.spawn()  # reads ./Nydusfile
egg = ny.spawn(nydusfile="path/to/Nydusfile")
path = ny.save(egg, Path("agent.egg"))

egg = ny.load(Path("agent.egg"))
egg.skills.skills  # list of AgentSkill
egg.memory.memory  # list of MemoryRecord
egg.inspect_secrets()

result = ny.hatch(egg, target=AgentType.LETTA)

Module Contents

Classes

Nydus

Main SDK entry point (mirrors CLI behavior).

API

class pynydus.client.client.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.