argus-code 0.2.0__py3-none-any.whl

argus/detectors/__init__.py

@@ -0,0 +1,6 @@
+"""Detectors — one module per finding type.
+
+Importing this module auto-imports every known detector so their
+``@register`` decorators run and the registry is populated.
+"""
+from . import tool_error_rate_spike  # noqa: F401

argus/detectors/base.py

@@ -0,0 +1,34 @@
+"""Detector contract.
+
+Detectors are pure: they read from a Repository and return findings.
+Writes are performed by the scheduler, not the detector. This split keeps
+detectors trivially unit-testable and the alerts table single-writer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from ..schema.types import AlertSeverity
+
+if TYPE_CHECKING:
+    from ..store.repository import Repository
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One alert-shaped result returned by a detector."""
+
+    detector: str
+    dedup_key: str
+    severity: AlertSeverity
+    title: str
+    message: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Detector(Protocol):
+    name: str
+
+    def detect(self, repo: "Repository", now_iso: str) -> list[Finding]: ...

argus/detectors/registry.py

@@ -0,0 +1,20 @@
+"""Detector registry. Mirrors argus.adapters.registry verbatim."""
+from __future__ import annotations
+
+from .base import Detector
+
+_REGISTRY: dict[str, type[Detector]] = {}
+
+
+def register(cls):
+    """Class decorator — adds ``cls`` to the registry by ``cls.name``."""
+    _REGISTRY[cls.name] = cls
+    return cls
+
+
+def available_detectors() -> list[Detector]:
+    return [cls() for cls in _REGISTRY.values()]
+
+
+def registered_detector_names() -> list[str]:
+    return list(_REGISTRY.keys())

argus/detectors/tool_error_rate_spike.py

@@ -0,0 +1,138 @@
+"""tool_error_rate_spike detector.
+
+For each tool, compares the trailing-7-day error rate (`window`) against
+the 28 days immediately before that (`baseline`). Fires a finding when:
+
+  - window_rate >= 2 * baseline_rate
+  - window_calls >= 20
+  - baseline_calls >= 20
+
+Severity ``warning`` for ratios in [2, 5), ``critical`` for >= 5. The
+20-call floor in each window suppresses the worst of the low-volume
+noise; deliberate decision to *not* add an absolute-rate floor on the
+ratio path for v1.
+
+Special case: a tool that had zero errors across the baseline but starts
+failing in the window (>= 5%) fires ``critical`` with a distinct title.
+That's the most informative behavior change and the pure-ratio rule can't
+express it (division by zero).
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
+
+from .base import Finding
+from .registry import register
+
+if TYPE_CHECKING:
+    from ..store.repository import Repository
+
+
+_WINDOW_DAYS = 7
+_BASELINE_DAYS = 28
+_MIN_CALLS = 20
+_WARNING_MULTIPLE = 2.0
+_CRITICAL_MULTIPLE = 5.0
+_ZERO_BASELINE_MIN_WINDOW_RATE = 0.05  # 5%
+
+
+def _iso_at_offset(now_iso: str, days_ago: float) -> str:
+    base = datetime.fromisoformat(now_iso.replace("Z", "+00:00"))
+    if base.tzinfo is None:
+        base = base.replace(tzinfo=timezone.utc)
+    return (base - timedelta(days=days_ago)).isoformat().replace("+00:00", "Z")
+
+
+@register
+class ToolErrorRateSpikeDetector:
+    name = "tool_error_rate_spike"
+
+    def detect(self, repo: "Repository", now_iso: str) -> list[Finding]:
+        window_start = _iso_at_offset(now_iso, _WINDOW_DAYS)
+        baseline_start = _iso_at_offset(now_iso, _WINDOW_DAYS + _BASELINE_DAYS)
+
+        window_rows = repo.tool_call_stats_in_range(
+            start_iso=window_start, end_iso=now_iso
+        )
+        baseline_rows = repo.tool_call_stats_in_range(
+            start_iso=baseline_start, end_iso=window_start
+        )
+        baseline_by_tool = {r["tool_name"]: r for r in baseline_rows}
+
+        findings: list[Finding] = []
+        for w in window_rows:
+            tool = w["tool_name"]
+            window_calls = int(w["calls"])
+            window_errors = int(w["errors"])
+            if window_calls < _MIN_CALLS:
+                continue
+
+            b = baseline_by_tool.get(tool)
+            if b is None:
+                continue
+            baseline_calls = int(b["calls"])
+            baseline_errors = int(b["errors"])
+            if baseline_calls < _MIN_CALLS:
+                continue
+
+            window_rate = window_errors / window_calls
+            baseline_rate = baseline_errors / baseline_calls
+
+            if baseline_rate == 0:
+                # "Broke from zero" — a previously-clean tool starting to
+                # fail. Fire critical when window_rate clears the noise
+                # floor; the call-count gates above already guarantee
+                # statistical relevance.
+                if window_rate < _ZERO_BASELINE_MIN_WINDOW_RATE:
+                    continue
+                findings.append(
+                    Finding(
+                        detector=self.name,
+                        dedup_key=tool,
+                        severity="critical",
+                        title=f"{tool} started failing this week (no prior errors)",
+                        message=(
+                            f"Last 7d: {window_rate * 100:.1f}% over {window_calls} calls. "
+                            f"Prior 28d: 0 errors over {baseline_calls} calls."
+                        ),
+                        metadata={
+                            "tool_name": tool,
+                            "window_rate": window_rate,
+                            "baseline_rate": 0.0,
+                            "window_calls": window_calls,
+                            "baseline_calls": baseline_calls,
+                        },
+                    )
+                )
+                continue
+
+            multiple = window_rate / baseline_rate
+            if multiple < _WARNING_MULTIPLE:
+                continue
+
+            severity = "critical" if multiple >= _CRITICAL_MULTIPLE else "warning"
+            findings.append(
+                Finding(
+                    detector=self.name,
+                    dedup_key=tool,
+                    severity=severity,
+                    title=(
+                        f"{tool} error rate jumped to {window_rate * 100:.1f}% "
+                        f"this week (baseline {baseline_rate * 100:.1f}%)"
+                    ),
+                    message=(
+                        f"Last 7d: {window_rate * 100:.1f}% over {window_calls} calls. "
+                        f"Prior 28d: {baseline_rate * 100:.1f}% over {baseline_calls} calls."
+                    ),
+                    metadata={
+                        "tool_name": tool,
+                        "window_rate": window_rate,
+                        "baseline_rate": baseline_rate,
+                        "window_calls": window_calls,
+                        "baseline_calls": baseline_calls,
+                        "multiple": multiple,
+                    },
+                )
+            )
+        return findings

argus/pricing/2026-05-02.json

@@ -0,0 +1,24 @@
+{
+  "version": "2026-05-02",
+  "models": {
+    "claude-opus-4-7":     { "input": 5,    "output": 25,  "cache_write_5m": 6.25, "cache_write_1h": 10,   "cache_read": 0.50 },
+    "claude-opus-4-6":     { "input": 5,    "output": 25,  "cache_write_5m": 6.25, "cache_write_1h": 10,   "cache_read": 0.50 },
+    "claude-opus-4-5":     { "input": 5,    "output": 25,  "cache_write_5m": 6.25, "cache_write_1h": 10,   "cache_read": 0.50 },
+    "claude-opus-4-1":     { "input": 15,   "output": 75,  "cache_write_5m": 18.75,"cache_write_1h": 30,   "cache_read": 1.50 },
+    "claude-opus-4":       { "input": 15,   "output": 75,  "cache_write_5m": 18.75,"cache_write_1h": 30,   "cache_read": 1.50 },
+    "claude-sonnet-4-6":   { "input": 3,    "output": 15,  "cache_write_5m": 3.75, "cache_write_1h": 6,    "cache_read": 0.30 },
+    "claude-sonnet-4-5":   { "input": 3,    "output": 15,  "cache_write_5m": 3.75, "cache_write_1h": 6,    "cache_read": 0.30 },
+    "claude-sonnet-4":     { "input": 3,    "output": 15,  "cache_write_5m": 3.75, "cache_write_1h": 6,    "cache_read": 0.30 },
+    "claude-haiku-4-5":    { "input": 1,    "output": 5,   "cache_write_5m": 1.25, "cache_write_1h": 2,    "cache_read": 0.10 },
+    "claude-haiku-3-5":    { "input": 0.80, "output": 4,   "cache_write_5m": 1,    "cache_write_1h": 1.60, "cache_read": 0.08 },
+    "claude-haiku-3":      { "input": 0.25, "output": 1.25,"cache_write_5m": 0.30, "cache_write_1h": 0.50, "cache_read": 0.03 },
+    "gpt-5.5":             { "input": 5,    "output": 30,                                                "cache_read": 0.50 },
+    "gpt-5.4":             { "input": 2.50, "output": 15,                                                "cache_read": 0.25 },
+    "gpt-5.4-mini":        { "input": 0.75, "output": 4.50,                                              "cache_read": 0.075 },
+    "gpt-5.4-nano":        { "input": 0.20, "output": 1.25,                                              "cache_read": 0.02 },
+    "gpt-5.3-codex":       { "input": 1.75, "output": 14,                                                "cache_read": 0.175 },
+    "gpt-5.3-chat-latest": { "input": 1.75, "output": 14,                                                "cache_read": 0.175 },
+    "gpt-5.2":             { "input": 1.75, "output": 14,                                                "cache_read": 0.175 },
+    "gpt-5.1":             { "input": 1.25, "output": 10,                                                "cache_read": 0.125 }
+  }
+}

argus/pricing/compute.py

@@ -0,0 +1,46 @@
+"""Per-turn cost computation."""
+from __future__ import annotations
+
+from typing import Any
+
+from .types import PricingTable
+
+PER_MTOK = 1_000_000
+
+
+def compute_turn_cost(t: Any, table: PricingTable) -> float:
+    """Compute the USD cost for one turn given a pricing table.
+
+    ``t`` is duck-typed — it must expose ``model``, ``fresh_input_tokens``,
+    ``output_tokens``, ``cache_read_tokens``, ``cache_write_tokens``,
+    ``cache_write_5m_tokens``, ``cache_write_1h_tokens``. Both
+    pydantic models (RawTurnEvent, Turn) and plain dicts work via
+    ``getattr`` / dict access.
+    """
+    def g(name: str, default: Any = None) -> Any:
+        if isinstance(t, dict):
+            return t.get(name, default)
+        return getattr(t, name, default)
+
+    model = g("model")
+    p = table.models.get(model)
+    if p is None:
+        return 0.0
+
+    cw5 = p.cache_write_5m if p.cache_write_5m is not None else p.input
+    cw1 = p.cache_write_1h if p.cache_write_1h is not None else p.input
+
+    cw5_tokens = g("cache_write_5m_tokens")
+    cw1_tokens = g("cache_write_1h_tokens")
+
+    if cw5_tokens is not None and cw1_tokens is not None:
+        write_tier = (cw5_tokens * cw5 + cw1_tokens * cw1) / PER_MTOK
+    else:
+        write_tier = (g("cache_write_tokens", 0) * cw5) / PER_MTOK
+
+    return (
+        (g("fresh_input_tokens", 0) * p.input) / PER_MTOK
+        + (g("output_tokens", 0) * p.output) / PER_MTOK
+        + (g("cache_read_tokens", 0) * p.cache_read) / PER_MTOK
+        + write_tier
+    )

argus/pricing/load.py

@@ -0,0 +1,45 @@
+"""Load the bundled pricing JSON shipped inside the wheel."""
+from __future__ import annotations
+
+import json
+from importlib import resources
+from pathlib import Path
+
+from .types import PricingTable
+
+_DEFAULT_FILENAME = "2026-05-02.json"
+
+
+def _bundled_dir() -> Path:
+    """Path of the bundled ``pricing/`` directory.
+
+    Works in:
+    - installed wheel (data shipped alongside the package as argus/pricing/)
+    - editable install (`uv pip install -e .`)
+    - dev `uv run` from the repo (pricing/ at repo root)
+
+    The in-wheel path coincides with the source layout's ``argus/pricing``
+    subpackage (which has its own ``__init__.py``). We only trust that
+    location if the expected JSON actually lives there — otherwise we fall
+    back to the repo-root ``pricing/`` directory.
+    """
+    # In-wheel location: only trust it if the expected file is present.
+    try:
+        traversable = resources.files("argus") / "pricing"
+        candidate = Path(str(traversable))
+        if (candidate / _DEFAULT_FILENAME).exists():
+            return candidate
+    except (ModuleNotFoundError, FileNotFoundError):
+        pass
+
+    # Dev fallback: repo-root pricing/.
+    # python/argus/pricing/load.py → parents[3] is the repo root.
+    here = Path(__file__).resolve()
+    return here.parents[3] / "pricing"
+
+
+def load_pricing_table(path: Path | None = None) -> PricingTable:
+    """Read a pricing JSON from disk and parse it."""
+    p = path or (_bundled_dir() / _DEFAULT_FILENAME)
+    raw = p.read_text(encoding="utf-8")
+    return PricingTable.model_validate(json.loads(raw))

argus/pricing/refresh.py

@@ -0,0 +1,91 @@
+"""Diff against current pricing and fetch the latest from LiteLLM."""
+from __future__ import annotations
+
+import datetime as dt
+import json
+from typing import Any, Callable
+
+from pydantic import BaseModel
+
+from .types import ModelPricing, PricingTable
+
+LITELLM_URL = (
+    "https://raw.githubusercontent.com/BerriAI/litellm/main/"
+    "model_prices_and_context_window.json"
+)
+
+
+class PricingDiff(BaseModel):
+    added: list[str]
+    removed: list[str]
+    changed: list[str]
+    unchanged: list[str]
+
+
+def diff_pricing(old: PricingTable, new: PricingTable) -> PricingDiff:
+    """Return added / removed / changed / unchanged model-key sets."""
+    old_keys = set(old.models.keys())
+    new_keys = set(new.models.keys())
+
+    added = sorted(new_keys - old_keys)
+    removed = sorted(old_keys - new_keys)
+    changed: list[str] = []
+    unchanged: list[str] = []
+    for k in new_keys & old_keys:
+        a = old.models[k].model_dump()
+        b = new.models[k].model_dump()
+        if json.dumps(a, sort_keys=True) == json.dumps(b, sort_keys=True):
+            unchanged.append(k)
+        else:
+            changed.append(k)
+    return PricingDiff(
+        added=added,
+        removed=removed,
+        changed=sorted(changed),
+        unchanged=sorted(unchanged),
+    )
+
+
+def fetch_litellm_table(
+    url: str = LITELLM_URL,
+    fetch: Callable[[str], dict[str, Any]] | None = None,
+) -> PricingTable:
+    """Fetch LiteLLM's per-token pricing JSON and convert to per-MTok shape.
+
+    ``fetch`` is the network function; tests inject a stub so no real
+    HTTPS is made. Default is httpx.
+    """
+    if fetch is None:
+        import httpx  # local import — httpx is the runtime default
+
+        def _fetch(u: str) -> dict[str, Any]:
+            r = httpx.get(u, timeout=30.0)
+            r.raise_for_status()
+            return r.json()
+
+        fetch = _fetch
+
+    raw = fetch(url)
+    models: dict[str, ModelPricing] = {}
+    for k, v in raw.items():
+        if k == "sample_spec":
+            continue
+        if not isinstance(v, dict) or "input_cost_per_token" not in v:
+            continue
+        input_ = (v.get("input_cost_per_token") or 0) * 1_000_000
+        output = (v.get("output_cost_per_token") or 0) * 1_000_000
+        cache_read = (v.get("cache_read_input_token_cost") or 0) * 1_000_000
+        cache_write = (v.get("cache_creation_input_token_cost") or 0) * 1_000_000
+        entry: dict[str, Any] = {
+            "input": input_,
+            "output": output,
+            "cache_read": cache_read,
+        }
+        if cache_write:
+            entry["cache_write_5m"] = cache_write
+            entry["cache_write_1h"] = cache_write * 1.6
+        models[k] = ModelPricing.model_validate(entry)
+    return PricingTable(
+        version=dt.datetime.now(dt.timezone.utc).date().isoformat(),
+        models=models,
+    )

argus/pricing/types.py

@@ -0,0 +1,21 @@
+"""Pricing-table model — direct port of src/pricing/types.ts."""
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPricing(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    input: float
+    output: float
+    cache_write_5m: float | None = None
+    cache_write_1h: float | None = None
+    cache_read: float
+
+
+class PricingTable(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    version: str
+    models: dict[str, ModelPricing] = Field(default_factory=dict)

argus/scaffold/scaffolder.py

@@ -0,0 +1,45 @@
+"""Copy a template directory into a project — the `argus claude init` core."""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# CLAUDE.md is the user's project brain — never overwrite it, even with --force.
+_CLAUDE_MD = "CLAUDE.md"
+
+
+@dataclass
+class ScaffoldResult:
+    created: list[Path] = field(default_factory=list)
+    skipped: list[tuple[Path, str]] = field(default_factory=list)  # (path, reason)
+
+
+def scaffold_project(
+    template_dir: Path, dest: Path, *, force: bool = False
+) -> ScaffoldResult:
+    """Copy every file under ``template_dir`` into ``dest``, preserving layout.
+
+    - A template file at ``CLAUDE.md`` lands at ``dest/CLAUDE.md``; everything
+      else (all under ``.claude/``) lands at ``dest/.claude/...``.
+    - An existing destination file is skipped unless ``force`` is set.
+    - ``CLAUDE.md`` is NEVER overwritten, even with ``force``.
+    """
+    result = ScaffoldResult()
+    for src in sorted(p for p in template_dir.rglob("*") if p.is_file()):
+        rel = src.relative_to(template_dir)
+        target = dest / rel
+        is_claude_md = rel.as_posix() == _CLAUDE_MD
+
+        if target.exists():
+            if is_claude_md:
+                result.skipped.append((target, "CLAUDE.md exists, left untouched"))
+                continue
+            if not force:
+                result.skipped.append((target, "exists"))
+                continue
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(src, target)
+        result.created.append(target)
+    return result

argus/scaffold/snapshot.py

@@ -0,0 +1,73 @@
+"""Snapshot a project's .claude/ into a named user template (`template create`)."""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .storage import RESERVED_TEMPLATE_NAMES, user_templates_dir
+
+# Never snapshot these — session/history/cache, or machine-local config.
+_EXCLUDED_DIRS = {
+    "projects", "todos", "shell-snapshots", "statsig", "logs", "ide",
+    "__pycache__", ".DS_Store",
+}
+_EXCLUDED_TOP_FILE_SUFFIXES = (".local.json",)
+_EXCLUDED_TOP_FILE_NAMES = {"history.jsonl"}
+_COPY_IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store")
+
+
+def snapshot_candidates(project_dir: Path) -> list[str]:
+    """Subfolder names under ``project_dir/.claude/`` eligible for snapshotting."""
+    claude = project_dir / ".claude"
+    if not claude.is_dir():
+        return []
+    return sorted(
+        p.name
+        for p in claude.iterdir()
+        if p.is_dir() and p.name not in _EXCLUDED_DIRS
+    )
+
+
+def _safe_top_files(claude: Path) -> list[Path]:
+    out: list[Path] = []
+    for p in claude.iterdir():
+        if not p.is_file():
+            continue
+        if p.name in _EXCLUDED_TOP_FILE_NAMES:
+            continue
+        if any(p.name.endswith(s) for s in _EXCLUDED_TOP_FILE_SUFFIXES):
+            continue
+        out.append(p)
+    return out
+
+
+def snapshot_template(
+    project_dir: Path, name: str, data_dir: Path, *, include_subdirs: list[str]
+) -> Path:
+    """Copy chosen ``.claude/`` subfolders + safe top-level files into a template.
+
+    Raises ``ValueError`` if ``name`` is reserved, the template already exists,
+    or there is no ``.claude/`` directory to snapshot. Returns the new template dir.
+    """
+    if name in RESERVED_TEMPLATE_NAMES:
+        raise ValueError(f"'{name}' is reserved, pick another name")
+    claude = project_dir / ".claude"
+    if not claude.is_dir():
+        raise ValueError(f"no .claude/ directory found in {project_dir}")
+
+    target_root = user_templates_dir(data_dir) / name
+    if target_root.exists():
+        raise ValueError(
+            f"template '{name}' already exists; delete it or choose another name"
+        )
+
+    dest_claude = target_root / ".claude"
+    dest_claude.mkdir(parents=True)
+
+    for f in _safe_top_files(claude):
+        shutil.copyfile(f, dest_claude / f.name)
+    for sub in include_subdirs:
+        src = claude / sub
+        if src.is_dir():
+            shutil.copytree(src, dest_claude / sub, ignore=_COPY_IGNORE)
+    return target_root

argus/scaffold/storage.py

@@ -0,0 +1,60 @@
+"""Locate and resolve `argus claude` project-scaffolding templates.
+
+Two tiers:
+- bundled templates ship inside the wheel (read-only), mirroring ``pricing/``.
+- user templates live under ``~/.argus/templates/<name>/`` (read-write).
+
+``resolve_template`` checks the user dir first, then bundled.
+"""
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+RESERVED_TEMPLATE_NAMES = {"default"}
+
+
+def bundled_templates_dir() -> Path:
+    """Path of the bundled ``templates/`` dir (in-wheel, else repo-root in dev)."""
+    try:
+        traversable = resources.files("argus") / "templates"
+        candidate = Path(str(traversable))
+        if (candidate / "default" / "CLAUDE.md").exists():
+            return candidate
+    except (ModuleNotFoundError, FileNotFoundError):
+        pass
+    # Dev fallback: repo-root templates/.
+    # python/argus/scaffold/storage.py -> parents[3] is the repo root.
+    return Path(__file__).resolve().parents[3] / "templates"
+
+
+def user_templates_dir(data_dir: Path) -> Path:
+    """Path of the user template store (``~/.argus/templates`` by default)."""
+    return data_dir / "templates"
+
+
+def _subdir_names(d: Path) -> list[str]:
+    if not d.is_dir():
+        return []
+    return sorted(p.name for p in d.iterdir() if p.is_dir())
+
+
+def list_templates(data_dir: Path) -> list[str]:
+    """All available template names: bundled ∪ user, sorted and de-duped."""
+    names = set(_subdir_names(bundled_templates_dir()))
+    names.update(_subdir_names(user_templates_dir(data_dir)))
+    return sorted(names)
+
+
+def resolve_template(name: str, data_dir: Path) -> Path:
+    """Return the directory for ``name``, preferring user templates.
+
+    Raises ``KeyError`` if no template with that name exists in either tier.
+    """
+    user = user_templates_dir(data_dir) / name
+    if user.is_dir():
+        return user
+    bundled = bundled_templates_dir() / name
+    if bundled.is_dir():
+        return bundled
+    raise KeyError(name)