devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/core/sentinel.py

@@ -0,0 +1,385 @@
+"""
+Sentinel — Brand Consistency Auditor Agent
+
+Audits all agent outputs for brand voice consistency, messaging alignment,
+ICP accuracy, and content quality. Produces a scored audit report with
+specific remediation recommendations.
+"""
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from devrel_origin.core.base import load_agent_prompt, strip_markdown_fences
+from devrel_origin.core.llm import LLMClient
+from devrel_origin.tools.api_client import PostHogClient
+
+logger = logging.getLogger(__name__)
+
+
+# Per-agent map of content fields to scan. Each agent stores its prose
+# under a different key (Mox under "blog_post", Pax under "body", etc.),
+# so Sentinel must check each agent's actual primary field rather than
+# assuming a universal "content" key. Order within the list = priority;
+# the first non-empty value wins.
+_AGENT_CONTENT_FIELDS: dict[str, list[str]] = {
+    "kai_content": ["content", "body"],
+    "mox_campaigns": [
+        "blog_post",
+        "landing_page",
+        "social_batch",
+        "campaign_brief",
+        "content",
+    ],
+    "pax_sales": ["body", "battle_card", "sequence", "content"],
+    "rex_competitive": ["analysis", "summary", "content"],
+    "dex_docs": ["architecture", "api_reference", "content"],
+    "iris_themes": ["recommendations", "content"],
+    "vox_video": ["script", "content"],
+    "sage_triage": ["content"],
+    "echo_social": ["content"],
+}
+
+
+def _safe_json_loads(raw: str) -> dict[str, Any]:
+    """Parse JSON even when an LLM wraps it in prose or markdown fences."""
+    cleaned = strip_markdown_fences(raw or "").strip()
+    try:
+        parsed = json.loads(cleaned)
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start == -1 or end == -1 or end <= start:
+            raise
+        parsed = json.loads(cleaned[start : end + 1])
+        return parsed if isinstance(parsed, dict) else {}
+
+
+@dataclass
+class AuditItem:
+    """Audit result for a single content piece."""
+
+    agent: str
+    content_type: str
+    score: int  # 1-10
+    passed: bool
+    issues: list[dict[str, str]] = field(default_factory=list)
+    strengths: list[str] = field(default_factory=list)
+
+
+@dataclass
+class BrandAuditReport:
+    """Complete brand consistency audit."""
+
+    overall_score: int  # 1-100
+    items: list[AuditItem]
+    voice_consistency: int  # 1-10
+    icp_alignment: int  # 1-10
+    messaging_coherence: int  # 1-10
+    cross_piece_issues: list[str]
+    recommendations: list[str]
+
+
+class Sentinel:
+    """
+    Brand Consistency Auditor agent.
+
+    Capabilities:
+    - Audit generated content for brand voice adherence
+    - Check ICP alignment across all outputs
+    - Verify messaging consistency between agents
+    - Score content quality on multiple dimensions
+    - Produce remediation recommendations
+    """
+
+    _DEFAULT_SYSTEM_PROMPT = """You are Sentinel, a brand consistency auditor. \
+You review all content produced by the agent system and flag deviations from \
+brand standards.
+
+Audit dimensions:
+1. VOICE — Developer-authentic, not corporate marketing. No buzzwords, no fluff.
+2. ICP ALIGNMENT — Content targets the right audience (DevTools founders, \
+engineering leaders, developer advocates).
+3. MESSAGING COHERENCE — All pieces tell a consistent story. No contradictions \
+between what Kai's tutorial says and Mox's landing page claims.
+4. TECHNICAL ACCURACY — Claims are grounded, code examples work, APIs exist.
+5. CTA CONSISTENCY — Each piece has one clear CTA appropriate to its funnel stage.
+6. FORMATTING — Short paragraphs, clear hierarchy, scannable structure.
+
+Scoring:
+- 9-10: Exceptional, publish immediately
+- 7-8: Good, minor polish needed
+- 5-6: Acceptable with edits
+- 3-4: Significant issues, needs rewrite
+- 1-2: Off-brand, reject
+
+Be strict. Generic AI slop scores 3-4 regardless of technical accuracy."""
+
+    @property
+    def SYSTEM_PROMPT(self) -> str:
+        return load_agent_prompt(
+            "sentinel",
+            "system_prompt.txt",
+            self._DEFAULT_SYSTEM_PROMPT,
+        )
+
+    def __init__(
+        self,
+        api_client: PostHogClient,
+        knowledge_base_path: Path,
+        llm_client: Optional[LLMClient] = None,
+    ):
+        self.api_client = api_client
+        self.knowledge_base_path = knowledge_base_path
+        self.llm_client = llm_client
+
+    async def execute(
+        self,
+        task: str,
+        context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Run brand consistency audit on all generated content."""
+        logger.info(f"Sentinel executing: {task[:80]}...")
+
+        # Collect all content pieces from context
+        pieces = self._collect_content(context)
+        if not pieces:
+            return {
+                "agent": "sentinel",
+                "task": task,
+                "status": "no_content",
+                "overall_score": 0,
+                "message": "No content found to audit",
+            }
+
+        # Run LLM audit if available
+        if self.llm_client:
+            return await self._llm_audit(task, pieces)
+
+        # Fallback: basic structural checks
+        return self._structural_audit(task, pieces)
+
+    def _collect_content(
+        self,
+        context: Any,
+    ) -> list[dict[str, str]]:
+        """Extract all content pieces from SharedContext for auditing.
+
+        Walks ``_AGENT_CONTENT_FIELDS`` and picks the first non-empty
+        candidate field per agent. Each agent has a different primary
+        field (Mox stores under ``blog_post``, Pax under ``body``, etc.),
+        so a universal "content" key would silently audit only Kai.
+        """
+        pieces: list[dict[str, str]] = []
+        if not context:
+            return pieces
+
+        ctx_dict = context.to_dict() if hasattr(context, "to_dict") else dict(context)
+
+        for context_key, candidate_fields in _AGENT_CONTENT_FIELDS.items():
+            agent_data = ctx_dict.get(context_key, {})
+            if not isinstance(agent_data, dict):
+                continue
+            for fld in candidate_fields:
+                value = agent_data.get(fld)
+                if isinstance(value, str) and value.strip():
+                    pieces.append(
+                        {
+                            "agent": context_key,
+                            "content_type": fld,
+                            "content": value[:5000],
+                        }
+                    )
+                    break  # one piece per agent
+                if isinstance(value, list) and value:
+                    joined = "\n\n".join(str(v) for v in value[:3])[:5000]
+                    if joined.strip():
+                        pieces.append(
+                            {
+                                "agent": context_key,
+                                "content_type": fld,
+                                "content": joined,
+                            }
+                        )
+                        break
+
+        return pieces
+
+    async def _llm_audit(
+        self,
+        task: str,
+        pieces: list[dict[str, str]],
+    ) -> dict[str, Any]:
+        """Run comprehensive LLM-powered brand audit."""
+        pieces_text = ""
+        for p in pieces:
+            pieces_text += (
+                f"\n\n--- [{p['agent'].upper()} — {p['content_type']}] ---\n{p['content']}\n"
+            )
+
+        prompt = f"""Audit all content pieces below for brand consistency.
+
+{pieces_text}
+
+For each piece, evaluate:
+1. Voice score (1-10): developer-authentic vs marketing fluff
+2. ICP alignment (1-10): targets right audience
+3. Technical accuracy (1-10): claims grounded, code correct
+4. CTA clarity (1-10): one clear next step
+5. Formatting (1-10): scannable, short paragraphs
+
+Also evaluate cross-piece consistency:
+- Do pieces contradict each other?
+- Is the messaging aligned across all agents?
+- Are the same features described the same way?
+
+Return JSON:
+{{
+  "overall_score": <1-100>,
+  "voice_consistency": <1-10>,
+  "icp_alignment": <1-10>,
+  "messaging_coherence": <1-10>,
+  "items": [
+    {{
+      "agent": "...",
+      "content_type": "...",
+      "score": <1-10>,
+      "passed": true/false,
+      "issues": [{{"dimension": "...", "severity": "high|medium|low", "detail": "..."}}],
+      "strengths": ["..."]
+    }}
+  ],
+  "cross_piece_issues": ["..."],
+  "recommendations": ["..."]
+}}"""
+
+        raw = ""
+        try:
+            raw = await self.llm_client.generate(
+                system_prompt=self.SYSTEM_PROMPT,
+                user_prompt=prompt,
+                temperature=0.2,
+                max_tokens=4096,
+            )
+            audit = _safe_json_loads(raw)
+            return {
+                "agent": "sentinel",
+                "task": task,
+                "status": "audited",
+                **audit,
+            }
+        except json.JSONDecodeError as exc:
+            logger.warning(
+                "Sentinel LLM audit returned non-JSON response; marking audit_failed. "
+                "error=%s raw_head=%r",
+                exc,
+                (raw or "")[:200],
+            )
+            logger.debug("Full raw response: %s", raw)
+            return {
+                "agent": "sentinel",
+                "task": task,
+                "status": "audit_failed",
+                "overall_score": 0,
+                "items": [],
+                "cross_piece_issues": [],
+                "recommendations": ["Retry Sentinel audit; model response was not valid JSON."],
+                "error": str(exc),
+            }
+        except Exception as exc:
+            logger.warning(
+                "Sentinel LLM audit API error; falling back to structural: %s",
+                exc,
+            )
+            return self._structural_audit(task, pieces)
+
+    def _structural_audit(
+        self,
+        task: str,
+        pieces: list[dict[str, str]],
+    ) -> dict[str, Any]:
+        """Fallback: basic structural quality checks without LLM."""
+        items = []
+        total_score = 0
+
+        for p in pieces:
+            content = p["content"]
+            issues = []
+            score = 7  # Start at passing
+
+            # Check paragraph length
+            paragraphs = content.split("\n\n")
+            long_paras = [pp for pp in paragraphs if len(pp.split()) > 100]
+            if long_paras:
+                issues.append(
+                    {
+                        "dimension": "formatting",
+                        "severity": "medium",
+                        "detail": f"{len(long_paras)} paragraphs exceed 100 words",
+                    }
+                )
+                score -= 1
+
+            # Check for heading structure
+            if "## " not in content and "# " not in content:
+                issues.append(
+                    {
+                        "dimension": "formatting",
+                        "severity": "medium",
+                        "detail": "No heading hierarchy found",
+                    }
+                )
+                score -= 1
+
+            # Check for buzzwords
+            buzzwords = [
+                "revolutionary",
+                "game-changing",
+                "cutting-edge",
+                "best-in-class",
+                "world-class",
+                "synergy",
+                "leverage",
+                "disrupt",
+                "paradigm",
+            ]
+            found_buzzwords = [b for b in buzzwords if b in content.lower()]
+            if found_buzzwords:
+                issues.append(
+                    {
+                        "dimension": "voice",
+                        "severity": "high",
+                        "detail": f"Marketing buzzwords found: {', '.join(found_buzzwords)}",
+                    }
+                )
+                score -= 2
+
+            items.append(
+                {
+                    "agent": p["agent"],
+                    "content_type": p["content_type"],
+                    "score": max(1, score),
+                    "passed": score >= 6,
+                    "issues": issues,
+                }
+            )
+            total_score += max(1, score)
+
+        # Map item average from 1-7 scale onto 10-100 scale linearly so the
+        # structural fallback produces scores comparable to the LLM 1-100 path:
+        #   item_avg = 1 → 10, item_avg = 4 → 55, item_avg = 7 → 100
+        average_item = total_score / max(len(items), 1)
+        overall = int(round(((average_item - 1) / 6) * 90 + 10))
+        overall = max(0, min(100, overall))
+        return {
+            "agent": "sentinel",
+            "task": task,
+            "status": "audited_structural",
+            "overall_score": overall,
+            "items": items,
+            "cross_piece_issues": [],
+            "recommendations": [],
+        }

devrel_origin/core/types.py

@@ -0,0 +1,98 @@
+"""Typed return values for agent execute() methods."""
+
+from typing import NotRequired, TypedDict
+
+
+class SageTriageResult(TypedDict):
+    agent: str
+    status: str
+    issues: list[dict]
+    total_analyzed: int
+    prompt_used: NotRequired[str]
+
+
+class EchoSocialResult(TypedDict):
+    agent: str
+    status: str
+    brand: str
+    top_mentions: list[dict]
+    total_mentions: int
+    platforms: dict
+    sentiment_overall: dict
+    engagement_opportunities: list[dict]
+    reputation_risks: list[dict]
+    prompt_used: NotRequired[str]
+
+
+class IrisThemesResult(TypedDict):
+    agent: str
+    status: str
+    themes: list[dict]
+    prompt_used: NotRequired[str]
+    content: NotRequired[dict]
+
+
+class NovaExperimentResult(TypedDict):
+    agent: str
+    status: str
+    experiments: list[dict]
+    prompt_used: NotRequired[str]
+
+
+class KaiContentResult(TypedDict):
+    agent: str
+    status: str
+    content_type: NotRequired[str]
+    prompt_used: NotRequired[str]
+    content: NotRequired[dict]
+
+
+class RexCompetitiveResult(TypedDict):
+    agent: str
+    status: str
+    task: str
+    competitors_discovered: list[str]
+    kb_sources: list[str]
+    web_intel_sources: dict[str, int]
+    upstream_social_mentions: NotRequired[int]
+    upstream_community_issues: NotRequired[int]
+    prompt_used: NotRequired[str]
+    content: NotRequired[dict]
+
+
+class PaxSalesResult(TypedDict):
+    agent: str
+    status: str
+    asset_type: str
+    prompt_used: NotRequired[str]
+    content: NotRequired[str]
+
+
+class MoxCampaignResult(TypedDict):
+    agent: str
+    status: str
+    content_type: str
+    prompt_used: NotRequired[str]
+    content: NotRequired[str]
+
+
+class InstantlyAnalyticsResult(TypedDict):
+    agent: str
+    status: str
+    total_campaigns: int
+    total_sent: int
+    total_opened: int
+    total_replied: int
+    total_bounced: int
+    avg_open_rate: float
+    avg_reply_rate: float
+    avg_bounce_rate: float
+    per_campaign: list[dict]
+
+
+class InstantlyRepliesResult(TypedDict):
+    agent: str
+    status: str
+    total_replies: int
+    categories: dict
+    drafts: list[dict]

devrel_origin/core/video/__init__.py

@@ -0,0 +1,22 @@
+"""Video tutorial generation package for Vox agent."""
+
+from devrel_origin.core.video.assembler import VideoAssembler
+from devrel_origin.core.video.browser_recorder import BrowserAction, BrowserRecorder
+from devrel_origin.core.video.desktop_recorder import DesktopAction, DesktopRecorder
+from devrel_origin.core.video.overlay_renderer import OverlayConfig, OverlayRenderer
+from devrel_origin.core.video.script_parser import ScriptParser, TutorialStep, VideoTutorial
+from devrel_origin.core.video.tts_engine import TTSEngine
+
+__all__ = [
+    "ScriptParser",
+    "TutorialStep",
+    "VideoTutorial",
+    "TTSEngine",
+    "BrowserRecorder",
+    "BrowserAction",
+    "DesktopRecorder",
+    "DesktopAction",
+    "OverlayRenderer",
+    "OverlayConfig",
+    "VideoAssembler",
+]

devrel_origin/core/video/assembler.py

@@ -0,0 +1,131 @@
+"""
+Video assembler — final FFmpeg pipeline for concatenation and audio merging.
+Concatenates step videos, merges TTS audio tracks per step, outputs final .mp4.
+"""
+
+import asyncio
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Hard cap on FFmpeg subprocess wall-clock time (seconds). 5 minutes is
+# generous for normal merge/concat work but stops a stuck encoder from
+# hanging the whole pipeline.
+FFMPEG_TIMEOUT_S = 300
+
+
+async def _communicate_with_timeout(process: asyncio.subprocess.Process):
+    """Run ``process.communicate()`` with a hard timeout.
+
+    On timeout: send SIGKILL, await the reaper, then raise RuntimeError so
+    the surrounding pipeline error path engages and the caller logs the
+    failure instead of waiting indefinitely.
+    """
+    try:
+        return await asyncio.wait_for(process.communicate(), timeout=FFMPEG_TIMEOUT_S)
+    except asyncio.TimeoutError as exc:
+        process.kill()
+        await process.wait()
+        raise RuntimeError(
+            f"FFmpeg subprocess timed out after {FFMPEG_TIMEOUT_S}s; killed"
+        ) from exc
+
+
+class VideoAssembler:
+    def __init__(self, output_dir: Path):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    async def assemble(
+        self,
+        step_videos: list[Path],
+        step_audios: list[Path],
+        output_filename: str = "tutorial.mp4",
+    ) -> Path:
+        if len(step_videos) != len(step_audios):
+            raise ValueError(f"Mismatch: {len(step_videos)} videos vs {len(step_audios)} audios")
+        merged_steps = []
+        for i, (video, audio) in enumerate(zip(step_videos, step_audios, strict=True)):
+            merged_path = self.output_dir / f"merged_step_{i + 1}.mp4"
+            await self._merge_audio_video(video, audio, merged_path)
+            merged_steps.append(merged_path)
+        final_path = self.output_dir / output_filename
+        if len(merged_steps) == 1:
+            merged_steps[0].rename(final_path)
+        else:
+            await self._concatenate_videos(merged_steps, final_path)
+        for p in merged_steps:
+            if p.exists():
+                p.unlink()
+        logger.info(f"Final video assembled: {final_path}")
+        return final_path
+
+    async def _merge_audio_video(
+        self, video_path: Path, audio_path: Path, output_path: Path
+    ) -> None:
+        cmd = self._build_audio_merge_cmd(video_path, audio_path, output_path)
+        logger.info(f"Merging audio+video: {output_path.name}")
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+        _, stderr = await _communicate_with_timeout(process)
+        if process.returncode != 0:
+            err_text = stderr.decode()
+            logger.error(f"FFmpeg merge failed: {err_text[:500]}")
+            raise RuntimeError(f"Audio/video merge failed: {err_text[:200]}")
+
+    async def _concatenate_videos(self, video_paths: list[Path], output_path: Path) -> None:
+        concat_file = self.output_dir / "concat_list.txt"
+        concat_file.write_text(self._build_concat_file_content(video_paths))
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            str(concat_file),
+            "-c",
+            "copy",
+            str(output_path),
+        ]
+        logger.info(f"Concatenating {len(video_paths)} steps")
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+        _, stderr = await _communicate_with_timeout(process)
+        concat_file.unlink(missing_ok=True)
+        if process.returncode != 0:
+            err_text = stderr.decode()
+            logger.error(f"FFmpeg concat failed: {err_text[:500]}")
+            raise RuntimeError(f"Video concatenation failed: {err_text[:200]}")
+
+    def _build_concat_file_content(self, video_paths: list[Path]) -> str:
+        lines = [f"file '{path}'" for path in video_paths]
+        return "\n".join(lines)
+
+    def _build_audio_merge_cmd(
+        self, video_path: Path, audio_path: Path, output_path: Path
+    ) -> list[str]:
+        return [
+            "ffmpeg",
+            "-y",
+            "-i",
+            str(video_path),
+            "-i",
+            str(audio_path),
+            "-c:v",
+            "copy",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "192k",
+            "-map",
+            "0:v:0",
+            "-map",
+            "1:a:0",
+            "-shortest",
+            str(output_path),
+        ]