conversational-agent-client 0.1.0__py3-none-any.whl

conversational_agent_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: conversational-agent-client
+Version: 0.1.0
+Summary: Unofficial Python client for the Dust (dust.tt) conversational AI agent platform API
+Author: Egor Nesterov
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Zaymerstone/dust-python-sdk
+Project-URL: Repository, https://github.com/Zaymerstone/dust-python-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# dust-sdk (unofficial)
+
+An unofficial Python client for the [Dust](https://dust.tt) API.
+
+Dust ships an official [JavaScript/TypeScript SDK](https://docs.dust.tt/reference/javascript-sdk),
+but has no official Python client - despite Python being the dominant
+language for the data science, ML engineering, and automation teams
+that make up a large part of Dust's target audience (their own
+marketing highlights Data & Analytics as a core use case).
+
+This project closes that gap.
+
+## Installation
+
+```bash
+pip install dust-sdk
+```
+
+_(not yet published to PyPI — see [Status](#status) below)_
+
+## Quickstart
+
+```python
+from dust_sdk.client import DustClient
+
+client = DustClient(
+    api_key="your-dust-api-key",
+    workspace_id="your-workspace-id",
+    base_url="https://eu.dust.tt",  # or https://dust.tt — see note below
+)
+
+# List agents available in your workspace
+agents = client.list_agents()
+for agent in agents:
+    print(agent["sId"], "-", agent["name"])
+
+# Talk to an agent
+conversation = client.create_conversation(
+    message_content="What can you help me with?",
+    agent_sid="dust",
+)
+answer = client.get_last_agent_message_text(conversation)
+print(answer)
+```
+
+### ⚠️ `base_url` is required, no default
+
+Dust hosts separate regional infrastructure (`https://dust.tt` for US,
+`https://eu.dust.tt` for EU). Using the wrong one doesn't 404 — it
+returns a misleading `invalid_api_key_error`, making it look like your
+key is wrong when it's actually a region mismatch. Check which region
+your workspace lives in (visible in your workspace URL) before making
+your first call.
+
+## What's implemented
+
+| Method                            | Operation             | Verified against         |
+| --------------------------------- | --------------------- | ------------------------ |
+| `list_agents()`                   | GET agent list        | ✅ Live API call         |
+| `get_agent(sid)`                  | GET single agent      | ✅ Live API call         |
+| `list_spaces()`                   | GET spaces            | ✅ Live API call         |
+| `list_data_sources(space_id)`     | GET data sources      | ✅ Live API call         |
+| `list_documents(space_id, ds_id)` | GET documents         | 📄 Official OpenAPI spec |
+| `get_tables(space_id, ds_id)`     | GET tables            | 📄 Official OpenAPI spec |
+| `create_conversation(...)`        | POST new conversation | ✅ Live API call         |
+| `get_conversation(cid)`           | GET conversation      | ✅ Live API call         |
+| `import_agent(...)`               | POST create agent     | ✅ Live API call         |
+| `archive_agent(sid)`              | DELETE (soft) agent   | ✅ Live API call         |
+
+_"Live API call" means the response schema was confirmed against a
+real request during development, not just documentation. "Official
+OpenAPI spec" means it's based on Dust's published spec but hasn't
+been round-tripped against a live response yet (usually because
+testing it live requires resources — like a connected data source —
+that weren't available in the development workspace)._
+
+## Known limitations
+
+- **Message-sending is gated on Dust's Free plan.** Any endpoint that
+  invokes a model (`create_conversation` with an agent mention) returns
+  `429 rate_limit_error` on workspaces without a paid seat —
+  `Programmatic usage` is entirely disabled (`No access`) on Free,
+  independent of the regular in-app usage credits shown in the UI.
+  Write operations that _don't_ invoke a model (`import_agent`,
+  `archive_agent`) work fine on Free.
+- **Some `Private` API endpoints aren't accessible via API key at all**,
+  regardless of plan — e.g. `POST /spaces` (creating a space) returns
+  `401 not_authenticated` even with a valid Bearer token, because it's
+  a session-only, web-app-internal endpoint despite appearing in the
+  public API reference.
+- **The documentation contains at least one broken example URL.**
+  `GET /spaces` is shown at `https://dust.tt/api/w/{wId}/spaces`
+  (missing `/v1/`) — using that exact path returns a misleading
+  `401 not_authenticated` instead of a 404, making it look like an
+  auth problem. The correct path is `/api/v1/w/{wId}/spaces`.
+- **Response shapes aren't consistent across endpoints.** Most list
+  endpoints wrap results in an object (e.g. `{"data_sources": [...]}`),
+  but `GET .../tables` returns a bare JSON array. This SDK normalizes
+  both into consistent Python return types, but it's worth knowing if
+  you're calling the raw API directly.
+- **Dust's official OpenAPI spec has several inaccuracies**, found
+  through live testing:
+  - `agent.avatar_url` is required in practice, marked optional in the spec
+  - `editors` must be an array of email strings, not objects as the spec shows
+  - `generation_settings.reasoning_effort` is required but easy to miss
+  - Message `type` example values in the spec show `"human"`, but the
+    real API returns `"user_message"` / `"agent_message"`
+
+## Development
+
+```bash
+git clone https://github.com/Zaymerstone/dust-python-sdk.git
+cd dust-python-sdk
+python -m venv venv
+venv\Scripts\Activate.ps1   # Windows
+pip install -e .
+pip install pytest requests-mock
+pytest -v
+```
+
+Tests run entirely against recorded fixtures (`tests/fixtures/`) —
+no live API calls or credits are required to run the test suite.
+
+## Status
+
+This is an early-stage, unofficial project built to explore a gap in
+Dust's SDK coverage. 10 methods are implemented and tested; the full
+Dust API surface is 40+ endpoints. Contributions and feedback welcome.
+
+## License
+
+MIT

conversational_agent_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+conversational_agent_client-0.1.0.dist-info/licenses/LICENSE,sha256=4AUZ_FM--_3PAwlpt6iqDwQC78rPgIboopKIUf_TLPM,1089
+dust_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dust_sdk/client.py,sha256=7qaQ_YUb80WbJwtGqKmgL4XdYBIOpekwVOHwp3gM7GY,9167
+conversational_agent_client-0.1.0.dist-info/METADATA,sha256=Fq3zeYe0wxLtdeG0nh2ciJTTgRBVFl_cWEhrX60gDj8,6191
+conversational_agent_client-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+conversational_agent_client-0.1.0.dist-info/top_level.txt,sha256=0yubgCL7SL2-40eSRdvFCvPlLOePngrL_FTgSMKOFXY,9
+conversational_agent_client-0.1.0.dist-info/RECORD,,

conversational_agent_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

conversational_agent_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaymerstone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

conversational_agent_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dust_sdk

dust_sdk/client.py

@@ -0,0 +1,226 @@
+import requests
+
+
+class DustAPIError(Exception):
+    """Base exception for all Dust API errors."""
+    pass
+
+
+class DustClient:
+    def __init__(self, api_key: str, workspace_id: str, base_url: str):
+        """
+        base_url is required with no default on purpose: Dust hosts
+        separate regional infrastructure (e.g. https://eu.dust.tt
+        and https://dust.tt), and passing the wrong region produces
+        a confusing 'invalid_api_key_error' rather than a
+        'wrong region' error. So we force the SDK user to specify
+        it explicitly.
+        """
+        self.api_key = api_key
+        self.workspace_id = workspace_id
+        self.base_url = base_url.rstrip("/")
+
+    def _headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _handle_response(self, response: requests.Response) -> dict:
+        """
+        Shared response handling for all methods: status check and
+        JSON parsing. Extracted here after this same check started
+        being duplicated across 4 methods in a row (list_agents,
+        create_conversation, list_spaces, list_data_sources).
+        """
+        if response.status_code != 200:
+            raise DustAPIError(
+                f"Dust API returned {response.status_code}: {response.text}"
+            )
+        return response.json()
+
+    def list_agents(self) -> list[dict]:
+        """Returns the list of agent configurations in the workspace."""
+        url = f"{self.base_url}/api/v1/w/{self.workspace_id}/assistant/agent_configurations"
+        response = requests.get(url, headers=self._headers())
+        return self._handle_response(response)["agentConfigurations"]
+
+    def create_conversation(
+        self,
+        message_content: str,
+        agent_sid: str,
+        username: str = "sdk-user",
+        timezone: str = "UTC",
+        blocking: bool = True,
+    ) -> dict:
+        """
+        Creates a conversation and sends the first message to an agent.
+        Response schema confirmed against live data on 2026-07-09
+        (see NOTES.md).
+        """
+        url = f"{self.base_url}/api/v1/w/{self.workspace_id}/assistant/conversations"
+
+        payload = {
+            "message": {
+                "content": message_content,
+                "mentions": [{"configurationId": agent_sid}],
+                "context": {
+                    "timezone": timezone,
+                    "username": username,
+                },
+            },
+            "blocking": blocking,
+        }
+
+        response = requests.post(url, headers=self._headers(), json=payload)
+        return self._handle_response(response)["conversation"]
+
+    @staticmethod
+    def get_last_agent_message_text(conversation: dict) -> str | None:
+        """
+        Extracts the text of the last agent message.
+        conversation['content'] is a 2D array content[rank][version]:
+        rank = the message's position in the conversation, version =
+        edit/revision at that position. We take the latest version at
+        each rank and look for the last message of type agent_message.
+        """
+        for rank_group in reversed(conversation["content"]):
+            latest_version = rank_group[-1]
+            if latest_version.get("type") == "agent_message":
+                return latest_version.get("content")
+        return None
+
+    def list_spaces(self) -> list[dict]:
+        """Returns the list of spaces in the workspace."""
+        url = f"{self.base_url}/api/v1/w/{self.workspace_id}/spaces"
+        response = requests.get(url, headers=self._headers())
+        return self._handle_response(response)["spaces"]
+
+    def list_data_sources(self, space_id: str) -> list[dict]:
+        """Returns the list of data sources in the given space."""
+        url = f"{self.base_url}/api/v1/w/{self.workspace_id}/spaces/{space_id}/data_sources"
+        response = requests.get(url, headers=self._headers())
+        return self._handle_response(response)["data_sources"]
+
+    def get_agent(self, agent_sid: str) -> dict:
+        """Returns a single agent's configuration by its sId."""
+        url = f"{self.base_url}/api/v1/w/{self.workspace_id}/assistant/agent_configurations/{agent_sid}"
+        response = requests.get(url, headers=self._headers())
+        return self._handle_response(response)["agentConfiguration"]
+
+    def get_tables(self, space_id: str, data_source_id: str) -> list[dict]:
+        """
+        Returns the list of tables in the given data source.
+
+        Note: unlike the other methods, this endpoint returns a bare
+        JSON array ([...]) rather than a wrapper object (e.g.
+        {"data_sources": [...]}). Because of that, _handle_response()
+        can't be used as-is here — it assumes response.json() is a
+        dict, but here it's a list.
+        """
+        url = (
+            f"{self.base_url}/api/v1/w/{self.workspace_id}"
+            f"/spaces/{space_id}/data_sources/{data_source_id}/tables"
+        )
+        response = requests.get(url, headers=self._headers())
+
+        if response.status_code != 200:
+            raise DustAPIError(
+                f"Dust API returned {response.status_code}: {response.text}"
+            )
+
+        return response.json()
+
+    def list_documents(self, space_id: str, data_source_id: str) -> list[dict]:
+        """Returns the list of documents in the given data source."""
+        url = (
+            f"{self.base_url}/api/v1/w/{self.workspace_id}"
+            f"/spaces/{space_id}/data_sources/{data_source_id}/documents"
+        )
+        response = requests.get(url, headers=self._headers())
+        return self._handle_response(response)["documents"]
+
+    def get_conversation(self, conversation_id: str) -> dict:
+        """Returns a conversation by its id, including its full message history."""
+        url = (
+            f"{self.base_url}/api/v1/w/{self.workspace_id}"
+            f"/assistant/conversations/{conversation_id}"
+        )
+        response = requests.get(url, headers=self._headers())
+        return self._handle_response(response)["conversation"]
+
+    def import_agent(
+        self,
+        handle: str,
+        description: str,
+        instructions: str,
+        editors: list[str],
+        avatar_url: str,
+        model_id: str = "claude-sonnet-5",
+        provider_id: str = "anthropic",
+        temperature: float = 0.7,
+        reasoning_effort: str = "medium",
+        max_steps_per_run: int = 5,
+        scope: str = "hidden",
+        visualization_enabled: bool = False,
+    ) -> dict:
+        """
+        Creates a new agent in the workspace.
+
+        Field requirements were discovered empirically on 2026-07-09
+        through a series of live 400 errors (see NOTES.md) — the
+        official OpenAPI spec is inaccurate in several places:
+        - avatar_url is required, though marked optional in the spec
+        - editors is a list of strings (emails), not objects as shown
+          in the spec
+        - editors requires at least 1 element
+        - generation_settings.reasoning_effort is required
+
+        Note: unlike create_conversation, this method does NOT invoke
+        a model — it's a pure write operation, so it works even on
+        the Free plan despite "Programmatic access: No access".
+        """
+        url = (
+            f"{self.base_url}/api/v1/w/{self.workspace_id}"
+            f"/assistant/agent_configurations/import"
+        )
+
+        payload = {
+            "agent": {
+                "handle": handle,
+                "description": description,
+                "scope": scope,
+                "avatar_url": avatar_url,
+                "max_steps_per_run": max_steps_per_run,
+                "visualization_enabled": visualization_enabled,
+            },
+            "instructions": instructions,
+            "generation_settings": {
+                "model_id": model_id,
+                "provider_id": provider_id,
+                "temperature": temperature,
+                "reasoning_effort": reasoning_effort,
+            },
+            "tags": [],
+            "editors": editors,
+            "toolset": [],
+        }
+
+        response = requests.post(url, headers=self._headers(), json=payload)
+        return self._handle_response(response)["agentConfiguration"]
+
+    def archive_agent(self, agent_sid: str) -> dict:
+        """
+        Archives (soft-deletes) an agent by its sId.
+
+        Like import_agent, this operation does not invoke a model, so
+        it works on the Free plan despite "Programmatic access: No
+        access". Confirmed with a live call on 2026-07-09 — it worked
+        on the first try, with no validation errors.
+        """
+        url = (
+            f"{self.base_url}/api/v1/w/{self.workspace_id}"
+            f"/assistant/agent_configurations/{agent_sid}"
+        )
+        response = requests.delete(url, headers=self._headers())
+        return self._handle_response(response)