`pynydus.engine.refinement`¶

LLM refinement for spawning and hatching pipelines.

Spawning (Step 7): refine_skills / refine_memory use the configured LLM tier to deduplicate memory records and normalize skill formatting. The LLM always operates on already-redacted content.

Hatching (Step 3): refine_hatch uses the same tier to adapt or polish reconstructed files for the target platform’s conventions.

Module Contents¶

Classes¶

`RefinedMemoryRecord`	A single refined memory record returned by the LLM.
`RefinedMemoryOutput`	LLM response for memory deduplication and summarization.
`RefinedSkillRecord`	A single refined skill record returned by the LLM.
`RefinedSkillsOutput`	LLM response for skill cleanup.
`AdaptedFile`	A single file whose content has been adapted for the target platform.
`AdaptedFilesOutput`	LLM response for cross-platform file adaptation.

Functions¶

`_extract_placeholders`	Return all `{{SECRET_NNN}}` / `{{PII_NNN}}` tokens in text.
`_find_missing_placeholders`	Tokens present in original but absent from new.
`_load_agent_spec`	Load the AGENT_SPEC.md for a given agent type.
`refine_skills`	Clean up skill names and formatting via the configured LLM tier.
`refine_memory`	Deduplicate and summarize memory records via the configured LLM tier.
`_refine_memory`	Deduplicate and summarize memory records via LLM.
`_refine_skills`	Clean up skill names and formatting via LLM.
`refine_hatch`	Adapt or polish reconstructed files during hatching (Step 3) via LLM.

Data¶

`logger`
`REFINEMENT_RETRY_LIMIT`
`_PLACEHOLDER_RE`
`_MEMORY_SYSTEM_PROMPT`
`_SKILL_SYSTEM_PROMPT`
`_HATCH_SYSTEM_PROMPT`
`_HATCH_POLISH_PROMPT`
`_AGENT_SPEC_DIR`

API¶

pynydus.engine.refinement.logger¶: ‘getLogger(…)’

pynydus.engine.refinement.REFINEMENT_RETRY_LIMIT¶: 3

pynydus.engine.refinement._PLACEHOLDER_RE¶: ‘compile(…)’

pynydus.engine.refinement._extract_placeholders(text: str) → set[str]¶: Return all {{SECRET_NNN}} / {{PII_NNN}} tokens in text.

pynydus.engine.refinement._find_missing_placeholders(original: str, new: str) → set[str]¶: Tokens present in original but absent from new.

class pynydus.engine.refinement.RefinedMemoryRecord(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single refined memory record returned by the LLM.

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.

original_ids: list[str]¶

None

IDs of the original records this was derived from (multiple if merged).

text: str¶

None

The cleaned/deduplicated/summarized text.

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

None

Preserved label from the original record.

class pynydus.engine.refinement.RefinedMemoryOutput(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

LLM response for memory deduplication and summarization.

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.

records: list[pynydus.engine.refinement.RefinedMemoryRecord]¶

None

The refined set of memory records. Fewer or equal to the input count.

class pynydus.engine.refinement.RefinedSkillRecord(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single refined skill record returned by the LLM.

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.

original_id: str¶

None

ID of the original skill this corresponds to.

name: str¶

None

Cleaned/normalized skill name.

content: str¶

None

Cleaned/reformatted skill content.

class pynydus.engine.refinement.RefinedSkillsOutput(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

LLM response for skill cleanup.

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.engine.refinement.RefinedSkillRecord]¶

None

The refined skills. Same count as input (1:1, no merging).

class pynydus.engine.refinement.AdaptedFile(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

A single file whose content has been adapted for the target platform.

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.

path: str¶

None

Relative path of the file (must match an entry in files_created).

content: str¶

None

The adapted file content.

class pynydus.engine.refinement.AdaptedFilesOutput(/, **data: typing.Any)¶

Bases: pydantic.BaseModel

LLM response for cross-platform file adaptation.

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.

files: list[pynydus.engine.refinement.AdaptedFile]¶

None

Adapted file contents. Only includes files that needed changes.

warnings: list[str]¶

‘Field(…)’

Any warnings about adaptation issues.

pynydus.engine.refinement._MEMORY_SYSTEM_PROMPT = <Multiline-String>¶

pynydus.engine.refinement._SKILL_SYSTEM_PROMPT = <Multiline-String>¶

pynydus.engine.refinement._HATCH_SYSTEM_PROMPT = <Multiline-String>¶

pynydus.engine.refinement._HATCH_POLISH_PROMPT = <Multiline-String>¶

pynydus.engine.refinement._AGENT_SPEC_DIR¶: None

pynydus.engine.refinement._load_agent_spec(agent_type: pynydus.common.enums.AgentType) → str¶: Load the AGENT_SPEC.md for a given agent type.

pynydus.engine.refinement.refine_skills(skills: pynydus.api.schemas.SkillsModule, llm_config: pynydus.llm.LLMTierConfig, spawn_log: list[dict] | None = None) → pynydus.api.schemas.SkillsModule¶

Clean up skill names and formatting via the configured LLM tier.

Args: skills: Module containing skill records to refine. llm_config: LLM provider, model, and API key. spawn_log: If set, refinement log entries are appended here.

Returns: Updated SkillsModule with cleaned names and formatting.

pynydus.engine.refinement.refine_memory(memory: pynydus.api.schemas.MemoryModule, llm_config: pynydus.llm.LLMTierConfig, spawn_log: list[dict] | None = None) → pynydus.api.schemas.MemoryModule¶

Deduplicate and summarize memory records via the configured LLM tier.

Args: memory: Module containing memory records to refine. llm_config: LLM provider, model, and API key. spawn_log: If set, refinement log entries are appended here.

Returns: Updated MemoryModule with deduplicated/summarized records.

pynydus.engine.refinement._refine_memory(partial: pynydus.api.schemas.EggPartial, llm_config: pynydus.llm.LLMTierConfig) → pynydus.api.schemas.EggPartial¶

Deduplicate and summarize memory records via LLM.

Args: partial: EggPartial whose memory module will be refined in place. llm_config: LLM provider, model, and API key.

Returns: The same EggPartial with its memory module updated.

pynydus.engine.refinement._refine_skills(partial: pynydus.api.schemas.EggPartial, llm_config: pynydus.llm.LLMTierConfig) → pynydus.api.schemas.EggPartial¶

Clean up skill names and formatting via LLM.

Args: partial: EggPartial whose skills module will be refined in place. llm_config: LLM provider, model, and API key.

Returns: The same EggPartial with its skills module updated.

pynydus.engine.refinement.refine_hatch(file_dict: dict[str, str], egg: pynydus.api.schemas.Egg, llm_config: pynydus.llm.LLMTierConfig, *, target: str | None = None, log: list[dict] | None = None, spawn_log: list[dict] | None = None, raw_artifacts: dict[str, str] | None = None) → dict[str, str]¶

Adapt or polish reconstructed files during hatching (Step 3) via LLM.

Operates on a filename-to-content mapping with placeholders only. no disk I/O. Retries when redaction placeholders are dropped. on persistent failure, leaves affected paths unchanged.

Args: file_dict: Reconstructed files (paths relative to output root). egg: Egg being hatched (manifest, secrets metadata, agent type). llm_config: LLM provider, model, and API key. target: Explicit target platform type (e.g. “openclaw”). log: If set, hatch log entries (warnings, reverts) are appended here. spawn_log: Optional spawn pipeline log forwarded into the LLM context. raw_artifacts: Optional redacted raw/ snapshot for extra LLM context.

Returns: Updated file dict (unchanged keys omitted from LLM output stay as in file_dict).

pynydus.engine.refinement¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`pynydus.engine.refinement`¶