devsper 2.1.6__py3-none-any.whl

devsper/orchestration/meta_planner.py

@@ -0,0 +1,239 @@
+"""
+MetaPlanner: decomposes mega-tasks into sub-swarms with dependencies, SLAs, and priorities.
+Coordinates execution across sub-swarms and monitors SLA breaches.
+"""
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Literal
+
+from devsper.utils.models import generate
+
+
+@dataclass
+class SLAConfig:
+    max_duration_seconds: int
+    max_cost_usd: float | None = None
+    min_quality_score: float | None = None  # from critic scores
+    on_breach: Literal["cancel", "escalate", "continue"] = "continue"
+
+
+@dataclass
+class SubSwarmSpec:
+    swarm_id: str
+    root_task: str
+    priority: int  # 1 (highest) to 10 (lowest)
+    sla: SLAConfig
+    worker_count: int
+    model_override: str | None = None
+    depends_on: list[str] = field(default_factory=list)  # other swarm_ids
+
+
+@dataclass
+class SLABreach:
+    swarm_id: str
+    breach_type: Literal["duration", "cost", "quality"]
+    limit: float
+    actual: float
+    action_taken: str
+
+
+@dataclass
+class MetaRunResult:
+    mega_task: str
+    sub_swarm_results: dict[str, dict]  # swarm_id -> results
+    total_duration_seconds: float
+    total_cost_usd: float | None
+    sla_breaches: list[SLABreach]
+    final_synthesis: str
+
+
+def _validate_specs(specs: list[SubSwarmSpec]) -> None:
+    """Raise ValueError if priority out of range or depends_on has cycles."""
+    ids_ = {s.swarm_id for s in specs}
+    for s in specs:
+        if not (1 <= s.priority <= 10):
+            raise ValueError(f"SubSwarmSpec {s.swarm_id}: priority must be 1-10, got {s.priority}")
+        for dep in s.depends_on:
+            if dep not in ids_:
+                raise ValueError(f"SubSwarmSpec {s.swarm_id}: depends_on {dep!r} not in swarm ids")
+    # Cycle detection
+    graph: dict[str, list[str]] = {s.swarm_id: list(s.depends_on) for s in specs}
+    path = set()
+    visited = set()
+
+    def visit(n: str) -> None:
+        if n in path:
+            raise ValueError(f"Cycle in depends_on involving {n!r}")
+        if n in visited:
+            return
+        path.add(n)
+        for c in graph.get(n, []):
+            visit(c)
+        path.remove(n)
+        visited.add(n)
+
+    for n in graph:
+        if n not in visited:
+            visit(n)
+
+
+def _topological_order(specs: list[SubSwarmSpec]) -> list[SubSwarmSpec]:
+    """Return specs in dependency order (dependencies first)."""
+    by_id = {s.swarm_id: s for s in specs}
+    in_degree = {s.swarm_id: 0 for s in specs}
+    for s in specs:
+        for dep in s.depends_on:
+            in_degree[s.swarm_id] += 1
+    from collections import deque
+    q: list[str] = [i for i, d in in_degree.items() if d == 0]
+    order: list[str] = []
+    while q:
+        n = q.pop(0)
+        order.append(n)
+        for s in specs:
+            if n in s.depends_on:
+                in_degree[s.swarm_id] -= 1
+                if in_degree[s.swarm_id] == 0:
+                    q.append(s.swarm_id)
+    if len(order) != len(specs):
+        order = [s.swarm_id for s in sorted(specs, key=lambda x: (x.priority, x.swarm_id))]
+    return [by_id[i] for i in order if i in by_id]
+
+
+class MetaPlanner:
+    """Decomposes mega-tasks into sub-swarms and runs them with SLA monitoring."""
+
+    def __init__(self, model_name: str = "mock", max_swarms: int = 20) -> None:
+        self.model_name = model_name
+        self.max_swarms = max_swarms
+
+    async def decompose(self, mega_task: str) -> list[SubSwarmSpec]:
+        """LLM call: given mega_task, produce JSON list of SubSwarmSpecs. Validates no cycles and priority 1-10."""
+        prompt = f"""You are a meta-planner. Given the following mega-task, decompose it into independent or dependent sub-tasks, each to be run as a separate swarm.
+
+Mega-task: {mega_task}
+
+Respond with a JSON array of objects. Each object must have:
+- swarm_id: string (short id, e.g. "research", "code", "review")
+- root_task: string (the task this swarm will execute)
+- priority: int (1 = highest, 10 = lowest)
+- sla: object with max_duration_seconds (int), max_cost_usd (number or null), min_quality_score (number 0-1 or null), on_breach ("cancel"|"escalate"|"continue")
+- worker_count: int (1-8)
+- model_override: string or null
+- depends_on: array of swarm_ids that must complete before this one (can be empty)
+
+Ensure no circular dependencies. Return only the JSON array, no markdown."""
+
+        out = await asyncio.to_thread(generate, self.model_name, prompt)
+        text = (out or "").strip()
+        if "```" in text:
+            for part in text.split("```"):
+                part = part.strip()
+                if part.startswith("json") or part.startswith("["):
+                    text = part[4:].strip() if part.startswith("json") else part
+                    break
+        try:
+            raw = json.loads(text)
+        except json.JSONDecodeError:
+            raw = []
+        if not isinstance(raw, list):
+            raw = []
+        specs: list[SubSwarmSpec] = []
+        for i, item in enumerate(raw[: self.max_swarms]):
+            if not isinstance(item, dict):
+                continue
+            sla = item.get("sla") or {}
+            sla_config = SLAConfig(
+                max_duration_seconds=int(sla.get("max_duration_seconds", 300)),
+                max_cost_usd=float(sla["max_cost_usd"]) if sla.get("max_cost_usd") is not None else None,
+                min_quality_score=float(sla["min_quality_score"]) if sla.get("min_quality_score") is not None else None,
+                on_breach=(sla.get("on_breach") or "continue").lower()[:8],
+            )
+            if sla_config.on_breach not in ("cancel", "escalate", "continue"):
+                sla_config.on_breach = "continue"
+            spec = SubSwarmSpec(
+                swarm_id=str(item.get("swarm_id", f"swarm_{i}")),
+                root_task=str(item.get("root_task", mega_task)),
+                priority=int(item.get("priority", 5)),
+                sla=sla_config,
+                worker_count=max(1, min(8, int(item.get("worker_count", 2)))),
+                model_override=str(item["model_override"]) if item.get("model_override") else None,
+                depends_on=[str(d) for d in item.get("depends_on") or []],
+            )
+            specs.append(spec)
+        _validate_specs(specs)
+        return specs
+
+    async def run(self, mega_task: str, max_swarms: int | None = None, budget_usd: float | None = None) -> MetaRunResult:
+        """Decompose -> build DAG -> run sub-swarms in order; monitor SLAs; return aggregated result with synthesis."""
+        max_n = max_swarms or self.max_swarms
+        specs = await self.decompose(mega_task)
+        specs = specs[:max_n]
+        ordered = _topological_order(specs)
+        sub_swarm_results: dict[str, dict] = {}
+        sla_breaches: list[SLABreach] = []
+        total_cost: float | None = None
+        start = datetime.now(timezone.utc)
+
+        from devsper.swarm.swarm import Swarm
+        from devsper.config import get_config
+        from devsper.utils.event_logger import EventLog
+
+        cfg = get_config()
+        event_log = EventLog(events_folder_path=cfg.events_dir)
+
+        for spec in ordered:
+            swarm_start = datetime.now(timezone.utc)
+            swarm = Swarm(
+                worker_count=spec.worker_count,
+                worker_model=spec.model_override or cfg.models.worker,
+                planner_model=cfg.models.planner,
+                event_log=event_log,
+                config=cfg,
+            )
+            try:
+                result = swarm.run(spec.root_task)
+            except Exception as e:
+                result = {"error": str(e)}
+            elapsed = (datetime.now(timezone.utc) - swarm_start).total_seconds()
+            sub_swarm_results[spec.swarm_id] = result
+
+            if elapsed > spec.sla.max_duration_seconds:
+                breach = SLABreach(
+                    swarm_id=spec.swarm_id,
+                    breach_type="duration",
+                    limit=float(spec.sla.max_duration_seconds),
+                    actual=elapsed,
+                    action_taken=spec.sla.on_breach,
+                )
+                sla_breaches.append(breach)
+                if spec.sla.on_breach == "cancel":
+                    break
+
+        total_duration_seconds = (datetime.now(timezone.utc) - start).total_seconds()
+
+        # Final synthesis via LLM
+        results_summary = json.dumps({k: (v if isinstance(v, dict) else {"result": str(v)}) for k, v in sub_swarm_results.items()}, indent=0)[:6000]
+        synth_prompt = f"""Mega-task: {mega_task}
+
+Sub-swarm results summary:
+{results_summary}
+
+SLA breaches (if any): {[f"{b.swarm_id}: {b.breach_type}" for b in sla_breaches]}
+
+Write a short final synthesis (2-4 sentences) summarizing the overall outcome and any caveats."""
+
+        synth_out = await asyncio.to_thread(generate, self.model_name, synth_prompt)
+        final_synthesis = (synth_out or "").strip() or "No synthesis generated."
+
+        return MetaRunResult(
+            mega_task=mega_task,
+            sub_swarm_results=sub_swarm_results,
+            total_duration_seconds=total_duration_seconds,
+            total_cost_usd=total_cost,
+            sla_breaches=sla_breaches,
+            final_synthesis=final_synthesis,
+        )

devsper/orchestration/priority_queue.py

@@ -0,0 +1,61 @@
+"""
+PriorityScheduler: extends Scheduler with priority-aware task ordering.
+get_ready_tasks() returns tasks sorted by priority, then dependency impact, then estimated duration.
+"""
+
+from devsper.swarm.scheduler import Scheduler
+from devsper.types.task import Task, TaskStatus
+
+
+class PriorityScheduler(Scheduler):
+    """Scheduler that orders ready tasks by priority (1=highest), then by dependency impact, then shortest first."""
+
+    def __init__(self, run_id: str = "") -> None:
+        super().__init__(run_id=run_id)
+        self._priority: dict[str, int] = {}  # task_id -> priority (lower = higher priority)
+
+    def add_task(self, task: Task, priority: int = 5) -> None:
+        """Add a single task with optional priority (1-10, default 5)."""
+        if not (1 <= priority <= 10):
+            priority = max(1, min(10, priority))
+        self._priority[task.id] = priority
+        super().add_tasks([task])
+
+    def add_tasks(self, tasks: list[Task]) -> None:
+        """Add tasks; each task gets priority from task.priority if present, else 5."""
+        for t in tasks:
+            if t.id not in self._priority:
+                p = getattr(t, "priority", 5)
+                self._priority[t.id] = max(1, min(10, p)) if isinstance(p, int) else 5
+        super().add_tasks(tasks)
+
+    def bump_priority(self, task_id: str, new_priority: int) -> None:
+        """Set priority for a task (e.g. for SLA escalation). Lower number = higher priority."""
+        if task_id in self._tasks:
+            self._priority[task_id] = max(1, min(10, new_priority))
+
+    def _priority_of(self, task_id: str) -> int:
+        return self._priority.get(task_id, 5)
+
+    def get_ready_tasks(self) -> list[Task]:
+        """Return ready tasks sorted by: 1) priority (lower first), 2) dependencies satisfied count (unblock more first), 3) estimated duration (shortest first)."""
+        ready = super().get_ready_tasks()
+        if not ready:
+            return ready
+
+        def unblock_count(task_id: str) -> int:
+            return len(list(self._graph.successors(task_id)))
+
+        def estimated_duration(task: Task) -> float:
+            # Heuristic: length of description as proxy for duration
+            desc = task.description or ""
+            return float(len(desc))
+
+        ready.sort(
+            key=lambda t: (
+                self._priority_of(t.id),
+                -unblock_count(t.id),  # higher successor count first
+                estimated_duration(t),
+            )
+        )
+        return ready

devsper/plugins/__init__.py

@@ -0,0 +1,19 @@
+"""Plugin system: discover and load tools via entry_points."""
+
+from devsper.plugins.plugin_loader import load_plugins
+from devsper.plugins.plugin_registry import (
+    PluginInfo,
+    clear_plugins,
+    get_plugin,
+    list_plugins,
+    register_plugin,
+)
+
+__all__ = [
+    "load_plugins",
+    "PluginInfo",
+    "register_plugin",
+    "get_plugin",
+    "list_plugins",
+    "clear_plugins",
+]

devsper/plugins/plugin_loader.py

@@ -0,0 +1,70 @@
+"""Discover and load plugins via entry_points (devsper.plugins)."""
+
+import importlib.metadata
+import logging
+from devsper.tools.base import Tool
+from devsper.tools.registry import register
+
+from devsper.plugins.plugin_registry import register_plugin
+
+logger = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "devsper.plugins"
+
+
+def _load_entry_points(group: str = ENTRY_POINT_GROUP):
+    try:
+        eps = importlib.metadata.entry_points(group=group)
+    except TypeError:
+        eps = importlib.metadata.entry_points().get(group, [])
+    return list(eps)
+
+
+def _invoke_plugin(ep: importlib.metadata.EntryPoint) -> list[str]:
+    """
+    Load entry point and register tools. Entry point can be:
+    - A callable that returns a list of Tool instances
+    - A callable that takes no args and calls register() itself (returns None or list of tool names)
+    Returns list of tool names registered.
+    """
+    try:
+        fn = ep.load()
+    except Exception as e:
+        logger.warning("Plugin %s failed to load: %s", ep.name, e)
+        return []
+    registered: list[str] = []
+    try:
+        result = fn()
+        if result is None:
+            return registered
+        if isinstance(result, list):
+            for item in result:
+                if isinstance(item, Tool):
+                    register(item)
+                    registered.append(item.name)
+                elif isinstance(item, str):
+                    registered.append(item)
+    except Exception as e:
+        logger.warning("Plugin %s failed to run: %s", ep.name, e)
+    return registered
+
+
+def load_plugins(enabled: list[str] | None = None) -> list[str]:
+    """
+    Discover plugins from entry_points and register their tools.
+    If enabled is provided, only load those plugin names; otherwise load all.
+    Returns list of plugin names that were loaded.
+    """
+    loaded: list[str] = []
+    for ep in _load_entry_points():
+        if enabled is not None and ep.name not in enabled:
+            continue
+        try:
+            dist = ep.dist
+            version = dist.version if dist else ""
+        except Exception:
+            version = ""
+        tool_names = _invoke_plugin(ep)
+        register_plugin(ep.name, version=version, tools=tool_names)
+        loaded.append(ep.name)
+    return loaded

devsper/plugins/plugin_registry.py

@@ -0,0 +1,34 @@
+"""Registry of loaded plugins: name, version, tools registered."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class PluginInfo:
+    name: str
+    version: str = ""
+    tools_registered: list[str] = field(default_factory=list)
+
+
+_plugins: dict[str, PluginInfo] = {}
+
+
+def register_plugin(name: str, version: str = "", tools: list[str] | None = None) -> None:
+    _plugins[name] = PluginInfo(
+        name=name,
+        version=version,
+        tools_registered=list(tools or []),
+    )
+
+
+def get_plugin(name: str) -> PluginInfo | None:
+    return _plugins.get(name)
+
+
+def list_plugins() -> list[PluginInfo]:
+    return list(_plugins.values())
+
+
+def clear_plugins() -> None:
+    """Clear registry (mainly for tests)."""
+    _plugins.clear()

devsper/plugins/registry.py

@@ -0,0 +1,83 @@
+"""Shared HTTP client and token helpers for the devsper package registry."""
+
+import os
+
+import httpx
+
+REGISTRY_URL = os.environ.get(
+    "DEVSPER_REGISTRY_URL",
+    "https://registry.devsper.com",
+)
+
+CREDENTIAL_SERVICE = "devsper_registry"
+CREDENTIAL_USERNAME = "api_key"
+
+
+def get_token() -> str | None:
+    """Read stored API key from OS keychain, falling back to env var."""
+    try:
+        from devsper.credentials import get_credential
+
+        token = get_credential(CREDENTIAL_SERVICE, CREDENTIAL_USERNAME)
+        if token:
+            return token
+    except Exception:
+        pass
+    return os.environ.get("DEVSPER_API_KEY")
+
+
+def set_token(token: str) -> None:
+    """Store API key in OS keychain."""
+    from devsper.credentials import set_credential
+
+    set_credential(CREDENTIAL_SERVICE, CREDENTIAL_USERNAME, token)
+
+
+def delete_token() -> None:
+    """Remove API key from OS keychain."""
+    try:
+        from devsper.credentials import delete_credential
+
+        delete_credential(CREDENTIAL_SERVICE, CREDENTIAL_USERNAME)
+    except Exception:
+        pass
+
+
+def require_token() -> str:
+    """Get token or exit with helpful message."""
+    token = get_token()
+    if not token:
+        from rich.console import Console
+
+        Console().print(
+            "[red]Not logged in.[/red] Run [bold]devsper reg login[/bold] first.\n"
+            "Or set [bold]DEVSPER_API_KEY[/bold] env var for CI."
+        )
+        raise SystemExit(1)
+    return token
+
+
+class RegistryClient:
+    """Thin HTTP wrapper for the devsper package registry API."""
+
+    def __init__(self, token: str | None = None):
+        self.base = REGISTRY_URL.rstrip("/")
+        self.token = token
+        self._client = httpx.Client(timeout=30)
+
+    def _headers(self) -> dict:
+        h: dict[str, str] = {"Content-Type": "application/json"}
+        if self.token:
+            h["X-API-Key"] = self.token
+        return h
+
+    def get(self, path: str, **kwargs) -> httpx.Response:
+        return self._client.get(f"{self.base}{path}", headers=self._headers(), **kwargs)
+
+    def post(self, path: str, **kwargs) -> httpx.Response:
+        return self._client.post(
+            f"{self.base}{path}", headers=self._headers(), **kwargs
+        )
+
+    def close(self) -> None:
+        self._client.close()

devsper/protocols/__init__.py

@@ -0,0 +1,6 @@
+"""Protocol version constants for MCP and A2A."""
+
+MCP_PROTOCOL_VERSION = "2024-11-05"
+A2A_PROTOCOL_VERSION = "0.2.1"
+
+__all__ = ["MCP_PROTOCOL_VERSION", "A2A_PROTOCOL_VERSION"]

devsper/providers/__init__.py

@@ -0,0 +1,17 @@
+"""Provider adapters: base interface, router, and implementations."""
+
+from devsper.providers.base import BaseProvider, MockProvider
+from devsper.providers.router import ProviderRouter, get_router
+from devsper.providers.openai import OpenAIProvider
+from devsper.providers.anthropic import AnthropicProvider
+from devsper.providers.gemini import GeminiProvider
+
+__all__ = [
+    "BaseProvider",
+    "MockProvider",
+    "ProviderRouter",
+    "get_router",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "GeminiProvider",
+]

devsper/providers/anthropic.py

@@ -0,0 +1,84 @@
+"""Anthropic provider adapter using LangChain. Supports native Anthropic and Azure (Foundry) Claude."""
+
+import os
+from typing import Iterator
+
+from langchain_anthropic import ChatAnthropic
+from langchain_core.messages import HumanMessage
+
+from devsper.providers.base import BaseProvider
+
+
+def _normalize_azure_base_url(url: str) -> str:
+    """Strip trailing /messages so base URL ends with /v1; ChatAnthropic will append /messages."""
+    if not url:
+        return url
+    url = url.rstrip("/")
+    if url.endswith("/messages"):
+        return url[: -len("/messages")]
+    return url
+
+
+class AnthropicProvider(BaseProvider):
+    """
+    Anthropic API adapter. Uses ANTHROPIC_API_KEY (or pass api_key).
+    When AZURE_ANTHROPIC_* env vars are set, uses Azure Foundry Claude endpoint instead.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        azure: bool = False,
+        azure_endpoint: str | None = None,
+        azure_api_key: str | None = None,
+        azure_deployment: str | None = None,
+    ) -> None:
+        self.azure = azure or bool(
+            os.environ.get("AZURE_ANTHROPIC_ENDPOINT") or os.environ.get("AZURE_ANTHROPIC_API_KEY")
+        )
+        if self.azure:
+            self.azure_endpoint = _normalize_azure_base_url(
+                azure_endpoint or os.environ.get("AZURE_ANTHROPIC_ENDPOINT", "")
+            )
+            self.azure_api_key = azure_api_key or os.environ.get("AZURE_ANTHROPIC_API_KEY")
+            self.azure_deployment = (azure_deployment or os.environ.get("AZURE_ANTHROPIC_DEPLOYMENT_NAME") or "").strip()
+            if not self.azure_endpoint or not self.azure_api_key:
+                raise ValueError(
+                    "Azure Anthropic requires AZURE_ANTHROPIC_ENDPOINT and AZURE_ANTHROPIC_API_KEY"
+                )
+            self.api_key = self.azure_api_key
+        else:
+            self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+            self.azure_endpoint = ""
+            self.azure_api_key = ""
+            self.azure_deployment = ""
+            if not self.api_key:
+                raise ValueError("Anthropic requires api_key or ANTHROPIC_API_KEY")
+
+    def generate(self, model: str, prompt: str, stream: bool = False) -> str | Iterator[str]:
+        """Call Anthropic (or Azure Claude) API and return the model output text."""
+        if self.azure:
+            deployment = (model or self.azure_deployment or "").strip() or self.azure_deployment
+            if not deployment:
+                raise ValueError("Azure Anthropic requires model name or AZURE_ANTHROPIC_DEPLOYMENT_NAME")
+            llm = ChatAnthropic(
+                model=deployment,
+                anthropic_api_url=self.azure_endpoint,
+                anthropic_api_key=self.azure_api_key,
+                temperature=0,
+            )
+        else:
+            llm = ChatAnthropic(
+                model=model,
+                api_key=self.api_key,
+                temperature=0,
+            )
+        message = llm.invoke([HumanMessage(content=prompt)])
+        content = message.content
+        text = content if isinstance(content, str) else str(content)
+        if stream:
+            def _gen():
+                yield text
+            return _gen()
+        return text