Data Models¶

Core Pydantic models for the Egg data structure. These types are all importable from the top-level PyNydus package (pynydus).

Egg¶

class Egg(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

The canonical portable artifact.

Redacted sources and spawn pipeline log align with raw/ and spawn_log.json in the .egg archive. Use :func:~pynydus.engine.packager.load to populate these from disk, and :func:~pynydus.engine.packager.save to write them.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

manifest: pynydus.api.schemas.Manifest¶: None

skills: pynydus.api.schemas.SkillsModule¶: ‘Field(…)’

mcp: pynydus.api.schemas.McpModule¶: ‘Field(…)’

memory: pynydus.api.schemas.MemoryModule¶: ‘Field(…)’

secrets: pynydus.api.schemas.SecretsModule¶: ‘Field(…)’

raw_artifacts: dict[str, str]¶

‘Field(…)’

Redacted source snapshots (ZIP raw/…).

spawn_log: list[dict]¶

‘Field(…)’

Structured spawn pipeline events (ZIP spawn_log.json).

nydusfile: str | None¶

None

Embedded Nydusfile text when present in the archive (ZIP Nydusfile).

a2a_card: dict[str, Any] | None¶

None

A2A agent card (agent-card.json).

agents_md: str | None¶

None

Per-egg deployment runbook (AGENTS.md).

apm_yml: str | None¶

None

Passthrough APM manifest from source project.

spec_snapshots: dict[str, str] | None¶

None

Embedded spec markdown snapshots keyed by standard name.

inspect_secrets() → list[dict]¶

Return a summary of all secret placeholders and their occurrences.

Returns: List of dicts with placeholder, name, kind, required, and occurrences.

Manifest¶

class Manifest(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Top-level Egg metadata.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

nydus_version: str¶: None

min_nydus_version: str¶: ‘0.0.7’

egg_version: str¶: ‘1.0’

created_at: datetime.datetime¶: None

agent_type: pynydus.common.enums.AgentType¶: None

signature: str = <Multiline-String>¶

base_egg: str | None¶

None

Base egg reference this egg inherited from (e.g. ‘nydus/openclaw:0.3.0’).

redaction_policy: pynydus.api.schemas.RedactionPolicy | None¶: None

agent_name: str | None¶: None

agent_description: str | None¶: None

llm_model: str | None¶: None

llm_context_window: int | None¶: None

embedding_model: str | None¶: None

source_dir: str | None¶: None

sources: Annotated[list[pynydus.api.schemas.SourceEntry], Field(max_length=1)]¶

‘Field(…)’

At most one source entry (FROM-only spawns may omit this list).

class RedactionPolicy(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Records what redaction was applied during spawning.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

pii_redacted: bool¶: True

secrets_placeholder_only: bool¶: True

class SourceEntry(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

The single SOURCE tree that contributed to this egg, if any.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

agent_type: str¶: None

source_path: str = <Multiline-String>¶

Module containers¶

class SkillsModule(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Container for all skills in an Egg (agentskills.io format).

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

skills: list[pynydus.api.skill_format.AgentSkill]¶: ‘Field(…)’

class McpModule(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Raw MCP server configs. Nydus does not model MCP fields.

Stored as mcp.json in the egg archive using Claude Desktop format ({ "mcpServers": { "<name>": { ... } } }).

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

configs: dict[str, dict[str, Any]]¶: ‘Field(…)’

class MemoryModule(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Container for all memory records in an Egg.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

memory: list[pynydus.api.schemas.MemoryRecord]¶: ‘Field(…)’

class SecretsModule(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Container for all redaction placeholder records in an Egg.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

secrets: list[pynydus.api.schemas.SecretRecord]¶: ‘Field(…)’

Records¶

class AgentSkill(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Spec-compliant representation of a single Agent Skill (agentskills.io).

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

name: str¶: None

description: str = <Multiline-String>¶

version: str¶: ‘1.0’

license: str = <Multiline-String>¶

compatibility: list[str]¶: ‘Field(…)’

allowed_tools: list[str]¶: ‘Field(…)’

metadata: dict[str, Any]¶: ‘Field(…)’

body: str = <Multiline-String>¶: Markdown body: the main skill content (instructions, code, etc.).

class MemoryRecord(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single memory record.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: str¶: None

text: str¶: None

label: pynydus.common.enums.MemoryLabel¶: None

agent_type: str¶: None

source_store: str¶: None

skill_ref: str | None¶: None

timestamp: datetime.datetime | None¶: None

shareable: bool¶: True

class SecretRecord(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single redaction placeholder record (credential or PII). Spec §6.2.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: str¶: None

placeholder: str¶: None

kind: pynydus.common.enums.SecretKind¶: None

pii_type: str | None¶: None

name: str¶: None

required_at_hatch: bool¶: False

injection_mode: pynydus.common.enums.InjectionMode¶: None

description: str = <Multiline-String>¶

value_present: bool¶: False

occurrences: list[str]¶: ‘Field(…)’

Pipeline results¶

class HatchResult(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Output from a hatcher.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

target: pynydus.common.enums.AgentType¶: None

output_dir: pathlib.Path¶: None

files_created: list[str]¶: ‘Field(…)’

warnings: list[str]¶: ‘Field(…)’

hatch_log: list[dict]¶

‘Field(…)’

Structured log entries produced during the hatch pipeline.

class ValidationReport(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Result of validating an Egg or source input.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

valid: bool¶: None

issues: list[pynydus.api.schemas.ValidationIssue]¶: ‘Field(…)’

class ValidationIssue(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single validation finding (error or warning).

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

level: Literal[error, warning]¶: None

message: str¶: None

location: str | None¶: None

class DiffReport(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Result of comparing two Eggs.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

identical: bool¶: None

manifest_changes: list[pynydus.api.schemas.ManifestChange]¶: ‘Field(…)’

entries: list[pynydus.api.schemas.DiffEntry]¶: ‘Field(…)’

class DiffEntry(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single record-level difference within a module type.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

bucket: pynydus.common.enums.ModuleType¶

None

Which module the record belongs to (skill, memory, secret).

change: pynydus.common.enums.DiffChange¶

None

Type of change: ADDED, REMOVED, or MODIFIED.

id: str | None¶

None

Record ID.

field: str | None¶

None

Which field changed (None for add/remove of whole records).

old: str | None¶

None

Old value (stringified). None for additions.

new: str | None¶

None

New value (stringified). None for removals.

class ManifestChange(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single manifest-level field difference between two Eggs.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field: str¶

None

Which manifest field changed.

old: str | None¶

None

Old value (stringified).

new: str | None¶

None

New value (stringified).

class EggPartial(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

Intermediate result from a spawner before full packaging.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

skills: pynydus.api.schemas.SkillsModule¶: ‘Field(…)’

mcp: pynydus.api.schemas.McpModule¶: ‘Field(…)’

memory: pynydus.api.schemas.MemoryModule¶: ‘Field(…)’

secrets: pynydus.api.schemas.SecretsModule¶: ‘Field(…)’

raw_artifacts: dict[str, str]¶: ‘Field(…)’

spawn_log: list[dict]¶: ‘Field(…)’

Enums¶

These types are defined in pynydus.common.enums and re-exported from pynydus.api.schemas for convenience.

class AgentType¶

Bases: enum.StrEnum

Supported agent platforms.

OPENCLAW¶: ‘openclaw’

ZEROCLAW¶: ‘zeroclaw’

LETTA¶: ‘letta’

class ModuleType¶

Bases: enum.StrEnum

Top-level module types in an Egg (skill, memory, secret).

SKILL¶: ‘skill’

MEMORY¶: ‘memory’

SECRET¶: ‘secret’

class SecretKind¶

Bases: enum.StrEnum

Kind of redacted value: credential (gitleaks) or PII (Presidio).

CREDENTIAL¶: ‘credential’

PII¶: ‘pii’

class InjectionMode¶

Bases: enum.StrEnum

How a secret value is provided at hatch time.

ENV¶: ‘env’

SUBSTITUTION¶: ‘substitution’

class MemoryLabel¶

Bases: enum.StrEnum

Canonical labels for memory records, assigned by spawners.

PERSONA¶: ‘persona’

FLOW¶: ‘flow’

CONTEXT¶: ‘context’

STATE¶: ‘state’

class HatchMode¶

Bases: enum.StrEnum

Hatching mode: rebuild from structured modules or passthrough raw snapshot.

REBUILD¶: ‘rebuild’

PASSTHROUGH¶: ‘passthrough’

class DiffChange¶

Bases: enum.StrEnum

Type of change reported in a diff entry.

ADDED¶: ‘added’

REMOVED¶: ‘removed’

MODIFIED¶: ‘modified’