feed-the-machine 1.6.1 → 1.7.0

package/bin/playbook_engine/__init__.py

@@ -0,0 +1 @@
+# playbook_engine - Reusable workflow playbooks for eng-buddy

package/bin/playbook_engine/conftest.py

@@ -0,0 +1,8 @@
+"""Configure sys.path so tests can run from project root or module directory."""
+import sys
+from pathlib import Path
+
+# Add playbook_engine directory to sys.path so `from models import ...` works
+_this_dir = Path(__file__).parent
+if str(_this_dir) not in sys.path:
+    sys.path.insert(0, str(_this_dir))

package/bin/playbook_engine/extractor.py

@@ -0,0 +1,33 @@
+"""PlaybookExtractor - extracts playbooks from completed traces."""
+
+from .models import Playbook, PlaybookStep
+from .registry import ToolRegistry
+from .tracer import Trace
+
+
+class PlaybookExtractor:
+    """Extracts a draft playbook from a workflow trace."""
+
+    def __init__(self, registry: ToolRegistry):
+        self.registry = registry
+
+    def extract_from_trace(self, trace: Trace, name: str = "Untitled") -> Playbook:
+        steps = []
+        for i, event in enumerate(trace.events, 1):
+            step = PlaybookStep(
+                number=i,
+                description=event.human_instruction or event.action or f"Step {i}",
+                tool=event.tool,
+                tool_params=event.params,
+                requires_human=bool(event.correction),
+                notes=event.correction or "",
+            )
+            steps.append(step)
+
+        return Playbook(
+            name=name,
+            description=f"Extracted from trace {trace.id}",
+            steps=steps,
+            source="extracted",
+            confidence=0.7,  # draft confidence
+        )

package/bin/playbook_engine/manager.py

@@ -0,0 +1,102 @@
+"""PlaybookManager - CRUD and matching for playbooks."""
+
+import json
+import os
+from typing import List, Optional
+
+from .models import Playbook
+
+
+class PlaybookManager:
+    """Manages approved and draft playbooks on disk as JSON files."""
+
+    def __init__(self, playbooks_dir: str):
+        self.playbooks_dir = playbooks_dir
+        self.approved_dir = playbooks_dir  # approved live at root
+        self.drafts_dir = os.path.join(playbooks_dir, "drafts")
+        self.archive_dir = os.path.join(playbooks_dir, "archive")
+        os.makedirs(self.approved_dir, exist_ok=True)
+        os.makedirs(self.drafts_dir, exist_ok=True)
+        os.makedirs(self.archive_dir, exist_ok=True)
+
+    # --- Read ---
+
+    def _load_from_dir(self, directory: str) -> List[Playbook]:
+        playbooks = []
+        for f in sorted(os.listdir(directory)):
+            if not f.endswith(".json"):
+                continue
+            path = os.path.join(directory, f)
+            try:
+                with open(path) as fh:
+                    playbooks.append(Playbook.from_dict(json.load(fh)))
+            except (json.JSONDecodeError, KeyError):
+                continue
+        return playbooks
+
+    def list_playbooks(self) -> List[Playbook]:
+        return self._load_from_dir(self.approved_dir)
+
+    def list_drafts(self) -> List[Playbook]:
+        return self._load_from_dir(self.drafts_dir)
+
+    def get(self, playbook_id: str) -> Optional[Playbook]:
+        for pb in self.list_playbooks():
+            if pb.id == playbook_id:
+                return pb
+        return None
+
+    def get_draft(self, playbook_id: str) -> Optional[Playbook]:
+        for pb in self.list_drafts():
+            if pb.id == playbook_id:
+                return pb
+        return None
+
+    # --- Write ---
+
+    def _save(self, pb: Playbook, directory: str) -> str:
+        path = os.path.join(directory, f"{pb.id}.json")
+        with open(path, "w") as fh:
+            json.dump(pb.to_dict(), fh, indent=2)
+        return path
+
+    def save_playbook(self, pb: Playbook) -> str:
+        return self._save(pb, self.approved_dir)
+
+    def save_draft(self, pb: Playbook) -> str:
+        return self._save(pb, self.drafts_dir)
+
+    def promote_draft(self, playbook_id: str) -> Optional[Playbook]:
+        pb = self.get_draft(playbook_id)
+        if not pb:
+            return None
+        # Move from drafts to approved
+        draft_path = os.path.join(self.drafts_dir, f"{pb.id}.json")
+        self.save_playbook(pb)
+        if os.path.exists(draft_path):
+            os.remove(draft_path)
+        return pb
+
+    def delete_draft(self, playbook_id: str) -> bool:
+        path = os.path.join(self.drafts_dir, f"{playbook_id}.json")
+        if os.path.exists(path):
+            os.remove(path)
+            return True
+        return False
+
+    # --- Matching ---
+
+    def match_ticket(self, ticket_type: str = "", text: str = "", source: str = "") -> List[Playbook]:
+        """Find playbooks whose trigger_keywords match the given text."""
+        text_lower = text.lower()
+        matches = []
+        for pb in self.list_playbooks():
+            score = 0
+            for kw in pb.trigger_keywords:
+                if kw.lower() in text_lower:
+                    score += 1
+            if score > 0:
+                # Temporarily set confidence based on keyword hit ratio
+                pb.confidence = round(score / max(len(pb.trigger_keywords), 1), 2)
+                matches.append(pb)
+        return sorted(matches, key=lambda p: p.confidence, reverse=True)

package/bin/playbook_engine/models.py

@@ -0,0 +1,84 @@
+"""Core data models for playbooks."""
+
+import uuid
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class PlaybookStep:
+    """A single step in a playbook."""
+    number: int
+    description: str
+    tool: str = ""  # e.g. "browser", "freshservice-api", "manual"
+    tool_params: dict = field(default_factory=dict)
+    requires_human: bool = False
+    notes: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "number": self.number,
+            "description": self.description,
+            "tool": self.tool,
+            "tool_params": self.tool_params,
+            "requires_human": self.requires_human,
+            "notes": self.notes,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PlaybookStep":
+        return cls(
+            number=d["number"],
+            description=d["description"],
+            tool=d.get("tool", ""),
+            tool_params=d.get("tool_params", {}),
+            requires_human=d.get("requires_human", False),
+            notes=d.get("notes", ""),
+        )
+
+
+@dataclass
+class Playbook:
+    """A reusable workflow playbook."""
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    name: str = ""
+    description: str = ""
+    trigger_keywords: List[str] = field(default_factory=list)
+    steps: List[PlaybookStep] = field(default_factory=list)
+    confidence: float = 1.0
+    version: int = 1
+    executions: int = 0
+    source: str = "manual"  # "manual", "extracted", "observed"
+    runbook_path: str = ""  # link to full runbook doc
+    related_links: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "trigger_keywords": self.trigger_keywords,
+            "steps": [s.to_dict() for s in self.steps],
+            "confidence": self.confidence,
+            "version": self.version,
+            "executions": self.executions,
+            "source": self.source,
+            "runbook_path": self.runbook_path,
+            "related_links": self.related_links,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Playbook":
+        return cls(
+            id=d["id"],
+            name=d.get("name", ""),
+            description=d.get("description", ""),
+            trigger_keywords=d.get("trigger_keywords", []),
+            steps=[PlaybookStep.from_dict(s) for s in d.get("steps", [])],
+            confidence=d.get("confidence", 1.0),
+            version=d.get("version", 1),
+            executions=d.get("executions", 0),
+            source=d.get("source", "manual"),
+            runbook_path=d.get("runbook_path", ""),
+            related_links=d.get("related_links", {}),
+        )

package/bin/playbook_engine/registry.py

@@ -0,0 +1,35 @@
+"""ToolRegistry - maps tools to their capabilities and defaults."""
+
+import json
+import os
+from typing import Optional
+
+
+class ToolRegistry:
+    """Loads tool definitions from the registry directory."""
+
+    def __init__(self, registry_dir: str):
+        self.registry_dir = registry_dir
+        self._tools: dict = {}
+        self._load()
+
+    def _load(self):
+        if not os.path.exists(self.registry_dir):
+            return
+        for f in os.listdir(self.registry_dir):
+            if not f.endswith(".json"):
+                continue
+            path = os.path.join(self.registry_dir, f)
+            try:
+                with open(path) as fh:
+                    data = json.load(fh)
+                    tool_name = data.get("name", f.replace(".json", ""))
+                    self._tools[tool_name] = data
+            except (json.JSONDecodeError, KeyError):
+                continue
+
+    def get_tool(self, name: str) -> Optional[dict]:
+        return self._tools.get(name)
+
+    def list_tools(self) -> list:
+        return list(self._tools.keys())

package/bin/playbook_engine/test_extractor.py

@@ -0,0 +1,72 @@
+import pytest
+import tempfile
+import yaml
+from tracer import WorkflowTracer, TraceEvent
+from registry import ToolRegistry
+from extractor import PlaybookExtractor
+from models import Playbook
+
+def make_registry(tmp_path):
+    reg_dir = tmp_path / "tool-registry"
+    reg_dir.mkdir()
+    (reg_dir / "_registry.yml").write_text(yaml.dump({
+        "tools": {
+            "jira": {"type": "mcp", "prefix": "mcp__mcp-atlassian__jira_", "capabilities": ["create_issue"], "auth": "persistent", "domains": ["ticket_management"]},
+            "slack": {"type": "mcp", "prefix": "mcp__slack__", "capabilities": ["post_message"], "auth": "persistent", "domains": ["communication"]},
+            "freshservice": {"type": "mcp", "prefix": "mcp__freshservice-mcp__", "capabilities": ["update_ticket"], "auth": "persistent", "domains": ["service_desk"]},
+        }
+    }))
+    (reg_dir / "jira.defaults.yml").write_text(yaml.dump({"create_issue": {"assignee": "test@test.com"}}))
+    return ToolRegistry(str(reg_dir))
+
+def test_extract_playbook_from_trace(tmp_path):
+    registry = make_registry(tmp_path)
+    tracer = WorkflowTracer(traces_dir=str(tmp_path / "traces"))
+
+    tracer.start_trace("ITWORK2-100")
+    tracer.add_event(TraceEvent(type="user_instruction", content="Do SSO onboarding for Linear"))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__mcp-atlassian__jira_create_issue", params={"project": "ITWORK2", "summary": "[SSO] Linear"}))
+    tracer.add_event(TraceEvent(type="user_manual_action", content="Configured SAML in Okta", inferred_step="Configure SAML", action_binding="playwright", auth_note="needs Okta admin"))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__slack__post_message", params={"channel": "C123", "text": "SSO configured"}))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__freshservice-mcp__update_ticket", params={"ticket_id": 456, "status": "resolved"}))
+
+    extractor = PlaybookExtractor(registry=registry)
+    pb = extractor.extract_from_trace(tracer.get_trace("ITWORK2-100"), name="SSO Onboarding")
+
+    assert pb.id == "sso-onboarding"
+    assert pb.confidence == "low"
+    assert pb.created_from == "session"
+    assert len(pb.steps) == 4  # jira + manual + slack + freshservice
+    assert pb.steps[0].action.tool == "mcp__mcp-atlassian__jira_create_issue"
+    assert pb.steps[1].human_required is True  # manual action
+    assert pb.steps[1].action.tool == "playwright"
+
+def test_extract_identifies_dynamic_params(tmp_path):
+    registry = make_registry(tmp_path)
+    tracer = WorkflowTracer(traces_dir=str(tmp_path / "traces"))
+
+    tracer.start_trace("t1")
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__mcp-atlassian__jira_create_issue", params={"project": "ITWORK2", "summary": "[SSO] Linear", "assignee": "test@test.com"}))
+
+    extractor = PlaybookExtractor(registry=registry)
+    pb = extractor.extract_from_trace(tracer.get_trace("t1"), name="Test")
+
+    # assignee matches default, so should NOT be in playbook params (it comes from defaults)
+    # summary is ticket-specific, so should be a param with a source
+    step = pb.steps[0]
+    assert "assignee" not in step.action.params  # comes from defaults
+    assert "summary" in step.action.params or "summary" in step.action.param_sources
+
+def test_extract_captures_user_rules(tmp_path):
+    registry = make_registry(tmp_path)
+    tracer = WorkflowTracer(traces_dir=str(tmp_path / "traces"))
+
+    tracer.start_trace("t1")
+    tracer.add_event(TraceEvent(type="user_rule", content="Always add SSO label", applies_to=["jira.create_issue"], persist=True))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__mcp-atlassian__jira_create_issue", params={"project": "ITWORK2"}))
+
+    extractor = PlaybookExtractor(registry=registry)
+    pb = extractor.extract_from_trace(tracer.get_trace("t1"), name="Test")
+    assert pb is not None
+    # The extractor should note persistent rules for default updates
+    assert len(extractor.pending_default_updates) > 0

package/bin/playbook_engine/test_integration.py

@@ -0,0 +1,129 @@
+"""End-to-end test: trace capture -> extraction -> storage -> matching -> execution dispatch."""
+
+import pytest
+import yaml
+import tempfile
+import json
+from tracer import WorkflowTracer, TraceEvent
+from registry import ToolRegistry
+from extractor import PlaybookExtractor
+from manager import PlaybookManager
+from models import Playbook
+
+@pytest.fixture
+def env(tmp_path):
+    """Set up a complete playbook environment."""
+    playbooks_dir = tmp_path / "playbooks"
+    playbooks_dir.mkdir()
+    (playbooks_dir / "drafts").mkdir()
+    (playbooks_dir / "archive").mkdir()
+
+    reg_dir = playbooks_dir / "tool-registry"
+    reg_dir.mkdir()
+    (reg_dir / "_registry.yml").write_text(yaml.dump({
+        "tools": {
+            "jira": {"type": "mcp", "prefix": "mcp__mcp-atlassian__jira_", "capabilities": ["create_issue", "transition_issue"], "auth": "persistent", "domains": ["ticket_management"]},
+            "slack": {"type": "mcp", "prefix": "mcp__slack__", "capabilities": ["post_message"], "auth": "persistent", "domains": ["communication"]},
+            "freshservice": {"type": "mcp", "prefix": "mcp__freshservice-mcp__", "capabilities": ["update_ticket"], "auth": "persistent", "domains": ["service_desk"]},
+            "playwright_cli": {"type": "browser", "tool": "playwright_cli", "capabilities": ["navigate", "click", "fill", "snapshot", "eval"], "auth": "per_domain", "domains": ["standard_web_ui"]},
+        }
+    }))
+    (reg_dir / "jira.defaults.yml").write_text(yaml.dump({
+        "create_issue": {"assignee": "kioja@test.com", "board_id": 70},
+    }))
+
+    traces_dir = tmp_path / "traces"
+    return {
+        "playbooks_dir": str(playbooks_dir),
+        "traces_dir": str(traces_dir),
+        "registry_dir": str(reg_dir),
+    }
+
+def test_full_flow(env):
+    """Simulate: work SSO ticket -> extract playbook -> match new ticket -> dispatch."""
+
+    # 1. Capture a workflow trace
+    tracer = WorkflowTracer(traces_dir=env["traces_dir"])
+    tracer.start_trace("ITWORK2-100")
+
+    tracer.add_event(TraceEvent(type="user_instruction", content="Do SSO onboarding for Linear"))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__mcp-atlassian__jira_create_issue",
+        params={"project": "ITWORK2", "summary": "[SSO] Linear", "assignee": "kioja@test.com", "board_id": 70}))
+    tracer.add_event(TraceEvent(type="user_manual_action", content="Configured SAML in Okta",
+        inferred_step="Configure SAML in IdP", action_binding="playwright", auth_note="Okta admin"))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__slack__post_message",
+        params={"channel": "C123", "text": "SSO ready for Linear"}))
+    tracer.add_event(TraceEvent(type="tool_call", tool="mcp__freshservice-mcp__update_ticket",
+        params={"ticket_id": 456, "status": 5}))
+    tracer.flush("ITWORK2-100")
+
+    # 2. Extract a playbook
+    registry = ToolRegistry(env["registry_dir"])
+    extractor = PlaybookExtractor(registry=registry)
+    trace = tracer.get_trace("ITWORK2-100")
+    pb = extractor.extract_from_trace(trace, name="SSO Onboarding")
+
+    assert pb.id == "sso-onboarding"
+    assert pb.confidence == "low"
+    assert len(pb.steps) == 4
+    assert pb.steps[1].human_required is True  # manual SAML config
+
+    # 3. Save as draft, review, promote
+    manager = PlaybookManager(env["playbooks_dir"])
+    manager.save_draft(pb)
+    assert len(manager.list_drafts()) == 1
+
+    manager.promote_draft("sso-onboarding")
+    assert len(manager.list_drafts()) == 0
+    assert len(manager.list_playbooks()) == 1
+
+    # 4. Match against a new ticket
+    matches = manager.match_ticket(
+        ticket_type="Service Request",
+        text="Please set up SSO for Notion",
+        source="freshservice",
+    )
+    assert len(matches) == 1
+    assert matches[0].id == "sso-onboarding"
+
+    # 5. Record execution and check confidence progression
+    promoted = manager.get("sso-onboarding")
+    promoted.record_execution(success=True)
+    assert promoted.confidence == "medium"
+    assert promoted.executions == 1
+    manager.save(promoted)
+
+    # Verify persistence
+    reloaded = manager.get("sso-onboarding")
+    assert reloaded.confidence == "medium"
+    assert reloaded.executions == 1
+
+def test_no_match_returns_empty(env):
+    manager = PlaybookManager(env["playbooks_dir"])
+    matches = manager.match_ticket(text="New laptop request", source="freshservice")
+    assert matches == []
+
+def test_dictated_playbook_flow(env):
+    """Path 2: User describes steps, engine creates playbook."""
+    registry = ToolRegistry(env["registry_dir"])
+    extractor = PlaybookExtractor(registry=registry)
+
+    pb = extractor.extract_from_description(
+        name="Employee Offboarding",
+        steps_text=[
+            "Disable user account in Okta",
+            "Remove from all Slack channels",
+            "Archive Jira tickets",
+            "Send confirmation email to manager",
+        ],
+    )
+
+    assert pb.id == "employee-offboarding"
+    assert pb.confidence == "medium"  # dictated starts at medium
+    assert len(pb.steps) == 4
+    assert pb.created_from == "dictated"
+
+    manager = PlaybookManager(env["playbooks_dir"])
+    manager.save(pb)
+    loaded = manager.get("employee-offboarding")
+    assert loaded is not None

package/bin/playbook_engine/test_manager.py

@@ -0,0 +1,85 @@
+import pytest
+import tempfile
+import os
+from manager import PlaybookManager
+from models import Playbook, PlaybookStep, ActionBinding, TriggerPattern
+
+def make_playbook(id="test", name="Test", confidence="high", keywords=None, steps=None):
+    return Playbook(
+        id=id, name=name, version=1, confidence=confidence,
+        trigger_patterns=[TriggerPattern(keywords=keywords or ["SSO"], source=["freshservice"])],
+        created_from="session", executions=3,
+        steps=steps or [],
+    )
+
+def test_save_and_load(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    pb = make_playbook()
+    mgr.save(pb)
+    loaded = mgr.get("test")
+    assert loaded.id == "test"
+    assert loaded.confidence == "high"
+
+def test_list_playbooks(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    mgr.save(make_playbook(id="a", name="A"))
+    mgr.save(make_playbook(id="b", name="B"))
+    pbs = mgr.list_playbooks()
+    assert len(pbs) == 2
+    assert {p.id for p in pbs} == {"a", "b"}
+
+def test_match_ticket(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    mgr.save(make_playbook(id="sso", keywords=["SSO", "SAML"]))
+    mgr.save(make_playbook(id="cert", keywords=["certificate", "renewal"]))
+    matches = mgr.match_ticket(ticket_type="Service Request", text="Set up SSO for Linear", source="freshservice")
+    assert len(matches) == 1
+    assert matches[0].id == "sso"
+
+def test_save_draft(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    pb = make_playbook(id="draft-test", confidence="low")
+    mgr.save_draft(pb)
+    drafts = mgr.list_drafts()
+    assert len(drafts) == 1
+    assert drafts[0].id == "draft-test"
+
+def test_promote_draft(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    pb = make_playbook(id="promote-test", confidence="low")
+    mgr.save_draft(pb)
+    mgr.promote_draft("promote-test")
+    assert mgr.get("promote-test") is not None
+    assert len(mgr.list_drafts()) == 0
+
+def test_archive_version(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    pb = make_playbook(id="versioned", confidence="high")
+    mgr.save(pb)
+    pb.version = 2
+    pb.update_history.append({"version": 2, "reason": "added step"})
+    mgr.save(pb, archive_previous=True)
+    loaded = mgr.get("versioned")
+    assert loaded.version == 2
+    archives = mgr.list_archive("versioned")
+    assert len(archives) == 1
+
+def test_invalid_playbook_id_rejected(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    import pytest
+    with pytest.raises(ValueError):
+        mgr.get("../../../etc/passwd")
+    with pytest.raises(ValueError):
+        mgr.get("UPPER_CASE")
+    with pytest.raises(ValueError):
+        mgr.get("")
+    with pytest.raises(ValueError):
+        mgr.delete_draft("../../bad")
+
+def test_delete_nonexistent_draft(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    assert mgr.delete_draft("nonexistent") is False
+
+def test_promote_nonexistent_draft(tmp_path):
+    mgr = PlaybookManager(str(tmp_path))
+    assert mgr.promote_draft("nonexistent") is None