devrel-swarm 0.2.4__py3-none-any.whl

devrel_swarm/__init__.py

@@ -0,0 +1,8 @@
+"""devrel-swarm — DevRel + Sales + Marketing agent system."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("devrel-swarm")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

devrel_swarm/cli/__init__.py

@@ -0,0 +1,82 @@
+"""Typer CLI app for devrel-swarm.
+
+Phase 2 registers `init` and `doctor`. Later phases register additional
+verb groups (run, content, sales, marketing, etc.).
+"""
+
+from __future__ import annotations
+
+import typer
+
+from devrel_swarm import __version__
+from devrel_swarm.cli.analytics import analytics_app
+from devrel_swarm.cli.config import config_app
+from devrel_swarm.cli.content import content_app
+from devrel_swarm.cli.cost import cost_command
+from devrel_swarm.cli.deliverables import deliverables_app
+from devrel_swarm.cli.docs import docs_app
+from devrel_swarm.cli.doctor import doctor_command
+from devrel_swarm.cli.experiment import experiment_command
+from devrel_swarm.cli.init import init_command
+from devrel_swarm.cli.intel import intel_command
+from devrel_swarm.cli.kb import kb_app
+from devrel_swarm.cli.listen import listen_command
+from devrel_swarm.cli.marketing import marketing_app
+from devrel_swarm.cli.run import run_command
+from devrel_swarm.cli.sales import sales_app
+from devrel_swarm.cli.schedule import schedule_app
+from devrel_swarm.cli.synthesize import synthesize_command
+from devrel_swarm.cli.triage import triage_command
+from devrel_swarm.cli.video import video_app
+
+app = typer.Typer(
+    name="devrel",
+    help="DevRel + Sales + Marketing agent system. Run from inside a project repo.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"devrel-swarm {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Root callback. Subcommands are registered below."""
+    return None
+
+
+app.command(name="init")(init_command)
+app.command(name="doctor")(doctor_command)
+app.add_typer(content_app, name="content")
+app.command(name="run")(run_command)
+app.command(name="triage")(triage_command)
+app.command(name="listen")(listen_command)
+app.command(name="synthesize")(synthesize_command)
+app.command(name="experiment")(experiment_command)
+app.command(name="intel")(intel_command)
+app.add_typer(sales_app, name="sales")
+app.add_typer(marketing_app, name="marketing")
+app.add_typer(kb_app, name="kb")
+app.add_typer(schedule_app, name="schedule")
+app.command(name="cost")(cost_command)
+app.add_typer(deliverables_app, name="deliverables")
+app.add_typer(config_app, name="config")
+app.add_typer(docs_app, name="docs")
+app.add_typer(video_app, name="video")
+app.add_typer(analytics_app, name="analytics")
+
+
+if __name__ == "__main__":
+    app()

devrel_swarm/cli/_common.py

@@ -0,0 +1,62 @@
+"""Shared CLI helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import typer
+from rich.console import Console
+
+from devrel_swarm.core.atlas import Atlas, DelegationResult
+from devrel_swarm.core.llm import LLMClient
+from devrel_swarm.project.paths import ProjectNotFoundError, ProjectPaths, find_devrel_root
+
+
+def find_paths_or_exit(console: Console) -> ProjectPaths:
+    try:
+        return ProjectPaths.from_root(find_devrel_root())
+    except ProjectNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=1) from None
+
+
+def build_atlas_or_exit(paths: ProjectPaths, console: Console) -> Atlas:
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        console.print("[red]ANTHROPIC_API_KEY is required.[/red]")
+        raise typer.Exit(code=1)
+    llm = LLMClient(api_key=api_key)
+    try:
+        return Atlas(llm_client=llm, project_paths=paths)
+    except TypeError:
+        # Atlas may not yet accept project_paths kwarg.
+        return Atlas(llm_client=llm)
+
+
+def render_result(result: DelegationResult, console: Console, *, json_output: bool = False) -> None:
+    if json_output:
+        # DelegationResult is a dataclass; convert via dict()/asdict.
+        from dataclasses import asdict
+
+        try:
+            payload = asdict(result)
+        except TypeError:
+            payload = {
+                "agent": getattr(result, "agent", "?"),
+                "task": getattr(result, "task", "?"),
+                "success": getattr(result, "success", False),
+                "result": getattr(result, "result", None),
+                "error": getattr(result, "error", None),
+            }
+        typer.echo(json.dumps(payload, default=str, indent=2))
+        return
+    if not result.success:
+        console.print(f"[red]✗[/red] {result.agent} failed: {result.error}")
+        raise typer.Exit(code=1)
+    console.print(f"[green]✓[/green] {result.agent} completed")
+    if isinstance(result.result, dict):
+        for k, v in list(result.result.items())[:8]:
+            console.print(f"  [dim]{k}:[/dim] {str(v)[:120]}")
+    elif result.result:
+        console.print(f"  {str(result.result)[:300]}")

devrel_swarm/cli/analytics.py

@@ -0,0 +1,497 @@
+"""`devrel analytics report` — Argus performance report.
+
+Pulls the last N days of metrics from PostHog, GitHub, Instantly, and
+Echo's social_mentions; ranks deterministically; emits structured
+recommendations via a single Sonnet call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devrel_swarm.cli._common import find_paths_or_exit
+from devrel_swarm.core.argus import (
+    Argus,
+    PerformanceReport,
+    compute_calibration,
+    write_recommendation_briefs,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+analytics_app = typer.Typer(
+    name="analytics",
+    help="Content performance analysis (Argus).",
+    no_args_is_help=True,
+)
+
+
+_SINCE_RE = re.compile(r"^(\d+)([dwmy])$")
+
+
+def _parse_since(since: str) -> timedelta:
+    """Accept '7d' / '30d' / '12w' / '3m' / '1y'."""
+    m = _SINCE_RE.match(since.strip())
+    if not m:
+        raise typer.BadParameter(f"--since must look like '7d', '30d', '12w': got {since!r}")
+    n, unit = int(m.group(1)), m.group(2)
+    days = {"d": 1, "w": 7, "m": 30, "y": 365}[unit]
+    return timedelta(days=n * days)
+
+
+def _build_argus(state_db_path: Path) -> Argus:
+    """Construct Argus with real collectors. Patched in unit tests."""
+    import os
+
+    from devrel_swarm.core.llm import LLMClient
+    from devrel_swarm.tools.analytics import (
+        GitHubCollector,
+        InstantlyCollector,
+        PostHogCollector,
+        SocialCollector,
+    )
+    from devrel_swarm.tools.api_client import PostHogClient
+    from devrel_swarm.tools.github_tools import GitHubTools
+    from devrel_swarm.tools.instantly_client import InstantlyClient
+
+    posthog_client = PostHogClient(
+        api_key=os.environ.get("POSTHOG_API_KEY", ""),
+        project_id=os.environ.get("POSTHOG_PROJECT_ID", ""),
+    )
+    github_client = GitHubTools(token=os.environ.get("GITHUB_TOKEN", ""))
+    instantly_client = InstantlyClient(
+        api_key=os.environ.get("INSTANTLY_API_KEY", ""),
+    )
+
+    llm = LLMClient(api_key=os.environ.get("ANTHROPIC_API_KEY", ""))
+    llm.set_agent("argus")
+    if state_db_path.is_file():
+        from devrel_swarm.project.cost_sink import make_sqlite_sink
+
+        llm.set_cost_sink(make_sqlite_sink(state_db_path))
+
+    return Argus(
+        posthog_collector=PostHogCollector(posthog_client),
+        github_collector=GitHubCollector(github_client),
+        instantly_collector=InstantlyCollector(instantly_client),
+        social_collector=SocialCollector(state_db_path),
+        llm_client=llm,
+        state_db_path=state_db_path,
+    )
+
+
+def _write_markdown_deliverable(
+    report: PerformanceReport,
+    deliverables_dir: Path,
+) -> Path:
+    deliverables_dir.mkdir(parents=True, exist_ok=True)
+    out = deliverables_dir / f"analytics-{report.period_end.date().isoformat()}.md"
+    out.write_text(report.to_markdown(), encoding="utf-8")
+    return out
+
+
+@analytics_app.command("summary")
+def summary_command(
+    root: str = typer.Option(
+        "~", "--root", help="Root to scan for .devrel/ directories. Default: $HOME."
+    ),
+    format_: str = typer.Option("md", "--format", help="md or json."),
+    max_depth: int = typer.Option(
+        4, "--max-depth", help="Max directory depth to descend (avoids slow $HOME walks)."
+    ),
+) -> None:
+    """Aggregate Argus reports across every .devrel/ project under a root.
+
+    Walks the filesystem looking for ``.devrel/state.db`` files (capped at
+    --max-depth) and reports total spend, total recommendations, and the
+    most recent report per project.
+    """
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.is_dir():
+        console.print(f"[red]{root_path} is not a directory.[/red]")
+        raise typer.Exit(code=1)
+
+    projects: list[dict] = []
+    for state_db in _walk_for_state_dbs(root_path, max_depth):
+        info = _summarize_project_db(state_db)
+        if info:
+            projects.append(info)
+
+    if format_ == "json":
+        sys.stdout.write(json.dumps(projects, indent=2, default=str))
+        sys.stdout.write("\n")
+        return
+
+    if format_ != "md":
+        raise typer.BadParameter("--format must be 'md' or 'json'")
+
+    lines = [f"# Argus cross-project summary — {len(projects)} projects under {root_path}", ""]
+    if not projects:
+        lines.append("_No .devrel/state.db files found._")
+        sys.stdout.write("\n".join(lines) + "\n")
+        return
+    lines.append("| project | last_report | total_recs | total_metrics | spend_usd |")
+    lines.append("|---|---|---|---|---|")
+    for p in sorted(projects, key=lambda x: x["last_report"] or "", reverse=True):
+        lines.append(
+            f"| {p['project']} | {(p['last_report'] or '—')[:10]} | "
+            f"{p['total_recs']} | {p['total_metrics']} | ${p['spend_usd']:.2f} |"
+        )
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+def _walk_for_state_dbs(root: Path, max_depth: int):
+    """Yield every state.db at root/**/.devrel/state.db up to max_depth.
+
+    Skips dot-directories other than .devrel (so ~/.cache, ~/.config etc
+    don't slow the walk to a crawl)."""
+
+    def _walk(dir_: Path, depth: int):
+        if depth > max_depth:
+            return
+        try:
+            entries = list(dir_.iterdir())
+        except PermissionError:
+            return
+        for child in entries:
+            if not child.is_dir():
+                continue
+            if child.name == ".devrel":
+                state_db = child / "state.db"
+                if state_db.is_file():
+                    yield state_db
+                continue
+            if child.name.startswith("."):
+                continue
+            yield from _walk(child, depth + 1)
+
+    yield from _walk(root, 0)
+
+
+def _summarize_project_db(state_db: Path) -> dict | None:
+    """Return per-project rollup or None if the DB has no Argus tables."""
+    try:
+        from devrel_swarm.project.state import open_db
+
+        with open_db(state_db) as conn:
+            try:
+                last_row = conn.execute(
+                    "SELECT MAX(period_end) AS p FROM analytics_reports"
+                ).fetchone()
+                rec_row = conn.execute(
+                    "SELECT COUNT(*) AS c FROM analytics_recommendations"
+                ).fetchone()
+                hist_row = conn.execute("SELECT COUNT(*) AS c FROM metric_history").fetchone()
+            except Exception:  # noqa: BLE001 — table missing means not an Argus project
+                return None
+            cost_row = conn.execute(
+                "SELECT COALESCE(SUM(cost_usd), 0.0) AS total FROM costs WHERE agent = 'argus'"
+            ).fetchone()
+    except Exception:  # noqa: BLE001
+        return None
+
+    return {
+        "project": str(state_db.parent.parent),
+        "last_report": last_row["p"] if last_row else None,
+        "total_recs": int(rec_row["c"]) if rec_row else 0,
+        "total_metrics": int(hist_row["c"]) if hist_row else 0,
+        "spend_usd": float(cost_row["total"]) if cost_row else 0.0,
+    }
+
+
+@analytics_app.command("history")
+def history_command(
+    content_id: str = typer.Argument(
+        ..., help="Content ID to show history for (e.g., 'blog/cli-launch')."
+    ),
+    format_: str = typer.Option("md", "--format", help="md or json."),
+) -> None:
+    """Show the metric trajectory of one piece of content across reports."""
+    paths = find_paths_or_exit(console)
+    if format_ not in {"md", "json"}:
+        raise typer.BadParameter("--format must be 'md' or 'json'")
+
+    from devrel_swarm.project.state import open_db
+
+    if not paths.state_db.is_file():
+        console.print("[yellow]No state.db yet. Run 'devrel analytics report' first.[/yellow]")
+        raise typer.Exit(code=1)
+
+    with open_db(paths.state_db) as conn:
+        rows = conn.execute(
+            "SELECT period_end, primary_metric, metric_name, content_type "
+            "FROM metric_history WHERE content_id = ? ORDER BY period_end ASC",
+            (content_id,),
+        ).fetchall()
+
+    if not rows:
+        console.print(f"[yellow]No history for content_id={content_id}[/yellow]")
+        raise typer.Exit(code=1)
+
+    if format_ == "json":
+        sys.stdout.write(
+            json.dumps(
+                [
+                    {
+                        "period_end": r["period_end"],
+                        "primary_metric": r["primary_metric"],
+                        "metric_name": r["metric_name"],
+                        "content_type": r["content_type"],
+                    }
+                    for r in rows
+                ],
+                indent=2,
+            )
+        )
+        sys.stdout.write("\n")
+        return
+
+    # Markdown
+    lines = [f"# History for `{content_id}` ({rows[0]['content_type']})", ""]
+    metric_name = rows[0]["metric_name"]
+    lines.append(f"| period_end | {metric_name} | delta |")
+    lines.append("|---|---|---|")
+    prev = None
+    for r in rows:
+        v = r["primary_metric"]
+        if prev is None:
+            delta = "—"
+        else:
+            d = ((v - prev) / prev * 100) if prev else 0.0
+            delta = f"{d:+.1f}%"
+        lines.append(f"| {r['period_end'][:10]} | {v:g} | {delta} |")
+        prev = v
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+@analytics_app.command("diff")
+def diff_command(
+    period_a: str = typer.Argument(..., help="Earlier period (YYYY-MM-DD or full ISO)."),
+    period_b: str = typer.Argument(..., help="Later period (YYYY-MM-DD or full ISO)."),
+    format_: str = typer.Option("md", "--format", help="md or json."),
+    limit: int = typer.Option(20, "--limit", help="Top N changes by absolute delta."),
+) -> None:
+    """Compare two periods side-by-side. Shows the top movers (gainers + losers).
+
+    Periods are matched against metric_history.period_end with a prefix
+    match: '2026-04-25' matches any timestamp starting with that date.
+    """
+    paths = find_paths_or_exit(console)
+    if format_ not in {"md", "json"}:
+        raise typer.BadParameter("--format must be 'md' or 'json'")
+
+    from devrel_swarm.project.state import open_db
+
+    if not paths.state_db.is_file():
+        console.print("[yellow]No state.db. Run 'devrel analytics report' first.[/yellow]")
+        raise typer.Exit(code=1)
+
+    with open_db(paths.state_db) as conn:
+        a_rows = conn.execute(
+            "SELECT content_id, primary_metric, metric_name, content_type "
+            "FROM metric_history WHERE period_end LIKE ?",
+            (f"{period_a}%",),
+        ).fetchall()
+        b_rows = conn.execute(
+            "SELECT content_id, primary_metric, metric_name, content_type "
+            "FROM metric_history WHERE period_end LIKE ?",
+            (f"{period_b}%",),
+        ).fetchall()
+
+    if not a_rows or not b_rows:
+        console.print(
+            f"[yellow]No history for one or both periods (a={len(a_rows)}, b={len(b_rows)}).[/yellow]"
+        )
+        raise typer.Exit(code=1)
+
+    a_by_id = {r["content_id"]: r for r in a_rows}
+    b_by_id = {r["content_id"]: r for r in b_rows}
+
+    rows: list[dict] = []
+    for cid in set(a_by_id) | set(b_by_id):
+        a_val = a_by_id.get(cid, {"primary_metric": None})["primary_metric"]
+        b_val = b_by_id.get(cid, {"primary_metric": None})["primary_metric"]
+        if a_val is None and b_val is not None:
+            kind, delta_pct = "new", None
+            sort_key = b_val
+        elif a_val is not None and b_val is None:
+            kind, delta_pct = "gone", None
+            sort_key = a_val
+        else:
+            kind = "changed"
+            delta_pct = ((b_val - a_val) / a_val * 100.0) if a_val else 0.0
+            sort_key = abs(delta_pct)
+        rows.append(
+            {
+                "content_id": cid,
+                "kind": kind,
+                "a": a_val,
+                "b": b_val,
+                "delta_pct": delta_pct,
+                "_sort": sort_key,
+                "metric_name": (a_by_id.get(cid) or b_by_id[cid])["metric_name"],
+            }
+        )
+
+    rows.sort(key=lambda r: r["_sort"] or 0, reverse=True)
+    rows = rows[:limit]
+
+    if format_ == "json":
+        payload = [{k: v for k, v in r.items() if not k.startswith("_")} for r in rows]
+        sys.stdout.write(json.dumps(payload, indent=2))
+        sys.stdout.write("\n")
+        return
+
+    lines = [f"# Diff: {period_a} → {period_b}", ""]
+    lines.append("| content_id | kind | a | b | delta |")
+    lines.append("|---|---|---|---|---|")
+    for r in rows:
+        a_disp = f"{r['a']:g}" if r["a"] is not None else "—"
+        b_disp = f"{r['b']:g}" if r["b"] is not None else "—"
+        d_disp = f"{r['delta_pct']:+.1f}%" if r["delta_pct"] is not None else "—"
+        lines.append(f"| {r['content_id']} | {r['kind']} | {a_disp} | {b_disp} | {d_disp} |")
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+@analytics_app.command("calibration")
+def calibration_command(
+    format_: str = typer.Option("md", "--format", help="md or json."),
+) -> None:
+    """Show how well past Argus recommendations have actually panned out.
+
+    Scores each historical double_down/retire recommendation against the
+    metric_history observations recorded after first_seen_period. Other
+    actions are counted as 'unscored' (no clean post-hoc test).
+    """
+    paths = find_paths_or_exit(console)
+    if format_ not in {"md", "json"}:
+        raise typer.BadParameter("--format must be 'md' or 'json'")
+
+    if not paths.state_db.is_file():
+        console.print("[yellow]No state.db. Run 'devrel analytics report' first.[/yellow]")
+        raise typer.Exit(code=1)
+
+    cal = compute_calibration(paths.state_db)
+    if format_ == "json":
+        sys.stdout.write(json.dumps(cal, indent=2))
+        sys.stdout.write("\n")
+        return
+
+    lines = ["# Argus calibration", ""]
+    lines.append(f"- scored recommendations: **{cal['scored_recs']}**")
+    lines.append(
+        f"- unscored (insufficient post-period data or non-scoreable action): {cal['unscored_recs']}"
+    )
+    if cal.get("high_conf_rate") is not None:
+        lines.append(f"- high-confidence (≥0.8) hit rate: {cal['high_conf_rate']:.0%}")
+    if cal.get("low_conf_rate") is not None:
+        lines.append(f"- low-confidence (<0.5) hit rate: {cal['low_conf_rate']:.0%}")
+    lines.append("")
+    if not cal["by_action"]:
+        lines.append(
+            "_No scored recommendations yet. Calibration needs at least one rec with metric_history rows after its first_seen_period._"
+        )
+    else:
+        lines.append("| action | n | panned_out | rate | avg_conf | lift vs coin-flip |")
+        lines.append("|---|---|---|---|---|---|")
+        for action, stats in sorted(cal["by_action"].items()):
+            lines.append(
+                f"| {action} | {stats['n']} | {stats['panned_out']} | "
+                f"{stats['rate']:.0%} | {stats['avg_confidence']:.2f} | "
+                f"{stats['calibrated_lift']:+.2f} |"
+            )
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+@analytics_app.command("report")
+def report_command(
+    since: str = typer.Option("7d", "--since", help="Lookback window (e.g., 7d, 30d, 12w)."),
+    format_: str = typer.Option("md", "--format", help="stdout format: md or json."),
+    push: bool = typer.Option(False, "--push", help="Push the report to configured Slack/email."),
+    push_on_partial: bool = typer.Option(
+        False,
+        "--push-on-partial",
+        help="Override the all-green push gate. Push even if some sources failed.",
+    ),
+) -> None:
+    """Produce an Argus performance report for the last `--since` window."""
+    paths = find_paths_or_exit(console)
+    if format_ not in {"md", "json"}:
+        raise typer.BadParameter("--format must be 'md' or 'json'")
+
+    delta = _parse_since(since)
+    end = datetime.now(timezone.utc)
+    start = end - delta
+
+    argus = _build_argus(paths.state_db)
+    report = asyncio.run(argus.run(period_start=start, period_end=end))
+
+    out_path = _write_markdown_deliverable(report, paths.deliverables_dir)
+    err_console.print(f"[dim]Wrote deliverable: {out_path}[/dim]")
+
+    brief_paths = write_recommendation_briefs(report, paths.deliverables_dir)
+    if brief_paths:
+        err_console.print(
+            f"[dim]Wrote {len(brief_paths)} content brief(s) for actionable recs[/dim]"
+        )
+
+    if format_ == "json":
+        sys.stdout.write(json.dumps(report.to_json(), indent=2, default=str))
+        sys.stdout.write("\n")
+    else:
+        sys.stdout.write(report.to_markdown())
+
+    if push:
+        failed_sources = [k for k, v in report.sources_ok.items() if not v]
+        if failed_sources and not push_on_partial:
+            err_console.print(
+                f"[yellow]Skipping push: data is partial (failed sources: "
+                f"{', '.join(failed_sources)}). Pass --push-on-partial to override.[/yellow]"
+            )
+        else:
+            try:
+                asyncio.run(_push_report(report, end))
+            except Exception as exc:  # noqa: BLE001
+                err_console.print(f"[yellow]Push failed: {exc}[/yellow]")
+
+
+async def _push_report(report: PerformanceReport, end: datetime) -> None:
+    """Push the markdown report to Telegram + email if configured.
+
+    Builds a fresh NotificationConfig from env vars; matches how
+    devrel-swarm's other push paths construct the notification service.
+    """
+    import os
+
+    from devrel_swarm.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=[
+            r.strip() for r in os.environ.get("EMAIL_RECIPIENTS", "").split(",") if r.strip()
+        ]
+        or None,
+    )
+    svc = NotificationService(config)
+    try:
+        markdown = report.to_markdown()
+        subject = f"Argus report — {end.date().isoformat()}"
+        await svc.send_telegram(markdown[:4000])
+        await svc.send_email(subject, f"<pre>{markdown}</pre>")
+    finally:
+        await svc.close()