afterai-runner 0.1.0__tar.gz

afterai_runner-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: afterai-runner
+Version: 0.1.0
+Summary: AfterAI Runner — AIS signal emission and agent evaluation on customer infrastructure
+Author-email: AfterAI <support@useafter.ai>
+License: MIT
+Keywords: afterai,ais,runner,eval,signals,evaluation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: afterai>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+
+# AfterAI Runner v0
+
+Runner v0 collects **pre-aggregated** D1–W5 metrics from customer-controlled artifact files and emits AIS payloads to the AfterAI API. It does not manage baselines, evaluate thresholds, or trigger ACE.
+
+- **Manifest-driven**: you provide a JSON or YAML manifest listing `system` + local artifact paths.
+- **Artifact contract**: each artifact file is one signal (required: `signal_key`, `cadence`, `window`, `metrics`).
+- **Stateless**: no local state; duplicate sends are allowed. Always sends `external_id`.
+- **Local filesystem only (v0)**: artifact paths must be local; no S3, GCS, or HTTPS.
+
+## Install
+
+```bash
+pip install afterai-runner
+```
+
+Or from source:
+
+```bash
+cd afterai-runner && pip install -e .
+```
+
+## Config
+
+| Env | Required | Default |
+|-----|----------|---------|
+| `AFTERAI_API_KEY` | Yes | — |
+| `AFTERAI_BASE_URL` | No | `https://api.useafter.ai` |
+
+## Usage
+
+```bash
+# Run ingestion from a manifest
+afterai-runner run --manifest manifest.yaml
+
+# Print payloads without sending
+afterai-runner run --manifest manifest.yaml --dry-run
+
+# Optional: ACE-from-AIS rule (out-of-band). Reads GET /signals/debug, applies threshold, POSTs inferred ACE.
+afterai-runner ace-from-ais --min-signals 2 --hours 24
+afterai-runner ace-from-ais --min-signals 2 --severity high,critical --dry-run
+```
+
+## Manifest example
+
+**manifest.yaml** (or `.json`):
+
+```yaml
+version: "2026-02"
+artifacts:
+  - system: my-system-01
+    path: /path/to/D1-2026-02-03.json
+  - system: my-system-01
+    path: /path/to/W1-2026-W05.json
+```
+
+`path` must be a **local filesystem path** (no remote URIs in v0).
+
+## Artifact example
+
+One file = one signal. **D1-2026-02-03.json**:
+
+```json
+{
+  "signal_key": "D1",
+  "cadence": "daily",
+  "window": {
+    "start": "2026-02-03T00:00:00Z",
+    "end": "2026-02-03T23:59:59Z"
+  },
+  "metrics": {
+    "score_mean": 0.87,
+    "fail_rate": 0.03
+  }
+}
+```
+
+Optional passthrough: `severity`, `confidence`, `tags`, `source`, `evidence_refs`, `baseline_ref`, `created_at`.  
+Runner adds: `system`, `external_id`, `type: "ais"`, and `created_at` if missing; defaults `severity="low"`, `confidence=0.8` if missing.
+
+## external_id format
+
+- **Daily**: `{system}:{signal_key}:{YYYY-MM-DD}`
+- **Weekly**: `{system}:{signal_key}:{YYYY-Www}` (ISO week from `window.end`)
+
+## Docs
+
+- [Quickstart](docs/quickstart.md)
+- [Deployment recipes](docs/deployment-recipes.md) (cron, GitHub Actions, K8s CronJob)
+
+## License
+
+MIT

afterai_runner-0.1.0/README.md

@@ -0,0 +1,92 @@
+# AfterAI Runner v0
+
+Runner v0 collects **pre-aggregated** D1–W5 metrics from customer-controlled artifact files and emits AIS payloads to the AfterAI API. It does not manage baselines, evaluate thresholds, or trigger ACE.
+
+- **Manifest-driven**: you provide a JSON or YAML manifest listing `system` + local artifact paths.
+- **Artifact contract**: each artifact file is one signal (required: `signal_key`, `cadence`, `window`, `metrics`).
+- **Stateless**: no local state; duplicate sends are allowed. Always sends `external_id`.
+- **Local filesystem only (v0)**: artifact paths must be local; no S3, GCS, or HTTPS.
+
+## Install
+
+```bash
+pip install afterai-runner
+```
+
+Or from source:
+
+```bash
+cd afterai-runner && pip install -e .
+```
+
+## Config
+
+| Env | Required | Default |
+|-----|----------|---------|
+| `AFTERAI_API_KEY` | Yes | — |
+| `AFTERAI_BASE_URL` | No | `https://api.useafter.ai` |
+
+## Usage
+
+```bash
+# Run ingestion from a manifest
+afterai-runner run --manifest manifest.yaml
+
+# Print payloads without sending
+afterai-runner run --manifest manifest.yaml --dry-run
+
+# Optional: ACE-from-AIS rule (out-of-band). Reads GET /signals/debug, applies threshold, POSTs inferred ACE.
+afterai-runner ace-from-ais --min-signals 2 --hours 24
+afterai-runner ace-from-ais --min-signals 2 --severity high,critical --dry-run
+```
+
+## Manifest example
+
+**manifest.yaml** (or `.json`):
+
+```yaml
+version: "2026-02"
+artifacts:
+  - system: my-system-01
+    path: /path/to/D1-2026-02-03.json
+  - system: my-system-01
+    path: /path/to/W1-2026-W05.json
+```
+
+`path` must be a **local filesystem path** (no remote URIs in v0).
+
+## Artifact example
+
+One file = one signal. **D1-2026-02-03.json**:
+
+```json
+{
+  "signal_key": "D1",
+  "cadence": "daily",
+  "window": {
+    "start": "2026-02-03T00:00:00Z",
+    "end": "2026-02-03T23:59:59Z"
+  },
+  "metrics": {
+    "score_mean": 0.87,
+    "fail_rate": 0.03
+  }
+}
+```
+
+Optional passthrough: `severity`, `confidence`, `tags`, `source`, `evidence_refs`, `baseline_ref`, `created_at`.  
+Runner adds: `system`, `external_id`, `type: "ais"`, and `created_at` if missing; defaults `severity="low"`, `confidence=0.8` if missing.
+
+## external_id format
+
+- **Daily**: `{system}:{signal_key}:{YYYY-MM-DD}`
+- **Weekly**: `{system}:{signal_key}:{YYYY-Www}` (ISO week from `window.end`)
+
+## Docs
+
+- [Quickstart](docs/quickstart.md)
+- [Deployment recipes](docs/deployment-recipes.md) (cron, GitHub Actions, K8s CronJob)
+
+## License
+
+MIT

afterai_runner-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "afterai-runner"
+version = "0.1.0"
+description = "AfterAI Runner — AIS signal emission and agent evaluation on customer infrastructure"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "AfterAI", email = "support@useafter.ai"}
+]
+keywords = ["afterai", "ais", "runner", "eval", "signals", "evaluation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "requests>=2.28.0",
+    "afterai>=0.1.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+afterai-runner = "afterai_runner.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

afterai_runner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

afterai_runner-0.1.0/src/afterai_runner/__init__.py

@@ -0,0 +1,7 @@
+"""
+AfterAI Runner v0 — manifest-driven ingestion of pre-aggregated D1–W5 metrics
+and emission of AIS payloads to the AfterAI API.
+"""
+from .__version__ import __version__
+
+__all__ = ["__version__"]

afterai_runner-0.1.0/src/afterai_runner/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

afterai_runner-0.1.0/src/afterai_runner/ace_rules.py

@@ -0,0 +1,180 @@
+"""
+Minimal out-of-band ACE-from-AIS rule: read AIS via GET /signals/debug,
+apply a simple threshold (e.g. N high-severity signals per system in last W hours),
+emit inferred ACE via POST /ingest using SDK-style payload.
+"""
+from datetime import datetime, timezone, timedelta
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .config import get_api_key, get_base_url
+
+
+def _parse_rfc3339_to_utc(s: Optional[str]) -> Optional[datetime]:
+    if not s:
+        return None
+    try:
+        normalized = s.strip().replace("Z", "+00:00")
+        dt = datetime.fromisoformat(normalized)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+    except Exception:
+        return None
+
+
+def fetch_signals_debug(
+    base_url: str,
+    api_key: str,
+    limit: int = 100,
+    system: Optional[str] = None,
+    timeout: int = 30,
+) -> List[Dict[str, Any]]:
+    """GET /signals/debug; returns list of items with id, system, severity, created_at, etc."""
+    url = f"{base_url.rstrip('/')}/signals/debug"
+    params: Dict[str, Any] = {"limit": limit}
+    if system:
+        params["system"] = system
+    resp = requests.get(
+        url,
+        headers={"X-API-Key": api_key},
+        params=params,
+        timeout=timeout,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return data.get("items") or []
+
+
+def filter_by_severity_and_hours(
+    items: List[Dict[str, Any]],
+    severities: List[str],
+    hours: int,
+    now: Optional[datetime] = None,
+) -> List[Dict[str, Any]]:
+    """Keep items whose severity is in severities and created_at is within the last hours."""
+    if now is None:
+        now = datetime.now(timezone.utc)
+    cutoff = now - timedelta(hours=hours)
+    out = []
+    for item in items:
+        if item.get("severity") not in severities:
+            continue
+        created = _parse_rfc3339_to_utc(item.get("created_at"))
+        if created is None or created < cutoff:
+            continue
+        out.append(item)
+    return out
+
+
+def group_by_system(items: List[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]]]:
+    """Group debug items by system; each value is list of items (with id)."""
+    by_system: Dict[str, List[Dict[str, Any]]] = {}
+    for item in items:
+        sys_id = (item.get("system") or "").strip()
+        if not sys_id:
+            continue
+        by_system.setdefault(sys_id, []).append(item)
+    return by_system
+
+
+def build_inferred_ace_payload(
+    system_id: str,
+    ais_refs: List[str],
+    occurred_at: str,
+    environment: str = "production",
+) -> Dict[str, Any]:
+    """Build minimal ACE payload for inferred ACE (drift_detector source, pending, extensions.ais_refs)."""
+    return {
+        "schema_version": "1.0.0",
+        "occurred_at": occurred_at,
+        "system": {
+            "system_id": system_id,
+            "name": system_id,
+            "type": "other",
+        },
+        "source": {
+            "origin": "drift_detector",
+            "actor": {"actor_type": "system", "actor_id": "afterai-drift"},
+        },
+        "change": {
+            "change_type": "eval",
+            "intent": "observed",
+            "baseline": {},
+            "candidate": {},
+        },
+        "risk": {
+            "severity": "high",
+            "blast_radius": "single_app",
+            "customer_impact": "minor",
+        },
+        "fingerprints": {
+            "change_fingerprint": "ais-escalation",
+        },
+        "environment": environment,
+        "status": "pending",
+        "extensions": {"ais_refs": ais_refs},
+    }
+
+
+def post_ace(
+    base_url: str,
+    api_key: str,
+    payload: Dict[str, Any],
+    idempotency_key: Optional[str] = None,
+    timeout: int = 30,
+) -> Dict[str, Any]:
+    """POST ACE to /ingest. Returns response JSON."""
+    url = f"{base_url.rstrip('/')}/ingest"
+    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    resp = requests.post(url, json=payload, headers=headers, timeout=timeout)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def run_ace_from_ais_rule(
+    base_url: str,
+    api_key: str,
+    min_signals: int = 2,
+    severities: Optional[List[str]] = None,
+    hours: int = 24,
+    limit: int = 100,
+    system_filter: Optional[str] = None,
+    dry_run: bool = False,
+) -> List[Dict[str, Any]]:
+    """
+    Fetch AIS, filter by severity and time, group by system; for each system with
+    >= min_signals matching items, build and POST an inferred ACE (unless dry_run).
+    Returns list of ACE responses (or would-be payloads if dry_run).
+    """
+    if severities is None:
+        severities = ["high", "critical"]
+    items = fetch_signals_debug(base_url, api_key, limit=limit, system=system_filter)
+    filtered = filter_by_severity_and_hours(items, severities, hours)
+    by_system = group_by_system(filtered)
+    now_iso = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    results = []
+    for sys_id, sys_items in by_system.items():
+        if len(sys_items) < min_signals:
+            continue
+        signal_ids = [it["id"] for it in sys_items if it.get("id")]
+        if not signal_ids:
+            continue
+        payload = build_inferred_ace_payload(
+            system_id=sys_id,
+            ais_refs=signal_ids,
+            occurred_at=now_iso,
+        )
+        if dry_run:
+            results.append({"system": sys_id, "dry_run": True, "payload": payload})
+            continue
+        idempotency_key = f"ace-from-ais:{sys_id}:{now_iso[:13]}"
+        try:
+            ack = post_ace(base_url, api_key, payload, idempotency_key=idempotency_key)
+            results.append({"system": sys_id, "ace_id": ack.get("ace_id"), "ack": ack})
+        except requests.exceptions.HTTPError as e:
+            results.append({"system": sys_id, "error": str(e), "response": getattr(e.response, "text", "")})
+    return results

afterai_runner-0.1.0/src/afterai_runner/artifact.py

@@ -0,0 +1,115 @@
+"""
+Artifact contract: one file = one signal. Validates required keys and RFC3339 window.
+"""
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+# D1–D5, W1–W5
+VALID_SIGNAL_KEYS = frozenset(
+    f"{p}{i}" for p in ("D", "W") for i in range(1, 6)
+)
+CADENCE_VALUES = ("daily", "weekly")
+
+
+def _parse_rfc3339(s: str) -> None:
+    """Validate RFC3339-like string (raise if invalid)."""
+    if not s or not isinstance(s, str):
+        raise ValueError("RFC3339 value must be a non-empty string")
+    s = s.strip()
+    # Accept Z or +00:00
+    from datetime import datetime
+    normalized = s.replace("Z", "+00:00")
+    try:
+        datetime.fromisoformat(normalized)
+    except Exception as e:
+        raise ValueError(f"Invalid RFC3339 datetime: {s}") from e
+
+
+class WindowModel(BaseModel):
+    """Window with start/end RFC3339."""
+    start: str = Field(..., description="Window start (RFC3339)")
+    end: str = Field(..., description="Window end (RFC3339)")
+
+    @field_validator("start", "end")
+    @classmethod
+    def check_rfc3339(cls, v: str) -> str:
+        _parse_rfc3339(v)
+        return v
+
+
+class ArtifactIn(BaseModel):
+    """
+    Artifact JSON (one file = one signal).
+    Required: signal_key, cadence, window, metrics.
+    Optional passthrough: severity, confidence, tags, source, evidence_refs, baseline_ref, created_at.
+    """
+    signal_key: str = Field(..., description="D1–D5 or W1–W5")
+    cadence: str = Field(..., description="daily | weekly")
+    window: WindowModel = Field(..., description="start/end RFC3339")
+    metrics: Dict[str, Any] = Field(..., description="Pre-aggregated metrics object")
+
+    severity: Optional[str] = None
+    confidence: Optional[float] = None
+    tags: Optional[List[str]] = None
+    source: Optional[Any] = None
+    evidence_refs: Optional[List[str]] = None
+    baseline_ref: Optional[str] = None
+    created_at: Optional[str] = None
+
+    @field_validator("signal_key")
+    @classmethod
+    def valid_signal_key(cls, v: str) -> str:
+        key = (v or "").strip()
+        if key not in VALID_SIGNAL_KEYS:
+            raise ValueError(
+                f"signal_key must be one of D1–D5, W1–W5; got {v!r}"
+            )
+        return key
+
+    @field_validator("cadence")
+    @classmethod
+    def valid_cadence(cls, v: str) -> str:
+        c = (v or "").strip().lower()
+        if c not in CADENCE_VALUES:
+            raise ValueError(
+                f"cadence must be 'daily' or 'weekly'; got {v!r}"
+            )
+        return c
+
+
+def load_artifact(path: str | Path) -> ArtifactIn:
+    """
+    Load and validate artifact JSON from a local file path.
+    Raises FileNotFoundError if path missing, ValueError for invalid content.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"Artifact file not found: {p}")
+    if not p.is_file():
+        raise ValueError(f"Artifact path is not a file: {p}")
+
+    try:
+        raw = p.read_text(encoding="utf-8")
+    except OSError as e:
+        raise ValueError(f"Cannot read artifact file {p}: {e}") from e
+
+    try:
+        data = __import__("json").loads(raw)
+    except Exception as e:
+        raise ValueError(f"Artifact JSON parse error in {p}: {e}") from e
+
+    if not isinstance(data, dict):
+        raise ValueError(f"Artifact root must be a JSON object; got {type(data).__name__}")
+
+    for key in ("signal_key", "cadence", "window", "metrics"):
+        if key not in data:
+            raise ValueError(f"Artifact missing required key: {key}")
+
+    if not isinstance(data.get("window"), dict):
+        raise ValueError("Artifact 'window' must be an object with start and end")
+    if "start" not in data["window"] or "end" not in data["window"]:
+        raise ValueError("Artifact window must have 'start' and 'end' (RFC3339)")
+
+    return ArtifactIn(**data)