pynydus 0.0.4__tar.gz

pynydus-0.0.4/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.3
+Name: pynydus
+Version: 0.0.4
+Summary: Portable state transport for AI agents
+Author: Nydus Team
+Author-email: Nydus Team <contact@nydus.ag>
+License: MIT
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.0
+Requires-Dist: presidio-analyzer>=2.2
+Requires-Dist: presidio-anonymizer>=2.2
+Requires-Dist: instructor>=1.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/NydusAI/nydus/main/assets/logo.png" alt="Nydus" width="420">
+</p>
+
+<p align="center">
+  <strong>Portable state transport for AI agents</strong><br>
+  Transport agent state between any two frameworks without manual migration
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/pynydus/"><img src="https://img.shields.io/pypi/v/pynydus?color=blue" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pynydus/"><img src="https://img.shields.io/pypi/pyversions/pynydus" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="#status"><img src="https://img.shields.io/badge/status-early%20development-orange" alt="Status"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> •
+  <a href="#how-it-works">How it works</a> •
+  <a href="#cli">CLI</a> •
+  <a href="#python-sdk">Python SDK</a>
+</p>
+
+---
+
+## How it works
+
+- **Spawn**: read source agent artifacts, redact PII, and package everything into a portable **Egg** (`.egg` archive)
+- **Hatch**: decode an Egg into any supported target runtime, with optional LLM refinement and secret injection
+
+```
+Source artifacts → Spawn → Egg (.egg) → Hatch → Target-native files
+```
+
+### The Egg format
+
+An `.egg` file is a signed ZIP archive containing:
+
+```
+manifest.json          # metadata, source type, versions
+memory.json            # labeled memory records
+secrets.json           # PII placeholders + secret requirements
+skills/<slug>/SKILL.md # portable skill definitions (agentskills.io)
+mcp/<server>.json      # MCP server configs
+raw/...                # redacted source files (for pass-through hatch)
+```
+
+## Install
+
+```bash
+pip install pynydus
+```
+
+## CLI
+
+```bash
+# Create a Nydusfile in your project directory
+cat > Nydusfile << 'EOF'
+SOURCE openclaw ./my-agent/
+REDACT pii
+EOF
+
+# Spawn an egg
+nydus spawn -o agent.egg
+
+# Inspect and validate
+nydus inspect agent.egg
+nydus inspect agent.egg --secrets --logs
+nydus validate agent.egg
+
+# Generate a template .env from the egg's secret requirements
+nydus env agent.egg -o agent.env
+
+# Hatch into a target runtime
+nydus hatch agent.egg --target letta --secrets agent.env
+
+# Compare two eggs
+nydus diff v1.egg v2.egg
+
+# Signing
+nydus keygen
+nydus spawn -o signed.egg  # auto-signs if key exists
+```
+
+## Python SDK
+
+```python
+from pynydus.client import Nydus
+
+ny = Nydus()
+
+# Spawn from a Nydusfile in the current directory
+egg_path = ny.spawn()
+
+# Hatch into a target runtime with secret injection
+result = ny.hatch(egg_path, target="letta", secrets="agent.env")
+print(result.output_dir, result.files_created)
+```
+
+## Project structure
+
+```
+pynydus/
+  api/           # Egg data model, schemas, errors
+  agents/        # Per-platform spawners + hatchers
+    openclaw/
+    zeroclaw/
+    letta/
+  engine/        # Core pipelines: spawn, hatch, pack, validate, diff, refine
+  cmd/           # Typer CLI
+  client/        # Python SDK
+  pkg/           # Utilities: presidio, LLM, signing, config
+  remote/        # Nest registry client
+```
+
+## License
+
+MIT

pynydus-0.0.4/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/NydusAI/nydus/main/assets/logo.png" alt="Nydus" width="420">
+</p>
+
+<p align="center">
+  <strong>Portable state transport for AI agents</strong><br>
+  Transport agent state between any two frameworks without manual migration
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/pynydus/"><img src="https://img.shields.io/pypi/v/pynydus?color=blue" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pynydus/"><img src="https://img.shields.io/pypi/pyversions/pynydus" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="#status"><img src="https://img.shields.io/badge/status-early%20development-orange" alt="Status"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> •
+  <a href="#how-it-works">How it works</a> •
+  <a href="#cli">CLI</a> •
+  <a href="#python-sdk">Python SDK</a>
+</p>
+
+---
+
+## How it works
+
+- **Spawn**: read source agent artifacts, redact PII, and package everything into a portable **Egg** (`.egg` archive)
+- **Hatch**: decode an Egg into any supported target runtime, with optional LLM refinement and secret injection
+
+```
+Source artifacts → Spawn → Egg (.egg) → Hatch → Target-native files
+```
+
+### The Egg format
+
+An `.egg` file is a signed ZIP archive containing:
+
+```
+manifest.json          # metadata, source type, versions
+memory.json            # labeled memory records
+secrets.json           # PII placeholders + secret requirements
+skills/<slug>/SKILL.md # portable skill definitions (agentskills.io)
+mcp/<server>.json      # MCP server configs
+raw/...                # redacted source files (for pass-through hatch)
+```
+
+## Install
+
+```bash
+pip install pynydus
+```
+
+## CLI
+
+```bash
+# Create a Nydusfile in your project directory
+cat > Nydusfile << 'EOF'
+SOURCE openclaw ./my-agent/
+REDACT pii
+EOF
+
+# Spawn an egg
+nydus spawn -o agent.egg
+
+# Inspect and validate
+nydus inspect agent.egg
+nydus inspect agent.egg --secrets --logs
+nydus validate agent.egg
+
+# Generate a template .env from the egg's secret requirements
+nydus env agent.egg -o agent.env
+
+# Hatch into a target runtime
+nydus hatch agent.egg --target letta --secrets agent.env
+
+# Compare two eggs
+nydus diff v1.egg v2.egg
+
+# Signing
+nydus keygen
+nydus spawn -o signed.egg  # auto-signs if key exists
+```
+
+## Python SDK
+
+```python
+from pynydus.client import Nydus
+
+ny = Nydus()
+
+# Spawn from a Nydusfile in the current directory
+egg_path = ny.spawn()
+
+# Hatch into a target runtime with secret injection
+result = ny.hatch(egg_path, target="letta", secrets="agent.env")
+print(result.output_dir, result.files_created)
+```
+
+## Project structure
+
+```
+pynydus/
+  api/           # Egg data model, schemas, errors
+  agents/        # Per-platform spawners + hatchers
+    openclaw/
+    zeroclaw/
+    letta/
+  engine/        # Core pipelines: spawn, hatch, pack, validate, diff, refine
+  cmd/           # Typer CLI
+  client/        # Python SDK
+  pkg/           # Utilities: presidio, LLM, signing, config
+  remote/        # Nest registry client
+```
+
+## License
+
+MIT

pynydus-0.0.4/pynydus/__init__.py

@@ -0,0 +1,33 @@
+"""pynydus — Portable state transport for AI agents."""
+
+__version__ = "0.1.0"
+EGG_SPEC_VERSION = "2.0"
+
+from pynydus.api.schemas import (
+    DiffReport,
+    Egg,
+    HatchResult,
+    Manifest,
+    McpServerConfig,
+    MemoryRecord,
+    SecretRecord,
+    SkillRecord,
+    SpawnAttachments,
+    ValidationReport,
+)
+from pynydus.client.client import Nydus
+
+__all__ = [
+    "DiffReport",
+    "EGG_SPEC_VERSION",
+    "Egg",
+    "HatchResult",
+    "Manifest",
+    "McpServerConfig",
+    "MemoryRecord",
+    "Nydus",
+    "SecretRecord",
+    "SkillRecord",
+    "SpawnAttachments",
+    "ValidationReport",
+]

pynydus-0.0.4/pynydus/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent connectors — one sub-package per framework (spawner + hatcher)."""

pynydus-0.0.4/pynydus/agents/letta/README.md

@@ -0,0 +1,46 @@
+# Letta Agent
+
+## Spawner: source files → Egg
+
+Supports both directory-based and SQLite database inputs.
+
+### Directory mode
+
+| Source file | Egg field | Label |
+|---|---|---|
+| `agent_state.json` → `system` | `MemoryRecord` | `FLOW` |
+| `agent_state.json` → `memory.persona` | `MemoryRecord` | `PERSONA` |
+| `agent_state.json` → `memory.human` | `MemoryRecord` | `CONTEXT` |
+| `agent_state.json` → `memory.<other>` | `MemoryRecord` | `CONTEXT` |
+| `agent_state.json` → `tools[]` | `SkillRecord` | |
+| `system_prompt.md` / `.txt` | `MemoryRecord` (fallback if no system in state) | `FLOW` |
+| `archival_memory.json` | `MemoryRecord` | `STATE` |
+| `archival/*` | `MemoryRecord` | `STATE` |
+| `tools/*.py` | `SkillRecord` | |
+| `.letta/config.json` | `SecretRecord` | |
+
+### Database mode (`agent.db`)
+
+| DB table | Egg field | Label |
+|---|---|---|
+| `blocks` (persona) | `MemoryRecord` | `PERSONA` |
+| `blocks` (human) | `MemoryRecord` | `CONTEXT` |
+| `blocks` (system) | `MemoryRecord` | `FLOW` |
+| `blocks` (other) | `MemoryRecord` | `CONTEXT` |
+| `archival_memory` | `MemoryRecord` | `STATE` |
+| `tools` | `SkillRecord` | |
+| `agents` → config JSON | `SecretRecord` | |
+
+Detection: directory with `agent_state.json`, `.letta/`, `tools/`, or
+`agent.db`, or a `.db` file directly.
+
+## Hatcher: Egg → target files
+
+| Egg field | Target file | Notes |
+|---|---|---|
+| `MemoryRecord` (`PERSONA`) | `agent_state.json` → `memory.persona` | Appended to block value |
+| `MemoryRecord` (`CONTEXT`) | `agent_state.json` → `memory.human` | Appended to block value |
+| `MemoryRecord` (`FLOW`) | `agent_state.json` → `system` + `system_prompt.md` | Duplicate for convenience |
+| `MemoryRecord` (`STATE`) | `archival_memory.json` | Array of `{text, timestamp}` |
+| `SkillRecord` | `tools/<name>.py` + `agent_state.json` → `tools[]` | Source code in both |
+| `SecretRecord` (`CREDENTIAL`) | `.letta/config.json` | `{name: placeholder}` |

pynydus-0.0.4/pynydus/agents/letta/__init__.py

@@ -0,0 +1 @@
+"""Letta agent connector."""

pynydus-0.0.4/pynydus/agents/letta/hatcher.py

@@ -0,0 +1,230 @@
+"""Letta hatcher connector. Spec §10.3.
+
+Produces a valid Letta agent project directory from an Egg:
+- agent_state.json     <- memory blocks + agent config skeleton
+- tools/               <- skill records as Python tool files
+- archival_memory.json <- state memory
+- system_prompt.md     <- flow memory
+
+All 4 MemoryLabel values have explicit mappings:
+- PERSONA -> memory.persona block in agent_state.json
+- CONTEXT -> memory.human block in agent_state.json
+- FLOW    -> system field + system_prompt.md
+- STATE   -> archival_memory.json
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pynydus.api.errors import HatchError
+from pynydus.api.raw_types import RenderResult
+from pynydus.api.schemas import (
+    Egg,
+    HatchResult,
+    MemoryLabel,
+    SecretKind,
+    ValidationIssue,
+    ValidationReport,
+)
+from pynydus.pkg.connector_utils import skill_to_filename as _skill_to_filename
+
+_LABEL_TO_BLOCK: dict[MemoryLabel, str] = {
+    MemoryLabel.PERSONA: "persona",
+    MemoryLabel.CONTEXT: "human",
+    MemoryLabel.FLOW: "system",
+}
+
+
+class LettaHatcher:
+    """Produce a valid Letta agent directory from an Egg."""
+
+    def render(self, egg: Egg) -> RenderResult:
+        """Render Egg records into target file contents.
+
+        Returns a dict of ``filename -> content`` with ``{{SECRET_NNN}}``
+        and ``{{PII_NNN}}`` placeholders intact.
+        """
+        files: dict[str, str] = {}
+        warnings: list[str] = []
+
+        # --- agent_state.json ---
+        agent_state = self._build_agent_state(egg)
+        files["agent_state.json"] = json.dumps(agent_state, indent=2) + "\n"
+
+        # --- system_prompt.md ---
+        system_records = [
+            m for m in egg.memory.memory if m.label == MemoryLabel.FLOW
+        ]
+        if system_records:
+            files["system_prompt.md"] = "\n\n".join(r.text for r in system_records) + "\n"
+
+        # --- tools/ directory ---
+        if egg.skills.skills:
+            for skill in egg.skills.skills:
+                fname = _skill_to_filename(skill.name)
+                files[f"tools/{fname}"] = skill.content + "\n"
+
+        # --- archival_memory.json (state) ---
+        state_records = [
+            m for m in egg.memory.memory if m.label == MemoryLabel.STATE
+        ]
+        if state_records:
+            entries = []
+            for rec in state_records:
+                entry: dict[str, str | None] = {"text": rec.text}
+                entry["timestamp"] = rec.timestamp.isoformat() if rec.timestamp else None
+                entries.append(entry)
+            files["archival_memory.json"] = json.dumps(entries, indent=2) + "\n"
+
+        # --- .letta/config.json (credential placeholders) ---
+        credentials = [
+            s for s in egg.secrets.secrets if s.kind == SecretKind.CREDENTIAL
+        ]
+        if credentials:
+            config = {s.name: s.placeholder for s in credentials}
+            files[".letta/config.json"] = json.dumps(config, indent=2) + "\n"
+
+        if not files:
+            raise HatchError("Egg produced no output files for Letta target")
+
+        return RenderResult(files=files, warnings=warnings)
+
+    def hatch(self, egg: Egg, output_dir: Path) -> HatchResult:
+        """Generate Letta project files from an Egg.
+
+        .. deprecated::
+            Use :meth:`render` instead. The pipeline now handles disk I/O.
+        """
+        result = self.render(egg)
+
+        output_dir.mkdir(parents=True, exist_ok=True)
+        files_created: list[str] = []
+        for fname, content in result.files.items():
+            fpath = output_dir / fname
+            fpath.parent.mkdir(parents=True, exist_ok=True)
+            fpath.write_text(content)
+            files_created.append(fname)
+
+        return HatchResult(
+            target="letta",
+            output_dir=output_dir,
+            files_created=files_created,
+            warnings=list(result.warnings),
+        )
+
+    def validate(self, result: HatchResult) -> ValidationReport:
+        """Validate generated Letta output."""
+        issues: list[ValidationIssue] = []
+
+        if "agent_state.json" not in result.files_created:
+            issues.append(
+                ValidationIssue(
+                    level="warning",
+                    message="agent_state.json was not generated",
+                    location=str(result.output_dir),
+                )
+            )
+
+        for fname in result.files_created:
+            fpath = result.output_dir / fname
+            if not fpath.exists():
+                issues.append(
+                    ValidationIssue(
+                        level="error",
+                        message=f"Expected file not found: {fname}",
+                        location=str(fpath),
+                    )
+                )
+
+        state_path = result.output_dir / "agent_state.json"
+        if state_path.exists():
+            try:
+                data = json.loads(state_path.read_text())
+                if not isinstance(data, dict):
+                    issues.append(
+                        ValidationIssue(
+                            level="error",
+                            message="agent_state.json is not a JSON object",
+                            location=str(state_path),
+                        )
+                    )
+                elif "memory" not in data and "system" not in data:
+                    issues.append(
+                        ValidationIssue(
+                            level="warning",
+                            message="agent_state.json has no memory blocks or system prompt",
+                            location=str(state_path),
+                        )
+                    )
+            except json.JSONDecodeError:
+                issues.append(
+                    ValidationIssue(
+                        level="error",
+                        message="agent_state.json is not valid JSON",
+                        location=str(state_path),
+                    )
+                )
+
+        return ValidationReport(
+            valid=not any(i.level == "error" for i in issues),
+            issues=issues,
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _build_agent_state(self, egg: Egg) -> dict:
+        """Build the agent_state.json content from Egg data."""
+        state: dict = {
+            "name": "nydus_agent",
+            "memory": {},
+            "tools": [],
+        }
+
+        for mem_rec in egg.memory.memory:
+            if mem_rec.label in _LABEL_TO_BLOCK:
+                block_name = _LABEL_TO_BLOCK[mem_rec.label]
+                if block_name in state["memory"]:
+                    state["memory"][block_name]["value"] += "\n\n" + mem_rec.text
+                else:
+                    state["memory"][block_name] = {
+                        "value": mem_rec.text,
+                        "limit": 5000,
+                    }
+
+        flow_records = [
+            m for m in egg.memory.memory if m.label == MemoryLabel.FLOW
+        ]
+        if flow_records:
+            state["system"] = "\n\n".join(r.text for r in flow_records)
+
+        for skill in egg.skills.skills:
+            state["tools"].append({
+                "name": _skill_to_module_name(skill.name),
+                "source_code": skill.content,
+            })
+
+        if egg.manifest.source_metadata:
+            state["metadata"] = {
+                "nydus_source": egg.manifest.source_connector,
+                "nydus_version": egg.manifest.nydus_version,
+            }
+
+        return state
+
+
+# ---------------------------------------------------------------------------
+# Utility functions
+# ---------------------------------------------------------------------------
+
+
+def _skill_to_module_name(name: str) -> str:
+    """Convert a skill display name to a Python module name."""
+    module = name.lower().strip().replace(" ", "_").replace("-", "_")
+    module = "".join(c for c in module if c.isalnum() or c == "_")
+    if module and module[0].isdigit():
+        module = f"tool_{module}"
+    return module or "tool"