agentx-python 0.6.27__tar.gz → 0.6.29__tar.gz

{agentx_python-0.6.27/agentx_python.egg-info → agentx_python-0.6.29}/PKG-INFO

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

@@ -111,6 +111,50 @@ class AgentX:
                 f"Failed to list workforces: {response.status_code} - {response.reason}"
             )
 
+    def ping(self) -> dict:
+        """Verify the client can actually reach AgentX and that the API key is accepted.
+
+        The constructor is deliberately lazy (no network call - standard SDK behavior, so
+        offline construction and tests work), and trace delivery is fire-and-forget, so a
+        wrong ``base_url`` or ``api_key`` otherwise surfaces only as a one-time warning in
+        logs while traces silently go nowhere. Call this once at startup of a long-running
+        service to fail fast instead::
+
+            client = AgentX.from_env()
+            client.ping()  # raises immediately on a bad URL or key
+
+        Raises :class:`agentx.exceptions.AgentXConnectionError` when the URL is unreachable,
+        :class:`agentx.exceptions.AgentXAuthError` when the key is rejected, and
+        :class:`agentx.exceptions.AgentXAPIError` on any other non-OK response. Returns
+        ``{"ok": True, "base_url": ...}`` on success.
+        """
+        from agentx.exceptions import AgentXAPIError, AgentXAuthError, AgentXConnectionError
+
+        base = api_base()
+        # /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"
+        try:
+            response = requests.get(url, headers=get_headers(self.api_key), timeout=10)
+        except requests.RequestException as exc:
+            raise AgentXConnectionError(
+                f"Cannot reach AgentX at {base} ({exc.__class__.__name__}: {exc}). "
+                "Check base_url / AGENTX_API_BASE_URL - for self-host it should look like "
+                "http://localhost:4700/api/v1."
+            ) from exc
+        if response.status_code in (401, 403):
+            raise AgentXAuthError(
+                f"AgentX at {base} rejected the API key (HTTP {response.status_code}). "
+                "Check api_key / AGENTX_API_KEY - for self-host, copy the 'Default project "
+                "API key' from the engine's startup log."
+            )
+        if not response.ok:
+            raise AgentXAPIError(
+                f"AgentX at {base} responded HTTP {response.status_code} to the health probe.",
+                status_code=response.status_code,
+            )
+        return {"ok": True, "base_url": base}
+
     def get_profile(self):
         """Get the current user's profile information."""
         url = f"{api_base()}/access/getProfile"

{agentx_python-0.6.27 → agentx_python-0.6.29}/agentx/evaluations/client.py

@@ -32,9 +32,23 @@ _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
+# wait out the whole job on one connection. Matches EvaluationRunContext.analyze()'s own
+# default timeout.
+_SELF_HOST_ANALYZE_TIMEOUT = 1800
+
 
 class AgentXEvaluationsError(Exception):
-    pass
+    """An evaluations API call failed.
+
+    ``status_code`` carries the HTTP status when the failure came from a response rather
+    than from the transport, so callers can branch on it instead of matching on the message
+    text. It is ``None`` for connection errors and for retry exhaustion.
+    """
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
 
 
 class AgentXAuthError(AgentXEvaluationsError):
@@ -69,6 +83,8 @@ class EvaluationsClient:
         if not _api_base.endswith("/custom-agent-evaluations"):
             _api_base = f"{_api_base}/custom-agent-evaluations"
         self._base_url = _api_base
+        # None until an analysis call tells us which engine this is; see _api_root.
+        self._analysis_on_dashboard_router: Optional[bool] = None
         self._session = requests.Session()
         self._session.headers.update(
             {
@@ -86,6 +102,8 @@ class EvaluationsClient:
         self.datasets = DatasetClient(self)
         self.settings = EvaluationSettingsClient(self)
         self.prompts = PromptClient(self)
+        from agentx.evaluations.tool_schemas import ToolSchemaClient
+        self.tool_schemas = ToolSchemaClient(self)
 
     # ------------------------------------------------------------------
     # Low-level HTTP
@@ -103,10 +121,29 @@ class EvaluationsClient:
         """Same as _with_workspace(), for GET requests that take workspaceId as a query param."""
         return {"workspaceId": self._workspace_id} if self._workspace_id else None
 
-    def _request(self, method: str, path: str, timeout: int = 30, **kwargs) -> Any:
-        url = f"{self._base_url}{path}"
+    def _request(
+        self,
+        method: str,
+        path: str,
+        timeout: int = 30,
+        base: Optional[str] = None,
+        retry: bool = True,
+        **kwargs,
+    ) -> Any:
+        """Call the evaluations API.
+
+        ``base`` overrides the ``/custom-agent-evaluations`` prefix for the handful of
+        routes that live on a different router (see ``_api_root``).
+
+        ``retry=False`` disables the backoff loop entirely. Use it for any request that is
+        both slow and billable: the loop retries on ``requests.RequestException``, which
+        includes read timeouts, so a synchronous endpoint that outlives its timeout would
+        otherwise be re-invoked, and paid for, up to four times.
+        """
+        url = f"{base or self._base_url}{path}"
+        schedule = [0.0] + (_RETRY_BACKOFF if retry else [])
         last_exc: Optional[Exception] = None
-        for attempt, wait in enumerate([0.0] + _RETRY_BACKOFF):
+        for attempt, wait in enumerate(schedule):
             if wait:
                 time.sleep(wait)
             try:
@@ -120,14 +157,22 @@ class EvaluationsClient:
                 raise AgentXAuthError("Invalid or missing API key")
             if resp.status_code == 422:
                 raise AgentXValidationError(resp.text)
-            if resp.status_code in _RETRYABLE_STATUS and attempt < _MAX_RETRIES - 1:
+            if (
+                resp.status_code in _RETRYABLE_STATUS
+                and retry
+                and attempt < _MAX_RETRIES - 1
+            ):
                 logger.debug(
                     "Retryable status %d (attempt %d)", resp.status_code, attempt + 1
                 )
-                last_exc = AgentXEvaluationsError(f"HTTP {resp.status_code}")
+                last_exc = AgentXEvaluationsError(
+                    f"HTTP {resp.status_code}", status_code=resp.status_code
+                )
                 continue
             if not resp.ok:
-                raise AgentXEvaluationsError(f"HTTP {resp.status_code}: {resp.text}")
+                raise AgentXEvaluationsError(
+                    f"HTTP {resp.status_code}: {resp.text}", status_code=resp.status_code
+                )
             try:
                 return resp.json()
             except Exception:
@@ -303,6 +348,10 @@ class EvaluationsClient:
         # 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.
+        #
+        # On self-host the fallback route runs the analysis synchronously and returns only when
+        # it is done, so the caller's poll loop sees a terminal status on its first check. The
+        # request is therefore given the full analysis timeout and, critically, no retries.
         payload: Dict[str, Any] = {}
         if mode is not None:
             payload["mode"] = mode
@@ -310,23 +359,235 @@ class EvaluationsClient:
             payload["qualityMode"] = quality_mode
         if judges is not None:
             payload["judges"] = [{"model": m} for m in judges]
-        return self._request("POST", f"/runs/{run_id}/analyze", json=payload, timeout=30)
+
+        if not self._analysis_on_dashboard_router:
+            try:
+                return self._request(
+                    "POST", f"/runs/{run_id}/analyze", json=payload, timeout=30
+                )
+            except AgentXEvaluationsError as exc:
+                if not self._note_missing_analysis_route(exc, "analyze"):
+                    raise
+
+        return self._request(
+            "POST",
+            f"/evaluate/analyze/{run_id}",
+            base=self._api_root,
+            json=payload,
+            timeout=_SELF_HOST_ANALYZE_TIMEOUT,
+            retry=False,
+        )
 
     def get_analysis_status(self, run_id: str) -> AnalysisStatus:
-        data = self._request("GET", f"/runs/{run_id}/analyze-status")
+        if not self._analysis_on_dashboard_router:
+            try:
+                return AnalysisStatus(
+                    **self._request("GET", f"/runs/{run_id}/analyze-status")
+                )
+            except AgentXEvaluationsError as exc:
+                if not self._note_missing_analysis_route(exc, "analyze-status"):
+                    raise
+
+        data = self._request(
+            "GET", f"/evaluate/analyze/{run_id}/status", base=self._api_root
+        )
         return AnalysisStatus(**data)
 
     def get_run(self, run_id: str) -> Dict[str, Any]:
         return self._request("GET", f"/runs/{run_id}")
 
     def get_report(self, run_id: str) -> Report:
-        data = self._request("GET", f"/runs/{run_id}/report")
-        return Report(**data)
+        if not self._analysis_on_dashboard_router:
+            try:
+                return Report(**self._request("GET", f"/runs/{run_id}/report"))
+            except AgentXEvaluationsError as exc:
+                if not self._note_missing_analysis_route(exc, "report"):
+                    raise
+
+        return self._report_from_dashboard(run_id)
 
     def get_missing_results(self, run_id: str) -> List[Dict[str, Any]]:
         data = self._request("GET", f"/runs/{run_id}/missing-results")
         return data if isinstance(data, list) else data.get("missing", [])
 
+    # ------------------------------------------------------------------
+    # Self-host analysis fallback
+    #
+    # The self-host engine (AgentX-trace-eval) mounts two routers: the SDK's
+    # /custom-agent-evaluations, and /evaluate for the dashboard. Its
+    # /custom-agent-evaluations router implements the run lifecycle - runs, results,
+    # finalize, gate - but not /analyze, /analyze-status or /report, which exist only on
+    # /evaluate. Hosted AgentX serves all of them from the SDK's own router.
+    #
+    # So the three analysis calls try the SDK route first and fall back to the dashboard
+    # route on a 404, which means hosted behaviour is byte-for-byte unchanged: it never
+    # 404s, so it never falls back. The outcome is cached on the client so the probe costs
+    # one request per process, not one per call.
+    # ------------------------------------------------------------------
+
+    @property
+    def _api_root(self) -> str:
+        """The API base with the ``/custom-agent-evaluations`` suffix removed."""
+        suffix = "/custom-agent-evaluations"
+        if self._base_url.endswith(suffix):
+            return self._base_url[: -len(suffix)]
+        return self._base_url
+
+    def _note_missing_analysis_route(
+        self, exc: AgentXEvaluationsError, route: str
+    ) -> bool:
+        """Return True if ``exc`` is the 404 that means "this engine is self-host".
+
+        Only a 404 qualifies. Anything else - auth, validation, a 500, a dead connection -
+        is a real failure on a route that does exist, and must propagate rather than be
+        retried against a different endpoint that would mask it.
+        """
+        if exc.status_code != 404:
+            return False
+        if self._analysis_on_dashboard_router is None:
+            logger.info(
+                "%s is not served from %s; using the dashboard router at %s "
+                "(self-host engine)",
+                route,
+                self._base_url,
+                self._api_root,
+            )
+        self._analysis_on_dashboard_router = True
+        return True
+
+    def _report_from_dashboard(self, run_id: str) -> Report:
+        """Assemble a Report from the dashboard's evaluation record.
+
+        Self-host has no /report route; it returns the analysis nested inside the
+        evaluation itself, under ``analysis.analysis`` with its statistics one level up.
+        The field names already match the Report models, so this is a reshape, not a
+        translation.
+        """
+        record = self._request("GET", f"/evaluate/{run_id}", base=self._api_root)
+        envelope = record.get("analysis") or {}
+        body = envelope.get("analysis") or {}
+
+        if not envelope:
+            raise AgentXEvaluationsError(
+                f"Run {run_id} has no analysis to report. Nothing has analyzed it yet, "
+                "or the analysis failed - call analyze_run() first."
+            )
+
+        dataset_id = record.get("datasetId")
+        if isinstance(dataset_id, dict):  # populated reference, not a bare id
+            dataset_id = dataset_id.get("_id") or dataset_id.get("id")
+
+        return Report(
+            runId=run_id,
+            datasetId=dataset_id or "",
+            status=envelope.get("status") or "completed",
+            statistics=envelope.get("statistics"),
+            **body,
+        )
+
+    # ------------------------------------------------------------------
+    # Prompt improvement loop (examples -> propose -> publish). These ride the engine's
+    # /evaluate dialect via _api_root(), same precedent get_report/_analysis already use for
+    # routes that live on the dashboard router (self-host only).
+    # ------------------------------------------------------------------
+
+    def get_prompt_examples(self, prompt_id: str, window: Optional[str] = None) -> dict:
+        params = {"window": window} if window else None
+        return self._request(
+            "GET", f"/evaluate/prompts/{prompt_id}/examples", base=self._api_root, params=params
+        )
+
+    def propose_prompt(self, prompt_id: str) -> dict:
+        # One real judge call - no retry (see _request's retry note).
+        return self._request(
+            "POST", f"/evaluate/prompts/{prompt_id}/propose", base=self._api_root, timeout=180, retry=False
+        )
+
+    def publish_prompt_version(
+        self, prompt_id: str, *, text: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        payload: dict = {"text": text, "source": source}
+        if reasoning is not None:
+            payload["reasoning"] = reasoning
+        if based_on_version is not None:
+            payload["basedOnVersion"] = based_on_version
+        return self._request(
+            "POST", f"/evaluate/prompts/{prompt_id}/versions", base=self._api_root, json=payload
+        )
+
+    # ------------------------------------------------------------------
+    # Tool schema registry (same version-scoped propose/publish loop as prompts)
+    # ------------------------------------------------------------------
+
+    def list_tool_schemas(self) -> List[dict]:
+        data = self._request("GET", "/evaluate/tool-schemas", base=self._api_root)
+        return data.get("toolSchemas", []) if isinstance(data, dict) else data
+
+    def create_tool_schema(self, *, name: str, definition: str, description: Optional[str] = None) -> dict:
+        payload: dict = {"name": name, "definition": definition}
+        if description is not None:
+            payload["description"] = description
+        return self._request("POST", "/evaluate/tool-schemas", base=self._api_root, json=payload)
+
+    def get_tool_schema_examples(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        params = {"window": window} if window else None
+        return self._request(
+            "GET", f"/evaluate/tool-schemas/{tool_schema_id}/examples", base=self._api_root, params=params
+        )
+
+    def propose_tool_schema(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        payload = {"window": window} if window else {}
+        return self._request(
+            "POST", f"/evaluate/tool-schemas/{tool_schema_id}/propose",
+            base=self._api_root, json=payload, timeout=180, retry=False,
+        )
+
+    def publish_tool_schema_version(
+        self, tool_schema_id: str, *, definition: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        payload: dict = {"definition": definition, "source": source}
+        if reasoning is not None:
+            payload["reasoning"] = reasoning
+        if based_on_version is not None:
+            payload["basedOnVersion"] = based_on_version
+        return self._request(
+            "POST", f"/evaluate/tool-schemas/{tool_schema_id}/versions", base=self._api_root, json=payload
+        )
+
+    # ------------------------------------------------------------------
+    # CI gate history + conversation simulation (self-host)
+    # ------------------------------------------------------------------
+
+    def list_gates(self) -> List[dict]:
+        """Recorded CI gate verdicts, newest first - the dashboard's CI Gates history."""
+        data = self._request("GET", "/evaluate/ci/gates", base=self._api_root)
+        return data.get("gates", []) if isinstance(data, dict) else data
+
+    def simulate_conversation(
+        self, *, model: str, system_prompt: str, persona: str, goal: str,
+        max_turns: int = 5, tools: Optional[List[dict]] = None, agent_name: Optional[str] = None,
+    ) -> dict:
+        """Run a persona-driven multi-turn simulation against a prompt (the Playground's
+        "Simulate conversation"). Blocking and judge-billed: one LLM call per simulated turn
+        plus the closing judgment, so expect it to take tens of seconds."""
+        payload: dict = {
+            "model": model,
+            "messages": [{"role": "system", "content": system_prompt}],
+            "persona": persona,
+            "goal": goal,
+            "maxTurns": max_turns,
+        }
+        if tools:
+            payload["tools"] = tools
+        if agent_name:
+            payload["agentName"] = agent_name
+        return self._request(
+            "POST", "/evaluate/playground/simulate", base=self._api_root, json=payload,
+            timeout=600, retry=False,
+        )
+
 
 # ---------------------------------------------------------------------------
 # Helpers

{agentx_python-0.6.27 → agentx_python-0.6.29}/agentx/evaluations/evaluation_settings.py

@@ -32,6 +32,7 @@ class EvaluationSettingsBuilder:
         rouge_score: bool = False,
         similarity_model: Optional[str] = None,
         sovereignty_models: Optional[List[str]] = None,
+        code_scorers: Optional[List[Dict[str, Any]]] = None,
     ):
         self._client = client
         self._payload: Dict[str, Any] = {
@@ -68,6 +69,11 @@ class EvaluationSettingsBuilder:
                 "enabled": True,
                 "models": list(sovereignty_models),
             }
+        # Sandboxed JS scorers run per result alongside the judge - each entry is
+        # {"name": ..., "enabled": True, "code": "..."} where the code is a JS function body
+        # receiving (input, output, expected, toolCalls) and returning {score, reasoning}.
+        if code_scorers:
+            self._payload["codeScorers"] = list(code_scorers)
 
     def publish(self) -> EvaluationSettings:
         logger.info("Publishing evaluation settings '%s'", self._payload["name"])
@@ -96,6 +102,7 @@ class EvaluationSettingsClient:
         rouge_score: bool = False,
         similarity_model: Optional[str] = None,
         sovereignty_models: Optional[List[str]] = None,
+        code_scorers: Optional[List[Dict[str, Any]]] = None,
     ) -> EvaluationSettingsBuilder:
         return EvaluationSettingsBuilder(
             self._client,
@@ -113,6 +120,7 @@ class EvaluationSettingsClient:
             rouge_score=rouge_score,
             similarity_model=similarity_model,
             sovereignty_models=sovereignty_models,
+            code_scorers=code_scorers,
         )
 
     def get(self, evaluation_settings_id: str) -> EvaluationSettings:

{agentx_python-0.6.27 → agentx_python-0.6.29}/agentx/evaluations/prompts.py

@@ -51,5 +51,24 @@ class PromptClient:
         second lookup method."""
         return self._client.get_prompt(name, version=version)
 
+    def examples(self, prompt_id: str, window: Optional[str] = None) -> dict:
+        """The merged evidence (worst eval-run results + low-rated online-evaluator traffic)
+        a propose() call will rewrite from - version-scoped to the prompt's current version."""
+        return self._client.get_prompt_examples(prompt_id, window=window)
+
+    def propose(self, prompt_id: str) -> dict:
+        """Ask the judge for a rewrite grounded in examples(). Returns the proposal
+        (revisedText/reasoning/sourceBreakdown) without publishing anything."""
+        return self._client.propose_prompt(prompt_id)
+
+    def publish_version(
+        self, prompt_id: str, *, text: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        """Publish a new version (the human-approval step of the propose flow)."""
+        return self._client.publish_prompt_version(
+            prompt_id, text=text, source=source, reasoning=reasoning, based_on_version=based_on_version
+        )
+
     def list(self) -> List[Prompt]:
         return self._client.list_prompts()

{agentx_python-0.6.27 → agentx_python-0.6.29}/agentx/evaluations/runner.py

@@ -271,6 +271,13 @@ class EvaluationRunContext:
     # UI reads, computed once in the API.
     # ------------------------------------------------------------------
 
+    def results(self) -> list:
+        """Per-result rows for this run (rating, justification, code scorer rows, trace ids,
+        latency/tokens, similarity metrics) - what the dashboard's run detail table shows,
+        fetched fresh from the engine."""
+        detail = self._client.get_run(self.run_id)
+        return detail.get("results", []) if isinstance(detail, dict) else []
+
     @property
     def run_id(self) -> str:
         """The server-side run id - handy for fetching the run's full results afterwards."""
@@ -362,11 +369,18 @@ class EvaluationRunContext:
         try:
             report = self._client.get_report(self._run.run_id)
         except Exception as exc:
+            # Deliberately not status="completed". A placeholder that claims completion is
+            # indistinguishable from a real report of an evaluation that scored nothing -
+            # print_report renders empty statistics and no recommendations either way - so
+            # the one signal that something went wrong used to be a logger.warning that is
+            # invisible unless the caller configured logging. Say it on stdout, and let the
+            # status carry the truth for anything reading the object.
+            print(f"  {red('✗')}  Could not fetch the report: {dim(str(exc))}")
             logger.warning("Could not fetch report: %s", exc)
             report = Report(
                 runId=self._run.run_id,
                 datasetId=self._dataset.id,
-                status="completed",
+                status="unavailable",
             )
 
         self._report = report
@@ -394,6 +408,7 @@ class EvaluationsRunner:
         self.datasets = client.datasets
         self.settings = client.settings
         self.prompts = client.prompts
+        self.tool_schemas = client.tool_schemas
 
     def list_models(self, provider: Optional[str] = None) -> List[ModelInfo]:
         """List the LLM models AgentX supports - the same set selectable for
@@ -402,6 +417,20 @@ class EvaluationsRunner:
         against."""
         return self._client.list_models(provider)
 
+    def list_gates(self) -> list:
+        """Recorded CI gate verdicts, newest first (the dashboard's CI Gates history)."""
+        return self._client.list_gates()
+
+    def simulate_conversation(self, **kwargs) -> dict:
+        """Persona-driven multi-turn simulation against a prompt - see
+        EvaluationsClient.simulate_conversation for parameters."""
+        return self._client.simulate_conversation(**kwargs)
+
+    def get_run(self, run_id: str) -> dict:
+        """Run summary + per-result rows by id, without needing the EvaluationRunContext that
+        created it (e.g. from a separate process)."""
+        return self._client.get_run(run_id)
+
     def get_analysis_status(self, run_id: str) -> AnalysisStatus:
         """Check on an in-progress ``.analyze()`` job by run id, without needing
         the ``EvaluationRunContext`` that started it (e.g. from a separate

agentx_python-0.6.29/agentx/evaluations/tool_schemas.py

@@ -0,0 +1,48 @@
+"""Tool schema registry client, surfaced as ``client.evaluations.tool_schemas``.
+
+The tool-definition analog of the prompt registry: register the JSON definition your agent
+actually passes to its LLM, let production failures accumulate as evidence against it, then
+propose -> validate -> publish improved versions. See the dashboard's Improve > Tools & MCPs.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.evaluations.client import EvaluationsClient
+
+
+class ToolSchemaClient:
+    def __init__(self, client: "EvaluationsClient"):
+        self._client = client
+
+    def list(self) -> List[dict]:
+        return self._client.list_tool_schemas()
+
+    def create(self, *, name: str, definition: str, description: Optional[str] = None) -> dict:
+        return self._client.create_tool_schema(name=name, definition=definition, description=description)
+
+    def get_or_create(self, *, name: str, definition: str, description: Optional[str] = None) -> dict:
+        """Idempotent register: returns the existing schema of this name if present."""
+        existing = next((t for t in self.list() if t.get("name") == name), None)
+        if existing:
+            return existing
+        return self.create(name=name, definition=definition, description=description)
+
+    def examples(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        """Failure evidence recorded against this tool (agent-tool-failure signals, low-rated
+        eval results that called it) - what propose() rewrites from."""
+        return self._client.get_tool_schema_examples(tool_schema_id, window=window)
+
+    def propose(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        """Judge-written definition rewrite grounded in examples(). Nothing is published."""
+        return self._client.propose_tool_schema(tool_schema_id, window=window)
+
+    def publish_version(
+        self, tool_schema_id: str, *, definition: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        return self._client.publish_tool_schema_version(
+            tool_schema_id, definition=definition, source=source,
+            reasoning=reasoning, based_on_version=based_on_version,
+        )

{agentx_python-0.6.27 → agentx_python-0.6.29}/agentx/exceptions.py

@@ -15,6 +15,10 @@ class AgentXAuthError(AgentXError):
     """Invalid or missing API key."""
 
 
+class AgentXConnectionError(AgentXError):
+    """The AgentX API (or self-host engine) could not be reached at the configured base_url."""
+
+
 class AgentXAPIError(AgentXError):
     """Unexpected API error."""
 

agentx_python-0.6.29/agentx/monitor/agents.py

@@ -0,0 +1,28 @@
+"""Agent registry helpers, surfaced as ``client.monitor.agents`` (self-host).
+
+Agents in self-host are lightweight name rows - normally auto-created the first time a trace
+arrives under a name. These helpers exist for flows that need the agent id before any traffic
+(e.g. enabling a monitoring profile up front).
+"""
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.monitor.client import MonitorClient
+
+
+class MonitorAgentClient:
+    def __init__(self, client: "MonitorClient"):
+        self._client = client
+
+    def list(self) -> List[dict]:
+        return self._client.list_agents()
+
+    def create(self, name: str) -> dict:
+        return self._client.create_agent(name)
+
+    def ensure(self, name: str) -> dict:
+        """Get-or-create by name - idempotent, safe to re-run."""
+        existing = next((a for a in self.list() if a.get("name") == name), None)
+        return existing if existing is not None else self.create(name)