soothe-plugins 0.2.6__py3-none-any.whl

soothe_plugins/README.md

@@ -0,0 +1,150 @@
+# Soothe Community Plugins
+
+Welcome to the Soothe Community Plugins repository! This package contains
+community-contributed plugins for the Soothe agent orchestration framework.
+
+## What Are Community Plugins?
+
+Community plugins are third-party extensions that add new capabilities to Soothe
+without modifying the core framework. They follow the RFC-0018 Plugin Extension
+System specification.
+
+## Available Plugins
+
+### PaperScout (`paperscout`)
+
+ArXiv paper recommendation agent that delivers personalized daily paper
+recommendations by analyzing your Zotero library.
+
+**Features**:
+- Fetches papers from ArXiv based on configurable categories
+- Analyzes your Zotero library to understand research interests
+- Ranks papers by relevance using sentence embeddings
+- Sends daily email digests with TLDR summaries
+- Discovers code repositories via PapersWithCode
+
+**Installation**:
+```bash
+pip install soothe[paperscout]
+```
+
+**Configuration**:
+```yaml
+subagents:
+  paperscout:
+    enabled: true
+    model: "openai:gpt-4o-mini"
+    config:
+      arxiv_categories:
+        - cs.AI
+        - cs.CV
+        - cs.LG
+      max_papers: 25
+      smtp:
+        host: "${SMTP_HOST}"
+        port: 587
+        user: "${SMTP_USER}"
+        password: "${SMTP_PASSWORD}"
+      zotero:
+        api_key: "${ZOTERO_API_KEY}"
+        library_id: "${ZOTERO_LIBRARY_ID}"
+```
+
+**Usage**:
+```bash
+# Use via TUI (default)
+soothe "Find recent papers on transformer architectures" --subagent paperscout
+
+# Or headless mode
+soothe "Find recent papers" --subagent paperscout --no-tui
+```
+
+## Creating a New Plugin
+
+To create a new community plugin:
+
+1. **Create a package** in `src/soothe_plugins/your_plugin/`
+2. **Define events** in `events.py` using `register_event()`
+3. **Create plugin class** in `__init__.py` with `@plugin` decorator
+4. **Implement functionality** in `implementation.py`
+5. **Add tests** in `tests/unit/community/test_your_plugin/`
+6. **Update dependencies** in `pyproject.toml` (optional extras)
+
+See the PaperScout plugin for a complete example.
+
+## Plugin Development Guidelines
+
+### 1. Follow RFC-0018
+
+All plugins must comply with RFC-0018 Plugin Extension System:
+- Use `@plugin` decorator for plugin registration
+- Use `@tool` or `@subagent` decorators for capabilities
+- Register custom events using `register_event()`
+- Respect trust levels and permissions
+
+### 2. Self-Containment
+
+Each plugin should be self-contained:
+- Define its own events in `events.py`
+- Include all necessary data models
+- Handle configuration through Soothe's config system
+- Document dependencies clearly
+
+### 3. Testing
+
+- Provide comprehensive test coverage (>80%)
+- Mock all external APIs and services
+- Test plugin lifecycle (load/unload)
+- Test event emission
+
+### 4. Documentation
+
+- Create a README for the plugin
+- Document configuration options
+- Provide usage examples
+- List dependencies and installation requirements
+
+### 5. Code Quality
+
+- Follow Soothe's Python style guide
+- Use type hints on all public functions
+- Add Google-style docstrings
+- Run `./scripts/verify_finally.sh` before committing
+
+## Directory Structure
+
+```
+src/soothe_plugins/
+├── __init__.py              # Package init
+├── README.md                # This file
+└── paperscout/              # Example plugin
+    ├── __init__.py          # Plugin registration
+    ├── events.py            # Event definitions
+    ├── implementation.py    # Core implementation
+    ├── state.py             # Configuration/state models
+    ├── nodes.py             # Workflow nodes
+    ├── reranker.py          # Paper ranking
+    ├── email.py             # Email formatting
+    ├── models.py            # Data models
+    └── gap_scanner.py       # Gap detection
+```
+
+## Contributing
+
+To contribute a plugin:
+
+1. Fork the repository
+2. Create your plugin in `src/soothe_plugins/your_plugin/`
+3. Add tests in `tests/unit/community/test_your_plugin/`
+4. Update this README with your plugin's documentation
+5. Submit a pull request
+
+## Support
+
+- **Documentation**: See `docs/specs/RFC-0018.md` for plugin architecture
+- **Examples**: See existing plugins in this directory
+- **Issues**: Report issues on GitHub
+
+## License
+
+Community plugins follow the same license as the main Soothe project.

soothe_plugins/__init__.py

@@ -0,0 +1,20 @@
+"""Soothe Community Plugins.
+
+This package contains community-contributed plugins for Soothe,
+including subagents, tools, and other extensions built on the
+RFC-0018 plugin system.
+
+All plugins in this package are third-party contributions and follow
+the standard plugin architecture with @plugin and @subagent decorators.
+"""
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("soothe-plugins")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+]

soothe_plugins/_paths.py

@@ -0,0 +1,17 @@
+"""Path helpers for community plugins (mirrors ``soothe.utils.path.expand_path``)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def expand_path(path: str | Path) -> Path:
+    """Expand and resolve a filesystem path."""
+    path_str = str(path)
+    expanded = os.path.expandvars(path_str)
+    expanded_path = Path(expanded).expanduser()
+    return expanded_path.resolve()
+
+
+__all__ = ["expand_path"]

soothe_plugins/sample_echo/__init__.py

@@ -0,0 +1,44 @@
+"""Sample echo subagent — minimal community plugin for Soothe integration tests."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from soothe_sdk.plugin import plugin, subagent
+
+from .implementation import create_echo_subagent_spec
+
+__all__ = ["SampleEchoPlugin", "create_echo_subagent_spec"]
+
+logger = logging.getLogger(__name__)
+
+
+@plugin(
+    name="sample_echo",
+    version="1.0.0",
+    description="Minimal echo subagent for testing soothe-plugins against the Soothe daemon",
+    dependencies=["langgraph>=0.2.0"],
+    trust_level="standard",
+)
+class SampleEchoPlugin:
+    """Registers a no-LLM subgraph so CI can validate plugin subagent loading."""
+
+    async def on_load(self, context: Any) -> None:
+        """No-op load hook."""
+        context.logger.info("sample_echo plugin loaded")
+
+    @subagent(
+        name="sample_echo",
+        description=("Echoes the user's last message with a sample_echo tag. For automated tests only."),
+    )
+    async def create_sample_echo(
+        self,
+        model: Any,
+        config: Any,
+        context: Any,
+        **_kwargs: Any,
+    ) -> dict[str, Any]:
+        """Materialize the echo subgraph (model and global config unused)."""
+        _ = model, config, context
+        return create_echo_subagent_spec()

soothe_plugins/sample_echo/implementation.py

@@ -0,0 +1,47 @@
+"""Minimal LangGraph subagent for integration testing (no LLM)."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, TypedDict
+
+from langchain_core.messages import AIMessage, HumanMessage
+from langgraph.graph import END, START, StateGraph
+from langgraph.graph.message import add_messages
+
+
+class EchoState(TypedDict):
+    """Graph state: conversation messages only."""
+
+    messages: Annotated[list[Any], add_messages]
+
+
+def _echo_node(state: EchoState) -> dict[str, Any]:
+    """Return an assistant message echoing the last human input."""
+    text = ""
+    for msg in reversed(state.get("messages", [])):
+        if isinstance(msg, HumanMessage):
+            text = str(msg.content)
+            break
+    body = f"[sample_echo] {text!r}"
+    return {"messages": [AIMessage(content=body)]}
+
+
+def create_echo_subagent_spec() -> dict[str, Any]:
+    """Build a compiled subgraph spec for deepagents ``task`` delegation.
+
+    Returns:
+        Subagent dict with ``name``, ``description``, and ``runnable``.
+    """
+    graph = StateGraph(EchoState)
+    graph.add_node("echo", _echo_node)
+    graph.add_edge(START, "echo")
+    graph.add_edge("echo", END)
+    compiled = graph.compile()
+    return {
+        "name": "sample_echo",
+        "description": (
+            "Test-only community subagent that echoes the last user message. "
+            "Use for plugin and resolver integration checks."
+        ),
+        "runnable": compiled,
+    }

soothe_plugins/skillify/__init__.py

@@ -0,0 +1,288 @@
+"""Skillify subagent plugin -- skill warehouse indexing and semantic retrieval (RFC-0004).
+
+Community plugin for Soothe that provides:
+  1. Background indexing loop (asyncio.Task) keeping the vector index in sync
+     with the skill warehouse.
+  2. Retrieval CompiledSubAgent (LangGraph) serving on-demand skill bundles
+     for user goals or downstream agents like Weaver.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any, TypedDict
+
+from langchain_core.messages import AIMessage
+from langgraph.graph import END, START, StateGraph
+from langgraph.graph.message import add_messages
+from soothe_sdk.plugin import plugin, subagent
+
+from .events import (
+    SkillifyCompletedEvent,
+    SkillifyDispatchedEvent,
+    SkillifyIndexingPendingEvent,
+    SkillifyRetrieveCompletedEvent,
+    SkillifyRetrieveNotReadyEvent,
+    SkillifyRetrieveStartedEvent,
+)
+from .indexer import SkillIndexer
+from .retriever import SkillRetriever
+from .warehouse import SkillWarehouse
+
+if TYPE_CHECKING:
+    from deepagents.middleware.subagents import CompiledSubAgent
+    from langchain_core.language_models import BaseChatModel
+
+    from .models import SkillBundle
+
+logger = logging.getLogger(__name__)
+
+SKILLIFY_DESCRIPTION = (
+    "Skill retrieval agent for semantic search over the skill warehouse. "
+    "Given a task description or objective, returns a ranked bundle of relevant "
+    "skills with paths and relevance scores. Use when you need to find skills "
+    "matching a specific capability or goal."
+)
+
+
+def _emit_event(event_dict: dict[str, Any], ctx_logger: logging.Logger) -> None:
+    """Emit progress event via logger or event emission.
+
+    For community plugins, we use logger.info() for visibility.
+    Daemon may intercept and convert to progress events.
+    """
+    event_type = event_dict.get("type", "unknown")
+    ctx_logger.info(f"[{event_type}] {event_dict}")
+
+
+class SkillifyState(TypedDict):
+    """State for the Skillify retrieval graph."""
+
+    messages: Annotated[list[Any], add_messages]
+
+
+def _build_skillify_graph(retriever: SkillRetriever) -> Any:
+    """Build and compile the Skillify retrieval LangGraph."""
+
+    async def _retrieve_async(state: dict[str, Any]) -> dict[str, Any]:
+        messages = state.get("messages", [])
+        query = ""
+        for msg in reversed(messages):
+            if hasattr(msg, "type") and msg.type == "human":
+                query = msg.content if hasattr(msg, "content") else str(msg)
+                break
+        if not query and messages:
+            last = messages[-1]
+            query = last.content if hasattr(last, "content") else str(last)
+
+        _emit_event(SkillifyDispatchedEvent(task=query[:200]).to_dict(), logger)
+
+        if not retriever.is_ready:
+            _emit_event(SkillifyIndexingPendingEvent(query=query[:200]).to_dict(), logger)
+
+        _emit_event(SkillifyRetrieveStartedEvent(query=query[:200]).to_dict(), logger)
+
+        bundle: SkillBundle = await retriever.retrieve(query)
+
+        if bundle.query.startswith("[Indexing in progress]"):
+            _emit_event(SkillifyRetrieveNotReadyEvent(message=bundle.query).to_dict(), logger)
+            _emit_event(SkillifyCompletedEvent(duration_ms=0, result_count=0).to_dict(), logger)
+            return {"messages": [AIMessage(content=bundle.query)]}
+
+        top_score = bundle.results[0].score if bundle.results else 0.0
+        _emit_event(
+            SkillifyRetrieveCompletedEvent(
+                query=query[:200],
+                result_count=len(bundle.results),
+                top_score=round(top_score, 3),
+            ).to_dict(),
+            logger,
+        )
+
+        result_lines = [f"Found {len(bundle.results)} relevant skills (total indexed: {bundle.total_indexed}):\n"]
+        for i, sr in enumerate(bundle.results, 1):
+            result_lines.append(
+                f"{i}. **{sr.record.name}** (score: {sr.score:.3f})\n"
+                f"   Path: {sr.record.path}\n"
+                f"   Description: {sr.record.description[:200]}\n"
+                f"   Tags: {', '.join(sr.record.tags) if sr.record.tags else 'none'}"
+            )
+
+        result_text = "\n".join(result_lines)
+        _emit_event(
+            SkillifyCompletedEvent(
+                duration_ms=0,
+                result_count=len(bundle.results),
+            ).to_dict(),
+            logger,
+        )
+        return {"messages": [AIMessage(content=result_text)]}
+
+    def retrieve_sync(state: dict[str, Any]) -> dict[str, Any]:
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        if loop.is_running():
+            new_loop = asyncio.new_event_loop()
+            try:
+                return new_loop.run_until_complete(_retrieve_async(state))
+            finally:
+                new_loop.close()
+        else:
+            return loop.run_until_complete(_retrieve_async(state))
+
+    graph = StateGraph(SkillifyState)
+    graph.add_node("retrieve", retrieve_sync)
+    graph.add_edge(START, "retrieve")
+    graph.add_edge("retrieve", END)
+    return graph.compile()
+
+
+def _resolve_dependencies(soothe_cfg: Any) -> tuple[Any, Any]:
+    """Resolve VectorStore and Embeddings from context services."""
+    # Use context services if available
+    if hasattr(soothe_cfg, "services"):
+        services = soothe_cfg.services
+        vector_store = services.get("vector_store")
+        embeddings_factory = services.get("embeddings_factory")
+        if vector_store and embeddings_factory:
+            return vector_store, embeddings_factory
+
+    # Fallback: use soothe_config protocol methods
+    if hasattr(soothe_cfg, "create_vector_store_for_role"):
+        vs = soothe_cfg.create_vector_store_for_role("skillify")
+        embeddings_factory = soothe_cfg.create_embedding_model
+        return vs, embeddings_factory
+
+    # Last resort: create basic implementations
+    msg = "Cannot resolve vector_store or embeddings from context or config"
+    raise ValueError(msg)
+
+
+def _start_background_indexer(indexer: SkillIndexer) -> None:
+    """Start the indexer background loop, creating an event loop if needed."""
+    try:
+        loop = asyncio.get_running_loop()
+        indexer._start_task = loop.create_task(indexer.start())
+    except RuntimeError:
+        pass
+
+
+@plugin(
+    name="skillify",
+    version="1.0.0",
+    description="Skill warehouse indexing and semantic retrieval",
+    dependencies=["langgraph>=0.2.0"],
+    trust_level="standard",
+)
+class SkillifyPlugin:
+    """Skillify community plugin for skill warehouse indexing and retrieval."""
+
+    def __init__(self) -> None:
+        self._indexer: SkillIndexer | None = None
+
+    async def on_load(self, context: Any) -> None:
+        """Trigger event self-registration."""
+        import soothe_plugins.skillify.events  # noqa: F401
+
+        context.logger.info("Skillify plugin loaded")
+
+    async def on_unload(self) -> None:
+        """Stop the background indexer."""
+        if self._indexer is not None:
+            try:
+                await self._indexer.stop()
+            except Exception:
+                pass
+            self._indexer = None
+
+    @subagent(
+        name="skillify",
+        description=SKILLIFY_DESCRIPTION,
+    )
+    async def create_skillify(
+        self,
+        model: str | BaseChatModel | None,
+        config: Any,
+        context: Any,
+        **_kwargs: Any,
+    ) -> CompiledSubAgent:
+        """Create a Skillify subagent.
+
+        Args:
+            model: Unused (Skillify does not need an LLM).
+            config: Plugin context (PluginContext instance from soothe_sdk).
+            context: Plugin context (same as config parameter - deprecated parameter name).
+            **_kwargs: Additional config (ignored).
+
+        Returns:
+            CompiledSubAgent dict with background indexer.
+        """
+
+        soothe_cfg = context.soothe_config
+        plugin_cfg = context.config if hasattr(context, "config") else {}
+        ctx_logger = context.logger if hasattr(context, "logger") else logger
+
+        # Get plugin-specific config
+        skillify_cfg = plugin_cfg.get("skillify", {})
+
+        # Resolve warehouse paths
+        soothe_home = Path.home() / ".soothe"  # Default SOOTHE_HOME
+        if hasattr(soothe_cfg, "home"):
+            soothe_home = Path(soothe_cfg.home)
+
+        default_warehouse = str(soothe_home / "agents" / "skillify" / "warehouse")
+        warehouse_paths = skillify_cfg.get("warehouse_paths", [])
+        if isinstance(warehouse_paths, list) and default_warehouse not in warehouse_paths:
+            warehouse_paths.insert(0, default_warehouse)
+
+        warehouse = SkillWarehouse(paths=warehouse_paths)
+        vector_store, embeddings = _resolve_dependencies(soothe_cfg)
+
+        # Extract config parameters with defaults
+        collection = skillify_cfg.get("index_collection", "soothe_skillify")
+        interval = skillify_cfg.get("index_interval_seconds", 300)
+        top_k = skillify_cfg.get("retrieval_top_k", 10)
+        embedding_dims = skillify_cfg.get("embedding_dims", 1536)
+
+        def emit_callback(event: dict[str, Any]) -> None:
+            _emit_event(event, ctx_logger)
+
+        self._indexer = SkillIndexer(
+            warehouse=warehouse,
+            vector_store=vector_store,
+            embeddings=embeddings,
+            interval_seconds=interval,
+            collection=collection,
+            embedding_dims=embedding_dims,
+            event_callback=emit_callback,
+        )
+
+        retriever = SkillRetriever(
+            vector_store=vector_store,
+            embeddings=embeddings,
+            top_k=top_k,
+            ready_event=self._indexer.ready_event,
+        )
+
+        _start_background_indexer(self._indexer)
+
+        runnable = _build_skillify_graph(retriever)
+
+        spec: CompiledSubAgent = {
+            "name": "skillify",
+            "description": SKILLIFY_DESCRIPTION,
+            "runnable": runnable,
+        }
+        spec["_skillify_indexer"] = self._indexer  # type: ignore[typeddict-unknown-key]
+        spec["_skillify_retriever"] = retriever  # type: ignore[typeddict-unknown-key]
+        return spec
+
+    def get_subagents(self) -> list[Any]:
+        """Get list of subagent factory functions."""
+        return [self.create_skillify]