agentx-python 0.8.23__tar.gz → 0.8.25__tar.gz

{agentx_python-0.8.23 → agentx_python-0.8.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.8.23
+Version: 0.8.25
 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
@@ -108,7 +108,9 @@ Also see [SDK Developer Docs](https://developers.agentx.so), [API Reference Docs
 pip install --upgrade agentx-python
 ```
 
-Requires Python 3.9 or newer.
+Requires Python 3.9 or newer for the core SDK. Some integration extras have higher floors set
+by their upstream packages - `[crewai]`, `[autogen]`, and `[databricks]` need Python 3.10+ (`[all]`
+therefore does too); the core tracer and every REST surface stay 3.9-compatible.
 
 #### Run the self-host governance suite locally
 

{agentx_python-0.8.23 → agentx_python-0.8.25}/README.md

@@ -43,7 +43,9 @@ Also see [SDK Developer Docs](https://developers.agentx.so), [API Reference Docs
 pip install --upgrade agentx-python
 ```
 
-Requires Python 3.9 or newer.
+Requires Python 3.9 or newer for the core SDK. Some integration extras have higher floors set
+by their upstream packages - `[crewai]`, `[autogen]`, and `[databricks]` need Python 3.10+ (`[all]`
+therefore does too); the core tracer and every REST surface stay 3.9-compatible.
 
 #### Run the self-host governance suite locally
 

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/agentx.py

@@ -4,6 +4,7 @@ import os
 import logging
 
 from agentx.util import get_headers, api_base, normalize_base
+from agentx.exceptions import AgentXError
 from agentx.resources.agent import Agent
 from agentx.resources.workforce import Workforce
 
@@ -19,8 +20,8 @@ class AgentX:
         # The api_key is NOT written back into os.environ (it used to be): every sub-client
         # below receives it explicitly, and mutating process-global state from a constructor
         # re-pointed unrelated code - the same leak the base_url write below had (deep-dive
-        # round 3, bug #1). Static flows that still read the env (AgentX.list_workforces,
-        # bare get_headers()) now require the caller to set AGENTX_API_KEY themselves.
+        # round 3, bug #1). Flows that still read the env (bare get_headers()) now require
+        # the caller to set AGENTX_API_KEY themselves.
         self.api_key = api_key or os.getenv("AGENTX_API_KEY")
 
         # base_url overrides AGENTX_API_BASE_URL env var (and the SDK default). It is
@@ -136,34 +137,54 @@ class AgentX:
         return cls(base_url=base_url) if base_url else cls()
 
     def get_agent(self, id: str) -> Agent:
+        """Fetch one hosted-platform agent by id.
+
+        Hosted platform only - the self-host engine does not serve /access/agents;
+        use ``client.monitor.agents.list()`` for self-host agent rows instead.
+        """
         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(self.api_key))
         # Check if response was successful
         if response.status_code == 200:
-            return Agent(**response.json())
+            return Agent(**response.json())._bind(self.api_key, self.base_url)
         else:
-            raise Exception(f"Failed to retrieve agent: {response.reason}")
+            raise AgentXError(
+                f"Failed to retrieve agent: {response.reason}. This endpoint is "
+                "hosted-platform only - on self-host use client.monitor.agents.list()."
+            )
 
     def list_agents(self) -> List[Agent]:
+        """List the hosted platform's agents.
+
+        Hosted platform only - the self-host engine does not serve /access/agents;
+        use ``client.monitor.agents.list()`` for self-host agent rows instead.
+        """
         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(self.api_key))
         # Check if response was successful
         if response.status_code == 200:
-            return [Agent(**agent) for agent in response.json()]
+            return [Agent(**agent)._bind(self.api_key, self.base_url) for agent in response.json()]
         else:
-            raise Exception(f"Failed to list agents: {response.reason}")
-
-    @staticmethod
-    def list_workforces() -> List["Workforce"]:
-        """List all workforces/teams. Static, so it reads AGENTX_API_KEY from the environment
-        directly - the constructor no longer writes ``api_key`` into os.environ, so set the
-        env var yourself before calling this."""
-        url = f"{api_base()}/access/teams"
-        response = requests.get(url, headers=get_headers())
+            raise AgentXError(
+                f"Failed to list agents: {response.reason}. This endpoint is "
+                "hosted-platform only - on self-host use client.monitor.agents.list()."
+            )
+
+    def list_workforces(self) -> List["Workforce"]:
+        """List all workforces/teams, each bound to this client's credentials - including each
+        workforce's ``manager`` and ``agents``, so their calls authenticate the same way.
+
+        This used to be documented as a static call (``AgentX.list_workforces()``); that form
+        was broken (the old staticmethod body referenced ``self`` and raised NameError on any
+        non-empty response). Construct a client instead - ``AgentX().list_workforces()`` picks
+        up AGENTX_API_KEY / AGENTX_API_BASE_URL from the environment, which is what the static
+        form effectively did."""
+        url = f"{self.base_url or api_base()}/access/teams"
+        response = requests.get(url, headers=get_headers(self.api_key))
         if response.status_code == 200:
-            return [Workforce(**workforce) for workforce in response.json()]
+            return [Workforce(**workforce)._bind(self.api_key, self.base_url) for workforce in response.json()]
         else:
             raise Exception(
                 f"Failed to list workforces: {response.status_code} - {response.reason}"
@@ -214,12 +235,18 @@ class AgentX:
         return {"ok": True, "base_url": base}
 
     def get_profile(self):
-        """Get the current user's profile information."""
+        """Get the current user's profile information.
+
+        Hosted platform only - the self-host engine does not serve /access/getProfile;
+        self-host agent/monitoring data lives under ``client.monitor`` (e.g.
+        ``client.monitor.agents.list()``).
+        """
         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:
-            raise Exception(
-                f"Failed to get profile: {response.status_code} - {response.reason}"
+            raise AgentXError(
+                f"Failed to get profile: {response.status_code} - {response.reason}. "
+                "This endpoint is hosted-platform only - on self-host use client.monitor."
             )

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/evaluations/client.py

@@ -35,7 +35,6 @@ _DEFAULT_BASE_URL = f"{_UTIL_API_BASE}/custom-agent-evaluations"
 SDK_NAME = "agentx-python"
 
 _RETRYABLE_STATUS = {429, 500, 502, 503, 504}
-_MAX_RETRIES = 3
 _RETRY_BACKOFF = [1.0, 2.0, 4.0]
 
 # The self-host analyze route judges every result before it responds, so the client has to
@@ -182,8 +181,8 @@ class EvaluationsClient:
             if resp.status_code == 422:
                 raise AgentXValidationError(resp.text)
             # Gate on the schedule itself so HTTP-status retries walk the SAME full backoff
-            # schedule connection errors do - the old `attempt < _MAX_RETRIES - 1` gate left
-            # the schedule's last entry unreachable for HTTP retries (ingest_client precedent).
+            # schedule connection errors do - an earlier fixed retry-count gate left the
+            # schedule's last entry unreachable for HTTP retries (ingest_client precedent).
             if (
                 resp.status_code in _RETRYABLE_STATUS
                 and retry
@@ -248,7 +247,9 @@ class EvaluationsClient:
         """Deletes the dataset, its grading config, and both version histories. Past runs are
         kept (their dataset reference degrades to a bare id). The engine refuses (409) when the
         dataset's config is attached to a live scorer."""
-        self._request("DELETE", f"/datasets/{dataset_id}")
+        # retry=False: a lost response + transport retry would turn a successful
+        # delete into a spurious 404.
+        self._request("DELETE", f"/datasets/{dataset_id}", retry=False)
 
     def list_datasets(self) -> List[Dataset]:
         data = self._request("GET", "/datasets", params=self._workspace_params())
@@ -440,6 +441,12 @@ class EvaluationsClient:
         quality_mode: Optional[str] = None,
         judges: Optional[List[str]] = None,
     ) -> Dict[str, Any]:
+        """Start the qualitative AI-analysis job for a run.
+
+        ``mode`` ("auto"/"sync"/"batch") is hosted-only: self-host engines run the analysis
+        synchronously and ignore it - check the response's mode field for what actually ran
+        (mirrors EvaluationRun.analyze's docstring).
+        """
         # Starts the durable analysis job and returns immediately (e.g. {"jobId": ..., "status":
         # "pending"}); poll get_analysis_status() until it reaches a terminal status, then call
         # get_report(). mode/quality_mode/judges mirror the dashboard's AnalyzeEvaluationRequest.
@@ -506,9 +513,10 @@ class EvaluationsClient:
         return self._report_from_dashboard(run_id)
 
     def get_missing_results(self, run_id: str) -> List[Dict[str, Any]]:
-        """Deprecated: on self-host the route's response body has no top-level list, so this
-        always returns ``[]``. Use :meth:`get_submitted_keys` - the same route's
-        ``submittedKeys`` - to find out what a run still needs."""
+        """Deprecated: on self-host the route returns ``missing: []`` deliberately empty -
+        the engine cannot know the client's case list - so this always returns ``[]``.
+        Use :meth:`get_submitted_keys` - the same route's ``submittedKeys`` - to find out
+        what a run still needs."""
         import warnings
 
         warnings.warn(
@@ -517,8 +525,10 @@ class EvaluationsClient:
             DeprecationWarning,
             stacklevel=2,
         )
-        data = self._request("GET", f"/runs/{run_id}/missing-results")
-        return data if isinstance(data, list) else data.get("missing", [])
+        # No request at all: the route returns `missing: []` deliberately empty (the engine
+        # cannot know the client's case list), so the round-trip only ever bought an empty
+        # result.
+        return []
 
     def get_submitted_keys(self, run_id: str) -> List[str]:
         """Idempotency keys this run has already accepted - what execute() uses to resume a

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/evaluations/datasets.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import csv
 import logging
+import warnings
 from pathlib import Path
 from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union
 
@@ -21,7 +22,8 @@ class DatasetBuilder:
     ``judge_prompt``/``judge_model`` are LLM-as-judge overrides for the dataset's grading
     config. NOTE (self-host): the engine's dataset-create route currently ignores both -
     set them on a judge scorer / the evaluation settings instead. ``sovereignty_models``
-    is accepted on the wire but not acted on by the self-host engine.
+    is dropped by the self-host engine on this route - use
+    ``client.monitor.judge_scorers.builder(sovereignty_models=...)`` which persists it.
     """
 
     def __init__(
@@ -93,8 +95,9 @@ class DatasetBuilder:
         if rouge_score:
             self._payload["rougeScore"] = {"enabled": True}
         # Sovereignty & Portability - the models to compare on this dataset (use
-        # client.evaluations.list_models() to discover valid ids). Self-host: accepted on
-        # the wire but not acted on by the engine (see class docstring).
+        # client.evaluations.list_models() to discover valid ids). Self-host: dropped by
+        # the engine on this route - use client.monitor.judge_scorers.builder(
+        # sovereignty_models=...) which persists it (see class docstring).
         if sovereignty_models:
             self._payload["sovereigntyIndex"] = {
                 "enabled": True,
@@ -161,9 +164,11 @@ class DatasetBuilder:
             main["smokeTest"] = {"enabled": True, "count": smoke_test_count}
             if smoke_test_guidance:
                 main["smokeTest"]["guidance"] = smoke_test_guidance
-        if expected_tools:
+        # `is not None`, not truthiness: an explicit empty list is a real assertion (an empty
+        # expectedTrajectory means "this case calls no tools") and must reach the wire.
+        if expected_tools is not None:
             main["expectedTrajectory"] = {"tools": expected_tools, "mode": trajectory_match_mode}
-        if expected_retrieval_context:
+        if expected_retrieval_context is not None:
             main["expectedRetrievalContext"] = expected_retrieval_context
         if splits:
             main["splits"] = splits
@@ -178,6 +183,15 @@ class DatasetBuilder:
     def publish(self) -> Dataset:
         if not self._payload["questions"]:
             raise ValueError("Dataset must have at least one case before publishing")
+        # Warn at publish time, where the request is known: the engine's dataset-create
+        # route drops sovereigntyIndex, so comparison models set here never persist.
+        sov = self._payload.get("sovereigntyIndex")
+        if isinstance(sov, dict) and sov.get("models"):
+            warnings.warn(
+                "Self-host ignores sovereigntyIndex on datasets/grading configs - use "
+                "judge_scorers.builder(sovereignty_models=...) for model comparison runs.",
+                stacklevel=2,
+            )
         logger.info(
             "Publishing dataset '%s' with %d case(s)",
             self._payload["name"],

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/evaluations/evaluation_settings.py

@@ -64,8 +64,9 @@ class EvaluationSettingsBuilder:
         if rouge_score:
             self._payload["rougeScore"] = {"enabled": True}
         # Sovereignty & Portability - the models to compare when this config runs
-        # (use client.evaluations.list_models() to discover valid ids). Self-host: accepted
-        # on the wire but not acted on by the engine (same caveat as DatasetBuilder's).
+        # (use client.evaluations.list_models() to discover valid ids). Self-host: dropped
+        # by the engine on this route - use client.monitor.judge_scorers.builder(
+        # sovereignty_models=...) which persists it (same caveat as DatasetBuilder's).
         if sovereignty_models:
             self._payload["sovereigntyIndex"] = {
                 "enabled": True,
@@ -91,6 +92,15 @@ class EvaluationSettingsBuilder:
             ]
 
     def publish(self) -> EvaluationSettings:
+        # Warn at publish time, where the request is known: the engine's settings-create
+        # route drops sovereigntyIndex, so comparison models set here never persist.
+        sov = self._payload.get("sovereigntyIndex")
+        if isinstance(sov, dict) and sov.get("models"):
+            warnings.warn(
+                "Self-host ignores sovereigntyIndex on datasets/grading configs - use "
+                "judge_scorers.builder(sovereignty_models=...) for model comparison runs.",
+                stacklevel=2,
+            )
         logger.info("Publishing evaluation settings '%s'", self._payload["name"])
         return self._client.create_evaluation_settings(self._payload)
 

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/evaluations/models.py

@@ -179,27 +179,22 @@ class Prompt(BaseModel):
 # Evaluation subject
 # ---------------------------------------------------------------------------
 
-FrameworkKind = Literal[
-    "raw_python",
-    "openai",
-    "anthropic",
-    "google",
-    "langchain",
-    "llamaindex",
-    "crewai",
-    "autogen",
-    "n8n",
-    "flowise",
-    "other",
-]
-
 RuntimeKind = Literal["local", "ci", "customer_hosted", "low_code"]
 
 
 class EvaluationSubject(BaseModel):
+    """Describes the agent under evaluation.
+
+    ``framework`` is an open string - the engine accepts any label (it also stamps
+    values like ``openai-agents``, ``langgraph``, ``google-genai``, ``litellm`` from
+    the tracing integrations). Common values: ``raw_python``, ``openai``,
+    ``anthropic``, ``google``, ``langchain``, ``llamaindex``, ``crewai``,
+    ``autogen``, ``n8n``, ``flowise``, ``other``.
+    """
+
     kind: Literal["custom_agent", "agentx_agent", "agentx_team"] = "custom_agent"
     display_name: Optional[str] = Field(default=None, alias="displayName")
-    framework: Optional[FrameworkKind] = None
+    framework: Optional[str] = None
     framework_version: Optional[str] = Field(default=None, alias="frameworkVersion")
     runtime: Optional[RuntimeKind] = "local"
     agent_instructions: Optional[str] = Field(default=None, alias="agentInstructions")

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/evaluations/reporting.py

@@ -172,7 +172,7 @@ def print_report(report: Report) -> None:
     if report.low_scoring_cases:
         _section("Low-scoring Cases  (rating <= 5)")
         for case in report.low_scoring_cases[:5]:
-            q = (case.get("query") or case.get("questionText", ""))[:80]
+            q = (case.get("query") or case.get("questionText") or "")[:80]
             rating = case.get("rating", "?")
             justification = case.get("justification", "")
             print(f"  {red(f'[{rating}]')} {q}")

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/evaluations/runner.py

@@ -229,6 +229,7 @@ class EvaluationRunContext:
                 )
             return normalized(case)
 
+        executor = None
         if concurrency > 1:
             import concurrent.futures
             import contextvars
@@ -308,6 +309,12 @@ class EvaluationRunContext:
             # generator happens to be garbage-collected.
             if results_iter is not None:
                 results_iter.close()
+            # And release the pool itself here too: close() on a NEVER-STARTED generator
+            # (e.g. every case was already submitted, so next() was never called) does not
+            # run bounded()'s finally - its executor.shutdown would never fire. shutdown()
+            # is idempotent, so the double call on the normal path is harmless.
+            if executor is not None:
+                executor.shutdown(wait=False, cancel_futures=True)
             # Flush the trailing partial batch HERE, not after the try: a mid-run exception
             # (agent crash, Ctrl-C) used to discard up to max_batch - 1 already-paid-for
             # results still waiting in it.
@@ -546,7 +553,7 @@ class EvaluationRunContext:
                 response's mode field for what actually ran.
             quality_mode: "quality_first" or "balanced" - how many items get a second/third judge.
             judges: 1-3 model ids from ``client.evaluations.list_models()``, e.g.
-                ``["gpt-5.6-luna", "claude-opus-4-8"]``. Omit to let the engine score with its
+                ``["gpt-5.6-luna", "claude-opus-5"]``. Omit to let the engine score with its
                 platform default model (a single judge, rather than the dashboard's 3-judge
                 default - SDK runs are typically lighter-weight, quick-start evaluations).
             poll_interval: seconds between status checks while waiting.
@@ -566,16 +573,27 @@ class EvaluationRunContext:
                     judges=judges,
                 )
                 deadline = time.monotonic() + timeout
-                status = self._client.get_analysis_status(self._run.run_id)
-                while not status.is_terminal and time.monotonic() < deadline:
-                    level = _ANALYSIS_LEVEL_LABELS.get(status.progress.current_level, "")
-                    spinner.update(
-                        f"Analyzing, {level + ' ' if level else ''}{status.progress.overall_percentage}%"
-                    )
+                status = None
+                while True:
+                    try:
+                        status = self._client.get_analysis_status(self._run.run_id)
+                    except Exception as poll_exc:
+                        # One transient status-poll failure (network blip, engine restart)
+                        # must not abort the whole wait - the job keeps running
+                        # server-side, so keep polling until the deadline.
+                        logger.debug("Analysis status poll failed: %s", poll_exc)
+                    if status is not None and status.is_terminal:
+                        break
+                    if time.monotonic() >= deadline:
+                        break
+                    if status is not None:
+                        level = _ANALYSIS_LEVEL_LABELS.get(status.progress.current_level, "")
+                        spinner.update(
+                            f"Analyzing, {level + ' ' if level else ''}{status.progress.overall_percentage}%"
+                        )
                     time.sleep(poll_interval)
-                    status = self._client.get_analysis_status(self._run.run_id)
 
-                if not status.is_terminal:
+                if status is None or not status.is_terminal:
                     _say(f"  {yellow('!')}  Still running after {int(timeout)}s, check the dashboard for status")
                 elif status.status == "failed":
                     reason = status.failure_reason.message if status.failure_reason else "unknown error"

{agentx_python-0.8.23 → agentx_python-0.8.25}/agentx/integrations/crewai.py

@@ -84,7 +84,7 @@ class AgentXCrewObserver:
             if task_timings:
                 execution_steps, _ = self._build_steps_from_timings(task_timings, task_outputs)
             elif task_outputs:
-                execution_steps, _ = self._build_steps_evenly_divided(task_outputs, latency_ms)
+                execution_steps, _ = self._build_steps_evenly_divided(task_outputs, latency_ms, start)
 
             # Each task becomes its own real child span. tool_calls isn't passed to
             # _merge_child_run here: _build_steps_from_timings/_build_steps_evenly_divided both
@@ -144,14 +144,14 @@ class AgentXCrewObserver:
                     TaskFailedEvent,
                     TaskStartedEvent,
                 )
-            except ImportError:
+            except Exception:  # noqa: BLE001 - crewai import raises TypeError (PEP 604) on py3.9, not just ImportError
                 from crewai.utilities.events import crewai_event_bus
                 from crewai.utilities.events.task_events import (
                     TaskCompletedEvent,
                     TaskFailedEvent,
                     TaskStartedEvent,
                 )
-        except ImportError:
+        except Exception:  # noqa: BLE001 - crewai import raises TypeError (PEP 604) on py3.9, not just ImportError
             if not _warned_no_event_bus:
                 _warned_no_event_bus = True
                 logger.warning(
@@ -262,25 +262,33 @@ class AgentXCrewObserver:
 
         return execution_steps, tool_calls
 
-    def _build_steps_evenly_divided(self, task_outputs: List[Any], latency_ms: float) -> tuple:
+    def _build_steps_evenly_divided(self, task_outputs: List[Any], latency_ms: float, start: float) -> tuple:
         """
         Fallback for CrewAI versions predating the events module: no
         per-task timing is available, so attribute the total latency evenly
         across tasks so the timeline still sums to the measured wall-clock
-        duration.
+        duration. Each synthesized step also gets a real start_time/end_time
+        (consecutive per_step_s slices from the kickoff's start) so the
+        dashboard timeline can position it, not just size it.
         """
         tool_calls: List[Dict[str, Any]] = []
         execution_steps: List[Dict[str, Any]] = []
-        for task_out in task_outputs:
+        per_step_ms = latency_ms / len(task_outputs)
+        per_step_s = per_step_ms / 1000.0
+        for i, task_out in enumerate(task_outputs):
             description = getattr(task_out, "description", "task")
             name = description[:100]
             task_output = str(getattr(task_out, "raw", ""))
             tool_calls.append({"name": name, "input": description, "output": task_output})
-            execution_steps.append({"name": name, "duration_ms": 0, "input": description, "output": task_output})
-
-        per_step_ms = latency_ms / len(execution_steps)
-        for step in execution_steps:
-            step["duration_ms"] = per_step_ms
+            step_start = start + i * per_step_s
+            execution_steps.append({
+                "name": name,
+                "duration_ms": per_step_ms,
+                "start_time": step_start,
+                "end_time": step_start + per_step_s,
+                "input": description,
+                "output": task_output,
+            })
 
         return execution_steps, tool_calls
 
@@ -307,4 +315,6 @@ class AgentXCrewObserver:
             framework="crewai",
             session_id=session_id or self._session_id,
             sync=sync,
+            # Same statement kickoff() makes: the root of a crew run is the agent run itself.
+            span_kind="agent",
         )