pynydus.agents.letta.spawner

Letta spawner connector. Spec §10.3.

Parses a Letta agent export directory, database dump, or .af AgentFile:

• *.af (AgentFile) -> Letta’s official portable agent format (AgentFileSchema)

• agent_state.json -> memory blocks (persona, human, system) + agent config

• archival_memory.json / archival/ -> long-term archival memory records

• tools/ -> Python tool definitions -> skill records

• system_prompt.md -> system prompt -> memory record

• .letta/ marker directory (optional)

Also supports reading from a Letta SQLite database file (agent.db) as a fallback when structured JSON exports are not available.

Module Contents

Classes

LettaSpawner

Parse a Letta agent export directory, database, or AgentFile.

Functions

_extract_af_llm_embedding	Read neutral LLM / embedding fields from an AgentFile agent dict.
_load_agent_state_from_files	Load agent_state.json from a file dict.
_extract_block_text	Extract text from a memory block value (string or dict with value/text).
_extract_message_text	Extract text from a message.
_python_module_display_name	Convert a Python module name to a display name (e.g., search_web -> search web).

Data

_AGENT_STATE_FILES
_ARCHIVAL_FILES
_SYSTEM_PROMPT_FILES
_DB_FILES
_BLOCK_LABEL_MAP
FILE_PATTERNS	Glob patterns the pipeline uses to read source files from disk.

API

pynydus.agents.letta.spawner._AGENT_STATE_FILES

(‘agent_state.json’,)

pynydus.agents.letta.spawner._ARCHIVAL_FILES

(‘archival_memory.json’,)

pynydus.agents.letta.spawner._SYSTEM_PROMPT_FILES

(‘system_prompt.md’, ‘system_prompt.txt’)

pynydus.agents.letta.spawner._DB_FILES

(‘agent.db’,)

pynydus.agents.letta.spawner._BLOCK_LABEL_MAP: dict[str, pynydus.common.enums.MemoryLabel]

None

pynydus.agents.letta.spawner.FILE_PATTERNS

[’.json’, ‘.md’, ‘.txt’, ‘.yaml’, ‘.yml’, ‘.af’, ‘tools/.py’, ‘archival/.txt’, ‘archival/*.m…

Glob patterns the pipeline uses to read source files from disk.

pynydus.agents.letta.spawner._extract_af_llm_embedding(agent: dict) → tuple[str | None, int | None, str | None]

Read neutral LLM / embedding fields from an AgentFile agent dict.

class pynydus.agents.letta.spawner.LettaSpawner

Bases: pynydus.api.protocols.Spawner

Parse a Letta agent export directory, database, or AgentFile.

FILE_PATTERNS

None

parse(files: dict[str, str]) → pynydus.api.raw_types.ParseResult

Parse pre-redacted file contents into raw skills and memory.

Args: files: filename -> UTF-8 content (already redacted). DB-mode may use synthetic keys such as _db_tables.json.

Returns: Skills, memory, and MCP configs.

parse_db(db_path: pathlib.Path, supplemental_files: dict[str, str] | None = None) → pynydus.api.raw_types.ParseResult

Parse directly from a Letta SQLite database.

This is the special case for DB-mode extraction. The pipeline calls this instead of parse() when the source is a .db file.

Args: db_path: Path to the Letta agent.db SQLite file. supplemental_files: Additional text files to parse alongside the DB.

Returns: Skills and memory extracted from database tables.

_try_parse_agent_file(files: dict[str, str]) → pynydus.api.raw_types.ParseResult | None

Try to parse a .af AgentFile from the files dict.

Handles the real AgentFileSchema with top-level agents, blocks, tools, mcp_servers, skills, metadata.

static _parse_af_blocks(data: dict, memories: list[pynydus.api.raw_types.RawMemory], af_name: str | None) → None

Parse top-level blocks list from AgentFileSchema.

static _parse_af_system_prompt(agent: dict, memories: list[pynydus.api.raw_types.RawMemory], af_name: str | None) → None

Parse system field from the agent dict.

static _parse_af_tools(data: dict, skills: list[pynydus.api.raw_types.RawSkill], af_name: str | None) → None

Parse top-level tools list.

Only custom tools (with source_code) become skill records. Built-in Letta tools (letta_core, letta_builtin, letta_sleeptime_core) have source_code: null and are skipped.

static _parse_af_skills(data: dict, skills: list[pynydus.api.raw_types.RawSkill], af_name: str | None) → None

Parse top-level skills list (SkillSchema objects).

Each skill has name, optional files dict (must include SKILL.md), and optional source_url.

static _parse_af_tool_rules(agent: dict, memories: list[pynydus.api.raw_types.RawMemory], af_name: str | None) → None

Parse tool_rules from the agent dict as FLOW memory.

static _parse_af_messages(agent: dict, memories: list[pynydus.api.raw_types.RawMemory], af_name: str | None) → None

Parse messages from agent dict as STATE memory.

Message content is a list of {type, text} objects in AgentFileSchema, not a plain string.

static _parse_af_env_vars(agent: dict, memories: list[pynydus.api.raw_types.RawMemory], af_name: str | None) → None

Parse tool_exec_environment_variables from agent dict.

After redaction these become SECRET placeholders. We store them as CONTEXT memory so the pipeline secret scan can replace the raw values with {{SECRET_NNN}} placeholders.

static _parse_af_mcp_servers(data: dict, mcp_configs: dict[str, dict]) → None

Parse top-level mcp_servers list.

_parse_skills(files: dict[str, str]) → list[pynydus.api.raw_types.RawSkill]

Parse skills from file contents dict.

_parse_memories(files: dict[str, str]) → list[pynydus.api.raw_types.RawMemory]

Parse memories from agent state, system prompt, and archival memory.

static _parse_mcp_configs(files: dict[str, str]) → dict[str, dict]

static _get_tables(conn: sqlite3.Connection) → set[str]

pynydus.agents.letta.spawner._load_agent_state_from_files(files: dict[str, str]) → dict | None

Load agent_state.json from a file dict.

pynydus.agents.letta.spawner._extract_block_text(block_value: object) → str

Extract text from a memory block value (string or dict with value/text).

pynydus.agents.letta.spawner._extract_message_text(msg: dict) → str

Extract text from a message.

In AgentFileSchema, content is a list of {type, text} objects. Falls back to plain string for legacy formats.

pynydus.agents.letta.spawner._python_module_display_name(stem: str) → str

Convert a Python module name to a display name (e.g., search_web -> search web).