devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/tools/notifications.py

@@ -0,0 +1,245 @@
+"""
+Notifications — Telegram and email delivery for agent outputs.
+
+Provides async delivery of content digests and alerts to configured channels.
+"""
+
+import asyncio
+import logging
+import smtplib
+import ssl
+from dataclasses import dataclass
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+TELEGRAM_API = "https://api.telegram.org"
+
+
+@dataclass
+class NotificationConfig:
+    """Notification channel configuration."""
+
+    telegram_bot_token: str = ""
+    telegram_chat_id: str = ""
+    email_smtp_host: str = "smtp.gmail.com"
+    email_smtp_port: int = 587
+    email_sender: str = ""
+    email_password: str = ""  # App password for Gmail
+    email_recipients: list[str] | None = None
+
+
+class NotificationService:
+    """Async notification delivery to Telegram and email.
+
+    Usage::
+
+        svc = NotificationService(config)
+        await svc.send_telegram("Pipeline complete!")
+        await svc.send_email("Weekly Report", html_body)
+        await svc.send_digest(context)  # Auto-formats and sends both
+    """
+
+    def __init__(self, config: NotificationConfig):
+        self.config = config
+        self._client = httpx.AsyncClient(timeout=15.0)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # -- Telegram ---------------------------------------------------------
+
+    async def send_telegram(self, message: str, parse_mode: str = "Markdown") -> bool:
+        """Send a message to the configured Telegram chat."""
+        if not self.config.telegram_bot_token or not self.config.telegram_chat_id:
+            logger.debug("Telegram not configured, skipping")
+            return False
+
+        try:
+            url = f"{TELEGRAM_API}/bot{self.config.telegram_bot_token}/sendMessage"
+            resp = await self._client.post(
+                url,
+                json={
+                    "chat_id": self.config.telegram_chat_id,
+                    "text": message[:4096],
+                    "parse_mode": parse_mode,
+                },
+            )
+            resp.raise_for_status()
+            logger.info("Telegram message sent")
+            return True
+        except Exception as exc:
+            logger.warning(f"Telegram send failed: {exc}")
+            return False
+
+    # -- Email ------------------------------------------------------------
+
+    async def send_email(
+        self,
+        subject: str,
+        html_body: str,
+        recipients: list[str] | None = None,
+    ) -> bool:
+        """Send an HTML email via SMTP."""
+        cfg = self.config
+        if not cfg.email_sender or not cfg.email_password:
+            logger.debug("Email not configured, skipping")
+            return False
+
+        to_addrs = recipients or cfg.email_recipients or []
+        if not to_addrs:
+            logger.warning("No email recipients configured")
+            return False
+
+        msg = MIMEMultipart("alternative")
+        msg["Subject"] = subject
+        msg["From"] = cfg.email_sender
+        msg["To"] = ", ".join(to_addrs)
+        msg.attach(MIMEText(html_body, "html"))
+
+        def _send_sync() -> None:
+            ctx = ssl.create_default_context()
+            with smtplib.SMTP(cfg.email_smtp_host, cfg.email_smtp_port) as server:
+                server.starttls(context=ctx)
+                server.login(cfg.email_sender, cfg.email_password)
+                server.sendmail(cfg.email_sender, to_addrs, msg.as_string())
+
+        try:
+            loop = asyncio.get_running_loop()
+            await loop.run_in_executor(None, _send_sync)
+            logger.info(f"Email sent to {to_addrs}")
+            return True
+        except Exception as exc:
+            logger.warning(f"Email send failed: {exc}")
+            return False
+
+    # -- Digest -----------------------------------------------------------
+
+    async def send_digest(
+        self,
+        context: dict[str, Any],
+        mode: str = "daily",
+    ) -> dict[str, bool]:
+        """Format and send a content digest from SharedContext.
+
+        Args:
+            context: SharedContext.to_dict() output.
+            mode: "daily" for brief content summary, "weekly" for full report.
+
+        Returns:
+            Dict with "telegram" and "email" delivery status.
+        """
+        if mode == "weekly":
+            telegram_msg = self._format_weekly_telegram(context)
+            email_html = self._format_weekly_email(context)
+            subject = f"Weekly Agent Report — {context.get('week_of', 'unknown')}"
+        else:
+            telegram_msg = self._format_daily_telegram(context)
+            email_html = self._format_daily_email(context)
+            subject = "Daily Content Digest"
+
+        tg_ok = await self.send_telegram(telegram_msg)
+        email_ok = await self.send_email(subject, email_html)
+        return {"telegram": tg_ok, "email": email_ok}
+
+    def _format_daily_telegram(self, ctx: dict[str, Any]) -> str:
+        """Format a brief daily Telegram message."""
+        lines = [f"📊 *Daily Digest — {ctx.get('week_of', '')}*\n"]
+
+        if ctx.get("kai_content"):
+            task = ctx["kai_content"].get("task", "content")[:80]
+            lines.append(f"✍️ Kai: {task}")
+
+        if ctx.get("echo_social"):
+            total = ctx["echo_social"].get("total_mentions", 0)
+            lines.append(f"👂 Echo: {total} social mentions")
+
+        if ctx.get("sage_triage"):
+            issues = ctx["sage_triage"].get("issues", [])
+            lines.append(f"🔍 Sage: {len(issues)} issues triaged")
+
+        okr = ctx.get("okr_progress", {})
+        audit = okr.get("brand_audit", {})
+        if audit:
+            score = audit.get("overall_score", "?")
+            lines.append(f"🛡️ Sentinel: brand score {score}/100")
+
+        return "\n".join(lines)
+
+    def _format_weekly_telegram(self, ctx: dict[str, Any]) -> str:
+        """Format a full weekly Telegram report."""
+        lines = [f"📋 *Weekly Report — {ctx.get('week_of', '')}*\n"]
+
+        okr = ctx.get("okr_progress", {})
+        lines.append(f"Content produced: {'✅' if okr.get('content_produced') else '❌'}")
+        lines.append(f"Issues triaged: {okr.get('issues_triaged', 0)}")
+        lines.append(f"Social mentions: {okr.get('social_mentions_found', 0)}")
+        lines.append(f"Themes found: {okr.get('themes_identified', 0)}")
+        lines.append(f"Experiments designed: {okr.get('experiments_designed', 0)}")
+        lines.append(f"Competitors analyzed: {okr.get('competitors_analyzed', 0)}")
+
+        health = okr.get("pre_health", {})
+        if health:
+            lines.append(f"\n🏥 Health: {health.get('overall_score', '?')}/100")
+            for alert in health.get("alerts", [])[:3]:
+                lines.append(f"  ⚠️ {alert}")
+
+        return "\n".join(lines)
+
+    def _format_daily_email(self, ctx: dict[str, Any]) -> str:
+        """Format a daily email digest as HTML."""
+        sections = []
+
+        if ctx.get("kai_content"):
+            kai = ctx["kai_content"]
+            rev = kai.get("revision", {})
+            sections.append(f"""
+            <div style="border-left:4px solid #4CAF50;padding-left:16px;margin:16px 0">
+                <h3 style="margin:0">✍️ Kai — Content</h3>
+                <p><b>Task:</b> {kai.get("task", "N/A")[:100]}</p>
+                <p><b>Quality score:</b> {rev.get("final_score", "N/A")}/10
+                   ({rev.get("rounds", 0)} revision rounds)</p>
+            </div>""")
+
+        if ctx.get("echo_social"):
+            echo = ctx["echo_social"]
+            sections.append(f"""
+            <div style="border-left:4px solid #2196F3;padding-left:16px;margin:16px 0">
+                <h3 style="margin:0">👂 Echo — Social</h3>
+                <p><b>Mentions:</b> {echo.get("total_mentions", 0)}</p>
+            </div>""")
+
+        body = "\n".join(sections) if sections else "<p>No content generated today.</p>"
+        return f"""
+        <html><body style="font-family:system-ui,sans-serif;max-width:600px;margin:0 auto">
+            <h2>Daily Content Digest</h2>
+            {body}
+        </body></html>"""
+
+    def _format_weekly_email(self, ctx: dict[str, Any]) -> str:
+        """Format a weekly email report as HTML."""
+        okr = ctx.get("okr_progress", {})
+        audit = okr.get("brand_audit", {})
+
+        return f"""
+        <html><body style="font-family:system-ui,sans-serif;max-width:600px;margin:0 auto">
+            <h2>Weekly Agent Report — {ctx.get("week_of", "")}</h2>
+            <table style="width:100%;border-collapse:collapse">
+                <tr><td style="padding:8px;border-bottom:1px solid #eee"><b>Content produced</b></td>
+                    <td style="padding:8px;border-bottom:1px solid #eee">{"✅" if okr.get("content_produced") else "❌"}</td></tr>
+                <tr><td style="padding:8px;border-bottom:1px solid #eee"><b>Issues triaged</b></td>
+                    <td style="padding:8px;border-bottom:1px solid #eee">{okr.get("issues_triaged", 0)}</td></tr>
+                <tr><td style="padding:8px;border-bottom:1px solid #eee"><b>Social mentions</b></td>
+                    <td style="padding:8px;border-bottom:1px solid #eee">{okr.get("social_mentions_found", 0)}</td></tr>
+                <tr><td style="padding:8px;border-bottom:1px solid #eee"><b>Themes identified</b></td>
+                    <td style="padding:8px;border-bottom:1px solid #eee">{okr.get("themes_identified", 0)}</td></tr>
+                <tr><td style="padding:8px;border-bottom:1px solid #eee"><b>Experiments</b></td>
+                    <td style="padding:8px;border-bottom:1px solid #eee">{okr.get("experiments_designed", 0)}</td></tr>
+                <tr><td style="padding:8px;border-bottom:1px solid #eee"><b>Brand audit score</b></td>
+                    <td style="padding:8px;border-bottom:1px solid #eee">{audit.get("overall_score", "N/A")}/100</td></tr>
+            </table>
+        </body></html>"""

devrel_origin/tools/run_report.py

@@ -0,0 +1,193 @@
+"""
+Run Report — Structured observability for weekly pipeline cycles.
+
+Generates a JSON report after each cycle with timing, cost, quality,
+and error data. Stored alongside context archives for post-hoc analysis.
+"""
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentTiming:
+    """Timing data for a single agent delegation."""
+
+    agent: str
+    stage: int
+    started_at: str = ""
+    completed_at: str = ""
+    duration_seconds: float = 0.0
+    success: bool = True
+    error: str = ""
+
+
+@dataclass
+class RunReport:
+    """Complete run report for a weekly cycle."""
+
+    week_of: str = ""
+    started_at: str = ""
+    completed_at: str = ""
+    duration_seconds: float = 0.0
+    resumed_from_stage: int = 0
+    stages_completed: int = 0
+    agent_timings: list[AgentTiming] = field(default_factory=list)
+    cost: dict[str, Any] = field(default_factory=dict)
+    quality: dict[str, Any] = field(default_factory=dict)
+    health: dict[str, Any] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "week_of": self.week_of,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "duration_seconds": round(self.duration_seconds, 1),
+            "resumed_from_stage": self.resumed_from_stage,
+            "stages_completed": self.stages_completed,
+            "agent_timings": [
+                {
+                    "agent": t.agent,
+                    "stage": t.stage,
+                    "duration_seconds": round(t.duration_seconds, 1),
+                    "success": t.success,
+                    "error": t.error,
+                }
+                for t in self.agent_timings
+            ],
+            "cost": self.cost,
+            "quality": self.quality,
+            "health": self.health,
+            "errors": self.errors,
+        }
+
+    def save(self, archive_dir: Path) -> Path:
+        """Save report alongside context archive."""
+        archive_dir.mkdir(parents=True, exist_ok=True)
+        filepath = archive_dir / f"run_report_{self.week_of}.json"
+        filepath.write_text(json.dumps(self.to_dict(), indent=2))
+        logger.info(f"Run report saved: {filepath}")
+        return filepath
+
+    @classmethod
+    def load(cls, archive_dir: Path, week_of: str = "") -> "RunReport | None":
+        """Load a run report by week, or the most recent one."""
+        if week_of:
+            filepath = archive_dir / f"run_report_{week_of}.json"
+            if filepath.exists():
+                data = json.loads(filepath.read_text())
+                return cls._from_dict(data)
+            return None
+
+        # Find most recent
+        files = sorted(archive_dir.glob("run_report_*.json"), reverse=True)
+        if not files:
+            return None
+        data = json.loads(files[0].read_text())
+        return cls._from_dict(data)
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "RunReport":
+        report = cls(
+            week_of=data.get("week_of", ""),
+            started_at=data.get("started_at", ""),
+            completed_at=data.get("completed_at", ""),
+            duration_seconds=data.get("duration_seconds", 0),
+            resumed_from_stage=data.get("resumed_from_stage", 0),
+            stages_completed=data.get("stages_completed", 0),
+            cost=data.get("cost", {}),
+            quality=data.get("quality", {}),
+            health=data.get("health", {}),
+            errors=data.get("errors", []),
+        )
+        for t in data.get("agent_timings", []):
+            report.agent_timings.append(
+                AgentTiming(
+                    agent=t["agent"],
+                    stage=t.get("stage", 0),
+                    duration_seconds=t.get("duration_seconds", 0),
+                    success=t.get("success", True),
+                    error=t.get("error", ""),
+                )
+            )
+        return report
+
+    def summary(self) -> str:
+        """Human-readable summary for CLI output."""
+        lines = [
+            f"Run Report — {self.week_of}",
+            f"Duration: {self.duration_seconds:.0f}s"
+            f"  |  Stages: {self.stages_completed}"
+            f"  |  Resume: {self.resumed_from_stage}",
+            "",
+        ]
+
+        # Cost
+        cost = self.cost
+        if cost:
+            lines.append(
+                f"Cost: ${cost.get('total_cost_usd', 0):.4f} "
+                f"/ ${cost.get('budget_limit_usd', 0):.2f} budget"
+            )
+            per_agent = cost.get("per_agent", {})
+            if per_agent:
+                sorted_agents = sorted(
+                    per_agent.items(),
+                    key=lambda x: x[1].get("cost_usd", 0),
+                    reverse=True,
+                )
+                for name, data in sorted_agents[:5]:
+                    lines.append(
+                        f"  {name}: ${data.get('cost_usd', 0):.4f} ({data.get('calls', 0)} calls)"
+                    )
+
+        # Quality
+        quality = self.quality
+        if quality:
+            lines.append("")
+            lines.append(f"Quality: Sentinel score {quality.get('sentinel_score', 'N/A')}/100")
+            for agent, rev in quality.get("revision_traces", {}).items():
+                lines.append(
+                    f"  {agent}: score {rev.get('final_score', '?')}/10 "
+                    f"({rev.get('rounds', 0)} revisions)"
+                )
+
+        # Errors
+        if self.errors:
+            lines.append("")
+            lines.append(f"Errors ({len(self.errors)}):")
+            for err in self.errors[:5]:
+                lines.append(f"  - {err}")
+
+        return "\n".join(lines)
+
+
+def main() -> None:
+    """CLI: view run reports."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="View pipeline run reports")
+    parser.add_argument("--week", default="", help="Week to view (e.g., 2026-W14)")
+    parser.add_argument("--archive", default="context_archive", help="Archive directory")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    args = parser.parse_args()
+
+    report = RunReport.load(Path(args.archive), args.week)
+    if not report:
+        print("No run report found.")
+        return
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(report.summary())
+
+
+if __name__ == "__main__":
+    main()

devrel_origin/tools/scheduler.py

@@ -0,0 +1,231 @@
+"""
+Scheduler — Cron-based agent pipeline scheduling.
+
+Manages the weekly agent cascade schedule. Can install/remove system
+crontab entries or run as a standalone loop.
+"""
+
+import asyncio
+import logging
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScheduleEntry:
+    """A single scheduled agent run."""
+
+    name: str
+    cron: str  # Cron expression (e.g., "0 9 * * 1")
+    command: str  # Full command to execute
+    description: str = ""
+    enabled: bool = True
+
+
+# Default weekly schedule matching the cascade system
+DEFAULT_SCHEDULE: list[dict[str, str]] = [
+    {
+        "name": "weekly_cycle",
+        "cron": "0 9 * * 1",  # Monday 9am
+        "command": "python -m devrel_origin.core.atlas --weekly-cycle",
+        "description": "Full weekly pipeline",
+    },
+    {
+        "name": "daily_digest",
+        "cron": "0 13 * * 1-5",  # Mon-Fri 1pm
+        "command": "python -m devrel_origin.tools.scheduler --action digest --mode daily",
+        "description": "Daily content digest email + telegram",
+    },
+    {
+        "name": "weekly_report",
+        "cron": "0 17 * * 5",  # Friday 5pm
+        "command": "python -m devrel_origin.tools.scheduler --action digest --mode weekly",
+        "description": "Weekly report email + telegram",
+    },
+]
+
+
+class Scheduler:
+    """Manages cron-based agent scheduling.
+
+    Can install entries into the system crontab or run as a standalone
+    asyncio loop for environments without cron access.
+
+    Usage::
+
+        sched = Scheduler(project_dir="/path/to/devrel-origin")
+        sched.install_cron()  # Write to system crontab
+        sched.list_entries()  # Show current schedule
+        sched.remove_cron()   # Clean up
+    """
+
+    CRON_TAG = "# devrel-origin-agent"
+
+    def __init__(
+        self,
+        project_dir: str = ".",
+        schedule: list[dict[str, str]] | None = None,
+        python_path: str = "",
+    ):
+        self.project_dir = Path(project_dir).resolve()
+        self.python_path = python_path or sys.executable
+        self.entries = [ScheduleEntry(**entry) for entry in (schedule or DEFAULT_SCHEDULE)]
+
+    def _build_cron_line(self, entry: ScheduleEntry) -> str:
+        """Build a crontab line from a schedule entry."""
+        cmd = entry.command
+        if not cmd.startswith("/"):
+            cmd = f"cd {self.project_dir} && {self.python_path} -m {cmd.split('python -m ')[-1]}"
+        return f"{entry.cron} {cmd} {self.CRON_TAG} {entry.name}"
+
+    def get_current_crontab(self) -> str:
+        """Read the current user crontab."""
+        try:
+            result = subprocess.run(
+                ["crontab", "-l"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            return result.stdout if result.returncode == 0 else ""
+        except FileNotFoundError:
+            logger.warning("crontab not available on this system")
+            return ""
+
+    def install_cron(self) -> list[str]:
+        """Install schedule entries into the system crontab.
+
+        Removes existing devrel-origin entries first to prevent duplicates.
+        Returns the list of installed cron lines.
+        """
+        current = self.get_current_crontab()
+
+        # Remove existing devrel-origin entries
+        cleaned_lines = [line for line in current.splitlines() if self.CRON_TAG not in line]
+
+        # Add new entries
+        new_lines = []
+        for entry in self.entries:
+            if entry.enabled:
+                line = self._build_cron_line(entry)
+                new_lines.append(line)
+
+        all_lines = cleaned_lines + new_lines
+        new_crontab = "\n".join(all_lines) + "\n"
+
+        try:
+            subprocess.run(
+                ["crontab", "-"],
+                input=new_crontab,
+                text=True,
+                check=True,
+            )
+            logger.info(f"Installed {len(new_lines)} cron entries")
+        except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+            logger.warning(f"Failed to install crontab: {exc}")
+
+        return new_lines
+
+    def remove_cron(self) -> None:
+        """Remove all devrel-origin entries from the crontab."""
+        current = self.get_current_crontab()
+        cleaned = [line for line in current.splitlines() if self.CRON_TAG not in line]
+        new_crontab = "\n".join(cleaned) + "\n"
+
+        try:
+            subprocess.run(
+                ["crontab", "-"],
+                input=new_crontab,
+                text=True,
+                check=True,
+            )
+            logger.info("Removed all devrel-origin cron entries")
+        except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+            logger.warning(f"Failed to update crontab: {exc}")
+
+    def list_entries(self) -> list[dict[str, Any]]:
+        """List all configured schedule entries."""
+        return [
+            {
+                "name": e.name,
+                "cron": e.cron,
+                "description": e.description,
+                "enabled": e.enabled,
+                "command": e.command,
+            }
+            for e in self.entries
+        ]
+
+
+async def run_digest(mode: str = "daily") -> None:
+    """CLI entry point for sending content digests."""
+    import os
+
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+    from devrel_origin.tools.notifications import NotificationConfig, NotificationService
+
+    config = NotificationConfig(
+        telegram_bot_token=os.environ.get("TELEGRAM_BOT_TOKEN", ""),
+        telegram_chat_id=os.environ.get("TELEGRAM_CHAT_ID", ""),
+        email_sender=os.environ.get("EMAIL_SENDER", ""),
+        email_password=os.environ.get("EMAIL_PASSWORD", ""),
+        email_recipients=(
+            os.environ.get("EMAIL_RECIPIENTS", "").split(",")
+            if os.environ.get("EMAIL_RECIPIENTS")
+            else None
+        ),
+    )
+
+    from devrel_origin.core.atlas import SharedContext
+
+    archive_dir = Path(os.environ.get("CONTEXT_ARCHIVE", "context_archive"))
+    ctx = SharedContext.load(archive_dir)
+
+    svc = NotificationService(config)
+    try:
+        result = await svc.send_digest(ctx.to_dict(), mode=mode)
+        logger.info(f"Digest sent: {result}")
+    finally:
+        await svc.close()
+
+
+def main() -> None:
+    """CLI entry point for scheduler operations."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="devrel-origin scheduler")
+    parser.add_argument(
+        "--action",
+        choices=["install", "remove", "list", "digest"],
+        required=True,
+    )
+    parser.add_argument("--mode", default="daily", choices=["daily", "weekly"])
+    args = parser.parse_args()
+
+    if args.action == "digest":
+        asyncio.run(run_digest(args.mode))
+    elif args.action == "install":
+        sched = Scheduler()
+        lines = sched.install_cron()
+        for line in lines:
+            print(f"  {line}")
+    elif args.action == "remove":
+        sched = Scheduler()
+        sched.remove_cron()
+    elif args.action == "list":
+        sched = Scheduler()
+        for entry in sched.list_entries():
+            status = "✓" if entry["enabled"] else "✗"
+            print(f"  [{status}] {entry['name']}: {entry['cron']} — {entry['description']}")
+
+
+if __name__ == "__main__":
+    main()