agentx-python 0.4.8__tar.gz → 0.4.9__tar.gz

{agentx_python-0.4.8/agentx_python.egg-info → agentx_python-0.4.9}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.4.8
+Version: 0.4.9
 Summary: Official Python SDK for AgentX (https://www.agentx.so/)
-Home-page: https://github.com/AgentX-ai/AgentX-python-sdk
+Home-page: https://github.com/AgentX-ai/AgentX-python
 Author: Robin Wang and AgentX Team
 Author-email: contact@agentx.so
 Classifier: Programming Language :: Python :: 3
@@ -33,22 +33,22 @@ Dynamic: summary
 
 ---
 
-## a fast way to build AI Agents and create agent workforce
+## A fast way to build AI Agents and create agent workforces
 
 The official AgentX Python SDK for [AgentX](https://www.agentx.so/)
 
-Why build AI agent with AgentX?
+Why build AI agents with AgentX?
 
-- Simplicity, Agent - Conversation - Message structure.
-- Include chain-of-thoughts.
-- Choose from most open and closed sourced LLM vendors.
-- Built-in Voice(ASR, TTS), Image Gen, Document, CSV/excel tool, OCR, etc.
-- Support all running MCP (model context protocol).
-- Support RAG with built-in re-rank.
+- Simplicity — Agent → Conversation → Message structure.
+- Chain-of-thought built in.
+- Choose from most open and closed-source LLM vendors.
+- Built-in Voice (ASR, TTS), Image Gen, Document, CSV/Excel, OCR, and more.
+- Support for all running MCP (Model Context Protocol) servers.
+- RAG with built-in re-rank.
 - Multi-agent workforce orchestration.
 - Multiple agents working together with a designated manager agent.
-- Cross LLM vendor, multi-agent orchestration.
-- A2A - agent to agent protocol (coming soon)
+- Cross-LLM-vendor, multi-agent orchestration.
+- A2A — agent-to-agent protocol (coming soon)
 
 ## Installation
 
@@ -58,19 +58,14 @@ pip install --upgrade agentx-python
 
 ## Quick Start
 
-Get started with AgentX in just a few lines of code:
-
 ```python
 from agentx import AgentX
 
-# Initialize the client
 client = AgentX(api_key="your-api-key-here")
 
-# Get your agents
 agents = client.list_agents()
 print(f"You have {len(agents)} agents")
 
-# Start chatting with your first agent
 if agents:
     agent = agents[0]
     conversation = agent.new_conversation()
@@ -81,7 +76,7 @@ if agents:
 ## Usage
 
 Provide an `api_key` inline or set `AGENTX_API_KEY` as an environment variable.
-You can get an API key from https://app.agentx.so
+Get your API key at https://app.agentx.so
 
 ### Agent
 
@@ -89,24 +84,15 @@ You can get an API key from https://app.agentx.so
 from agentx import AgentX
 
 client = AgentX(api_key="<your api key here>")
-
-# Get the list of agents you have
 print(client.list_agents())
 ```
 
 ### Conversation
 
-Each Conversation has `agents` and `users` tied to it.
-
 ```python
-# get agent
 my_agent = client.get_agent(id="<agent id here>")
 
-# Get the list of conversation from this agent
 existing_conversations = my_agent.list_conversations()
-print(existing_conversations)
-
-# Get the list of history messages from a conversation
 last_conversation = existing_conversations[-1]
 msgs = last_conversation.list_messages()
 print(msgs)
@@ -114,8 +100,6 @@ print(msgs)
 
 ### Chat
 
-A `chat` needs to happen in the conversation. You can do `stream` response too, default `False`.
-
 ```python
 a_conversation = my_agent.get_conversation(id="<conversation id here>")
 
@@ -124,65 +108,34 @@ for chunk in response:
     print(chunk)
 ```
 
-output looks like:
-
-```
-text=None cot='The user is greeting and asking for my ' botId='xxx'
-text=None cot='name, which are casual, straightforward questions.' botId='xxx'
-text=None cot=' I can answer these directly' botId='xxx'
-text='Hello' cot=None botId='xxx'
-text='!' cot=None botId='xxx'
-text=' I' cot=None botId='xxx'
-text=' am' cot=None botId='xxx'
-text=' AgentX' cot=None botId='xxx'
-text=None cot=None botId='xxx'
-```
-
-\*`cot` stands for chain-of-thoughts
+\*`cot` stands for chain-of-thought
 
 ### Workforce
 
-A Workforce (team) consists of multiple agents working together with a designated manager agent.
-
 ```python
 from agentx import AgentX
 
 client = AgentX(api_key="<your api key here>")
 
-# Get the list of workforces/teams you have
 workforces = client.list_workforces()
-print(workforces)
-
-# Get a specific workforce
-workforce = workforces[0]  # or any specific workforce
+workforce = workforces[0]
 print(f"Workforce: {workforce.name}")
 print(f"Manager: {workforce.manager.name}")
 print(f"Agents: {[agent.name for agent in workforce.agents]}")
 ```
 
-#### Workforce Conversations
-
-```python
-# Create a new conversation with the workforce
-conversation = workforce.new_conversation()
-
-# List all existing conversations for the workforce
-conversations = workforce.list_conversations()
-print(conversations)
-```
-
 #### Chat with Workforce
 
-Chat with the entire workforce team and get streaming responses from all agents.
-
 ```python
-# Stream chat with the workforce
+conversation = workforce.new_conversation()
 response = workforce.chat_stream(conversation.id, "How can you help me with this project?")
 for chunk in response:
     if chunk.text:
         print(chunk.text, end="")
-    if chunk.cot:
-        print(f" [COT: {chunk.cot}]")
 ```
 
-The workforce chat allows you to leverage multiple specialized agents working together to provide comprehensive responses to your queries.
+---
+
+## Custom Agent Evaluations
+
+See **[EVALUATIONS.md](EVALUATIONS.md)** for full documentation — installation, dataset builder, framework examples (OpenAI, Anthropic, Google, LangChain, CrewAI, AutoGen, LlamaIndex, HTTP endpoints), and the complete API reference.

agentx_python-0.4.9/README.md

@@ -0,0 +1,112 @@
+![Logo](https://agentx-resources.s3.us-west-1.amazonaws.com/AgentX-logo-387x60.png)
+
+[![PyPI version](https://img.shields.io/pypi/v/agentx-python)](https://pypi.org/project/agentx-python/)
+
+---
+
+## A fast way to build AI Agents and create agent workforces
+
+The official AgentX Python SDK for [AgentX](https://www.agentx.so/)
+
+Why build AI agents with AgentX?
+
+- Simplicity — Agent → Conversation → Message structure.
+- Chain-of-thought built in.
+- Choose from most open and closed-source LLM vendors.
+- Built-in Voice (ASR, TTS), Image Gen, Document, CSV/Excel, OCR, and more.
+- Support for all running MCP (Model Context Protocol) servers.
+- RAG with built-in re-rank.
+- Multi-agent workforce orchestration.
+- Multiple agents working together with a designated manager agent.
+- Cross-LLM-vendor, multi-agent orchestration.
+- A2A — agent-to-agent protocol (coming soon)
+
+## Installation
+
+```bash
+pip install --upgrade agentx-python
+```
+
+## Quick Start
+
+```python
+from agentx import AgentX
+
+client = AgentX(api_key="your-api-key-here")
+
+agents = client.list_agents()
+print(f"You have {len(agents)} agents")
+
+if agents:
+    agent = agents[0]
+    conversation = agent.new_conversation()
+    response = conversation.chat("Hello! What can you help me with?")
+    print(response)
+```
+
+## Usage
+
+Provide an `api_key` inline or set `AGENTX_API_KEY` as an environment variable.
+Get your API key at https://app.agentx.so
+
+### Agent
+
+```python
+from agentx import AgentX
+
+client = AgentX(api_key="<your api key here>")
+print(client.list_agents())
+```
+
+### Conversation
+
+```python
+my_agent = client.get_agent(id="<agent id here>")
+
+existing_conversations = my_agent.list_conversations()
+last_conversation = existing_conversations[-1]
+msgs = last_conversation.list_messages()
+print(msgs)
+```
+
+### Chat
+
+```python
+a_conversation = my_agent.get_conversation(id="<conversation id here>")
+
+response = a_conversation.chat_stream("Hello, what is your name?")
+for chunk in response:
+    print(chunk)
+```
+
+\*`cot` stands for chain-of-thought
+
+### Workforce
+
+```python
+from agentx import AgentX
+
+client = AgentX(api_key="<your api key here>")
+
+workforces = client.list_workforces()
+workforce = workforces[0]
+print(f"Workforce: {workforce.name}")
+print(f"Manager: {workforce.manager.name}")
+print(f"Agents: {[agent.name for agent in workforce.agents]}")
+```
+
+#### Chat with Workforce
+
+```python
+conversation = workforce.new_conversation()
+response = workforce.chat_stream(conversation.id, "How can you help me with this project?")
+for chunk in response:
+    if chunk.text:
+        print(chunk.text, end="")
+```
+
+---
+
+## Custom Agent Evaluations
+
+See **[EVALUATIONS.md](EVALUATIONS.md)** for full documentation — installation, dataset builder, framework examples (OpenAI, Anthropic, Google, LangChain, CrewAI, AutoGen, LlamaIndex, HTTP endpoints), and the complete API reference.

{agentx_python-0.4.8 → agentx_python-0.4.9}/agentx/agentx.py

@@ -3,37 +3,50 @@ import requests
 import os
 import logging
 
-from agentx.util import get_headers
+from agentx.util import get_headers, api_base
 from agentx.resources.agent import Agent
 from agentx.resources.workforce import Workforce
 
 
 class AgentX:
 
-    def __init__(self, api_key: str = None):
+    def __init__(self, api_key: str = None, base_url: str = None):
         self.api_key = api_key or os.getenv("AGENTX_API_KEY")
         if self.api_key and not os.getenv("AGENTX_API_KEY"):
             os.environ["AGENTX_API_KEY"] = self.api_key
 
+        # base_url overrides AGENTX_API_BASE_URL env var (and the SDK default)
+        self.base_url = base_url or os.getenv("AGENTX_API_BASE_URL")
+        if self.base_url:
+            os.environ["AGENTX_API_BASE_URL"] = self.base_url
+
+        from agentx.evaluations.client import EvaluationsClient
+        from agentx.evaluations.runner import EvaluationsRunner
+        from agentx.version import VERSION
+        _eval_client = EvaluationsClient(
+            api_key=self.api_key,
+            sdk_version=VERSION,
+            base_url=self.base_url,
+        )
+        self.evaluations = EvaluationsRunner(_eval_client)
+
+    @classmethod
+    def from_env(cls) -> "AgentX":
+        """Create an AgentX client using AGENTX_API_KEY (and optionally AGENTX_API_BASE_URL) from the environment."""
+        return cls()
+
     def get_agent(self, id: str) -> Agent:
-        url = f"https://api.agentx.so/api/v1/access/agents/{id}"
+        url = f"{api_base()}/access/agents/{id}"
         # Make a GET request to the AgentX API
         response = requests.get(url, headers=get_headers())
         # Check if response was successful
         if response.status_code == 200:
-            agent_res = response.json()
-            return Agent(
-                id=agent_res.get("_id"),
-                name=agent_res.get("name"),
-                avatar=agent_res.get("avatar"),
-                createdAt=agent_res.get("createdAt"),
-                updatedAt=agent_res.get("updatedAt"),
-            )
+            return Agent(**response.json())
         else:
             raise Exception(f"Failed to retrieve agent: {response.reason}")
 
     def list_agents(self) -> List[Agent]:
-        url = "https://api.agentx.so/api/v1/access/agents"
+        url = f"{api_base()}/access/agents"
         # Make a GET request to the AgentX API
         response = requests.get(url, headers=get_headers())
         # Check if response was successful
@@ -45,7 +58,7 @@ class AgentX:
     @staticmethod
     def list_workforces() -> List["Workforce"]:
         """List all workforces/teams."""
-        url = "https://api.agentx.so/api/v1/access/teams"
+        url = f"{api_base()}/access/teams"
         response = requests.get(url, headers=get_headers())
         if response.status_code == 200:
             return [Workforce(**workforce) for workforce in response.json()]
@@ -56,7 +69,7 @@ class AgentX:
 
     def get_profile(self):
         """Get the current user's profile information."""
-        url = "https://api.agentx.so/api/v1/access/getProfile"
+        url = f"{api_base()}/access/getProfile"
         response = requests.get(url, headers=get_headers())
         if response.status_code == 200:
             return response.json()

agentx_python-0.4.9/agentx/evaluations/__init__.py

@@ -0,0 +1,3 @@
+from agentx.evaluations.client import EvaluationsClient
+
+__all__ = ["EvaluationsClient"]

agentx_python-0.4.9/agentx/evaluations/_term.py

@@ -0,0 +1,69 @@
+"""Minimal ANSI terminal helpers — no external dependencies."""
+from __future__ import annotations
+
+import itertools
+import sys
+import threading
+import time
+
+_IS_TTY = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _c(code: str) -> str:
+    return f"\033[{code}m" if _IS_TTY else ""
+
+
+RESET  = _c("0")
+BOLD   = _c("1")
+DIM    = _c("2")
+GREEN  = _c("32")
+YELLOW = _c("33")
+RED    = _c("31")
+CYAN   = _c("36")
+MAGENTA = _c("35")
+
+
+def green(s: str) -> str:   return f"{GREEN}{s}{RESET}"
+def yellow(s: str) -> str:  return f"{YELLOW}{s}{RESET}"
+def red(s: str) -> str:     return f"{RED}{s}{RESET}"
+def cyan(s: str) -> str:    return f"{CYAN}{s}{RESET}"
+def bold(s: str) -> str:    return f"{BOLD}{s}{RESET}"
+def dim(s: str) -> str:     return f"{DIM}{s}{RESET}"
+def magenta(s: str) -> str: return f"{MAGENTA}{s}{RESET}"
+
+
+class Spinner:
+    """Inline spinner that overwrites the current line on a TTY."""
+
+    _FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+    def __init__(self, message: str):
+        self._message = message
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def __enter__(self) -> "Spinner":
+        if not _IS_TTY:
+            print(f"  {self._message}...", flush=True)
+            return self
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, *_) -> None:
+        if not _IS_TTY:
+            return
+        self._stop.set()
+        if self._thread:
+            self._thread.join()
+        sys.stdout.write(f"\r{' ' * (len(self._message) + 12)}\r")
+        sys.stdout.flush()
+
+    def _spin(self) -> None:
+        for frame in itertools.cycle(self._FRAMES):
+            if self._stop.is_set():
+                break
+            sys.stdout.write(f"\r  {CYAN}{frame}{RESET}  {self._message}  {DIM}(this may take ~60s+){RESET}")
+            sys.stdout.flush()
+            time.sleep(0.08)

agentx_python-0.4.9/agentx/evaluations/adapters/__init__.py

@@ -0,0 +1,5 @@
+from agentx.evaluations.adapters.raw import RawCallableAdapter
+from agentx.evaluations.adapters.precomputed import PrecomputedAdapter
+from agentx.evaluations.adapters.http_endpoint import HttpEndpointAdapter
+
+__all__ = ["RawCallableAdapter", "PrecomputedAdapter", "HttpEndpointAdapter"]

agentx_python-0.4.9/agentx/evaluations/adapters/http_endpoint.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import requests
+
+from agentx.evaluations.models import EvaluationCase, EvaluationResult
+from agentx.evaluations.results import normalize_error, normalize_result
+
+
+class HttpEndpointAdapter:
+    """
+    Calls a user-hosted HTTP endpoint for each evaluation case.
+    The SDK (running locally) makes the request — the AgentX API never
+    touches the customer's endpoint.
+
+    The endpoint receives a POST with::
+
+        {"query": "...", "case_id": "...", "metadata": {...}}
+
+    It should respond with a JSON body containing at least ``output``
+    (or ``text``) and optionally ``trace`` and ``metadata``.
+
+    Usage::
+
+        adapter = HttpEndpointAdapter(
+            url="http://localhost:8080/eval",
+            headers={"Authorization": "Bearer my-token"},
+            timeout=30,
+        )
+    """
+
+    def __init__(
+        self,
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: int = 30,
+        method: str = "POST",
+    ):
+        self._url = url
+        self._headers = headers or {}
+        self._timeout = timeout
+        self._method = method.upper()
+
+    def run(self, case: EvaluationCase) -> EvaluationResult:
+        payload = {
+            "query": case.query,
+            "case_id": case.case_id,
+            "question_index": case.question_index,
+            "run_number": case.run_number,
+        }
+        start = time.monotonic()
+        try:
+            resp = requests.request(
+                self._method,
+                self._url,
+                json=payload,
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+            elapsed = int((time.monotonic() - start) * 1000)
+            raw = resp.json()
+        except Exception as exc:
+            elapsed = int((time.monotonic() - start) * 1000)
+            return normalize_error(case, exc, latency_ms=elapsed)
+
+        return normalize_result(case, raw, latency_ms=elapsed)

agentx_python-0.4.9/agentx/evaluations/adapters/precomputed.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Union
+
+from agentx.evaluations.models import EvaluationCase, EvaluationResult
+from agentx.evaluations.results import normalize_result
+
+
+class PrecomputedAdapter:
+    """
+    Adapter for pre-computed outputs — useful when you already have agent
+    responses and just want AgentX to score them.
+
+    Accepts a list or dict keyed by case_id::
+
+        outputs = {
+            "case-0": "You can reset your password from account settings.",
+            "case-1": {"output": "Contact support@example.com", "metadata": {...}},
+        }
+        adapter = PrecomputedAdapter(outputs)
+    """
+
+    def __init__(self, outputs: Union[List[Any], Dict[str, Any]]):
+        if isinstance(outputs, list):
+            self._lookup: Dict[str, Any] = {str(i): v for i, v in enumerate(outputs)}
+        else:
+            self._lookup = {str(k): v for k, v in outputs.items()}
+
+    def run(self, case: EvaluationCase) -> EvaluationResult:
+        raw = self._lookup.get(case.case_id) or self._lookup.get(str(case.question_index))
+        if raw is None:
+            raw = ""
+        return normalize_result(case, raw, latency_ms=0)

agentx_python-0.4.9/agentx/evaluations/adapters/raw.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from agentx.evaluations.models import EvaluationCase, EvaluationResult
+from agentx.evaluations.results import normalize_error, normalize_result
+
+
+class RawCallableAdapter:
+    """
+    Wraps any Python callable that accepts an EvaluationCase and returns
+    str | dict | EvaluationResult.
+
+    Usage::
+
+        def my_agent(case: EvaluationCase) -> str:
+            return my_llm.invoke(case.query)
+
+        adapter = RawCallableAdapter(my_agent)
+        result = adapter.run(case)
+    """
+
+    def __init__(self, fn: Callable[[EvaluationCase], Any]):
+        self._fn = fn
+
+    def run(self, case: EvaluationCase, latency_ms: int | None = None) -> EvaluationResult:
+        import time
+        start = time.monotonic()
+        try:
+            raw = self._fn(case)
+        except Exception as exc:
+            elapsed = int((time.monotonic() - start) * 1000)
+            return normalize_error(case, exc, latency_ms=elapsed)
+        elapsed = int((time.monotonic() - start) * 1000)
+        return normalize_result(case, raw, latency_ms=elapsed)