agentx-python 0.8.6__tar.gz → 0.8.8__tar.gz

{agentx_python-0.8.6 → agentx_python-0.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.8.6
+Version: 0.8.8
 Summary: Official Python SDK for AgentX (https://www.agentx.so/)
 Home-page: https://github.com/AgentX-ai/AgentX-python
 Author: Robin Wang and AgentX Team

{agentx_python-0.8.6 → agentx_python-0.8.8}/agentx/cli.py

@@ -7,26 +7,35 @@ AgentX SaaS and would never touch it, so it isn't bundled in this package. Inste
 downloads the matching release into ~/.agentx/bin the first time it's needed (mirroring
 AgentX-trace-eval's own install.sh) and then hands off to the real `agentx-server` binary.
 
+The installed release tag is stamped in ~/.agentx/bin/.version. The launcher never silently
+re-downloads, but it re-installs when you ask: `--update` fetches the newest release (engine +
+dashboard), and setting AGENTX_TRACE_EVAL_VERSION to a tag other than the stamped one switches
+to that release. When running "latest", a quick fail-open check against GitHub tells you if a
+newer release exists.
+
 Usage:
     agentx-trace-eval --dev
+    agentx-trace-eval --update --dev
     agentx-trace-eval --port 5000 --db-url postgres://...
 """
 
 import os
 import platform
+import re
 import shutil
 import stat
 import sys
 import tarfile
 import tempfile
 from pathlib import Path
-from typing import Tuple
+from typing import Optional, Tuple
 
 import requests
 
 REPO = "AgentX-ai/AgentX-trace-eval"
 INSTALL_DIR = Path(os.environ.get("AGENTX_INSTALL_DIR", str(Path.home() / ".agentx" / "bin")))
 _BIN_NAMES = ("agentx", "agentx-server", "agentx-engine")
+_VERSION_STAMP = ".version"
 
 
 def _platform_tag() -> Tuple[str, str]:
@@ -57,12 +66,22 @@ def _release_url(asset: str, version: str) -> str:
     return f"https://github.com/{REPO}/releases/download/{version}/{asset}"
 
 
-def _download(url: str, dest: Path) -> None:
+def _tag_from_release_url(url: str) -> Optional[str]:
+    # GitHub redirects releases/latest/download/... to releases/download/<tag>/...; the final
+    # URL is the one place the resolved tag shows up without a second API call.
+    match = re.search(r"/releases/download/([^/]+)/", url)
+    return match.group(1) if match else None
+
+
+def _download(url: str, dest: Path) -> Optional[str]:
+    """Downloads url to dest; returns the release tag resolved from the final (post-redirect)
+    URL, or None if it can't be determined."""
     response = requests.get(url, stream=True, timeout=60)
     response.raise_for_status()
     with open(dest, "wb") as f:
         for chunk in response.iter_content(chunk_size=1 << 16):
             f.write(chunk)
+    return _tag_from_release_url(response.url)
 
 
 def _extract_tar(archive: Path, dest_dir: Path) -> None:
@@ -76,6 +95,25 @@ def _extract_tar(archive: Path, dest_dir: Path) -> None:
             tar.extractall(dest_dir)  # Python < 3.12: filter kwarg doesn't exist yet
 
 
+def _stamped_version() -> Optional[str]:
+    try:
+        return (INSTALL_DIR / _VERSION_STAMP).read_text().strip() or None
+    except OSError:
+        return None
+
+
+def _latest_release_tag() -> Optional[str]:
+    """The newest published tag, or None when it can't be determined (offline, rate-limited).
+    Fail-open by design: an update NOTICE must never break launching the engine."""
+    try:
+        response = requests.get(f"https://api.github.com/repos/{REPO}/releases/latest", timeout=3)
+        response.raise_for_status()
+        tag = response.json().get("tag_name")
+        return tag if isinstance(tag, str) and tag else None
+    except Exception:
+        return None
+
+
 def _install(version: str = "latest") -> None:
     os_name, arch = _platform_tag()
     INSTALL_DIR.mkdir(parents=True, exist_ok=True)
@@ -86,7 +124,7 @@ def _install(version: str = "latest") -> None:
         archive = tmp_dir / "agentx.tar.gz"
         url = _release_url(f"agentx_{os_name}_{arch}.tar.gz", version)
         try:
-            _download(url, archive)
+            resolved_tag = _download(url, archive)
         except requests.HTTPError as exc:
             raise SystemExit(
                 f"agentx-trace-eval: failed to download {url} ({exc}).\n"
@@ -108,6 +146,11 @@ def _install(version: str = "latest") -> None:
         if not found_any:
             raise SystemExit(f"agentx-trace-eval: downloaded archive from {url} didn't contain any of {_BIN_NAMES}")
 
+    stamp = resolved_tag or (version if version != "latest" else None)
+    if stamp:
+        (INSTALL_DIR / _VERSION_STAMP).write_text(stamp + "\n")
+        print(f"agentx-trace-eval: installed {stamp}", file=sys.stderr)
+
     if os.environ.get("AGENTX_TRACE_EVAL_SKIP_WEB"):
         return
 
@@ -118,7 +161,9 @@ def _install(version: str = "latest") -> None:
     web_dir = INSTALL_DIR / "web"
     with tempfile.TemporaryDirectory() as tmp:
         web_archive = Path(tmp) / "agentx-web.tar.gz"
-        web_url = _release_url("agentx-web.tar.gz", version)
+        # Pin the dashboard to the tag the engine actually resolved to, so the two halves of one
+        # install can't skew (releases/latest assets are updated independently).
+        web_url = _release_url("agentx-web.tar.gz", stamp or version)
         try:
             _download(web_url, web_archive)
         except requests.HTTPError:
@@ -133,25 +178,54 @@ def _install(version: str = "latest") -> None:
         _extract_tar(web_archive, web_dir)
 
 
-def ensure_installed(version: str = "latest") -> Path:
-    """Downloads agentx-server (+ its engine) into ~/.agentx/bin if not already present there.
-    Returns the path to the agentx-server executable. Set AGENTX_INSTALL_DIR to change where
-    this looks/installs; set AGENTX_TRACE_EVAL_VERSION to pin a release tag instead of latest."""
+def ensure_installed(version: str = "latest", force: bool = False) -> Path:
+    """Downloads agentx-server (+ its engine and dashboard) into ~/.agentx/bin when it's missing
+    there, when `force` is set, or when `version` is a specific tag that differs from the
+    installed one. Returns the path to the agentx-server executable. Set AGENTX_INSTALL_DIR to
+    change where this looks/installs; set AGENTX_TRACE_EVAL_VERSION to pin a release tag."""
     server_path = INSTALL_DIR / "agentx-server"
-    if not server_path.exists():
+    installed = _stamped_version()
+    pin_changed = version != "latest" and installed is not None and installed != version
+    if force or pin_changed or not server_path.exists():
         _install(version=version)
     return server_path
 
 
+def _maybe_print_update_notice(installed: Optional[str]) -> None:
+    latest = _latest_release_tag()
+    if installed is None:
+        # Pre-stamp install (or a wiped stamp): age unknown, so always point at --update.
+        print(
+            "agentx-trace-eval: installed engine version unknown"
+            + (f" (newest release is {latest})" if latest else "")
+            + "; run with --update to fetch the newest release",
+            file=sys.stderr,
+        )
+    elif latest and latest != installed:
+        print(
+            f"agentx-trace-eval: engine {installed} is installed but {latest} is available; "
+            "run with --update to upgrade",
+            file=sys.stderr,
+        )
+
+
 def main() -> None:
+    args = sys.argv[1:]
+    force_update = "--update" in args
+    # --update belongs to this launcher, not to agentx-server - consume it before the handoff.
+    args = [a for a in args if a != "--update"]
+
     version = os.environ.get("AGENTX_TRACE_EVAL_VERSION", "latest")
-    server_path = ensure_installed(version=version)
+    server_path = ensure_installed(version=version, force=force_update)
     if not server_path.exists():
         raise SystemExit(f"agentx-trace-eval: {server_path} still missing after install, giving up")
 
+    if not force_update and version == "latest":
+        _maybe_print_update_notice(_stamped_version())
+
     # os.execv replaces this process rather than spawning a subprocess: signals, stdio, and the
     # exit code all pass straight through to agentx-server, same as invoking it directly.
-    os.execv(str(server_path), [str(server_path)] + sys.argv[1:])
+    os.execv(str(server_path), [str(server_path)] + args)
 
 
 if __name__ == "__main__":

{agentx_python-0.8.6 → agentx_python-0.8.8}/agentx/monitor/client.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 import os
 import time
-from typing import Any, List, Optional
+from typing import Any, Dict, List, Optional
 
 import requests
 
@@ -116,6 +116,10 @@ class MonitorClient:
         # The human-review queue (list / queue / label / dismiss) - what makes the
         # label-and-calibrate loop scriptable instead of dashboard-only.
         self.review_queue = ReviewQueueClient(self)
+        from agentx.monitor.rules import MonitorRulesClient
+
+        # Automation rules: route matching traffic into review / a dataset / a webhook.
+        self.rules = MonitorRulesClient(self)
         from agentx.monitor.scorers import ScorersClient
         # Scorers-catalog administration as code: template enable/disable, code/external scorer
         # CRUD and dry runs - full parity with the dashboard's Scorers page (P1.3).
@@ -264,6 +268,28 @@ class MonitorClient:
         plus deltas vs the prior window and the run-outcome breakdown."""
         return self._request("GET", "/kpis", params={"window": window})
 
+    def topics(self, window: str = "7d") -> dict:
+        """The Topics view's data over a window ("24h", "7d", "30d"): LLM-classified themes of
+        sampled production traffic with per-topic counts and sentiment. Empty until Topics is
+        enabled project-wide via ``set_topics(True)`` - classification spends one judge call
+        per sampled trace, so it is off by default."""
+        return self._request(
+            "GET", "/agent-monitoring/topics",
+            base=self._api_root(), params={"window": window},
+        )
+
+    def set_topics(self, enabled: bool, sample_rate: Optional[float] = None) -> dict:
+        """Turn Topics classification on/off for the whole project (Platform Settings >
+        Monitoring Defaults). ``sample_rate`` (0-1) optionally bounds what fraction of traffic
+        is classified - each classified trace costs one judge call."""
+        payload: Dict[str, Any] = {"topicsEnabled": enabled}
+        if sample_rate is not None:
+            payload["topicsSampleRate"] = sample_rate
+        return self._request(
+            "PUT", "/agent-monitoring/settings/monitoring-defaults",
+            base=self._api_root(), json=payload,
+        )
+
     def calibration(self, window: str = "7d") -> "CalibrationSummary":
         """Project-level judge calibration over a window ("24h", "7d", or "30d"): how often
         AgentX's own verdicts agreed with real-world ground truth reported later (ops outcomes

agentx_python-0.8.8/agentx/monitor/rules.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.monitor.client import MonitorClient
+
+logger = logging.getLogger(__name__)
+
+
+class MonitorRule(dict):
+    """Wire object for one automation rule (dict subclass so unknown fields round-trip)."""
+
+    @property
+    def id(self) -> str:
+        return self["_id"]
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.get("enabled"))
+
+
+class MonitorRulesClient:
+    """Surfaced as ``client.monitor.rules``: automation rules, evaluated on every ingested root
+    trace. A RULE routes traffic somewhere (it never scores): ``action`` is one of
+
+    - ``"review"`` - sample matching traces into the human-review queue (the stream that feeds
+      judge calibration and tuning),
+    - ``"dataset"`` - append matching traces as cases on a dataset (``action_config
+      {"datasetId": ...}``),
+    - ``"webhook"`` - POST the matching trace to your URL (``action_config {"url": ...}``).
+
+    ``filter`` narrows what matches: ``{"model": ..., "status": "error"|"any", "contains": ...,
+    "scopeMode": "all"|"selected", "agentIds": [...]}``; ``sample_rate`` (0-1, default 1)
+    down-samples the matches.
+    """
+
+    def __init__(self, client: "MonitorClient"):
+        self._client = client
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        return self._client._request(method, path, base=self._client._api_root(), **kwargs)
+
+    def list(self) -> List[MonitorRule]:
+        data = self._request("GET", "/agent-monitoring/rules")
+        return [MonitorRule(r) for r in data.get("rules", [])]
+
+    def create(
+        self,
+        name: str,
+        action: str,
+        *,
+        filter: Optional[Dict[str, Any]] = None,
+        sample_rate: Optional[float] = None,
+        action_config: Optional[Dict[str, Any]] = None,
+        enabled: bool = True,
+    ) -> MonitorRule:
+        payload: Dict[str, Any] = {"name": name, "action": action, "enabled": enabled}
+        if filter is not None:
+            payload["filter"] = filter
+        if sample_rate is not None:
+            payload["sampleRate"] = sample_rate
+        if action_config is not None:
+            payload["actionConfig"] = action_config
+        data = self._request("POST", "/agent-monitoring/rules", json=payload)
+        return MonitorRule(data.get("rule", data))
+
+    def update(self, rule_id: str, **fields: Any) -> MonitorRule:
+        """Sparse update. snake_case keys are mapped to the wire (``sample_rate`` ->
+        ``sampleRate``, ``action_config`` -> ``actionConfig``)."""
+        aliases = {"sample_rate": "sampleRate", "action_config": "actionConfig"}
+        payload = {aliases.get(k, k): v for k, v in fields.items()}
+        data = self._request("PUT", f"/agent-monitoring/rules/{rule_id}", json=payload)
+        return MonitorRule(data.get("rule", data))
+
+    def delete(self, rule_id: str) -> None:
+        self._request("DELETE", f"/agent-monitoring/rules/{rule_id}")

agentx_python-0.8.8/agentx/version.py

@@ -0,0 +1 @@
+VERSION = "0.8.8"

{agentx_python-0.8.6 → agentx_python-0.8.8}/agentx_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.8.6
+Version: 0.8.8
 Summary: Official Python SDK for AgentX (https://www.agentx.so/)
 Home-page: https://github.com/AgentX-ai/AgentX-python
 Author: Robin Wang and AgentX Team

{agentx_python-0.8.6 → agentx_python-0.8.8}/agentx_python.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ agentx/monitor/online_evaluators.py
 agentx/monitor/patterns.py
 agentx/monitor/profile.py
 agentx/monitor/review_queue.py
+agentx/monitor/rules.py
 agentx/monitor/scorers.py
 agentx/monitor/sessions.py
 agentx/monitor/signals.py
@@ -72,6 +73,7 @@ agentx_python.egg-info/entry_points.txt
 agentx_python.egg-info/not-zip-safe
 agentx_python.egg-info/requires.txt
 agentx_python.egg-info/top_level.txt
+tests/test_cli_launcher.py
 tests/test_deep_dive_fixes.py
 tests/test_docs_match_sdk.py
 tests/test_eval_scope.py

agentx_python-0.8.8/tests/test_cli_launcher.py

@@ -0,0 +1,89 @@
+"""The agentx-trace-eval launcher's staleness fixes: before these, ensure_installed downloaded
+once and then ran that binary forever - a July install silently served a July engine months
+later, with no version stamp, no way to ask for an update, and the dashboard fetched from
+releases/latest independently of the engine (so the two halves of one install could skew)."""
+
+import io
+import sys
+
+import pytest
+
+from agentx import cli
+
+
+@pytest.fixture
+def install_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(cli, "INSTALL_DIR", tmp_path)
+    return tmp_path
+
+
+def _fake_install(calls):
+    def fake(version="latest"):
+        calls.append(version)
+
+    return fake
+
+
+def test_tag_resolved_from_redirected_release_url():
+    url = "https://github.com/AgentX-ai/AgentX-trace-eval/releases/download/v0.3.0/agentx_darwin_arm64.tar.gz"
+    assert cli._tag_from_release_url(url) == "v0.3.0"
+    assert cli._tag_from_release_url("https://example.com/not-a-release") is None
+
+
+def test_existing_install_is_not_redownloaded(install_dir, monkeypatch):
+    (install_dir / "agentx-server").write_text("bin")
+    calls = []
+    monkeypatch.setattr(cli, "_install", _fake_install(calls))
+    cli.ensure_installed(version="latest")
+    assert calls == []
+
+
+def test_force_reinstalls_over_existing(install_dir, monkeypatch):
+    (install_dir / "agentx-server").write_text("bin")
+    calls = []
+    monkeypatch.setattr(cli, "_install", _fake_install(calls))
+    cli.ensure_installed(version="latest", force=True)
+    assert calls == ["latest"]
+
+
+def test_changed_version_pin_reinstalls(install_dir, monkeypatch):
+    (install_dir / "agentx-server").write_text("bin")
+    (install_dir / ".version").write_text("v0.2.0\n")
+    calls = []
+    monkeypatch.setattr(cli, "_install", _fake_install(calls))
+
+    # Same pin: no download. Different pin: download. "latest": trusts what's there.
+    cli.ensure_installed(version="v0.2.0")
+    assert calls == []
+    cli.ensure_installed(version="v0.3.0")
+    assert calls == ["v0.3.0"]
+    calls.clear()
+    cli.ensure_installed(version="latest")
+    assert calls == []
+
+
+def test_update_notice_names_both_versions(install_dir, monkeypatch, capsys):
+    monkeypatch.setattr(cli, "_latest_release_tag", lambda: "v0.9.0")
+    cli._maybe_print_update_notice("v0.2.0")
+    err = capsys.readouterr().err
+    assert "v0.2.0" in err and "v0.9.0" in err and "--update" in err
+
+
+def test_update_notice_handles_unstamped_install(install_dir, monkeypatch, capsys):
+    monkeypatch.setattr(cli, "_latest_release_tag", lambda: None)
+    cli._maybe_print_update_notice(None)
+    assert "--update" in capsys.readouterr().err
+
+
+def test_update_notice_is_silent_when_current(install_dir, monkeypatch, capsys):
+    monkeypatch.setattr(cli, "_latest_release_tag", lambda: "v0.2.0")
+    cli._maybe_print_update_notice("v0.2.0")
+    assert capsys.readouterr().err == ""
+
+
+def test_latest_release_tag_fails_open(monkeypatch):
+    def boom(*args, **kwargs):
+        raise OSError("offline")
+
+    monkeypatch.setattr(cli.requests, "get", boom)
+    assert cli._latest_release_tag() is None

agentx_python-0.8.6/agentx/version.py

@@ -1 +0,0 @@
-VERSION = "0.8.6"