devsper 2.1.6__py3-none-any.whl

devsper/dev/scaffold.py

@@ -0,0 +1,122 @@
+"""
+Repo scaffolder: generate repo structure from an architecture plan.
+
+Structure: repo/backend/, frontend/, tests/, docker/, README.md
+"""
+
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ArchitecturePlan:
+    """High-level architecture for the app to build."""
+
+    name: str
+    description: str
+    backend: str  # e.g. "fastapi", "flask"
+    frontend: str  # e.g. "react", "vanilla", "none"
+    features: list[str] = field(default_factory=list)
+
+
+def scaffold_repo(
+    root: str | Path,
+    plan: ArchitecturePlan,
+) -> list[str]:
+    """
+    Create directory structure and minimal files based on architecture plan.
+    Returns list of created paths (relative to root).
+    """
+    root = Path(root).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    created: list[str] = []
+
+    # Directories
+    dirs = ["backend", "frontend", "tests", "docker"]
+    for d in dirs:
+        (root / d).mkdir(parents=True, exist_ok=True)
+        created.append(d + "/")
+
+    # README
+    readme = f"""# {plan.name}
+
+{plan.description}
+
+## Structure
+
+- `backend/` — {plan.backend} API
+- `frontend/` — {plan.frontend} UI
+- `tests/` — integration and unit tests
+- `docker/` — container config
+
+## Run
+
+### Backend
+```bash
+cd backend && pip install -r requirements.txt && python -m uvicorn main:app --reload
+```
+
+### Frontend (if applicable)
+```bash
+cd frontend && npm install && npm run dev
+```
+"""
+    (root / "README.md").write_text(readme, encoding="utf-8")
+    created.append("README.md")
+
+    # Backend scaffold based on plan.backend
+    backend_dir = root / "backend"
+    if "fastapi" in plan.backend.lower():
+        (backend_dir / "main.py").write_text(
+            '"""FastAPI app entrypoint."""\n\nfrom fastapi import FastAPI\n\napp = FastAPI(title="'
+            + plan.name.replace('"', "'")
+            + '")\n\n\n@app.get("/")\ndef root():\n    return {"message": "Hello"}\n',
+            encoding="utf-8",
+        )
+        created.append("backend/main.py")
+        (backend_dir / "requirements.txt").write_text(
+            "fastapi>=0.100.0\nuvicorn[standard]>=0.22.0\n",
+            encoding="utf-8",
+        )
+        created.append("backend/requirements.txt")
+    elif "flask" in plan.backend.lower():
+        (backend_dir / "main.py").write_text(
+            '"""Flask app entrypoint."""\n\nfrom flask import Flask\n\napp = Flask(__name__)\n\n\n@app.route("/")\ndef root():\n    return {"message": "Hello"}\n',
+            encoding="utf-8",
+        )
+        created.append("backend/main.py")
+        (backend_dir / "requirements.txt").write_text(
+            "flask>=3.0.0\n",
+            encoding="utf-8",
+        )
+        created.append("backend/requirements.txt")
+    else:
+        (backend_dir / "main.py").write_text(
+            '"""App entrypoint."""\n\n# TODO: implement\n',
+            encoding="utf-8",
+        )
+        (backend_dir / "requirements.txt").write_text(
+            "\n",
+            encoding="utf-8",
+        )
+        created.append("backend/main.py")
+        created.append("backend/requirements.txt")
+
+    # Tests
+    tests_dir = root / "tests"
+    (tests_dir / "__init__.py").write_text("", encoding="utf-8")
+    (tests_dir / "test_app.py").write_text(
+        '"""Basic tests."""\nimport pytest\n\n\ndef test_placeholder():\n    assert True\n',
+        encoding="utf-8",
+    )
+    created.append("tests/__init__.py")
+    created.append("tests/test_app.py")
+
+    # Docker placeholder
+    (root / "docker" / "Dockerfile").write_text(
+        "# Dockerfile placeholder\nFROM python:3.12-slim\nWORKDIR /app\nCOPY backend/ .\nRUN pip install -r requirements.txt\nCMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\"]\n",
+        encoding="utf-8",
+    )
+    created.append("docker/Dockerfile")
+
+    return created

devsper/embeddings/__init__.py

@@ -0,0 +1,5 @@
+"""Local embedding service with sentence-transformers; fallback to provider embeddings."""
+
+from devsper.embeddings.service import embed
+
+__all__ = ["embed"]

devsper/embeddings/service.py

@@ -0,0 +1,36 @@
+"""
+Local embedding service using sentence-transformers (all-MiniLM-L6-v2).
+Falls back to provider embeddings (memory.embeddings.embed_text) if local model unavailable.
+"""
+
+
+def embed(text: str) -> list[float]:
+    """
+    Return embedding vector for text. Tries local sentence-transformers model first,
+    then falls back to provider embeddings (OpenAI/stub).
+    """
+    if not text or not str(text).strip():
+        return _fallback_embed(" ")
+    vec = _local_embed(text)
+    if vec is not None:
+        return vec
+    return _fallback_embed(text)
+
+
+def _local_embed(text: str) -> list[float] | None:
+    """Use sentence-transformers all-MiniLM-L6-v2 if available."""
+    try:
+        from sentence_transformers import SentenceTransformer
+
+        model = SentenceTransformer("all-MiniLM-L6-v2")
+        emb = model.encode(text[:8192], convert_to_numpy=True)
+        return emb.tolist()
+    except Exception:
+        return None
+
+
+def _fallback_embed(text: str) -> list[float]:
+    """Use provider embeddings (OpenAI or stub) from memory.embeddings."""
+    from devsper.memory.embeddings import embed_text
+
+    return embed_text(text)

devsper/explainability/__init__.py

@@ -0,0 +1,14 @@
+"""Explainability: decision tree, rationale, simulation (v2.0)."""
+
+from devsper.explainability.decision_tree import DecisionRecord, DecisionTreeBuilder, ToolConsideration
+from devsper.explainability.rationale import RationaleGenerator
+from devsper.explainability.simulation import SimulationMode, SimulationReport
+
+__all__ = [
+    "DecisionRecord",
+    "DecisionTreeBuilder",
+    "ToolConsideration",
+    "RationaleGenerator",
+    "SimulationMode",
+    "SimulationReport",
+]

devsper/explainability/decision_tree.py

@@ -0,0 +1,104 @@
+"""Decision records per task for explainability."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ToolConsideration:
+    tool_name: str
+    similarity_score: float
+    reliability_score: float
+    blended_score: float
+    selected: bool
+
+
+@dataclass
+class DecisionRecord:
+    task_id: str
+    task_description: str
+    strategy_selected: str
+    strategy_reason: str
+    tools_considered: list[ToolConsideration] = field(default_factory=list)
+    tools_selected: list[str] = field(default_factory=list)
+    model_tier: str = ""
+    model_selected: str = ""
+    model_reason: str = ""
+    memory_records_used: int = 0
+    kg_context_injected: bool = False
+    critic_score: float | None = None
+    confidence: float = 0.0
+    rationale: str = ""
+
+
+class DecisionTreeBuilder:
+    """Build DecisionRecords from events in a run."""
+
+    def build_from_events(self, run_id: str, events_dir: str) -> list[DecisionRecord]:
+        """Parse events from events_dir for this run_id and build one DecisionRecord per task."""
+        import os
+        import json
+        from pathlib import Path
+        records: list[DecisionRecord] = []
+        path = Path(events_dir)
+        if not path.is_dir():
+            return records
+        event_files = list(path.glob("*.jsonl"))
+        if run_id:
+            exact = path / f"{run_id}.jsonl"
+            if exact.is_file():
+                event_files = [exact]
+            else:
+                event_files = [f for f in event_files if run_id in f.stem or run_id in f.name]
+        events: list[dict] = []
+        for f in event_files:
+            try:
+                with open(f, "r", encoding="utf-8") as fp:
+                    for line in fp:
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            events.append(json.loads(line))
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+        task_ids = set()
+        for ev in events:
+            payload = ev.get("payload") or ev if isinstance(ev.get("payload"), dict) else {}
+            tid = payload.get("task_id") or ev.get("task_id")
+            if tid:
+                task_ids.add(tid)
+        for tid in sorted(task_ids):
+            task_events = [e for e in events if (e.get("payload") or {}).get("task_id") == tid or e.get("task_id") == tid]
+            model = ""
+            tier = ""
+            tools: list[str] = []
+            for e in task_events:
+                p = e.get("payload") or {}
+                if e.get("type") == "task_model_selected" or p.get("model"):
+                    model = p.get("model") or model
+                    tier = p.get("tier") or tier
+                if e.get("type") == "tool_called" or p.get("tool"):
+                    t = p.get("tool")
+                    if t and t not in tools:
+                        tools.append(t)
+            desc = next((p.get("description") for e in task_events for p in [e.get("payload") or {}] if p.get("description")), tid)
+            rec = DecisionRecord(
+                task_id=tid,
+                task_description=desc or tid,
+                strategy_selected=tier or "default",
+                strategy_reason="from events",
+                tools_considered=[],
+                tools_selected=tools,
+                model_tier=tier or "default",
+                model_selected=model or "unknown",
+                model_reason="from events",
+                memory_records_used=0,
+                kg_context_injected=False,
+                critic_score=None,
+                confidence=0.8,
+                rationale=f"Task classified as {tier or 'default'}. Selected {len(tools)} tools ({', '.join(tools)}). Used {model or 'unknown'} ({tier or 'default'} tier). Confidence: 80%.",
+            )
+            records.append(rec)
+        return records

devsper/explainability/rationale.py

@@ -0,0 +1,38 @@
+"""Rationale generation (LLM or template) for decision records."""
+
+from devsper.explainability.decision_tree import DecisionRecord
+
+
+class RationaleGenerator:
+    """Generate NL explanation for a DecisionRecord. Cached per task."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, str] = {}
+
+    async def generate(self, record: DecisionRecord, model: str = "mock") -> str:
+        """Use LLM to generate one-paragraph explanation. Cached per task_id."""
+        if record.task_id in self._cache:
+            return self._cache[record.task_id]
+        try:
+            from devsper.utils.models import generate
+            prompt = (
+                f"Explain in one short paragraph why this AI task was executed this way.\n"
+                f"Task: {record.task_description}\n"
+                f"Strategy: {record.strategy_selected}. Model: {record.model_selected}. "
+                f"Tools used: {', '.join(record.tools_selected)}. Confidence: {record.confidence:.0%}.\n"
+                f"Write 2-3 sentences only."
+            )
+            out = generate(model, prompt)
+            self._cache[record.task_id] = out or ""
+            return out or self.template_rationale(record)
+        except Exception:
+            return self.template_rationale(record)
+
+    def template_rationale(self, record: DecisionRecord) -> str:
+        """Template-based fallback (no LLM)."""
+        return (
+            f"Task classified as {record.strategy_selected}. "
+            f"Selected {len(record.tools_selected)} tools ({', '.join(record.tools_selected) or 'none'}). "
+            f"Used {record.model_selected} ({record.model_tier} tier). "
+            f"Confidence: {record.confidence:.0%}."
+        )

devsper/explainability/simulation.py

@@ -0,0 +1,56 @@
+"""Simulation mode: dry-run planning and scheduling without LLM or tool execution."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SimulationReport:
+    task_list: list[str] = field(default_factory=list)
+    estimated_cost: str = "N/A"
+    estimated_duration: str = "N/A"
+    tool_usage_plan: list[str] = field(default_factory=list)
+    model_tier_breakdown: dict = field(default_factory=dict)
+
+
+class SimulationMode:
+    """Dry-run: run planner and scheduler, build DecisionRecords, no LLM or tools."""
+
+    async def simulate(self, root_task: str) -> SimulationReport:
+        """Run planning and scheduling only; return SimulationReport."""
+        from devsper.swarm.planner import Planner
+        from devsper.swarm.scheduler import Scheduler
+        from devsper.types.task import Task, TaskStatus
+        from devsper.explainability.decision_tree import DecisionTreeBuilder, DecisionRecord
+        from devsper.explainability.rationale import RationaleGenerator
+        planner = Planner(model_name="mock", event_log=None)
+        tasks = planner.plan(root_task)
+        if not tasks:
+            tasks = [Task(id="1", description=root_task, status=TaskStatus.PENDING)]
+        scheduler = Scheduler()
+        for t in tasks:
+            scheduler.add_task(t)
+        task_list = [t.description or t.id for t in scheduler.get_all_tasks()]
+        records: list[DecisionRecord] = []
+        gen = RationaleGenerator()
+        for t in scheduler.get_all_tasks():
+            rec = DecisionRecord(
+                task_id=t.id,
+                task_description=t.description or t.id,
+                strategy_selected="default",
+                strategy_reason="simulation",
+                tools_selected=[],
+                model_tier="default",
+                model_selected="mock",
+                model_reason="simulation",
+                confidence=0.5,
+                rationale="",
+            )
+            rec.rationale = gen.template_rationale(rec)
+            records.append(rec)
+        return SimulationReport(
+            task_list=task_list,
+            estimated_cost="N/A",
+            estimated_duration="N/A",
+            tool_usage_plan=[],
+            model_tier_breakdown={"default": len(task_list)},
+        )

devsper/hitl/__init__.py

@@ -0,0 +1,13 @@
+"""Human-in-the-Loop: escalation triggers, approval requests, and notification."""
+
+from devsper.hitl.escalation import EscalationChecker, EscalationPolicy, EscalationTrigger
+from devsper.hitl.approval import ApprovalRequest, ApprovalStore, ApprovalNotifier
+
+__all__ = [
+    "ApprovalNotifier",
+    "ApprovalRequest",
+    "ApprovalStore",
+    "EscalationChecker",
+    "EscalationPolicy",
+    "EscalationTrigger",
+]

devsper/hitl/approval.py

@@ -0,0 +1,160 @@
+"""
+Approval store and notifier: persist pending approvals, notify approvers, resolve (approve/reject).
+"""
+
+import json
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Literal
+
+from devsper.hitl.escalation import EscalationPolicy, EscalationTrigger
+
+
+@dataclass
+class ApprovalRequest:
+    request_id: str
+    task: object  # Task
+    proposed_result: str
+    decision_record: object | None  # DecisionRecord
+    trigger: EscalationTrigger
+    created_at: str
+    expires_at: str
+    status: Literal["pending", "approved", "rejected", "timeout"] = "pending"
+    reviewer_notes: str | None = None
+
+    def to_dict(self) -> dict:
+        task = self.task
+        task_dict = getattr(task, "to_dict", lambda: {"id": getattr(task, "id", ""), "description": getattr(task, "description", "")})()
+        dr = self.decision_record
+        dr_dict = None
+        if dr is not None and hasattr(dr, "__dict__"):
+            dr_dict = {"task_id": getattr(dr, "task_id", ""), "critic_score": getattr(dr, "critic_score", None), "confidence": getattr(dr, "confidence", 0)}
+        return {
+            "request_id": self.request_id,
+            "task": task_dict,
+            "proposed_result": self.proposed_result,
+            "decision_record": dr_dict,
+            "trigger": {"type": self.trigger.type, "threshold": self.trigger.threshold},
+            "created_at": self.created_at,
+            "expires_at": self.expires_at,
+            "status": self.status,
+            "reviewer_notes": self.reviewer_notes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ApprovalRequest":
+        from devsper.types.task import Task
+        task_data = data.get("task") or {}
+        task = Task.from_dict(task_data) if isinstance(task_data, dict) else task_data
+        tr = data.get("trigger") or {}
+        trigger = EscalationTrigger(type=tr.get("type", "confidence_below"), threshold=tr.get("threshold", 0.5))
+        return cls(
+            request_id=data.get("request_id", ""),
+            task=task,
+            proposed_result=data.get("proposed_result", ""),
+            decision_record=data.get("decision_record"),
+            trigger=trigger,
+            created_at=data.get("created_at", ""),
+            expires_at=data.get("expires_at", ""),
+            status=data.get("status", "pending"),
+            reviewer_notes=data.get("reviewer_notes"),
+        )
+
+
+class ApprovalStore:
+    """Persist pending approvals under {data_dir}/approvals/{request_id}.json."""
+
+    def __init__(self, data_dir: str = ".devsper") -> None:
+        self.data_dir = data_dir
+        self._approvals_dir = os.path.join(data_dir, "approvals")
+        os.makedirs(self._approvals_dir, exist_ok=True)
+
+    def _path(self, request_id: str) -> str:
+        return os.path.join(self._approvals_dir, f"{request_id}.json")
+
+    def list_pending(self) -> list[ApprovalRequest]:
+        """Return all pending approval requests."""
+        out: list[ApprovalRequest] = []
+        for name in os.listdir(self._approvals_dir):
+            if name.endswith(".json"):
+                rid = name[:-5]
+                req = self.get(rid)
+                if req is not None and req.status == "pending":
+                    out.append(req)
+        return out
+
+    def get(self, request_id: str) -> ApprovalRequest | None:
+        """Load one request by id."""
+        path = self._path(request_id)
+        if not os.path.isfile(path):
+            return None
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                return ApprovalRequest.from_dict(json.load(f))
+        except Exception:
+            return None
+
+    def save(self, request: ApprovalRequest) -> None:
+        """Write request to disk."""
+        path = self._path(request.request_id)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(request.to_dict(), f, indent=0)
+
+    def resolve(self, request_id: str, approved: bool, notes: str = "") -> None:
+        """Mark request approved or rejected and save."""
+        req = self.get(request_id)
+        if req is None:
+            return
+        req.status = "approved" if approved else "rejected"
+        req.reviewer_notes = notes or req.reviewer_notes
+        self.save(req)
+
+
+class ApprovalNotifier:
+    """Send approval requests via configured channels (webhook, slack, email)."""
+
+    async def notify(self, request: ApprovalRequest, policy: EscalationPolicy) -> None:
+        """For each approver in policy.approvers, parse scheme and dispatch."""
+        for approver in policy.approvers or []:
+            if approver.startswith("webhook://"):
+                await self._notify_webhook(request, approver[10:].strip())
+            elif approver.startswith("slack://"):
+                await self._notify_slack(request, approver[8:].strip())
+            elif approver.startswith("email://"):
+                self._notify_email(request, approver[8:].strip())
+
+    async def _notify_webhook(self, request: ApprovalRequest, url: str) -> None:
+        try:
+            import httpx
+            async with httpx.AsyncClient() as client:
+                await client.post(url, json=request.to_dict(), timeout=10.0)
+        except Exception as e:
+            import sys
+            print(f"[hitl] webhook notification failed: {e}", file=sys.stderr)
+
+    async def _notify_slack(self, request: ApprovalRequest, webhook_or_channel: str) -> None:
+        try:
+            import httpx
+            payload = {
+                "text": f"Approval requested: {getattr(request.task, 'description', '')[:200]}...",
+                "blocks": [
+                    {"type": "section", "text": {"type": "mrkdwn", "text": f"*Task:* {getattr(request.task, 'description', '')[:300]}"}},
+                    {"type": "section", "text": {"type": "mrkdwn", "text": f"*Request ID:* `{request.request_id}`"}},
+                ],
+            }
+            if webhook_or_channel.startswith("http"):
+                async with httpx.AsyncClient() as client:
+                    await client.post(webhook_or_channel, json=payload, timeout=10.0)
+            else:
+                import sys
+                print("[hitl] slack:// URL must be webhook URL (https://hooks.slack.com/...)", file=sys.stderr)
+        except Exception as e:
+            import sys
+            print(f"[hitl] slack notification failed: {e}", file=sys.stderr)
+
+    def _notify_email(self, request: ApprovalRequest, _address: str) -> None:
+        import sys
+        print("[hitl] email notifications require external SMTP config; printing to stdout", file=sys.stderr)
+        print(f"Approval requested: request_id={request.request_id} task={getattr(request.task, 'description', '')[:100]}")

devsper/hitl/escalation.py

@@ -0,0 +1,95 @@
+"""
+Escalation policies and triggers: when to send a task for human approval.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+# Avoid circular import; Task, AgentResponse, DecisionRecord used at runtime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from devsper.types.task import Task
+    from devsper.agents.agent import AgentResponse
+    from devsper.explainability.decision_tree import DecisionRecord
+
+
+EscalationTriggerType = Literal[
+    "confidence_below",
+    "cost_above",
+    "tool_category",
+    "keyword_match",
+    "critic_score_below",
+    "sla_at_risk",
+]
+
+
+@dataclass
+class EscalationTrigger:
+    type: EscalationTriggerType
+    threshold: float | str  # number for numeric triggers, string for keyword/category
+
+
+@dataclass
+class EscalationPolicy:
+    triggers: list[EscalationTrigger]
+    approvers: list[str]  # email://, slack://, webhook://
+    timeout_seconds: int = 3600
+    on_timeout: Literal["auto_approve", "auto_reject", "escalate_further"] = "auto_approve"
+
+
+class EscalationChecker:
+    """Evaluate task + response + decision against configured triggers; return first match or None."""
+
+    def __init__(self, policies: list[EscalationPolicy]) -> None:
+        self.policies = policies
+        self._triggers: list[tuple[EscalationTrigger, EscalationPolicy]] = []
+        for p in policies:
+            for t in p.triggers:
+                self._triggers.append((t, p))
+
+    def evaluate(
+        self,
+        task: "Task",
+        response: "AgentResponse",
+        decision: "DecisionRecord | None",
+    ) -> tuple[EscalationTrigger, EscalationPolicy] | None:
+        """Check all configured triggers. Return first (trigger, policy) match or None."""
+        for trigger, policy in self._triggers:
+            if self._matches(trigger, task, response, decision):
+                return (trigger, policy)
+        return None
+
+    def _matches(
+        self,
+        trigger: EscalationTrigger,
+        task: "Task",
+        response: "AgentResponse",
+        decision: "DecisionRecord | None",
+    ) -> bool:
+        t = trigger.type
+        th = trigger.threshold
+        if t == "confidence_below" and decision is not None:
+            return (decision.confidence or 0) < float(th)
+        if t == "cost_above":
+            # Approximate cost from tokens if available
+            cost = 0.0
+            if getattr(response, "tokens_used", None):
+                cost = (response.tokens_used or 0) * 1e-6  # rough
+            return cost > float(th)
+        if t == "tool_category":
+            tools = getattr(response, "tools_called", []) or []
+            # Compare category names if we had a category; use tool names as proxy
+            return isinstance(th, str) and th.lower() in [str(x).lower() for x in tools]
+        if t == "keyword_match" and isinstance(th, str):
+            text = (task.description or "") + " " + (response.result or "")
+            return th.lower() in text.lower()
+        if t == "critic_score_below" and decision is not None:
+            score = decision.critic_score
+            if score is not None:
+                return score < float(th)
+            return False
+        if t == "sla_at_risk":
+            # Would need SLA context; treat as no match if not applicable
+            return False
+        return False

devsper/intelligence/__init__.py

@@ -0,0 +1,9 @@
+"""
+Swarm intelligence: task optimization, strategy selection, learning from runs.
+"""
+
+from devsper.intelligence.task_optimizer import TaskOptimizer
+from devsper.intelligence.strategy_selector import StrategySelector
+from devsper.intelligence.learning_engine import LearningEngine
+
+__all__ = ["TaskOptimizer", "StrategySelector", "LearningEngine"]