agentx-python 0.6.33__tar.gz → 0.6.35__tar.gz

{agentx_python-0.6.33 → agentx_python-0.6.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.6.33
+Version: 0.6.35
 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.6.33 → agentx_python-0.6.35}/agentx/agentx.py

@@ -20,10 +20,12 @@ class AgentX:
         if self.api_key and not os.getenv("AGENTX_API_KEY"):
             os.environ["AGENTX_API_KEY"] = self.api_key
 
-        # base_url overrides AGENTX_API_BASE_URL env var (and the SDK default)
+        # base_url overrides AGENTX_API_BASE_URL env var (and the SDK default). It is
+        # deliberately NOT written back into os.environ: the constructor used to do that, which
+        # made the last-constructed client silently re-point every other client in the process
+        # (deep-dive round 3, bug #1). Each sub-client below receives this value explicitly and
+        # captures it at construction instead.
         self.base_url = base_url or os.getenv("AGENTX_API_BASE_URL")
-        if self.base_url:
-            os.environ["AGENTX_API_BASE_URL"] = self.base_url
 
         self.workspace_id = workspace_id or os.getenv("AGENTX_WORKSPACE_ID")
 
@@ -58,23 +60,29 @@ class AgentX:
 
         # Report real, after-the-fact outcomes ("the ticket got reopened") against traces - the
         # ground truth behind the dashboard's Judge Calibration card. Self-host only.
-        self.outcomes = OutcomesClient(api_key=self.api_key)
+        self.outcomes = OutcomesClient(api_key=self.api_key, base_url=self.base_url)
 
         from agentx.projects import ProjectsClient
 
         # Project CRUD (self-host): isolated tenants with their own API keys (P1.1).
-        self.projects = ProjectsClient(api_key=self.api_key)
+        self.projects = ProjectsClient(api_key=self.api_key, base_url=self.base_url)
 
         from agentx.traces import TracesClient
 
         # The read side of tracing: trace-by-id detail and paginated listing (P1.2).
-        self.traces = TracesClient(api_key=self.api_key)
+        self.traces = TracesClient(api_key=self.api_key, base_url=self.base_url)
+
+        from agentx.export import ExportClient
+
+        # Bulk NDJSON egress for backup/migration (P2.1): manifest, per-entity streaming, and
+        # directory dumps. Self-host only.
+        self.export = ExportClient(api_key=self.api_key, base_url=self.base_url)
 
         from agentx.feedback import FeedbackClient
 
         # Forward end-user votes ("up"/"down") on traced responses - a "down" raises a signal
         # directly, and every vote feeds Judge Calibration alongside outcomes. Self-host only.
-        self.feedback = FeedbackClient(api_key=self.api_key)
+        self.feedback = FeedbackClient(api_key=self.api_key, base_url=self.base_url)
 
         _ingest_client = IngestClient(
             api_key=self.api_key,
@@ -90,9 +98,9 @@ class AgentX:
         return cls()
 
     def get_agent(self, id: str) -> Agent:
-        url = f"{api_base()}/access/agents/{id}"
+        url = f"{self.base_url or api_base()}/access/agents/{id}"
         # Make a GET request to the AgentX API
-        response = requests.get(url, headers=get_headers())
+        response = requests.get(url, headers=get_headers(self.api_key))
         # Check if response was successful
         if response.status_code == 200:
             return Agent(**response.json())
@@ -100,9 +108,9 @@ class AgentX:
             raise Exception(f"Failed to retrieve agent: {response.reason}")
 
     def list_agents(self) -> List[Agent]:
-        url = f"{api_base()}/access/agents"
+        url = f"{self.base_url or api_base()}/access/agents"
         # Make a GET request to the AgentX API
-        response = requests.get(url, headers=get_headers())
+        response = requests.get(url, headers=get_headers(self.api_key))
         # Check if response was successful
         if response.status_code == 200:
             return [Agent(**agent) for agent in response.json()]
@@ -140,7 +148,7 @@ class AgentX:
         """
         from agentx.exceptions import AgentXAPIError, AgentXAuthError, AgentXConnectionError
 
-        base = api_base()
+        base = (self.base_url or api_base()).rstrip("/")
         # /monitor/patterns: the cheapest key-authenticated endpoint that exists on both the
         # hosted API and the self-host engine's SDK-facing router.
         url = f"{base}/monitor/patterns"
@@ -167,8 +175,8 @@ class AgentX:
 
     def get_profile(self):
         """Get the current user's profile information."""
-        url = f"{api_base()}/access/getProfile"
-        response = requests.get(url, headers=get_headers())
+        url = f"{self.base_url or api_base()}/access/getProfile"
+        response = requests.get(url, headers=get_headers(self.api_key))
         if response.status_code == 200:
             return response.json()
         else:

agentx_python-0.6.35/agentx/export.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, Iterator, List, Optional
+
+import requests
+
+from agentx.util import api_base, get_headers
+
+logger = logging.getLogger(__name__)
+
+
+class AgentXExportError(Exception):
+    pass
+
+
+class ExportClient:
+    """Surfaced as ``client.export``: bulk NDJSON egress for backup and migration (self-host).
+
+    The engine's ``GET /export`` manifest lists every exportable entity (traces, signals,
+    events, runs, feedback, outcomes, scorer config, ...) with live row counts;
+    ``GET /export/<entity>`` streams the rows as NDJSON. Everything is scoped to the API key's
+    project, so an export can never cross a tenant boundary.
+
+    Typical uses::
+
+        client.export.dump("./backup")                     # full backup, one .ndjson per entity
+        client.export.dump("./nightly", since=yesterday)   # incremental
+        for row in client.export.iter("traces"):           # stream without touching disk
+            ...
+
+    Restore paths are documented in the self-host backup runbook: replay traces through
+    ``client.tracer`` / ``POST /ingest/traces``, or restore at the database level
+    (``pg_dump`` / SQLite file copy). There is deliberately no blind row-import endpoint.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        self._api_key = api_key
+        # Captured once at construction (deep-dive round 3, bug #1).
+        self._base_url = (base_url or api_base()).rstrip("/")
+
+    def manifest(self) -> List[Dict[str, Any]]:
+        """The exportable entities with live row counts: ``[{entity, rows, path}, ...]``."""
+        resp = requests.get(
+            f"{self._base_url}/export", headers=get_headers(self._api_key), timeout=30
+        )
+        if resp.status_code >= 400:
+            raise AgentXExportError(f"Export manifest failed ({resp.status_code}): {resp.text[:200]}")
+        return resp.json().get("entities", [])
+
+    def iter(self, entity: str, since: Optional[str] = None) -> Iterator[Dict[str, Any]]:
+        """Stream one entity's rows as dicts without buffering the whole table in memory.
+        ``since`` is an ISO-8601 date for incremental pulls (filters on the entity's own
+        timestamp column, e.g. ``createdAt`` for traces, ``lastSeenAt`` for signals)."""
+        params = {"since": since} if since else None
+        resp = requests.get(
+            f"{self._base_url}/export/{entity}",
+            headers=get_headers(self._api_key),
+            params=params,
+            stream=True,
+            timeout=120,
+        )
+        if resp.status_code >= 400:
+            raise AgentXExportError(f"Export of {entity!r} failed ({resp.status_code}): {resp.text[:200]}")
+        for line in resp.iter_lines(decode_unicode=True):
+            if line and line.strip():
+                yield json.loads(line)
+
+    def dump(
+        self,
+        directory: str,
+        entities: Optional[List[str]] = None,
+        since: Optional[str] = None,
+    ) -> Dict[str, int]:
+        """Write ``<entity>.ndjson`` files (plus a ``manifest.json``) into ``directory`` and
+        return ``{entity: rows_written}``. Defaults to every entity the engine advertises;
+        pass ``entities`` to restrict, ``since`` for an incremental snapshot."""
+        os.makedirs(directory, exist_ok=True)
+        manifest = self.manifest()
+        wanted = [e["entity"] for e in manifest] if entities is None else entities
+        written: Dict[str, int] = {}
+        for entity in wanted:
+            path = os.path.join(directory, f"{entity}.ndjson")
+            count = 0
+            with open(path, "w", encoding="utf-8") as fh:
+                for row in self.iter(entity, since=since):
+                    fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+                    count += 1
+            written[entity] = count
+            logger.debug("Exported %d %s rows to %s", count, entity, path)
+        with open(os.path.join(directory, "manifest.json"), "w", encoding="utf-8") as fh:
+            json.dump(
+                {"entities": manifest, "written": written, **({"since": since} if since else {})},
+                fh,
+                indent=2,
+            )
+        return written

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/feedback.py

@@ -26,8 +26,10 @@ class FeedbackClient:
     reopened", reported by a workflow); feedback is a human vote with up/down semantics.
     """
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
         self._api_key = api_key
+        # Captured once at construction (deep-dive round 3, bug #1).
+        self._base_url = (base_url or api_base()).rstrip("/")
 
     def report(
         self,
@@ -61,7 +63,7 @@ class FeedbackClient:
             payload["endUserId"] = end_user_id
 
         resp = requests.post(
-            f"{api_base()}/feedback",
+            f"{self._base_url}/feedback",
             headers={**get_headers(self._api_key), "Content-Type": "application/json"},
             json=payload,
             timeout=10,
@@ -79,7 +81,7 @@ class FeedbackClient:
         """All votes recorded on one trace, oldest first (``GET /feedback/trace/:traceId``) -
         the same rows the dashboard's trace dialog shows as up/down chips."""
         resp = requests.get(
-            f"{api_base()}/feedback/trace/{trace_id}",
+            f"{self._base_url}/feedback/trace/{trace_id}",
             headers=get_headers(self._api_key),
             timeout=10,
         )

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/monitor/client.py

@@ -85,7 +85,9 @@ class MonitorClient:
         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).
-        self.scorers = ScorersClient(api_key=api_key)
+        # Handed this client's own resolved API root, never the process-global default, so a
+        # second AgentX() with a different base_url can't re-point it (deep-dive bug #1).
+        self.scorers = ScorersClient(api_key=api_key, base_url=self._api_root())
         self.profile = MonitorProfileClient(self)
         self.online_evaluators = MonitorOnlineEvaluatorClient(self)
         from agentx.monitor.sessions import MonitorSessionClient
@@ -213,6 +215,17 @@ class MonitorClient:
         plus deltas vs the prior window and the run-outcome breakdown."""
         return self._request("GET", "/kpis", params={"window": window})
 
+    def calibration(self, window: str = "7d") -> dict:
+        """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
+        via ``client.outcomes`` and end-user downvotes). Returns the dashboard's Judge
+        Calibration numbers: compared count, agreement, falsePositiveRate, falseNegativeRate.
+        Per-evaluator calibration lives on ``client.monitor.online_evaluators.calibration``."""
+        return self._request(
+            "GET", "/agent-monitoring/calibration",
+            base=self._api_root(), params={"window": window},
+        )
+
     # ------------------------------------------------------------------
     # Signal endpoints
     # ------------------------------------------------------------------

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/monitor/scorers.py

@@ -33,13 +33,15 @@ class ScorersClient:
     wire.
     """
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
         self._api_key = api_key
+        # Captured once at construction (deep-dive round 3, bug #1).
+        self._base_url = (base_url or api_base()).rstrip("/")
 
     def _request(self, method: str, path: str, json: Any = None, params: Any = None) -> Any:
         resp = requests.request(
             method,
-            f"{api_base()}/agent-monitoring{path}",
+            f"{self._base_url}/agent-monitoring{path}",
             headers={**get_headers(self._api_key), "Content-Type": "application/json"},
             json=json,
             params=params,

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/outcomes.py

@@ -26,8 +26,10 @@ class OutcomesClient:
     tracker's webhook, a CRM workflow), and this method is the SDK's way to be that caller.
     """
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
         self._api_key = api_key
+        # Captured once at construction (deep-dive round 3, bug #1).
+        self._base_url = (base_url or api_base()).rstrip("/")
 
     def report(
         self,
@@ -69,7 +71,7 @@ class OutcomesClient:
             payload["reportedBy"] = reported_by
 
         resp = requests.post(
-            f"{api_base()}/outcomes",
+            f"{self._base_url}/outcomes",
             headers={**get_headers(self._api_key), "Content-Type": "application/json"},
             json=payload,
             timeout=10,

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/projects.py

@@ -25,13 +25,16 @@ class ProjectsClient:
     users; this client covers the default self-host (auth-disabled) mode.
     """
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
         self._api_key = api_key
+        # Captured once at construction so two clients with different bases can coexist
+        # (deep-dive round 3, bug #1) - never read from process-global state per call.
+        self._base_url = (base_url or api_base()).rstrip("/")
 
     def _request(self, method: str, path: str, json: Any = None) -> Any:
         resp = requests.request(
             method,
-            f"{api_base()}{path}",
+            f"{self._base_url}{path}",
             headers={**get_headers(self._api_key), "Content-Type": "application/json"},
             json=json,
             timeout=15,

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/traces.py

@@ -24,12 +24,14 @@ class TracesClient:
     span-tree read.
     """
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
         self._api_key = api_key
+        # Captured once at construction (deep-dive round 3, bug #1).
+        self._base_url = (base_url or api_base()).rstrip("/")
 
     def _request(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
         resp = requests.get(
-            f"{api_base()}{path}",
+            f"{self._base_url}{path}",
             headers=get_headers(self._api_key),
             params=params or {},
             timeout=15,

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/tracing/ingest_client.py

@@ -72,6 +72,11 @@ class IngestClient:
         # failures stay at DEBUG to avoid log spam. client.ping() is the fail-fast startup check.
         self._delivery_warning_emitted = False
 
+        # Dropped-trace accounting (deep-dive round 3, bug #5): fire-and-forget may drop traces
+        # (queue overflow, retries exhausted while the engine is down), but it must never drop
+        # them SILENTLY. First drop warns, then every 50th, with the cumulative count.
+        self._dropped = 0
+
         self._queue: queue.Queue[Optional[Dict[str, Any]]] = queue.Queue(maxsize=_QUEUE_MAX)
         self._worker = threading.Thread(target=self._drain, daemon=True, name="agentx-ingest")
         self._worker.start()
@@ -90,11 +95,44 @@ class IngestClient:
         try:
             self._queue.put_nowait(payload)
         except queue.Full:
-            logger.debug("agentx ingest queue full - trace dropped")
+            self._record_drop("queue full")
+
+    def flush(self, timeout: float = 5.0) -> bool:
+        """Block until all queued traces have been sent, or until ``timeout`` seconds elapse.
 
-    def flush(self, timeout: float = 5.0) -> None:
-        """Block until all queued traces have been sent (or timeout elapses)."""
-        self._queue.join()
+        Returns ``True`` when the queue fully drained, ``False`` on deadline - undelivered
+        traces stay queued and keep sending in the background. The old implementation called
+        ``queue.join()``, which has no deadline at all: with the engine down, each queued item
+        burned the full retry backoff and a ``flush(timeout=3)`` measurably blocked for over
+        two minutes (deep-dive round 3, bug #5). The timeout is now a real wall-clock bound.
+        """
+        deadline = time.time() + timeout
+        with self._queue.all_tasks_done:
+            while self._queue.unfinished_tasks:
+                remaining = deadline - time.time()
+                if remaining <= 0:
+                    logger.warning(
+                        "agentx flush(%.1fs) timed out with %d trace(s) still undelivered - "
+                        "they remain queued and keep sending in the background",
+                        timeout,
+                        self._queue.unfinished_tasks,
+                    )
+                    return False
+                self._queue.all_tasks_done.wait(remaining)
+        return True
+
+    def _record_drop(self, reason: str) -> None:
+        self._dropped += 1
+        if self._dropped == 1 or self._dropped % 50 == 0:
+            logger.warning(
+                "agentx dropped a trace (%s) - %d dropped total this process. "
+                "Tracing is fire-and-forget: traces that cannot be delivered are not persisted "
+                "locally. Use client.ping() at startup to fail fast on a bad endpoint.",
+                reason,
+                self._dropped,
+            )
+        else:
+            logger.debug("agentx dropped a trace (%s), %d total", reason, self._dropped)
 
     def send_trace_sync(self, payload: Dict[str, Any]) -> Optional[str]:
         """
@@ -372,7 +410,9 @@ class IngestClient:
             try:
                 self._send(payload)
             except Exception as exc:
-                logger.debug("agentx ingest send error: %s", exc)
+                # Anything _send didn't classify still cost us this payload - count it as a
+                # drop rather than whispering at DEBUG (bug #5's silent half).
+                self._record_drop(f"unexpected error: {exc}")
             finally:
                 self._queue.task_done()
 
@@ -397,4 +437,4 @@ class IngestClient:
             return
 
         self._warn_delivery(str(last_exc))
-        logger.debug("agentx ingest failed after retries: %s", last_exc)
+        self._record_drop(f"retries exhausted: {last_exc}")

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx/tracing/tracer.py

@@ -890,9 +890,11 @@ class Tracer:
             agent_id=agent_id,
         )
 
-    def flush(self, timeout: float = 5.0) -> None:
-        """Block until all queued traces have been delivered."""
-        self._client.flush(timeout)
+    def flush(self, timeout: float = 5.0) -> bool:
+        """Block until all queued traces have been delivered, or until ``timeout`` seconds
+        elapse. Returns ``True`` when everything drained, ``False`` on deadline (a warning is
+        logged and undelivered traces keep sending in the background)."""
+        return self._client.flush(timeout)
 
     # ------------------------------------------------------------------
     # CI/CD evaluation

agentx_python-0.6.35/agentx/version.py

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

{agentx_python-0.6.33 → agentx_python-0.6.35}/agentx_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.6.33
+Version: 0.6.35
 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.6.33 → agentx_python-0.6.35}/agentx_python.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ agentx/__init__.py
 agentx/agentx.py
 agentx/cli.py
 agentx/exceptions.py
+agentx/export.py
 agentx/feedback.py
 agentx/outcomes.py
 agentx/projects.py
@@ -67,6 +68,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_deep_dive_fixes.py
 tests/test_integration.py
 tests/test_integrations.py
 tests/test_selfhost_analysis_fallback.py

agentx_python-0.6.35/tests/test_deep_dive_fixes.py

@@ -0,0 +1,85 @@
+"""Regressions for deep-dive round 3's SDK bugs (sample-scripts/eval_framework_deep_dive/
+DEEP_DIVE_REPORT.md): bug #1 (base_url was process-global via os.environ, so the
+last-constructed client silently re-pointed every other client) and bug #5 (flush(timeout)
+called queue.join() with no deadline and dropped traces silently)."""
+
+import logging
+import os
+import time
+
+import pytest
+import requests
+
+from agentx import AgentX
+from agentx.tracing.ingest_client import IngestClient
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    monkeypatch.delenv("AGENTX_API_BASE_URL", raising=False)
+    monkeypatch.setenv("AGENTX_API_KEY", "agtx_test_key")
+    yield
+
+
+def test_second_client_does_not_repoint_the_first():
+    a = AgentX(api_key="k1", base_url="http://engine-a:1111/api/v1")
+    b = AgentX(api_key="k2", base_url="http://engine-b:2222/api/v1")
+
+    # The constructor must not leak its base into process-global state...
+    assert os.environ.get("AGENTX_API_BASE_URL") is None
+
+    # ...and every per-call-resolving surface of client A must still point at engine A.
+    for sub in (a.projects, a.traces, a.export, a.feedback, a.outcomes, a.monitor.scorers):
+        assert "engine-a:1111" in sub._base_url, type(sub).__name__
+    for sub in (b.projects, b.traces, b.export, b.feedback, b.outcomes, b.monitor.scorers):
+        assert "engine-b:2222" in sub._base_url, type(sub).__name__
+
+
+def test_env_var_still_works_as_a_default(monkeypatch):
+    monkeypatch.setenv("AGENTX_API_BASE_URL", "http://from-env:3333/api/v1")
+    c = AgentX(api_key="k")
+    assert "from-env:3333" in c.projects._base_url
+
+
+def _stalled_client(monkeypatch, per_call_delay: float) -> IngestClient:
+    client = IngestClient(api_key="k", sdk_version="test", base_url="http://localhost:9/api/v1")
+
+    def slow_post(*args, **kwargs):
+        time.sleep(per_call_delay)
+        raise ConnectionError("engine down")
+
+    monkeypatch.setattr(client._session, "post", slow_post)
+    return client
+
+
+def test_flush_timeout_is_a_wall_clock_bound(monkeypatch):
+    client = _stalled_client(monkeypatch, per_call_delay=2.0)
+    for i in range(5):
+        client.enqueue({"name": f"t{i}"})
+
+    t0 = time.time()
+    drained = client.flush(timeout=1.0)
+    elapsed = time.time() - t0
+
+    assert drained is False
+    # The old queue.join() implementation blocked for the full retry schedule of every queued
+    # item (measured 140s for 20 items); the deadline must now bind within a small margin.
+    assert elapsed < 3.0, f"flush(timeout=1.0) blocked for {elapsed:.1f}s"
+
+
+def test_dropped_traces_warn_instead_of_vanishing(monkeypatch, caplog):
+    client = IngestClient(api_key="k", sdk_version="test", base_url="http://localhost:9/api/v1")
+
+    def refuse(*args, **kwargs):
+        raise requests.exceptions.ConnectionError("connection refused")
+
+    monkeypatch.setattr(client._session, "post", refuse)
+    with caplog.at_level(logging.WARNING, logger="agentx.tracing.ingest_client"):
+        client.enqueue({"name": "doomed"})
+        for _ in range(200):  # wait out the retry backoff
+            if client._dropped >= 1:
+                break
+            time.sleep(0.1)
+
+    assert client._dropped >= 1
+    assert any("dropped a trace" in rec.message for rec in caplog.records)

agentx_python-0.6.33/agentx/version.py

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