agentops-accelerator 0.3.0__py3-none-any.whl

agentops/agent/sources/spec_detectors/_base.py

@@ -0,0 +1,58 @@
+"""Detector protocol and shared data classes for spec-conformance."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Protocol
+
+
+@dataclass
+class SpecTask:
+    """A single checklist item extracted from a spec document."""
+
+    text: str
+    checked: bool
+    line: int
+    mentioned_paths: List[str] = field(default_factory=list)
+
+
+@dataclass
+class SpecDocument:
+    """Unified view of a project's spec, populated by a :class:`Detector`.
+
+    The structure is intentionally narrow: every field is either a list
+    of strings (extracted via simple regex heuristics) or a primitive,
+    so detectors stay deterministic and easy to test.
+    """
+
+    format: str
+    root: Path
+    files: List[Path] = field(default_factory=list)
+    capabilities: List[str] = field(default_factory=list)
+    tasks: List[SpecTask] = field(default_factory=list)
+    references: Dict[str, List[str]] = field(default_factory=dict)
+    text: str = ""
+    last_modified: Optional[datetime] = None
+
+    @property
+    def is_empty(self) -> bool:
+        return not (self.capabilities or self.tasks or self.text.strip())
+
+
+class Detector(Protocol):
+    """Protocol every spec-format detector must satisfy."""
+
+    name: str
+
+    def hint_paths(self, workspace: Path) -> List[Path]:
+        """Paths that, if present, suggest the user *intends* to use
+        this spec format even when the actual content is missing or
+        empty (e.g. ``.specify/`` directory with no spec.md). Used by
+        the doctor to fire a ``spec_missing`` finding instead of
+        silently skipping the check."""
+
+    def detect(self, workspace: Path) -> Optional[SpecDocument]:
+        """Inspect ``workspace`` and return a :class:`SpecDocument`
+        when this format is detected. Return ``None`` to opt out."""

agentops/agent/sources/spec_detectors/agents_md.py

@@ -0,0 +1,75 @@
+"""Detector for the AGENTS.md / copilot-instructions.md convention."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from agentops.agent.sources.spec_detectors._base import SpecDocument
+from agentops.agent.sources.spec_detectors.spec_kit import (
+    _extract_capabilities,
+    _extract_references,
+    _extract_tasks,
+)
+
+_CANDIDATE_PATHS = (
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+    ".github/instructions.md",
+    "CLAUDE.md",
+)
+
+
+@dataclass
+class AgentsMdDetector:
+    """Detector for AGENTS.md-style single-file spec conventions."""
+
+    name: str = "agents-md"
+
+    def hint_paths(self, workspace: Path) -> List[Path]:
+        return [workspace / p for p in _CANDIDATE_PATHS if (workspace / p).exists()]
+
+    def detect(self, workspace: Path) -> Optional[SpecDocument]:
+        files: List[Path] = []
+        chunks: List[str] = []
+        latest_mtime: Optional[float] = None
+
+        for relative in _CANDIDATE_PATHS:
+            p = workspace / relative
+            if not p.is_file():
+                continue
+            files.append(p)
+            try:
+                text = p.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            chunks.append(f"# === {relative} ===\n{text}")
+            try:
+                mtime = p.stat().st_mtime
+                if latest_mtime is None or mtime > latest_mtime:
+                    latest_mtime = mtime
+            except OSError:
+                pass
+
+        if not files:
+            return None
+
+        merged = "\n\n".join(chunks)
+        last_modified = (
+            datetime.fromtimestamp(latest_mtime, tz=timezone.utc)
+            if latest_mtime is not None
+            else None
+        )
+
+        return SpecDocument(
+            format=self.name,
+            root=workspace,
+            files=files,
+            capabilities=_extract_capabilities(merged),
+            tasks=_extract_tasks(merged),
+            references=_extract_references(merged),
+            text=merged,
+            last_modified=last_modified,
+        )

agentops/agent/sources/spec_detectors/spec_kit.py

@@ -0,0 +1,172 @@
+"""Detector for the GitHub spec-kit layout (``.specify/``).
+
+Reads ``spec.md``, ``plan.md``, and ``tasks.md`` from the ``.specify/``
+directory at the workspace root. Capabilities are extracted from
+markdown headings + leading bullet points; tasks come from
+``- [ ]`` / ``- [x]`` checklist items in ``tasks.md``. References
+to evaluators, datasets, and agent ids are detected via backticked
+identifiers and common AgentOps keywords.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from agentops.agent.sources.spec_detectors._base import SpecDocument, SpecTask
+
+_SPECIFY_DIR = ".specify"
+_DOC_NAMES = ("spec.md", "plan.md", "tasks.md")
+
+_HEADING_RE = re.compile(r"^(#{1,3})\s+(.+?)\s*$", re.MULTILINE)
+_BULLET_RE = re.compile(r"^\s*[-*]\s+(.+?)\s*$", re.MULTILINE)
+_TASK_RE = re.compile(r"^\s*[-*]\s+\[([ xX])\]\s+(.+?)\s*$")
+_BACKTICK_RE = re.compile(r"`([^`\n]+)`")
+_EVALUATOR_RE = re.compile(r"\b([A-Z][A-Za-z0-9]*Evaluator)\b")
+_AGENT_ID_RE = re.compile(r"\b([a-z][a-z0-9_\-]*:[a-zA-Z0-9._\-]+)\b")
+_PATH_RE = re.compile(r"`?(\.?/?[\w\-./]+\.(?:py|md|yaml|yml|jsonl|json|ts|tsx|js))`?")
+
+
+@dataclass
+class SpecKitDetector:
+    """Detector for GitHub spec-kit (``.specify/``) projects."""
+
+    name: str = "spec-kit"
+
+    def hint_paths(self, workspace: Path) -> List[Path]:
+        base = workspace / _SPECIFY_DIR
+        return [base] if base.exists() else []
+
+    def detect(self, workspace: Path) -> Optional[SpecDocument]:
+        base = workspace / _SPECIFY_DIR
+        if not base.is_dir():
+            return None
+
+        files: List[Path] = []
+        chunks: List[str] = []
+        latest_mtime: Optional[float] = None
+        tasks: List[SpecTask] = []
+
+        for name in _DOC_NAMES:
+            p = base / name
+            if not p.is_file():
+                continue
+            files.append(p)
+            try:
+                text = p.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            chunks.append(f"# === {name} ===\n{text}")
+            try:
+                mtime = p.stat().st_mtime
+                if latest_mtime is None or mtime > latest_mtime:
+                    latest_mtime = mtime
+            except OSError:
+                pass
+            if name == "tasks.md":
+                tasks.extend(_extract_tasks(text))
+
+        if not files:
+            return None
+
+        merged = "\n\n".join(chunks)
+        capabilities = _extract_capabilities(merged)
+        references = _extract_references(merged)
+        last_modified = (
+            datetime.fromtimestamp(latest_mtime, tz=timezone.utc)
+            if latest_mtime is not None
+            else None
+        )
+
+        return SpecDocument(
+            format=self.name,
+            root=base,
+            files=files,
+            capabilities=capabilities,
+            tasks=tasks,
+            references=references,
+            text=merged,
+            last_modified=last_modified,
+        )
+
+
+def _extract_capabilities(text: str) -> List[str]:
+    """Heuristic capability extraction: top-2 heading levels + first-bullet items."""
+    caps: List[str] = []
+    seen: set[str] = set()
+    for match in _HEADING_RE.finditer(text):
+        level = len(match.group(1))
+        title = match.group(2).strip().rstrip("#").strip()
+        if level <= 2 and title and title.lower() not in seen:
+            caps.append(title)
+            seen.add(title.lower())
+    for match in _BULLET_RE.finditer(text):
+        item = match.group(1).strip()
+        if item.startswith("[") and "]" in item:
+            continue  # task checklist item handled separately
+        key = item.lower()
+        if key not in seen and len(item) > 4:
+            caps.append(item)
+            seen.add(key)
+    return caps[:60]
+
+
+def _extract_tasks(text: str) -> List[SpecTask]:
+    """Parse ``- [ ]`` / ``- [x]`` checklist items from ``tasks.md``."""
+    tasks: List[SpecTask] = []
+    for idx, raw_line in enumerate(text.splitlines(), start=1):
+        m = _TASK_RE.match(raw_line)
+        if not m:
+            continue
+        mark = m.group(1).lower()
+        item = m.group(2).strip()
+        paths = list(_PATH_RE.findall(item))
+        tasks.append(
+            SpecTask(
+                text=item,
+                checked=(mark == "x"),
+                line=idx,
+                mentioned_paths=[p for p in paths if p],
+            )
+        )
+    return tasks
+
+
+def _extract_references(text: str) -> Dict[str, List[str]]:
+    """Collect evaluator class names, agent-id-like tokens, and backticked
+    identifiers that look like file / module / dataset references."""
+    refs: Dict[str, List[str]] = {
+        "evaluators": [],
+        "agent_ids": [],
+        "datasets": [],
+        "files": [],
+    }
+    seen_per_bucket: Dict[str, set[str]] = {k: set() for k in refs}
+
+    def _push(bucket: str, value: str) -> None:
+        v = value.strip()
+        if not v or v in seen_per_bucket[bucket]:
+            return
+        seen_per_bucket[bucket].add(v)
+        refs[bucket].append(v)
+
+    for m in _EVALUATOR_RE.finditer(text):
+        _push("evaluators", m.group(1))
+
+    for m in _AGENT_ID_RE.finditer(text):
+        token = m.group(1)
+        if token.startswith(("http", "https")) or token in {"int:0", "str:0"}:
+            continue
+        _push("agent_ids", token)
+
+    for m in _BACKTICK_RE.finditer(text):
+        token = m.group(1).strip()
+        if "/" in token and "." in token:
+            _push("files", token)
+        elif token.endswith(".jsonl") or token.endswith(".yaml") or token.endswith(".yml"):
+            _push("datasets", token)
+
+    return refs

agentops/agent/time_range.py

@@ -0,0 +1,117 @@
+"""Time range parsing for the AgentOps cockpit.
+
+The cockpit supports three preset windows (``1d``, ``7d``, ``30d``)
+plus a ``custom`` mode driven by ``from`` / ``to`` ISO date strings.
+The parsing is intentionally tolerant: any unknown value falls back to
+the 7-day default so the cockpit never breaks on bad query strings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Iterable, Optional
+
+
+@dataclass(frozen=True)
+class TimeRange:
+    """A resolved time window for filtering cockpit data."""
+
+    key: str            # "1d" | "7d" | "30d" | "custom"
+    label: str          # display label, e.g. "Last 24h"
+    start: datetime     # UTC, inclusive
+    end: datetime       # UTC, exclusive
+    hours: int          # convenience: rounded duration in hours, used by KQL
+
+    def contains(self, ts: Optional[datetime]) -> bool:
+        """Return True if ``ts`` (UTC) falls inside this window."""
+        if ts is None:
+            return False
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=timezone.utc)
+        return self.start <= ts < self.end
+
+    def to_query(self) -> str:
+        """Return the URL query string that reproduces this range."""
+        if self.key == "custom":
+            return (
+                f"range=custom"
+                f"&from={self.start.strftime('%Y-%m-%d')}"
+                f"&to={self.end.strftime('%Y-%m-%d')}"
+            )
+        return f"range={self.key}"
+
+
+_PRESET_HOURS = {
+    "1d": 24,
+    "7d": 24 * 7,
+    "30d": 24 * 30,
+}
+
+_PRESET_LABELS = {
+    "1d": "Last 24h",
+    "7d": "Last 7 days",
+    "30d": "Last 30 days",
+}
+
+
+def parse_time_range(
+    range_param: Optional[str] = None,
+    from_param: Optional[str] = None,
+    to_param: Optional[str] = None,
+    *,
+    now: Optional[datetime] = None,
+) -> TimeRange:
+    """Parse the URL ``range``, ``from``, ``to`` params into a TimeRange.
+
+    Falls back to the ``7d`` preset on any malformed input.
+    """
+    current = now or datetime.now(timezone.utc)
+    key = (range_param or "7d").lower().strip()
+
+    if key == "custom":
+        start = _parse_iso_date(from_param)
+        end = _parse_iso_date(to_param)
+        if start and end and end > start:
+            # Inclusive end-of-day for the "to" date.
+            end = end + timedelta(days=1)
+            hours = max(int((end - start).total_seconds() // 3600), 1)
+            return TimeRange(
+                key="custom",
+                label=f"{start.strftime('%Y-%m-%d')} → {end.strftime('%Y-%m-%d')}",
+                start=start,
+                end=end,
+                hours=hours,
+            )
+        # Invalid custom params → fall through to default.
+        key = "7d"
+
+    if key not in _PRESET_HOURS:
+        key = "7d"
+
+    hours = _PRESET_HOURS[key]
+    return TimeRange(
+        key=key,
+        label=_PRESET_LABELS[key],
+        start=current - timedelta(hours=hours),
+        end=current,
+        hours=hours,
+    )
+
+
+def preset_keys() -> Iterable[str]:
+    """Iterate the supported preset keys, in display order."""
+    return ("1d", "7d", "30d")
+
+
+def _parse_iso_date(text: Optional[str]) -> Optional[datetime]:
+    if not text:
+        return None
+    text = text.strip()
+    # Accept either "2026-05-12" or full ISO-8601.
+    try:
+        if len(text) == 10:
+            return datetime.strptime(text, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+        return datetime.fromisoformat(text.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        return None

agentops/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for AgentOps."""