devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/core/video/tts_engine.py

@@ -0,0 +1,82 @@
+"""
+TTS engine — wraps OpenAI Text-to-Speech API for narration generation.
+Generates .mp3 audio files from narration text, one per tutorial step.
+"""
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from openai import AsyncOpenAI
+
+logger = logging.getLogger(__name__)
+
+
+def _require_openai() -> "type[AsyncOpenAI]":
+    """Import `openai` lazily so non-video users don't pay for the dep.
+
+    Vox-related deps (`openai`, `playwright`, `pyautogui`) live in the
+    optional `[video]` extra. Importing this module is cheap; only
+    instantiating `TTSEngine` requires `openai` to be installed.
+    """
+    try:
+        from openai import AsyncOpenAI as _AsyncOpenAI
+
+        return _AsyncOpenAI
+    except ImportError as e:
+        raise ImportError(
+            "TTSEngine requires the `openai` package. Install the optional "
+            "video extra: `pip install 'devrel-origin[video]'` (or `pipx "
+            "install 'devrel-origin[video]'`)."
+        ) from e
+
+
+DEFAULT_MODEL = "tts-1"
+DEFAULT_VOICE = "alloy"
+WORDS_PER_MINUTE = 150
+
+
+class TTSEngine:
+    """Generates narration audio using OpenAI TTS API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        output_dir: Path,
+        model: str = DEFAULT_MODEL,
+        voice: str = DEFAULT_VOICE,
+    ):
+        self._client = _require_openai()(api_key=api_key)
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.model = model
+        self.default_voice = voice
+
+    async def generate_audio(
+        self, text: str, filename_prefix: str, voice: Optional[str] = None
+    ) -> Path:
+        output_path = self.output_dir / f"{filename_prefix}.mp3"
+        selected_voice = voice or self.default_voice
+        logger.info(
+            f"Generating TTS audio: {filename_prefix} ({len(text)} chars, voice={selected_voice})"
+        )
+        response = await self._client.audio.speech.create(
+            model=self.model, voice=selected_voice, input=text
+        )
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None,
+            response.stream_to_file,
+            str(output_path),
+        )
+        logger.info(f"TTS audio saved to {output_path}")
+        return output_path
+
+    @staticmethod
+    def estimate_duration(text: str) -> float:
+        if not text.strip():
+            return 0.0
+        word_count = len(text.split())
+        return (word_count / WORDS_PER_MINUTE) * 60

devrel_origin/core/vox.py

@@ -0,0 +1,268 @@
+"""
+Vox — Video Tutorial Agent
+
+Generates polished video tutorials from written content or standalone tasks.
+Uses Playwright for screen recording, OpenAI TTS for narration, and FFmpeg
+for overlays and assembly.
+"""
+
+import logging
+import re
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from devrel_origin.core.video.script_parser import ScriptParser, TutorialStep, VideoTutorial
+from devrel_origin.tools.api_client import PostHogClient
+from devrel_origin.tools.search_tools import SearchTools
+
+logger = logging.getLogger(__name__)
+
+
+def _slug(text: str, max_len: int = 32) -> str:
+    """Slugify a free-form task string for use in filenames.
+
+    Lowercases, replaces runs of non-alphanumeric chars with single hyphens,
+    strips leading/trailing hyphens, truncates to ``max_len``, and falls
+    back to "tutorial" when the result would otherwise be empty (e.g.,
+    the input was all whitespace or punctuation).
+    """
+    return re.sub(r"[^a-zA-Z0-9]+", "-", text.lower()).strip("-")[:max_len] or "tutorial"
+
+
+def _check_ffmpeg() -> bool:
+    return shutil.which("ffmpeg") is not None
+
+
+def _check_playwright() -> bool:
+    try:
+        import playwright  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+class Vox:
+    """
+    Video Tutorial agent that produces screen-recorded tutorials.
+
+    Pipeline:
+    1. Parse script (from Kai's markdown or standalone task)
+    2. Generate TTS narration per step
+    3. Record browser session per step
+    4. Render overlays per step
+    5. Assemble final video
+
+    Dependencies (optional — gracefully degrades without them):
+    - playwright: browser recording
+    - ffmpeg (system binary): overlays + assembly
+    - openai: TTS narration
+    """
+
+    SYSTEM_PROMPT = """You are Vox, a video tutorial producer for OpenClaw.
+Your role is to transform written tutorials and task descriptions into
+structured video scripts with clear steps, narration text, and browser actions.
+
+Each step should have:
+1. A clear title
+2. Narration text (what to say during this step)
+3. A URL to navigate to
+4. Browser actions (click, type, scroll)
+5. Overlay text (code snippets or key points to display)
+
+Keep narration concise and developer-focused. Show, don't tell."""
+
+    def __init__(
+        self,
+        api_client: PostHogClient,
+        knowledge_base_path: Path,
+        output_dir: Path = Path("output/videos"),
+        openai_api_key: Optional[str] = None,
+        search_tools: Optional[SearchTools] = None,
+    ):
+        self.api_client = api_client
+        self.knowledge_base_path = knowledge_base_path
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.openai_api_key = openai_api_key
+        self.search_tools = search_tools
+        self.script_parser = ScriptParser()
+        self._has_ffmpeg = _check_ffmpeg()
+        self._has_playwright = _check_playwright()
+        if not self._has_ffmpeg:
+            logger.warning("FFmpeg not found — video rendering will be skipped")
+        if not self._has_playwright:
+            logger.warning("Playwright not installed — recording will be skipped")
+
+    async def execute(
+        self,
+        task: str,
+        context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Execute the video tutorial generation pipeline.
+
+        Args:
+            task: Description of the tutorial to produce.
+            context: Optional dict; if it contains 'kai_content' with a
+                     'content' key, that markdown is parsed into steps.
+
+        Returns:
+            Dict with agent name, parsed steps, status, and output path
+            (when full pipeline runs).
+        """
+        logger.info(f"Vox executing: {task[:80]}...")
+
+        # Validate against official docs to ensure accuracy
+        if self.search_tools:
+            try:
+                official_docs = await self.search_tools.fetch_official_docs(task)
+                if official_docs:
+                    logger.info(
+                        f"Fetched official docs for validation ({len(official_docs)} chars)"
+                    )
+            except Exception as exc:
+                logger.warning(f"Official docs fetch failed: {exc}")
+
+        source = "standalone_task"
+        steps: list[TutorialStep] = []
+
+        # Try to parse from Kai's markdown output first
+        if context and "kai_content" in context:
+            kai = context["kai_content"]
+            content = kai.get("content", "") if isinstance(kai, dict) else ""
+            if content:
+                steps = self.script_parser.parse_markdown(content)
+                source = "kai_content"
+
+        # Fall back to parsing the task string directly
+        if not steps:
+            steps = self.script_parser.parse_task(task)
+            source = "standalone_task"
+
+        ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+        output_filename = f"{ts}-{_slug(task)}.mp4"
+        tutorial = VideoTutorial(
+            title=task[:100],
+            steps=steps,
+            output_path=str(self.output_dir / output_filename),
+            source=source,
+        )
+
+        result: dict[str, Any] = {
+            "agent": "vox",
+            "task": task,
+            "source": source,
+            "steps": [
+                {
+                    "step_number": s.step_number,
+                    "title": s.title,
+                    "narration": s.narration[:200],
+                    "url": s.url,
+                    "actions_count": len(s.actions),
+                    "overlay_text": s.overlay_text[:100] if s.overlay_text else "",
+                    "duration_hint": s.duration_hint,
+                }
+                for s in steps
+            ],
+            "total_steps": len(steps),
+            "status": "script_only",
+        }
+
+        can_render = self._has_ffmpeg and self._has_playwright and self.openai_api_key
+        if can_render:
+            try:
+                output_path = await self._run_full_pipeline(tutorial)
+                result["status"] = "generated"
+                result["output_path"] = str(output_path)
+                result["total_duration"] = tutorial.total_duration
+            except Exception as exc:
+                logger.error(f"Video pipeline failed: {exc}")
+                result["status"] = "script_only"
+                result["pipeline_error"] = str(exc)
+
+        return result
+
+    async def _run_full_pipeline(self, tutorial: VideoTutorial) -> Path:
+        """Run the full TTS + recording + overlay + assembly pipeline."""
+        from devrel_origin.core.video.assembler import VideoAssembler
+        from devrel_origin.core.video.browser_recorder import BrowserRecorder
+        from devrel_origin.core.video.desktop_recorder import DesktopRecorder
+        from devrel_origin.core.video.overlay_renderer import OverlayRenderer
+        from devrel_origin.core.video.tts_engine import TTSEngine
+
+        tts_dir = self.output_dir / "tts"
+        recording_dir = self.output_dir / "recordings"
+        overlay_dir = self.output_dir / "overlays"
+
+        tts = TTSEngine(api_key=self.openai_api_key, output_dir=tts_dir)
+        recorder = BrowserRecorder(output_dir=recording_dir)
+        desktop_recorder = DesktopRecorder(output_dir=recording_dir)
+        overlays = OverlayRenderer(output_dir=overlay_dir)
+        assembler = VideoAssembler(output_dir=self.output_dir)
+
+        step_audios: list[Path] = []
+        step_videos: list[Path] = []
+        total_steps = len(tutorial.steps)
+
+        for step in tutorial.steps:
+            prefix = f"step_{step.step_number}"
+
+            audio_path = await tts.generate_audio(step.narration, prefix)
+            step_audios.append(audio_path)
+
+            # Choose recorder based on step type:
+            # URLs starting with "http" use browser recording;
+            # everything else (app names like "Figma", "VS Code") uses desktop recording.
+            if step.url.startswith("http"):
+                actions = recorder.parse_actions(step.actions)
+                video_path = await recorder.record_step(
+                    url=step.url,
+                    actions=actions,
+                    filename_prefix=prefix,
+                    duration_hint=step.duration_hint,
+                )
+            else:
+                desktop_actions = desktop_recorder.parse_actions(step.actions)
+                video_path = await desktop_recorder.record_step(
+                    actions=desktop_actions,
+                    filename_prefix=prefix,
+                    duration_hint=step.duration_hint,
+                    app_name=step.url if step.url else None,
+                )
+
+            overlaid_path = await overlays.render_overlays(
+                video_path=video_path,
+                title=step.title,
+                step_number=step.step_number,
+                total_steps=total_steps,
+                callout_text=step.overlay_text,
+                filename_prefix=prefix,
+            )
+            step_videos.append(overlaid_path)
+
+        final_path = await assembler.assemble(
+            step_videos=step_videos,
+            step_audios=step_audios,
+            output_filename=Path(tutorial.output_path).name,
+        )
+
+        tutorial.output_path = str(final_path)
+        tutorial.total_duration = sum(s.duration_hint for s in tutorial.steps)
+        return final_path
+
+    async def generate_from_tutorial(
+        self, tutorial_content: str, title: str = "Tutorial"
+    ) -> dict[str, Any]:
+        """Convenience method: generate a video from raw tutorial markdown.
+
+        Args:
+            tutorial_content: Markdown content with ## headings for steps.
+            title: Title for the tutorial task.
+
+        Returns:
+            Same dict as execute().
+        """
+        context = {"kai_content": {"content": tutorial_content}}
+        return await self.execute(title, context)

devrel_origin/core/watchdog.py

@@ -0,0 +1,321 @@
+"""
+Watchdog — System Health Monitor Agent
+
+Monitors agent pipeline health: checks for stale outputs, failed runs,
+token budget consumption, and integration connectivity. Produces a
+health report with actionable alerts.
+"""
+
+import asyncio
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+from devrel_origin.core.llm import LLMClient
+
+logger = logging.getLogger(__name__)
+
+
+def _compute_age_hours(timestamp_str: str) -> float:
+    """Parse an ISO 8601 timestamp string and return age in hours.
+
+    Returns 999.0 if the string is empty, malformed, or in the future.
+    """
+    if not timestamp_str:
+        return 999.0
+    try:
+        ts = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=timezone.utc)
+        age_seconds = (datetime.now(timezone.utc) - ts).total_seconds()
+        return max(0.0, age_seconds / 3600)
+    except (ValueError, TypeError):
+        return 999.0
+
+
+@dataclass
+class AgentHealthCheck:
+    """Health status for a single agent."""
+
+    agent: str
+    status: str  # "healthy", "stale", "failed", "unknown"
+    last_run: str
+    output_age_hours: float
+    issues: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SystemHealthReport:
+    """Full system health report."""
+
+    timestamp: str
+    overall_score: int  # 0-100
+    agents: list[AgentHealthCheck]
+    budget_usage: dict[str, Any]
+    integration_status: dict[str, str]
+    alerts: list[str]
+    recommendations: list[str]
+
+
+class Watchdog:
+    """
+    System health monitoring agent.
+
+    Capabilities:
+    - Check agent output freshness (stale detection)
+    - Monitor token budget consumption per agent
+    - Verify integration connectivity (APIs, search tools)
+    - Produce health scores and actionable alerts
+    - Track week-over-week health trends
+    """
+
+    STALE_THRESHOLD_HOURS = 168  # 7 days
+
+    def __init__(
+        self,
+        archive_dir: Path = Path("context_archive"),
+        llm_client: Optional[LLMClient] = None,
+    ):
+        self.archive_dir = archive_dir
+        self.llm_client = llm_client
+
+    async def execute(
+        self,
+        task: str,
+        context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Run system health check."""
+        logger.info(f"Watchdog executing: {task[:80]}...")
+
+        agent_checks = self._check_agent_health(context)
+        budget = self._check_budget(context)
+        integrations = await self._check_integrations()
+        alerts = self._generate_alerts(agent_checks, budget, integrations)
+        score = self._compute_health_score(agent_checks, integrations)
+
+        return {
+            "agent": "watchdog",
+            "task": task,
+            "timestamp": datetime.now().isoformat(),
+            "overall_score": score,
+            "agent_health": [
+                {
+                    "agent": c.agent,
+                    "status": c.status,
+                    "last_run": c.last_run,
+                    "issues": c.issues,
+                }
+                for c in agent_checks
+            ],
+            "budget_usage": budget,
+            "integration_status": integrations,
+            "alerts": alerts,
+            "status": "checked",
+        }
+
+    def _check_agent_health(
+        self,
+        context: dict[str, Any] | None,
+    ) -> list[AgentHealthCheck]:
+        """Check each agent's output freshness from context."""
+        checks = []
+        agent_fields = {
+            "sage": "sage_triage",
+            "echo": "echo_social",
+            "iris": "iris_themes",
+            "nova": "nova_experiments",
+            "kai": "kai_content",
+            "vox": "vox_video",
+            "dex": "dex_docs",
+            "rex": "rex_competitive",
+            "pax": "pax_sales",
+            "mox": "mox_campaigns",
+        }
+
+        for agent, field_name in agent_fields.items():
+            data = (context or {}).get(field_name, {})
+            if isinstance(data, dict) and data:
+                last_run_ts = data.get("timestamp", "") or ""
+                output_age_hours = _compute_age_hours(last_run_ts)
+                status = "stale" if output_age_hours > self.STALE_THRESHOLD_HOURS else "healthy"
+                checks.append(
+                    AgentHealthCheck(
+                        agent=agent,
+                        status=status,
+                        last_run=last_run_ts or "unknown",
+                        output_age_hours=output_age_hours,
+                        issues=(
+                            [
+                                f"{agent} output age {output_age_hours:.1f}h exceeds "
+                                f"{self.STALE_THRESHOLD_HOURS}h threshold"
+                            ]
+                            if status == "stale"
+                            else []
+                        ),
+                    )
+                )
+            else:
+                checks.append(
+                    AgentHealthCheck(
+                        agent=agent,
+                        status="stale" if context else "unknown",
+                        last_run="never",
+                        output_age_hours=999.0,
+                        issues=[f"{agent} has no output in current context"],
+                    )
+                )
+
+        return checks
+
+    def _check_budget(self, context: dict[str, Any] | None) -> dict[str, Any]:
+        """Check token budget consumption and cost."""
+        if not self.llm_client:
+            return {"status": "no_client", "per_agent": {}}
+
+        usage = self.llm_client.usage
+        budget_limit = getattr(self.llm_client, "budget_limit_usd", 0)
+        return {
+            "total_input_tokens": usage.total_input_tokens,
+            "total_output_tokens": usage.total_output_tokens,
+            "total_calls": usage.total_calls,
+            "total_cost_usd": round(usage.total_cost_usd, 4),
+            "budget_limit_usd": budget_limit,
+            "budget_remaining_usd": round(max(0, budget_limit - usage.total_cost_usd), 4),
+            "per_agent": dict(usage.per_agent),
+            "status": "tracked",
+        }
+
+    async def _check_integrations(self) -> dict[str, str]:
+        """Probe actual integration endpoints for connectivity."""
+        probes: dict[str, tuple[str, dict[str, str]]] = {}
+
+        github_token = os.environ.get("GITHUB_TOKEN", "")
+        if github_token:
+            probes["github"] = (
+                "https://api.github.com",
+                {"Authorization": f"Bearer {github_token}"},
+            )
+
+        anthropic_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        if anthropic_key:
+            probes["llm"] = (
+                "https://api.anthropic.com/v1/models",
+                {
+                    "x-api-key": anthropic_key,
+                    "anthropic-version": "2023-06-01",
+                },
+            )
+
+        firecrawl_key = os.environ.get("FIRECRAWL_API_KEY", "")
+        if firecrawl_key:
+            # Use a GET-able endpoint; /v1/scrape is POST-only and always
+            # returns 405 on GET, masking healthy auth as unhealthy.
+            probes["search"] = (
+                "https://api.firecrawl.dev/v1/team",
+                {"Authorization": f"Bearer {firecrawl_key}"},
+            )
+
+        instantly_key = os.environ.get("INSTANTLY_API_KEY", "")
+        if instantly_key:
+            probes["instantly"] = (
+                "https://api.instantly.ai/api/v2/campaigns?limit=1",
+                {"Authorization": f"Bearer {instantly_key}"},
+            )
+
+        status: dict[str, str] = {}
+        async with httpx.AsyncClient(timeout=5.0) as client:
+
+            async def _probe(name: str, url: str, headers: dict) -> tuple[str, str]:
+                try:
+                    resp = await client.get(url, headers=headers)
+                    if resp.status_code < 400:
+                        return name, "connected"
+                    return name, f"error_{resp.status_code}"
+                except Exception as exc:
+                    return name, f"unreachable: {type(exc).__name__}"
+
+            results = await asyncio.gather(
+                *[_probe(name, url, hdrs) for name, (url, hdrs) in probes.items()]
+            )
+            for name, result in results:
+                status[name] = result
+
+        # Mark unconfigured integrations
+        for name in ("github", "llm", "search", "instantly"):
+            if name not in status:
+                status[name] = "not_configured"
+
+        return status
+
+    def _generate_alerts(
+        self,
+        checks: list[AgentHealthCheck],
+        budget: dict[str, Any],
+        integrations: dict[str, str],
+    ) -> list[str]:
+        """Generate actionable alerts from health data."""
+        alerts = []
+
+        stale = [c for c in checks if c.status == "stale"]
+        if stale:
+            agents = ", ".join(c.agent for c in stale)
+            alerts.append(f"STALE: {agents} have no recent output")
+
+        # Any state that isn't healthy ("connected") or intentionally absent
+        # ("not_configured") is a real alert: error_405, error_500,
+        # unreachable: ConnectionError, etc.
+        failed_integrations = [
+            f"{k}={v}" for k, v in integrations.items() if v not in ("connected", "not_configured")
+        ]
+        if failed_integrations:
+            alerts.append(f"INTEGRATION: {', '.join(failed_integrations)} unhealthy")
+
+        # Budget alerts: prefer cost-vs-cap ratio when a budget is configured;
+        # fall back to absolute token threshold only when no budget is set.
+        total_tokens = budget.get("total_input_tokens", 0) + budget.get("total_output_tokens", 0)
+        total_cost_usd = budget.get("total_cost_usd", 0.0) or 0.0
+        budget_limit_usd = budget.get("budget_limit_usd", 0) or 0
+        if budget_limit_usd > 0:
+            spend_ratio = total_cost_usd / budget_limit_usd
+            if spend_ratio > 0.8:
+                alerts.append(
+                    f"BUDGET: {int(spend_ratio * 100)}% consumed "
+                    f"(${total_cost_usd:.2f} / ${budget_limit_usd:.2f})"
+                )
+        elif total_tokens > 500_000:
+            # Fallback: no budget configured, use absolute threshold
+            alerts.append(f"BUDGET: High token usage ({total_tokens:,} total)")
+
+        return alerts
+
+    def _compute_health_score(
+        self,
+        checks: list[AgentHealthCheck],
+        integrations: dict[str, str],
+    ) -> int:
+        """Compute overall system health score (0-100)."""
+        score = 100
+
+        # Deduct for stale/failed agents
+        for c in checks:
+            if c.status == "stale":
+                score -= 5
+            elif c.status == "failed":
+                score -= 10
+            elif c.status == "unknown":
+                score -= 3
+
+        # Deduct for integration issues. "not_configured" is intentional
+        # (no key set), so it's a smaller deduction than an actual failure.
+        for status in integrations.values():
+            if status == "not_configured":
+                score -= 2
+            elif status != "connected":
+                score -= 5
+
+        return max(0, score)

devrel_origin/project/__init__.py

@@ -0,0 +1 @@
+"""Project bootstrap: .devrel/ scaffold, config, state, paths."""