agentx-python 0.6.28__tar.gz → 0.6.30__tar.gz

{agentx_python-0.6.28 → agentx_python-0.6.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.6.28
+Version: 0.6.30
 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.28 → agentx_python-0.6.30}/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.28 → agentx_python-0.6.30}/agentx/evaluations/client.py

@@ -102,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
@@ -136,7 +138,7 @@ class EvaluationsClient:
         ``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.
+        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 [])
@@ -483,6 +485,109 @@ class EvaluationsClient:
             **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.28 → agentx_python-0.6.30}/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.28 → agentx_python-0.6.30}/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.28 → agentx_python-0.6.30}/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."""
@@ -401,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
@@ -409,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.30/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.28 → agentx_python-0.6.30}/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.28 → agentx_python-0.6.30}/agentx/integrations/moveworks.py

@@ -173,6 +173,17 @@ class MoveworksSyncReport:
         self.sessions_judged = 0
         self.sessions_judge_skipped = 0
         self.sessions_judge_failed = 0
+        # --evaluate-against: per-trace offline grading of the imported interactions.
+        self.traces_evaluated = 0
+        self.trace_eval_skipped_deduped = 0
+        self.trace_eval_failed = 0
+        self.trace_eval_ratings: List[float] = []
+
+    @property
+    def trace_eval_average(self) -> Optional[float]:
+        if not self.trace_eval_ratings:
+            return None
+        return sum(self.trace_eval_ratings) / len(self.trace_eval_ratings)
 
     def __repr__(self) -> str:  # also what the CLI prints
         base = (
@@ -180,6 +191,14 @@ class MoveworksSyncReport:
             f"ingested={self.ingested}, failed={self.failed}, "
             f"plugin_calls_attached={self.plugin_calls_attached}, skipped_no_time={self.skipped_no_time}"
         )
+        if self.traces_evaluated or self.trace_eval_failed or self.trace_eval_skipped_deduped:
+            avg = self.trace_eval_average
+            base += (
+                f", traces_evaluated={self.traces_evaluated}"
+                + (f" (avg {avg:.1f}/10)" if avg is not None else "")
+                + f", eval_skipped_deduped={self.trace_eval_skipped_deduped}"
+                + f", eval_failed={self.trace_eval_failed}"
+            )
         if self.sessions_judged or self.sessions_judge_skipped or self.sessions_judge_failed:
             base += (
                 f", sessions_judged={self.sessions_judged}, "
@@ -369,6 +388,7 @@ class MoveworksImporter:
         *,
         monitor: bool = False,
         judge_sessions: bool = False,
+        evaluate_against: Optional[str] = None,
         dry_run: bool = False,
         on_payload: Optional[Any] = None,
     ) -> MoveworksSyncReport:
@@ -376,12 +396,19 @@ class MoveworksImporter:
         Import every interaction in ``[since, until)``. Safe to re-run over the same window - the
         engine deduplicates on the deterministic ``span_id`` (and skips re-judging deduped spans).
 
-        ``monitor=True`` sets ``monitor: true`` on every trace - the engine's explicit opt-in that
-        runs pattern/built-in checks (PII, empty response, tool failure, active patterns) on each
-        imported trace. ``judge_sessions=True`` additionally asks the engine to judge every
+        Pattern/built-in checks and trace-scoped online evaluators run on every imported trace
+        by default (the engine's normal ingest-time posture); ``monitor=True`` is kept for
+        explicitness/compat. ``judge_sessions=True`` additionally asks the engine to judge every
         imported session with each enabled session-scoped evaluator after the sync; the request
         carries ``ifStale=true`` so a session already scored (e.g. by the engine's own 24h sweep)
-        is never judged twice. Returns a summary report.
+        is never judged twice.
+
+        ``evaluate_against=<dataset_or_config_id>`` is the offline-eval path for an agent that
+        can't be invoked from outside: each imported interaction's recorded input/output is
+        graded against that grading config's criteria (one judge call per NEW interaction -
+        spans the engine already had are skipped via its dedupe, so re-syncing a window never
+        re-bills). Ratings land as evaluation results linked to each trace, and the report
+        carries the average. Returns a summary report.
         """
         report = MoveworksSyncReport()
         conversations = self._conversation_index(since, until)
@@ -407,10 +434,23 @@ class MoveworksImporter:
                 on_payload(wire)
             if dry_run:
                 continue
-            if self._ingest.send_trace_sync(wire) is not None:
-                report.ingested += 1
-            else:
+            detail = self._ingest.send_trace_sync_detailed(wire)
+            if detail is None:
                 report.failed += 1
+                continue
+            report.ingested += 1
+            if evaluate_against:
+                if detail.get("deduped"):
+                    report.trace_eval_skipped_deduped += 1
+                    continue
+                try:
+                    verdict = self._ingest.evaluate_trace(detail["trace_id"], evaluate_against)
+                    report.traces_evaluated += 1
+                    if isinstance(verdict.get("rating"), (int, float)):
+                        report.trace_eval_ratings.append(float(verdict["rating"]))
+                except Exception as exc:
+                    report.trace_eval_failed += 1
+                    print(f"evaluate_against failed for trace {detail.get('trace_id')}: {exc}", file=sys.stderr)
 
         report.session_ids = session_ids
         if judge_sessions and not dry_run:
@@ -479,7 +519,14 @@ def cli_main(argv: Optional[List[str]] = None) -> None:
     sync.add_argument(
         "--monitor",
         action="store_true",
-        help="Run pattern/built-in checks (PII, empty response, tool failure, active patterns) on each imported trace",
+        help="Kept for compat - pattern/built-in checks and trace-scoped online evaluators already run "
+        "on every imported trace by default",
+    )
+    sync.add_argument(
+        "--evaluate-against",
+        metavar="DATASET_ID",
+        help="Offline eval during sync: grade each NEW imported interaction's recorded input/output "
+        "against this grading config (one judge call per interaction; re-synced spans are skipped)",
     )
     sync.add_argument(
         "--judge-sessions",
@@ -522,6 +569,7 @@ def cli_main(argv: Optional[List[str]] = None) -> None:
         until,
         monitor=args.monitor,
         judge_sessions=args.judge_sessions,
+        evaluate_against=args.evaluate_against,
         dry_run=args.dry_run,
         on_payload=on_payload,
     )

agentx_python-0.6.30/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)

{agentx_python-0.6.28 → agentx_python-0.6.30}/agentx/monitor/client.py

@@ -84,6 +84,10 @@ class MonitorClient:
         self.signals = MonitorSignalClient(self)
         self.profile = MonitorProfileClient(self)
         self.online_evaluators = MonitorOnlineEvaluatorClient(self)
+        from agentx.monitor.sessions import MonitorSessionClient
+        from agentx.monitor.agents import MonitorAgentClient
+        self.sessions = MonitorSessionClient(self)
+        self.agents = MonitorAgentClient(self)
 
     # ------------------------------------------------------------------
     # Low-level HTTP
@@ -97,8 +101,17 @@ class MonitorClient:
     def _workspace_params(self) -> Optional[dict]:
         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 _api_root(self) -> str:
+        """The API base with the ``/monitor`` suffix removed - for the handful of self-host
+        routes that live on the engine's other routers (ingest sessions, agent-monitoring
+        calibration/tuning/portability), same precedent EvaluationsClient._api_root sets."""
+        suffix = "/monitor"
+        if self._base_url.endswith(suffix):
+            return self._base_url[: -len(suffix)]
+        return self._base_url
+
+    def _request(self, method: str, path: str, timeout: int = 30, base: Optional[str] = None, **kwargs) -> Any:
+        url = f"{base or self._base_url}{path}"
         last_exc: Optional[Exception] = None
         for attempt, wait in enumerate([0.0] + _RETRY_BACKOFF):
             if wait:
@@ -228,6 +241,80 @@ class MonitorClient:
         profile = data.get("profile")
         return MonitorProfile(**profile) if profile else None
 
+    # ------------------------------------------------------------------
+    # Agents (the engine's SDK-facing /agents router - self-host)
+    # ------------------------------------------------------------------
+
+    def list_agents(self) -> List[dict]:
+        data = self._request("GET", "/agents", base=self._api_root())
+        return data.get("agents", []) if isinstance(data, dict) else data
+
+    def create_agent(self, name: str) -> dict:
+        data = self._request("POST", "/agents", base=self._api_root(), json={"name": name})
+        return data.get("agent", data) if isinstance(data, dict) else data
+
+    # ------------------------------------------------------------------
+    # Sessions (self-host)
+    # ------------------------------------------------------------------
+
+    def run_session_coherence_check(self, session_id: str) -> dict:
+        """One judge call over the assembled session - the dashboard's "Check coherence"
+        button. Raises AgentXMonitorError if the engine has no judge key configured."""
+        data = self._request(
+            "POST", f"/agent-monitoring/sessions/{session_id}/coherence-check",
+            base=self._api_root(), timeout=180,
+        )
+        return data.get("score", data) if isinstance(data, dict) else data
+
+    def list_session_spans(self, session_id: str) -> List[dict]:
+        data = self._request("GET", f"/ingest/sessions/{session_id}/spans", base=self._api_root())
+        return data.get("spans", []) if isinstance(data, dict) else data
+
+    # ------------------------------------------------------------------
+    # Model portability (self-host): replay a trace's input against other models
+    # ------------------------------------------------------------------
+
+    def run_model_portability(self, trace_id: str, model_ids: List[str]) -> dict:
+        """Replay the trace's captured input against ``model_ids`` and judge each output -
+        the dashboard trace detail's "Compare models" action. One LLM call per candidate
+        plus judging, so expect tens of seconds."""
+        return self._request(
+            "POST", f"/agent-monitoring/traces/{trace_id}/portability",
+            base=self._api_root(), json={"modelIds": model_ids}, timeout=300,
+        )
+
+    # ------------------------------------------------------------------
+    # Judge tuning (self-host): calibrate an online evaluator against recorded
+    # ground truth, then rewrite/validate/publish its criteria
+    # ------------------------------------------------------------------
+
+    def get_online_evaluator_calibration(self, evaluator_id: str, window: str = "7d") -> dict:
+        return self._request(
+            "GET", f"/agent-monitoring/online-evaluators/{evaluator_id}/calibration",
+            base=self._api_root(), params={"window": window},
+        )
+
+    def propose_online_evaluator_tuning(self, evaluator_id: str, window: str = "7d") -> dict:
+        data = self._request(
+            "POST", f"/agent-monitoring/online-evaluators/{evaluator_id}/tune",
+            base=self._api_root(), json={"window": window}, timeout=300,
+        )
+        return data.get("proposal", data) if isinstance(data, dict) else data
+
+    def validate_online_evaluator_tuning(
+        self, evaluator_id: str, criteria: dict, window: str = "7d"
+    ) -> dict:
+        return self._request(
+            "POST", f"/agent-monitoring/online-evaluators/{evaluator_id}/tune/validate",
+            base=self._api_root(), json={**criteria, "window": window}, timeout=600,
+        )
+
+    def publish_online_evaluator_tuning(self, evaluator_id: str, criteria: dict) -> dict:
+        return self._request(
+            "POST", f"/agent-monitoring/online-evaluators/{evaluator_id}/tune/publish",
+            base=self._api_root(), json=criteria, timeout=60,
+        )
+
     def update_profile(self, agent_id: str, payload: dict) -> MonitorProfile:
         data = self._request(
             "PUT", f"/profiles/{agent_id}", json=self._with_workspace(payload)

{agentx_python-0.6.28 → agentx_python-0.6.30}/agentx/monitor/online_evaluators.py

@@ -121,6 +121,27 @@ class MonitorOnlineEvaluatorClient:
     def delete(self, evaluator_id: str) -> None:
         self._client.delete_online_evaluator(evaluator_id)
 
+    def calibration(self, evaluator_id: str, window: str = "7d") -> dict:
+        """How often this evaluator's verdicts agreed with recorded ground truth (outcomes,
+        user feedback, human re-scores) in the window - including the disagreement cases a
+        tune() proposal would rewrite from."""
+        return self._client.get_online_evaluator_calibration(evaluator_id, window)
+
+    def tune(self, evaluator_id: str, window: str = "7d") -> dict:
+        """Judge-written rewrite of this evaluator's own criteria, grounded in calibration
+        disagreements. Returns the proposal (criteria + reasoning + changes); publishes nothing."""
+        return self._client.propose_online_evaluator_tuning(evaluator_id, window)
+
+    def validate_tuning(self, evaluator_id: str, criteria: dict, window: str = "7d") -> dict:
+        """Exact re-judging: candidate criteria re-judge the cases the current criteria got
+        wrong plus a control set they got right, measured against recorded reality. `criteria`
+        is {acceptanceCriteria, rejectionCriteria, evaluationCriteria} from tune()."""
+        return self._client.validate_online_evaluator_tuning(evaluator_id, criteria, window)
+
+    def publish_tuning(self, evaluator_id: str, criteria: dict) -> dict:
+        """Publish tuned criteria onto the evaluator's config (the human-approval step)."""
+        return self._client.publish_online_evaluator_tuning(evaluator_id, criteria)
+
     def ratings(self, evaluator_id: str, window: str = "7d") -> List[OnlineEvaluatorRatingPoint]:
         """Bucketed average-rating-over-time for this evaluator. ``window`` is one of
         ``"24h"``, ``"7d"``, ``"30d"``."""

agentx_python-0.6.30/agentx/monitor/sessions.py

@@ -0,0 +1,21 @@
+"""Session helpers, surfaced as ``client.monitor.sessions`` (self-host)."""
+from __future__ import annotations
+
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.monitor.client import MonitorClient
+
+
+class MonitorSessionClient:
+    def __init__(self, client: "MonitorClient"):
+        self._client = client
+
+    def coherence_check(self, session_id: str) -> dict:
+        """Judge the assembled multi-turn session for consistency/drift (one judge call).
+        Returns the score row: rating, justification, spanCount, driftSpanId."""
+        return self._client.run_session_coherence_check(session_id)
+
+    def spans(self, session_id: str) -> List[dict]:
+        """Every span in the session (roots and children), oldest first."""
+        return self._client.list_session_spans(session_id)

{agentx_python-0.6.28 → agentx_python-0.6.30}/agentx/tracing/ingest_client.py

@@ -66,6 +66,12 @@ class IngestClient:
             }
         )
 
+        # First delivery failure per client logs at WARNING (visible under default logging) -
+        # the tracer is fire-and-forget by design, so a wrong base_url or rejected key would
+        # otherwise fail silently forever with an empty dashboard as the only symptom. Repeat
+        # failures stay at DEBUG to avoid log spam. client.ping() is the fail-fast startup check.
+        self._delivery_warning_emitted = False
+
         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()
@@ -104,9 +110,11 @@ class IngestClient:
         try:
             resp = self._session.post(self._endpoint, json=payload, timeout=10)
         except requests.RequestException as exc:
+            self._warn_delivery(f"{exc.__class__.__name__}: {exc}")
             logger.debug("agentx ingest sync send error: %s", exc)
             return None
         if not resp.ok:
+            self._warn_delivery(f"HTTP {resp.status_code}", status=resp.status_code)
             logger.debug("agentx ingest sync HTTP %d: %s", resp.status_code, resp.text[:200])
             return None
         try:
@@ -114,6 +122,28 @@ class IngestClient:
         except Exception:
             return None
 
+    def send_trace_sync_detailed(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """``send_trace_sync`` returning the full response body instead of just the id - the
+        engine includes ``deduped: true`` for a span it had already ingested, which importers
+        (agentx-moveworks) use to skip re-evaluating on window re-syncs. Never raises."""
+        if self._workspace_id:
+            payload = {**payload, "workspaceId": self._workspace_id}
+        try:
+            resp = self._session.post(self._endpoint, json=payload, timeout=10)
+        except requests.RequestException as exc:
+            self._warn_delivery(f"{exc.__class__.__name__}: {exc}")
+            logger.debug("agentx ingest sync send error: %s", exc)
+            return None
+        if not resp.ok:
+            self._warn_delivery(f"HTTP {resp.status_code}", status=resp.status_code)
+            logger.debug("agentx ingest sync HTTP %d: %s", resp.status_code, resp.text[:200])
+            return None
+        try:
+            body = resp.json()
+            return body if isinstance(body, dict) and body.get("trace_id") else None
+        except Exception:
+            return None
+
     def evaluate_trace(
         self,
         trace_id: str,
@@ -310,6 +340,29 @@ class IngestClient:
     # Internal
     # ------------------------------------------------------------------
 
+    def _warn_delivery(self, detail: str, status: Optional[int] = None) -> None:
+        if self._delivery_warning_emitted:
+            return
+        self._delivery_warning_emitted = True
+        if status in (401, 403):
+            hint = (
+                "the API key was rejected - check api_key / AGENTX_API_KEY (for self-host, copy "
+                "the 'Default project API key' from the engine's startup log)"
+            )
+        else:
+            hint = (
+                "check base_url / AGENTX_API_BASE_URL (for self-host it should look like "
+                "http://localhost:4700/api/v1)"
+            )
+        logger.warning(
+            "AgentX traces are NOT being delivered to %s (%s) - %s. "
+            "Call client.ping() at startup to fail fast on misconfiguration. "
+            "Further delivery failures will log at DEBUG only.",
+            self._endpoint,
+            detail,
+            hint,
+        )
+
     def _drain(self) -> None:
         while True:
             payload = self._queue.get()
@@ -338,8 +391,10 @@ class IngestClient:
                 last_exc = Exception(f"HTTP {resp.status_code}")
                 continue
             if not resp.ok:
+                self._warn_delivery(f"HTTP {resp.status_code}", status=resp.status_code)
                 logger.debug("agentx ingest HTTP %d: %s", resp.status_code, resp.text[:200])
                 return
             return
 
+        self._warn_delivery(str(last_exc))
         logger.debug("agentx ingest failed after retries: %s", last_exc)

agentx_python-0.6.30/agentx/version.py

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

{agentx_python-0.6.28 → agentx_python-0.6.30}/agentx_python.egg-info/PKG-INFO

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

@@ -21,6 +21,7 @@ agentx/evaluations/redaction.py
 agentx/evaluations/reporting.py
 agentx/evaluations/results.py
 agentx/evaluations/runner.py
+agentx/evaluations/tool_schemas.py
 agentx/evaluations/tracing.py
 agentx/evaluations/adapters/__init__.py
 agentx/evaluations/adapters/http_endpoint.py
@@ -41,11 +42,13 @@ agentx/integrations/moveworks.py
 agentx/integrations/openai.py
 agentx/integrations/openai_agents.py
 agentx/monitor/__init__.py
+agentx/monitor/agents.py
 agentx/monitor/client.py
 agentx/monitor/models.py
 agentx/monitor/online_evaluators.py
 agentx/monitor/patterns.py
 agentx/monitor/profile.py
+agentx/monitor/sessions.py
 agentx/monitor/signals.py
 agentx/resources/__init__.py
 agentx/resources/agent.py

agentx_python-0.6.28/agentx/version.py

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