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

agentx_python-0.4.10/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: agentx-python
+Version: 0.4.10
+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
+Author-email: contact@agentx.so
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3>=1.26.11
+Requires-Dist: certifi
+Requires-Dist: requests
+Requires-Dist: pydantic
+Requires-Dist: pydantic_core
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+![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/)
+
+The official Python SDK for **[AgentX](https://www.agentx.so/)** — build, chat with, and orchestrate AI agents in a few lines of code.
+
+---
+
+## Contents
+
+- [Why AgentX](#why-agentx)
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Quick start](#quick-start)
+- [Working with agents](#working-with-agents)
+  - [List agents](#list-agents)
+  - [Start a conversation](#start-a-conversation)
+  - [Chat (streaming and non-streaming)](#chat-streaming-and-non-streaming)
+- [Workforce (multi-agent orchestration)](#workforce-multi-agent-orchestration)
+- [Agent Evaluations](#custom-agent-evaluations) — LLM-as-a-judge, cosine / Jaccard similarity
+- [Links](#links)
+
+---
+
+## Why AgentX
+
+- **Simple mental model** — `Agent → Conversation → Message`.
+- **Chain-of-thought** is built in, no extra plumbing.
+- **Bring any LLM** — works across major open and closed-source vendors.
+- **Batteries included** — voice (ASR/TTS), image generation, document/CSV/Excel/OCR, RAG with built-in re-ranking.
+- **MCP support** — connect any Model Context Protocol server.
+- **Multi-agent orchestration** — workforces of agents with a designated manager, across LLM vendors.
+- **Agent Evaluations** — score any agent (LangChain, CrewAI, OpenAI, Anthropic, HTTP, …) with LLM-as-a-judge ratings plus optional cosine and Jaccard similarity metrics.
+- **A2A** — Each agent can be published with agent-to-agent protocol compatible.
+
+---
+
+## Installation
+
+```bash
+pip install --upgrade agentx-python
+```
+
+Requires Python 3.9 or newer.
+
+---
+
+## Authentication
+
+Get your API key at [app.agentx.so](https://app.agentx.so), then either pass it inline or expose it as an environment variable.
+
+```python
+# Option A — pass the key inline
+from agentx import AgentX
+client = AgentX(api_key="your-api-key-here")
+
+# Option B — set AGENTX_API_KEY in your environment, then:
+client = AgentX.from_env()
+```
+
+---
+
+## Quick start
+
+```python
+from agentx import AgentX
+
+client = AgentX.from_env()
+
+# Pick an existing agent and chat with it
+agent = client.list_agents()[0]
+conversation = agent.new_conversation()
+print(conversation.chat("Hello! What can you help me with?"))
+```
+
+That's it. The remaining sections show the same primitives in more detail.
+
+---
+
+## Working with agents
+
+### List agents
+
+```python
+agents = client.list_agents()
+print(f"You have {len(agents)} agents")
+```
+
+### Start a conversation
+
+```python
+agent = client.get_agent(id="<agent-id>")
+
+# Either resume an existing conversation…
+existing = agent.list_conversations()
+last = existing[-1]
+for msg in last.list_messages():
+    print(msg)
+
+# …or start a fresh one
+conversation = agent.new_conversation()
+```
+
+### Chat (streaming and non-streaming)
+
+```python
+# Blocking — returns the full response once it's ready
+response = conversation.chat("What is your name?")
+print(response)
+
+# Streaming — yields ChatResponse objects as the model produces them
+for chunk in conversation.chat_stream("Hello, what is your name?"):
+    if chunk.text:
+        print(chunk.text, end="")
+```
+
+Each `ChatResponse` chunk exposes the agent's `text` and, where applicable, its `cot` (chain-of-thought) reasoning, along with any retrieved references and tasks.
+
+---
+
+## Workforce (multi-agent orchestration)
+
+A **workforce** is a team of agents coordinated by a designated manager agent. Workforces can mix LLM vendors and route work between specialists.
+
+```python
+workforces = client.list_workforces()
+workforce = workforces[0]
+
+print(f"Workforce: {workforce.name}")
+print(f"Manager:   {workforce.manager.name}")
+print(f"Agents:    {[a.name for a in workforce.agents]}")
+
+# Chat with the workforce — the manager decides which agent(s) to delegate to
+conversation = workforce.new_conversation()
+for chunk in workforce.chat_stream(conversation.id, "How can you help me with this project?"):
+    if chunk.text:
+        print(chunk.text, end="")
+```
+
+---
+
+## Custom agent evaluations
+
+Evaluate **any** AI agent — LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI, Anthropic, HTTP endpoints, or plain Python — using AgentX as the scoring and reporting backend. Includes optional **cosine** and **Jaccard** similarity metrics alongside LLM-graded ratings.
+
+```python
+report = (
+    client.evaluations
+    .run(dataset_id="evds_…", subject={"kind": "custom_agent", "framework": "raw_python"})
+    .execute(my_agent_fn)
+    .finalize()
+    .analyze()
+)
+
+print(report.average_rating)       # LLM-graded score, 0–10
+print(report.cosine_similarity)    # embedding cosine, 0–1 (None if not enabled)
+print(report.jaccard_similarity)   # token-set overlap, 0–1 (None if not enabled)
+```
+
+See **[EVALUATIONS.md](EVALUATIONS.md)** for the full guide — dataset builder, framework adapters, similarity metrics, and the complete API reference.
+
+---
+
+## Links
+
+- **Dashboard** — [app.agentx.so](https://app.agentx.so)
+- **Website** — [agentx.so](https://www.agentx.so/)
+- **PyPI** — [agentx-python](https://pypi.org/project/agentx-python/)
+- **Evaluations docs** — [EVALUATIONS.md](EVALUATIONS.md)

agentx_python-0.4.10/README.md

@@ -0,0 +1,169 @@
+![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/)
+
+The official Python SDK for **[AgentX](https://www.agentx.so/)** — build, chat with, and orchestrate AI agents in a few lines of code.
+
+---
+
+## Contents
+
+- [Why AgentX](#why-agentx)
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Quick start](#quick-start)
+- [Working with agents](#working-with-agents)
+  - [List agents](#list-agents)
+  - [Start a conversation](#start-a-conversation)
+  - [Chat (streaming and non-streaming)](#chat-streaming-and-non-streaming)
+- [Workforce (multi-agent orchestration)](#workforce-multi-agent-orchestration)
+- [Agent Evaluations](#custom-agent-evaluations) — LLM-as-a-judge, cosine / Jaccard similarity
+- [Links](#links)
+
+---
+
+## Why AgentX
+
+- **Simple mental model** — `Agent → Conversation → Message`.
+- **Chain-of-thought** is built in, no extra plumbing.
+- **Bring any LLM** — works across major open and closed-source vendors.
+- **Batteries included** — voice (ASR/TTS), image generation, document/CSV/Excel/OCR, RAG with built-in re-ranking.
+- **MCP support** — connect any Model Context Protocol server.
+- **Multi-agent orchestration** — workforces of agents with a designated manager, across LLM vendors.
+- **Agent Evaluations** — score any agent (LangChain, CrewAI, OpenAI, Anthropic, HTTP, …) with LLM-as-a-judge ratings plus optional cosine and Jaccard similarity metrics.
+- **A2A** — Each agent can be published with agent-to-agent protocol compatible.
+
+---
+
+## Installation
+
+```bash
+pip install --upgrade agentx-python
+```
+
+Requires Python 3.9 or newer.
+
+---
+
+## Authentication
+
+Get your API key at [app.agentx.so](https://app.agentx.so), then either pass it inline or expose it as an environment variable.
+
+```python
+# Option A — pass the key inline
+from agentx import AgentX
+client = AgentX(api_key="your-api-key-here")
+
+# Option B — set AGENTX_API_KEY in your environment, then:
+client = AgentX.from_env()
+```
+
+---
+
+## Quick start
+
+```python
+from agentx import AgentX
+
+client = AgentX.from_env()
+
+# Pick an existing agent and chat with it
+agent = client.list_agents()[0]
+conversation = agent.new_conversation()
+print(conversation.chat("Hello! What can you help me with?"))
+```
+
+That's it. The remaining sections show the same primitives in more detail.
+
+---
+
+## Working with agents
+
+### List agents
+
+```python
+agents = client.list_agents()
+print(f"You have {len(agents)} agents")
+```
+
+### Start a conversation
+
+```python
+agent = client.get_agent(id="<agent-id>")
+
+# Either resume an existing conversation…
+existing = agent.list_conversations()
+last = existing[-1]
+for msg in last.list_messages():
+    print(msg)
+
+# …or start a fresh one
+conversation = agent.new_conversation()
+```
+
+### Chat (streaming and non-streaming)
+
+```python
+# Blocking — returns the full response once it's ready
+response = conversation.chat("What is your name?")
+print(response)
+
+# Streaming — yields ChatResponse objects as the model produces them
+for chunk in conversation.chat_stream("Hello, what is your name?"):
+    if chunk.text:
+        print(chunk.text, end="")
+```
+
+Each `ChatResponse` chunk exposes the agent's `text` and, where applicable, its `cot` (chain-of-thought) reasoning, along with any retrieved references and tasks.
+
+---
+
+## Workforce (multi-agent orchestration)
+
+A **workforce** is a team of agents coordinated by a designated manager agent. Workforces can mix LLM vendors and route work between specialists.
+
+```python
+workforces = client.list_workforces()
+workforce = workforces[0]
+
+print(f"Workforce: {workforce.name}")
+print(f"Manager:   {workforce.manager.name}")
+print(f"Agents:    {[a.name for a in workforce.agents]}")
+
+# Chat with the workforce — the manager decides which agent(s) to delegate to
+conversation = workforce.new_conversation()
+for chunk in workforce.chat_stream(conversation.id, "How can you help me with this project?"):
+    if chunk.text:
+        print(chunk.text, end="")
+```
+
+---
+
+## Custom agent evaluations
+
+Evaluate **any** AI agent — LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI, Anthropic, HTTP endpoints, or plain Python — using AgentX as the scoring and reporting backend. Includes optional **cosine** and **Jaccard** similarity metrics alongside LLM-graded ratings.
+
+```python
+report = (
+    client.evaluations
+    .run(dataset_id="evds_…", subject={"kind": "custom_agent", "framework": "raw_python"})
+    .execute(my_agent_fn)
+    .finalize()
+    .analyze()
+)
+
+print(report.average_rating)       # LLM-graded score, 0–10
+print(report.cosine_similarity)    # embedding cosine, 0–1 (None if not enabled)
+print(report.jaccard_similarity)   # token-set overlap, 0–1 (None if not enabled)
+```
+
+See **[EVALUATIONS.md](EVALUATIONS.md)** for the full guide — dataset builder, framework adapters, similarity metrics, and the complete API reference.
+
+---
+
+## Links
+
+- **Dashboard** — [app.agentx.so](https://app.agentx.so)
+- **Website** — [agentx.so](https://www.agentx.so/)
+- **PyPI** — [agentx-python](https://pypi.org/project/agentx-python/)
+- **Evaluations docs** — [EVALUATIONS.md](EVALUATIONS.md)

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

@@ -23,6 +23,7 @@ class AgentX:
         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,

{agentx_python-0.4.9 → agentx_python-0.4.10}/agentx/evaluations/_term.py

@@ -1,4 +1,5 @@
 """Minimal ANSI terminal helpers — no external dependencies."""
+
 from __future__ import annotations
 
 import itertools
@@ -13,23 +14,42 @@ 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")
+RESET = _c("0")
+BOLD = _c("1")
+DIM = _c("2")
+GREEN = _c("32")
 YELLOW = _c("33")
-RED    = _c("31")
-CYAN   = _c("36")
+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}"
+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:
@@ -64,6 +84,8 @@ class Spinner:
         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.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_python-0.4.10}/agentx/evaluations/adapters/precomputed.py

@@ -27,7 +27,9 @@ class PrecomputedAdapter:
             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))
+        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_python-0.4.10}/agentx/evaluations/adapters/raw.py

@@ -23,8 +23,11 @@ class RawCallableAdapter:
     def __init__(self, fn: Callable[[EvaluationCase], Any]):
         self._fn = fn
 
-    def run(self, case: EvaluationCase, latency_ms: int | None = None) -> EvaluationResult:
+    def run(
+        self, case: EvaluationCase, latency_ms: int | None = None
+    ) -> EvaluationResult:
         import time
+
         start = time.monotonic()
         try:
             raw = self._fn(case)

{agentx_python-0.4.9 → agentx_python-0.4.10}/agentx/evaluations/client.py

@@ -42,26 +42,33 @@ class AgentXValidationError(AgentXEvaluationsError):
 
 
 class EvaluationsClient:
-    def __init__(self, api_key: str, sdk_version: str = "unknown", base_url: str = None):
+    def __init__(
+        self, api_key: str, sdk_version: str = "unknown", base_url: str = None
+    ):
         if not api_key:
             raise AgentXAuthError("AGENTX_API_KEY is required")
         self._api_key = api_key
         self._sdk_version = sdk_version
         # Priority: constructor arg > env var > SDK default
         # Always append /custom-agent-evaluations so users only need to provide /api/v1
-        _api_base = (base_url or os.getenv("AGENTX_API_BASE_URL", _UTIL_API_BASE)).rstrip("/")
+        _api_base = (
+            base_url or os.getenv("AGENTX_API_BASE_URL", _UTIL_API_BASE)
+        ).rstrip("/")
         if not _api_base.endswith("/custom-agent-evaluations"):
             _api_base = f"{_api_base}/custom-agent-evaluations"
         self._base_url = _api_base
         self._session = requests.Session()
-        self._session.headers.update({
-            "x-api-key": self._api_key,
-            "Content-Type": "application/json",
-            "User-Agent": f"{SDK_NAME}/{self._sdk_version}",
-            "accept": "*/*",
-        })
+        self._session.headers.update(
+            {
+                "x-api-key": self._api_key,
+                "Content-Type": "application/json",
+                "User-Agent": f"{SDK_NAME}/{self._sdk_version}",
+                "accept": "*/*",
+            }
+        )
         # Expose dataset builder factory
         from agentx.evaluations.datasets import DatasetClient
+
         self.datasets = DatasetClient(self)
 
     # ------------------------------------------------------------------
@@ -86,7 +93,9 @@ class EvaluationsClient:
             if resp.status_code == 422:
                 raise AgentXValidationError(resp.text)
             if resp.status_code in _RETRYABLE_STATUS and attempt < _MAX_RETRIES - 1:
-                logger.debug("Retryable status %d (attempt %d)", resp.status_code, attempt + 1)
+                logger.debug(
+                    "Retryable status %d (attempt %d)", resp.status_code, attempt + 1
+                )
                 last_exc = AgentXEvaluationsError(f"HTTP {resp.status_code}")
                 continue
             if not resp.ok:
@@ -107,7 +116,10 @@ class EvaluationsClient:
 
     def list_datasets(self) -> List[Dataset]:
         data = self._request("GET", "/datasets")
-        return [Dataset(**d) for d in (data if isinstance(data, list) else data.get("datasets", []))]
+        return [
+            Dataset(**d)
+            for d in (data if isinstance(data, list) else data.get("datasets", []))
+        ]
 
     def get_dataset(self, dataset_id: str) -> Dataset:
         data = self._request("GET", f"/datasets/{dataset_id}")
@@ -124,6 +136,7 @@ class EvaluationsClient:
         python_version: Optional[str] = None,
     ) -> EvaluationRun:
         from agentx.version import VERSION
+
         payload = {
             "datasetId": dataset_id,
             "evaluationSubject": subject.model_dump(by_alias=True, exclude_none=True),
@@ -138,7 +151,9 @@ class EvaluationsClient:
         data = self._request("POST", "/runs", json=payload)
         return EvaluationRun(**data)
 
-    def append_results(self, run_id: str, batch_id: str, results: List[EvaluationResult]) -> BatchAppendResponse:
+    def append_results(
+        self, run_id: str, batch_id: str, results: List[EvaluationResult]
+    ) -> BatchAppendResponse:
         payload = {
             "batchId": batch_id,
             "results": [_result_to_payload(r) for r in results],
@@ -147,7 +162,9 @@ class EvaluationsClient:
         return BatchAppendResponse(**data)
 
     def finalize_run(self, run_id: str) -> Dict[str, Any]:
-        return self._request("POST", f"/runs/{run_id}/finalize", json={"status": "completed"})
+        return self._request(
+            "POST", f"/runs/{run_id}/finalize", json={"status": "completed"}
+        )
 
     def analyze_run(self, run_id: str) -> Dict[str, Any]:
         return self._request("POST", f"/runs/{run_id}/analyze", json={}, timeout=300)
@@ -168,6 +185,7 @@ class EvaluationsClient:
 # Helpers
 # ---------------------------------------------------------------------------
 
+
 def _result_to_payload(r: EvaluationResult) -> dict:
     d = r.model_dump(by_alias=True, exclude_none=True)
     # Rename snake_case fields the model may have stored locally
@@ -180,4 +198,5 @@ def _result_to_payload(r: EvaluationResult) -> dict:
 
 def _python_version() -> str:
     import sys
+
     return f"{sys.version_info.major}.{sys.version_info.minor}"

{agentx_python-0.4.9 → agentx_python-0.4.10}/agentx/evaluations/datasets.py

@@ -57,16 +57,22 @@ class DatasetBuilder:
             main["expectedKnowledgeBase"] = expected_knowledge_base
         if expected_delegations:
             main["expectedDelegations"] = expected_delegations
-        self._payload["questions"].append({
-            "main_question": main,
-            "follow_up_questions": follow_up_questions or [],
-        })
+        self._payload["questions"].append(
+            {
+                "main_question": main,
+                "follow_up_questions": follow_up_questions or [],
+            }
+        )
         return self
 
     def publish(self) -> Dataset:
         if not self._payload["questions"]:
             raise ValueError("Dataset must have at least one case before publishing")
-        logger.info("Publishing dataset '%s' with %d case(s)", self._payload["name"], len(self._payload["questions"]))
+        logger.info(
+            "Publishing dataset '%s' with %d case(s)",
+            self._payload["name"],
+            len(self._payload["questions"]),
+        )
         return self._client.create_dataset(self._payload)
 
     # ------------------------------------------------------------------
@@ -109,9 +115,15 @@ class DatasetBuilder:
                 builder.add_case(
                     query=query,
                     expected_results=row.get("expected_results", "").strip() or None,
-                    expected_capabilities=_split_semi(row.get("expected_capabilities", "")),
-                    expected_knowledge_base=_split_semi(row.get("expected_knowledge_base", "")),
-                    expected_delegations=_split_semi(row.get("expected_delegations", "")),
+                    expected_capabilities=_split_semi(
+                        row.get("expected_capabilities", "")
+                    ),
+                    expected_knowledge_base=_split_semi(
+                        row.get("expected_knowledge_base", "")
+                    ),
+                    expected_delegations=_split_semi(
+                        row.get("expected_delegations", "")
+                    ),
                 )
 
         if invalid:
@@ -150,7 +162,9 @@ class DatasetBuilder:
                 query=query,
                 expected_results=_str_or_none(row.get("expected_results")),
                 expected_capabilities=_split_semi(row.get("expected_capabilities", "")),
-                expected_knowledge_base=_split_semi(row.get("expected_knowledge_base", "")),
+                expected_knowledge_base=_split_semi(
+                    row.get("expected_knowledge_base", "")
+                ),
                 expected_delegations=_split_semi(row.get("expected_delegations", "")),
             )
 
@@ -204,6 +218,7 @@ class DatasetClient:
 # Helpers
 # ---------------------------------------------------------------------------
 
+
 def _split_semi(value: Any) -> Optional[List[str]]:
     if not value:
         return None