soothe-plugins 0.2.6__py3-none-any.whl

soothe_plugins/weaver/generator.py

@@ -0,0 +1,177 @@
+"""AgentGenerator -- manifest and system prompt generation (RFC-0005) -- community edition."""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from langchain_core.language_models import BaseChatModel
+
+import anyio
+
+from .models import AgentBlueprint, AgentManifest
+
+logger = logging.getLogger(__name__)
+
+_SYSTEM_PROMPT_GENERATION = """\
+You are generating a system prompt for a specialist AI agent.
+
+Agent name: {agent_name}
+Agent description: {description}
+
+The agent must fulfil this objective:
+{objective}
+
+Expected input: {expected_input}
+Expected output: {expected_output}
+Constraints: {constraints}
+
+The agent has access to these skills (integrated instructions):
+{skills_text}
+
+{bridge_instructions}
+
+The agent has these tools available: {tools}
+
+Generate a comprehensive system prompt for this agent. The prompt should:
+1. Define the agent's role and responsibilities clearly
+2. Incorporate the skill instructions naturally (do not reference them as "skills")
+3. Include the bridge instructions as part of the workflow
+4. Specify the expected input/output format
+5. Include any constraints as operational rules
+
+Output ONLY the system prompt text (markdown format). Do not include meta-commentary."""
+
+
+class AgentGenerator:
+    """Generates agent packages (manifest + system prompt) from blueprints.
+
+    Args:
+        model: Chat model for system prompt generation.
+    """
+
+    def __init__(self, model: BaseChatModel) -> None:
+        """Initialize the agent generator.
+
+        Args:
+            model: Chat model for system prompt generation.
+        """
+        self._model = model
+
+    async def generate(
+        self,
+        blueprint: AgentBlueprint,
+        output_dir: Path,
+    ) -> AgentManifest:
+        """Generate an agent package from a blueprint.
+
+        Creates the output directory with ``manifest.yml``, ``system_prompt.md``,
+        and a ``skills/`` subdirectory with copied skill files.
+
+        Args:
+            blueprint: Complete agent specification.
+            output_dir: Directory to write the agent package into.
+
+        Returns:
+            The generated ``AgentManifest``.
+        """
+        adir = anyio.Path(output_dir)
+        await adir.mkdir(parents=True, exist_ok=True)
+
+        skills_dir = output_dir / "skills"
+        await anyio.Path(skills_dir).mkdir(exist_ok=True)
+        copied_skills = self._copy_skills(blueprint, skills_dir)
+
+        system_prompt = await self._generate_system_prompt(blueprint)
+
+        prompt_path = output_dir / "system_prompt.md"
+        await anyio.Path(prompt_path).write_text(system_prompt, encoding="utf-8")
+
+        manifest = AgentManifest(
+            name=blueprint.agent_name,
+            description=blueprint.capability.description,
+            skills=copied_skills,
+            tools=blueprint.tools,
+            capabilities=blueprint.capability.required_capabilities,
+            created_at=datetime.now(UTC),
+        )
+
+        manifest_path = output_dir / "manifest.yml"
+        self._write_manifest(manifest, manifest_path)
+
+        logger.info("Generated agent '%s' at %s", blueprint.agent_name, output_dir)
+        return manifest
+
+    async def _generate_system_prompt(self, blueprint: AgentBlueprint) -> str:
+        """Use LLM to craft a system prompt from the blueprint."""
+        skills_text = (
+            "\n\n".join(f"### {sid}\n{content[:2000]}" for sid, content in blueprint.harmonized.skill_contents.items())
+            or "(no specific skills)"
+        )
+
+        bridge = ""
+        if blueprint.harmonized.bridge_instructions:
+            bridge = f"Additional integration instructions:\n{blueprint.harmonized.bridge_instructions}"
+
+        constraints = ", ".join(blueprint.capability.constraints) or "none"
+        tools = ", ".join(blueprint.tools) or "standard file and shell tools"
+
+        prompt = _SYSTEM_PROMPT_GENERATION.format(
+            agent_name=blueprint.agent_name,
+            description=blueprint.capability.description,
+            objective=blueprint.capability.description,
+            expected_input=blueprint.capability.expected_input or "user request",
+            expected_output=blueprint.capability.expected_output or "task result",
+            constraints=constraints,
+            skills_text=skills_text,
+            bridge_instructions=bridge,
+            tools=tools,
+        )
+
+        try:
+            resp = await self._model.ainvoke([{"role": "user", "content": prompt}])
+            return str(resp.content).strip()
+        except Exception:
+            logger.exception("System prompt generation failed")
+            return self._fallback_prompt(blueprint)
+
+    @staticmethod
+    def _fallback_prompt(blueprint: AgentBlueprint) -> str:
+        """Generate a minimal system prompt when LLM call fails."""
+        return (
+            f"You are {blueprint.agent_name}, a specialist agent.\n\n"
+            f"## Objective\n{blueprint.capability.description}\n\n"
+            f"## Expected Input\n{blueprint.capability.expected_input}\n\n"
+            f"## Expected Output\n{blueprint.capability.expected_output}\n"
+        )
+
+    @staticmethod
+    def _copy_skills(blueprint: AgentBlueprint, skills_dir: Path) -> list[str]:
+        """Copy skill files into the agent's skills directory."""
+        copied: list[str] = []
+        for sid, content in blueprint.harmonized.skill_contents.items():
+            skill_subdir = skills_dir / sid
+            skill_subdir.mkdir(exist_ok=True)
+            (skill_subdir / "SKILL.md").write_text(content, encoding="utf-8")
+            copied.append(str(skill_subdir))
+        return copied
+
+    @staticmethod
+    def _write_manifest(manifest: AgentManifest, path: Path) -> None:
+        """Write the manifest as YAML."""
+        try:
+            import yaml
+
+            data = manifest.model_dump(mode="json")
+            if "created_at" in data and hasattr(data["created_at"], "isoformat"):
+                data["created_at"] = data["created_at"].isoformat()
+            path.write_text(yaml.dump(data, default_flow_style=False, sort_keys=False), encoding="utf-8")
+        except ImportError:
+            import json
+
+            data = manifest.model_dump(mode="json")
+            path.with_suffix(".json").write_text(json.dumps(data, indent=2, default=str), encoding="utf-8")

soothe_plugins/weaver/models.py

@@ -0,0 +1,136 @@
+"""Weaver data models (RFC-0005) -- community edition."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class CapabilitySignature(BaseModel):
+    """Structured analysis of what the user request requires.
+
+    Args:
+        description: One-paragraph summary of what the agent should do.
+        required_capabilities: Capability keywords (e.g. ``arxiv_search``).
+        constraints: Operational limits or requirements.
+        expected_input: What the agent receives from the user.
+        expected_output: What the agent should produce.
+    """
+
+    description: str
+    required_capabilities: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+    expected_input: str = ""
+    expected_output: str = ""
+
+
+class AgentManifest(BaseModel):
+    """Metadata file for a generated agent package.
+
+    Args:
+        name: Agent identifier (lowercase, hyphenated).
+        description: Human-readable description for the ``task`` tool.
+        type: Agent type (currently always ``subagent``).
+        system_prompt_file: Filename of the system prompt markdown.
+        skills: Skill paths copied into the package.
+        tools: Langchain tool group names enabled for this agent.
+        capabilities: Capability keywords this agent provides.
+        created_at: Creation timestamp.
+        version: Monotonically increasing version number.
+    """
+
+    name: str
+    description: str
+    type: Literal["subagent"] = "subagent"
+    system_prompt_file: str = "system_prompt.md"
+    skills: list[str] = Field(default_factory=list)
+    tools: list[str] = Field(default_factory=list)
+    capabilities: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    version: int = 1
+
+
+class ReuseCandidate(BaseModel):
+    """A previously generated agent that may fulfill the current request.
+
+    Args:
+        manifest: The agent's manifest metadata.
+        confidence: Semantic similarity score in [0, 1].
+        path: Absolute path to the agent directory.
+    """
+
+    manifest: AgentManifest
+    confidence: float
+    path: str
+
+
+class SkillConflict(BaseModel):
+    """A detected conflict between two skills.
+
+    Args:
+        skill_a_id: First skill identifier.
+        skill_b_id: Second skill identifier.
+        conflict_type: Nature of the conflict.
+        description: Human-readable conflict description.
+        severity: Impact level.
+        resolution: LLM-proposed resolution strategy.
+    """
+
+    skill_a_id: str
+    skill_b_id: str
+    conflict_type: Literal["contradictory", "ambiguous", "version_mismatch"]
+    description: str
+    severity: Literal["low", "medium", "high"]
+    resolution: str
+
+
+class SkillConflictReport(BaseModel):
+    """Full analysis of conflicts, overlaps, and gaps in a candidate skill set.
+
+    Args:
+        conflicts: Typed conflict entries between skill pairs.
+        overlaps: Pairs of skill IDs with redundant coverage.
+        gaps: Missing capabilities identified by analysis.
+        harmonization_summary: Human-readable summary of the analysis.
+    """
+
+    conflicts: list[SkillConflict] = Field(default_factory=list)
+    overlaps: list[list[str]] = Field(default_factory=list)
+    gaps: list[str] = Field(default_factory=list)
+    harmonization_summary: str = ""
+
+
+class HarmonizedSkillSet(BaseModel):
+    """Output of skill harmonization -- a clean, unified instruction corpus.
+
+    Args:
+        skills: Final skill IDs retained after harmonization.
+        skill_contents: Mapping of skill_id to merged/cleaned content.
+        bridge_instructions: LLM-generated glue logic connecting skills.
+        dropped_skills: Skill IDs removed during deduplication.
+        merge_log: Human-readable log of merge decisions.
+    """
+
+    skills: list[str] = Field(default_factory=list)
+    skill_contents: dict[str, str] = Field(default_factory=dict)
+    bridge_instructions: str = ""
+    dropped_skills: list[str] = Field(default_factory=list)
+    merge_log: list[str] = Field(default_factory=list)
+
+
+class AgentBlueprint(BaseModel):
+    """Complete specification for agent generation.
+
+    Args:
+        capability: The analysed capability signature.
+        harmonized: The harmonized skill set.
+        tools: Resolved tool group names.
+        agent_name: Generated agent name (lowercase, hyphenated).
+    """
+
+    capability: CapabilitySignature
+    harmonized: HarmonizedSkillSet
+    tools: list[str] = Field(default_factory=list)
+    agent_name: str = ""

soothe_plugins/weaver/registry.py

@@ -0,0 +1,214 @@
+"""GeneratedAgentRegistry -- filesystem-based agent registry (RFC-0005) -- community edition."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .models import AgentManifest
+
+if TYPE_CHECKING:
+    from deepagents.middleware.subagents import SubAgent
+
+logger = logging.getLogger(__name__)
+
+
+class GeneratedAgentRegistry:
+    """Manages generated agent packages under a base directory.
+
+    Each agent is a subdirectory containing ``manifest.yml`` (or
+    ``manifest.json``) and ``system_prompt.md``.
+
+    Args:
+        base_dir: Root directory for generated agents
+            (e.g. ``~/.soothe/generated_agents``).
+    """
+
+    def __init__(self, base_dir: Path) -> None:
+        """Initialize the generated agent registry.
+
+        Args:
+            base_dir: Root directory for generated agents
+                (e.g. ``~/.soothe/generated_agents``).
+        """
+        self._base_dir = Path(base_dir).expanduser().resolve()
+
+    @property
+    def base_dir(self) -> Path:
+        """The base directory for generated agents."""
+        return self._base_dir
+
+    def list_agents(self) -> list[AgentManifest]:
+        """Scan base_dir for ``*/manifest.yml`` and return parsed manifests.
+
+        Returns:
+            List of valid ``AgentManifest`` objects found.
+        """
+        manifests: list[AgentManifest] = []
+        if not self._base_dir.is_dir():
+            return manifests
+
+        for manifest_path in self._base_dir.glob("*/manifest.yml"):
+            try:
+                manifest = self._load_manifest(manifest_path)
+                if manifest:
+                    manifests.append(manifest)
+            except Exception:
+                logger.warning("Failed to load manifest %s", manifest_path, exc_info=True)
+
+        for manifest_path in self._base_dir.glob("*/manifest.json"):
+            try:
+                manifest = self._load_manifest_json(manifest_path)
+                if manifest:
+                    manifests.append(manifest)
+            except Exception:
+                logger.warning("Failed to load manifest %s", manifest_path, exc_info=True)
+
+        return manifests
+
+    def get_agent(self, name: str) -> tuple[AgentManifest, Path] | None:
+        """Get a specific agent by name.
+
+        Args:
+            name: Agent name to look up.
+
+        Returns:
+            Tuple of (manifest, agent_dir) or ``None``.
+        """
+        agent_dir = self._base_dir / name
+        if not agent_dir.is_dir():
+            return None
+
+        for ext in ("yml", "json"):
+            manifest_path = agent_dir / f"manifest.{ext}"
+            if manifest_path.is_file():
+                loader = self._load_manifest if ext == "yml" else self._load_manifest_json
+                manifest = loader(manifest_path)
+                if manifest:
+                    return manifest, agent_dir
+        return None
+
+    def register(self, manifest: AgentManifest, path: Path) -> None:
+        """Record a new agent entry (idempotent).
+
+        Args:
+            manifest: The agent manifest.
+            path: Absolute path to the agent directory.
+        """
+        logger.info("Registered generated agent '%s' at %s", manifest.name, path)
+
+    def load_as_subagent(self, name: str) -> "SubAgent" | None:
+        """Load a generated agent as a deepagents SubAgent dict.
+
+        Args:
+            name: Agent name to load.
+
+        Returns:
+            A ``SubAgent`` dict or ``None`` if not found.
+        """
+        result = self.get_agent(name)
+        if result is None:
+            return None
+
+        manifest, agent_dir = result
+        prompt_path = agent_dir / manifest.system_prompt_file
+        system_prompt = ""
+        if prompt_path.is_file():
+            try:
+                system_prompt = prompt_path.read_text(encoding="utf-8")
+            except Exception:
+                logger.warning("Failed to read system prompt for '%s'", name, exc_info=True)
+
+        return {
+            "name": manifest.name,
+            "description": manifest.description,
+            "system_prompt": system_prompt,
+        }
+
+    def cleanup_old_agents(self, max_age_days: int = 30, max_agents: int = 100) -> int:
+        """Remove old/unused generated agents.
+
+        Args:
+            max_age_days: Delete agents not accessed for N days.
+            max_agents: Keep at most N agents (delete oldest first).
+
+        Returns:
+            Number of agents deleted.
+        """
+        import shutil
+        from datetime import UTC, datetime, timedelta
+
+        deleted = 0
+
+        if not self._base_dir.is_dir():
+            return deleted
+
+        # Get all agents with their access times
+        agents: list[tuple[Path, datetime]] = []
+        try:
+            for manifest_file in self._base_dir.glob("*/manifest.yml"):
+                try:
+                    stat = manifest_file.stat()
+                    atime = datetime.fromtimestamp(stat.st_atime, tz=UTC)
+                    agents.append((manifest_file.parent, atime))
+                except Exception:
+                    logger.debug("Failed to stat %s", manifest_file, exc_info=True)
+                    continue
+
+            # Sort by access time (oldest first)
+            agents.sort(key=lambda x: x[1])
+
+            # Delete by age
+            cutoff = datetime.now(UTC) - timedelta(days=max_age_days)
+            for agent_dir, atime in agents:
+                if atime < cutoff:
+                    try:
+                        shutil.rmtree(agent_dir)
+                        deleted += 1
+                        logger.info("Deleted old generated agent: %s", agent_dir.name)
+                    except Exception:
+                        logger.warning("Failed to delete agent %s", agent_dir, exc_info=True)
+
+            # Delete by count (if still over limit)
+            remaining = [(d, t) for d, t in agents if t >= cutoff]
+            if len(remaining) > max_agents:
+                for agent_dir, _ in remaining[:-max_agents]:
+                    try:
+                        shutil.rmtree(agent_dir)
+                        deleted += 1
+                        logger.info("Deleted excess generated agent: %s", agent_dir.name)
+                    except Exception:
+                        logger.warning("Failed to delete agent %s", agent_dir, exc_info=True)
+        except Exception:
+            logger.warning("Agent cleanup failed", exc_info=True)
+
+        return deleted
+
+    @staticmethod
+    def _load_manifest(path: Path) -> AgentManifest | None:
+        """Load a YAML manifest file."""
+        try:
+            import yaml
+
+            data = yaml.safe_load(path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return None
+            return AgentManifest(**data)
+        except Exception:
+            logger.debug("Failed to parse YAML manifest %s", path, exc_info=True)
+            return None
+
+    @staticmethod
+    def _load_manifest_json(path: Path) -> AgentManifest | None:
+        """Load a JSON manifest file."""
+        import json
+
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return None
+            return AgentManifest(**data)
+        except Exception:
+            logger.debug("Failed to parse JSON manifest %s", path, exc_info=True)
+            return None

soothe_plugins/weaver/reuse.py

@@ -0,0 +1,151 @@
+"""ReuseIndex -- vector search over previously generated agents (RFC-0005) -- community edition."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from .models import AgentManifest, CapabilitySignature, ReuseCandidate
+
+if TYPE_CHECKING:
+    from langchain_core.embeddings import Embeddings
+
+    from soothe_sdk.protocols import VectorStoreProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class ReuseIndex:
+    """Semantic index of previously generated agents for reuse-first strategy.
+
+    Args:
+        vector_store: Vector store for agent description embeddings.
+        embeddings: Embedding model for vectorization.
+        threshold: Minimum confidence score to consider a reuse hit.
+        collection: Vector store collection name.
+        embedding_dims: Embedding vector dimensionality.
+    """
+
+    def __init__(
+        self,
+        vector_store: "VectorStoreProtocol",
+        embeddings: Embeddings,
+        threshold: float = 0.85,
+        collection: str = "soothe_weaver_reuse",
+        embedding_dims: int = 1536,
+    ) -> None:
+        """Initialize the reuse index.
+
+        Args:
+            vector_store: Vector store for agent description embeddings.
+            embeddings: Embedding model for vectorization.
+            threshold: Minimum confidence score to consider a reuse hit.
+            collection: Vector store collection name.
+            embedding_dims: Embedding vector dimensionality.
+        """
+        self._vector_store = vector_store
+        self._embeddings = embeddings
+        self._threshold = threshold
+        self._collection = collection
+        self._embedding_dims = embedding_dims
+        self._initialized = False
+
+    async def _ensure_collection(self) -> None:
+        if self._initialized:
+            return
+        try:
+            await self._vector_store.create_collection(
+                vector_size=self._embedding_dims,
+                distance="cosine",
+            )
+        except Exception:
+            logger.debug("Reuse collection creation failed (may already exist)", exc_info=True)
+        self._initialized = True
+
+    async def find_reusable(self, capability: CapabilitySignature) -> ReuseCandidate | None:
+        """Search for an existing generated agent matching the capability.
+
+        Args:
+            capability: The analysed capability signature.
+
+        Returns:
+            A ``ReuseCandidate`` if confidence >= threshold, else ``None``.
+        """
+        await self._ensure_collection()
+
+        try:
+            vector = await self._embeddings.aembed_query(capability.description)
+        except Exception:
+            logger.exception("Failed to embed capability description")
+            return None
+
+        try:
+            results = await self._vector_store.search(
+                query=capability.description,
+                vector=vector,
+                limit=5,
+            )
+        except Exception:
+            logger.exception("Reuse index search failed")
+            return None
+
+        if not results:
+            return None
+
+        best = results[0]
+        confidence = best.score or 0.0
+        if confidence < self._threshold:
+            return None
+
+        payload = best.payload
+        try:
+            manifest = AgentManifest(**payload.get("manifest", {}))
+        except Exception:
+            logger.warning("Failed to parse reuse candidate manifest", exc_info=True)
+            return None
+
+        return ReuseCandidate(
+            manifest=manifest,
+            confidence=confidence,
+            path=payload.get("path", ""),
+        )
+
+    async def index_agent(self, manifest: AgentManifest, path: str) -> None:
+        """Add a newly generated agent to the reuse index.
+
+        Args:
+            manifest: The agent's manifest.
+            path: Absolute path to the agent directory.
+        """
+        await self._ensure_collection()
+
+        text = f"{manifest.name}: {manifest.description}"
+        if manifest.capabilities:
+            text += f"\nCapabilities: {', '.join(manifest.capabilities)}"
+
+        try:
+            vector = await self._embeddings.aembed_query(text)
+        except Exception:
+            logger.exception("Failed to embed agent description for reuse index")
+            return
+
+        payload: dict[str, Any] = {
+            "manifest": manifest.model_dump(mode="json"),
+            "path": path,
+            "agent_name": manifest.name,
+        }
+
+        try:
+            await self._vector_store.insert(
+                vectors=[vector],
+                payloads=[payload],
+                ids=[manifest.name],
+            )
+        except Exception:
+            logger.exception("Failed to index agent in reuse store")
+
+    async def close(self) -> None:
+        """Close the underlying vector store if supported."""
+        close_method = getattr(self._vector_store, "close", None)
+        if callable(close_method):
+            await close_method()