dmt-agent-api 0.3.0__py3-none-any.whl

dumate/resources.py

@@ -0,0 +1,206 @@
+"""Legacy API resources. Responses retain the original JSON field names."""
+from ._common import segment, fields
+from .errors import PaginationError, ProtocolError
+
+class Resource:
+    def __init__(self, client, path):
+        self._client = client
+        self._path = path
+
+    def iter(self, **params):
+        """Iterate cursor pages; raise rather than silently return partial data."""
+        cursor = params.pop("cursor", None)
+        seen = set()
+        while True:
+            page = self.list(cursor=cursor, **params)
+            if not isinstance(page, dict) or not isinstance(page.get("data"), list):
+                raise PaginationError("Invalid list response")
+            yield from page["data"]
+            if page.get("hasMore") is False:
+                return
+            if page.get("hasMore") is not True:
+                raise PaginationError("Missing explicit hasMore")
+            nxt = page.get("nextCursor")
+            if not isinstance(nxt, (str, int)) or isinstance(nxt, bool) or not str(nxt) or str(nxt) == str(cursor) or str(nxt) in seen:
+                raise PaginationError("Cursor did not advance")
+            seen.add(str(nxt))
+            cursor = str(nxt)
+
+class Agents(Resource):
+    def list(self, *, keyword=None, cursor=None, limit=None):
+        return self._client._request("GET", self._path, params=fields(keyword=keyword, cursor=cursor, limit=limit))
+
+    def create(self, *, name, description=None, system=None, skills=None, files=None, mcp_servers=None, tools=None):
+        return self._client._request("POST", self._path, json=fields(name=name, description=description, system=system, skills=skills, files=files, mcpServers=mcp_servers, tools=tools))
+
+    def get(self, agent_id, *, version=None):
+        return self._client._request("GET", f"{self._path}/{segment(agent_id)}", params=fields(version=version))
+
+    def update(self, agent_id, *, version, system=None, skills=None, files=None, mcp_servers=None, tools=None):
+        return self._client._request("POST", f"{self._path}/{segment(agent_id)}", json=fields(version=version, system=system, skills=skills, files=files, mcpServers=mcp_servers, tools=tools))
+
+    def delete(self, agent_id):
+        """Destructive: the platform also deletes associated sessions."""
+        return self._client._request("DELETE", f"{self._path}/{segment(agent_id)}")
+
+class Skills(Resource):
+    def list(self, *, page=1, page_size=20, skill_id=None, keyword=None, order=None):
+        return self._client._request("GET", self._path, params=fields(page=page, pageSize=page_size, skillId=skill_id, keyword=keyword, order=order))
+
+    def iter(self, *, page_size=20, **params):
+        page_number, count, total = 1, 0, None
+        seen = set()
+        while True:
+            page = self.list(page=page_number, page_size=page_size, **params)
+            if not isinstance(page, dict) or not isinstance(page.get("data"), list) or not isinstance(page.get("total"), int):
+                raise PaginationError("Invalid Skill page")
+            if total is not None and page["total"] != total:
+                raise PaginationError("Skill total changed while paginating")
+            total = page["total"]
+            for row in page["data"]:
+                identity = (row.get("id"), row.get("releaseId"))
+                if not identity[0] or identity in seen:
+                    raise PaginationError("Repeated or unidentified Skill")
+                seen.add(identity)
+                count += 1
+                yield row
+            if count == total:
+                return
+            if count > total or not page["data"]:
+                raise PaginationError("Skill page count inconsistent with total")
+            page_number += 1
+
+    def ensure(self, *, name, file):
+        """Reuse an exact name; upload only when absent. Does not update existing content."""
+        matches = [row for row in self.iter(keyword=name) if row.get("name") == name]
+        if len(matches) > 1:
+            raise ProtocolError("Multiple matching Skills; select an explicit ID")
+        return matches[0] if matches else self.upload(file)
+
+    def upload(self, file):
+        return self._client._upload("POST", f"{self._path}/upload", file)
+
+    def create(self, *, url):
+        return self._client._request("POST", self._path, json={"url": url})
+
+    def get(self, skill_id, *, release_id=None):
+        return self._client._request("GET", f"{self._path}/{segment(skill_id)}", params=fields(releaseId=release_id))
+
+    def update(self, skill_id, *, url):
+        return self._client._request("POST", f"{self._path}/{segment(skill_id)}", json={"url": url})
+
+    def update_zip(self, skill_id, file):
+        return self._client._upload("POST", f"{self._path}/{segment(skill_id)}/update", file)
+
+    def delete(self, skill_id):
+        return self._client._request("DELETE", f"{self._path}/{segment(skill_id)}")
+
+    def mount(self, skill_id, *, release_id=None, type="custom"):
+        """Read releaseId, never confuse it with the display version."""
+        skill = self.get(skill_id, release_id=release_id)
+        if not skill.get("releaseId"):
+            raise ProtocolError("Skill releaseId is not available yet")
+        if type not in ("custom", "official"):
+            raise ValueError("type must be custom or official")
+        return {"skillID": skill_id, "releaseID": skill["releaseId"], "type": type}
+
+class Vaults(Resource):
+    def list(self, *, cursor=None, limit=None):
+        return self._client._request("GET", self._path, params=fields(cursor=cursor, limit=limit))
+
+    def create(self, *, name):
+        return self._client._request("POST", self._path, json={"name": name})
+
+    def get(self, vault_id):
+        return self._client._request("GET", f"{self._path}/{segment(vault_id)}")
+
+    def delete(self, vault_id):
+        return self._client._request("DELETE", f"{self._path}/{segment(vault_id)}")
+
+    def credentials(self, vault_id):
+        return Credentials(self._client, f"{self._path}/{segment(vault_id)}/credentials")
+
+class Credentials(Resource):
+    def list(self, *, cursor=None, limit=None, auth_type=None):
+        return self._client._request("GET", self._path, params=fields(cursor=cursor, limit=limit, authType=auth_type))
+
+    def create(self, *, name, auth):
+        return self._client._request("POST", self._path, json={"name": name, "auth": auth})
+
+    def get(self, credential_id):
+        return self._client._request("GET", f"{self._path}/{segment(credential_id)}")
+
+    def delete(self, credential_id):
+        return self._client._request("DELETE", f"{self._path}/{segment(credential_id)}")
+
+class Sessions(Resource):
+    def list(self, *, cursor=None, limit=None, status=None):
+        return self._client._request("GET", self._path, params=fields(cursor=cursor, limit=limit, status=status))
+
+    def create(self, *, agent_id, metadata=None, vault_ids=None, skills=None, mcp_servers=None):
+        return self._client._request("POST", self._path, json=fields(agent={"id": agent_id}, metadata=metadata, vaultIds=vault_ids, skills=skills, mcpServers=mcp_servers))
+
+    def get(self, session_id):
+        return self._client._request("GET", f"{self._path}/{segment(session_id)}")
+
+    def update(self, session_id, *, metadata=None, vault_ids=None, skills=None, mcp_servers=None):
+        return self._client._request("POST", f"{self._path}/{segment(session_id)}", json=fields(metadata=metadata, vaultIds=vault_ids, skills=skills, mcpServers=mcp_servers))
+
+    def delete(self, session_id):
+        return self._client._request("DELETE", f"{self._path}/{segment(session_id)}")
+
+    def history(self, session_id, *, limit=None, paginated=False):
+        return self._client._request("GET", f"{self._path}/{segment(session_id)}/events", params=fields(limit=limit, paginated=str(paginated).lower()))
+
+    def send(self, session_id, *, message, file_ids=None):
+        content = [{"type": "text", "text": message}]
+        content.extend({"type": "file", "file_id": fid} for fid in (file_ids or []))
+        return self._client._send(session_id, {"type": "user.message", "content": content})
+
+    def send_event(self, session_id, event):
+        if not isinstance(event, dict) or not isinstance(event.get("type"), str):
+            raise ValueError("event must be a single typed object")
+        return self._client._request("POST", f"{self._path}/{segment(session_id)}/events", json={"events": [event]})
+
+    def interrupt(self, session_id):
+        return self.send_event(session_id, {"type": "user.interrupt"})
+
+    def submit_tool_result(self, session_id, *, custom_tool_use_id, content, is_error=False):
+        return self.send_event(session_id, {"type": "user.custom_tool_result", "content": [{"customToolUseId": custom_tool_use_id, "content": content, "isError": is_error}]})
+
+    def resource_points(self, session_id, *, start_at=None, end_at=None):
+        if start_at is not None and start_at < 0 or end_at is not None and end_at < 0:
+            raise ValueError("timestamps must be non-negative")
+        if start_at is not None and end_at is not None and start_at >= end_at:
+            raise ValueError("start_at must be less than end_at")
+        return self._client._request("GET", f"{self._path}/{segment(session_id)}/resource-points", params=fields(startAt=start_at, endAt=end_at))
+
+    def stream(self, session_id, *, message=None, file_ids=None):
+        """Context manager; connect before optional send, never automatically resend."""
+        return self._client._stream(session_id, message=message, file_ids=file_ids)
+
+class Files(Resource):
+    def list(self, *, cursor=None, limit=None, order=None, file_ids=None):
+        return self._client._request("GET", self._path, params=fields(cursor=cursor, limit=limit, order=order, fileIds=file_ids))
+
+    def upload(self, file, *, session_id=None, mime_type=None):
+        return self._client._upload("POST", self._path, file, data=fields(sessionId=session_id, mimeType=mime_type))
+
+    def update(self, file_id, file):
+        return self._client._upload("PUT", f"{self._path}/{segment(file_id)}", file)
+
+    def get(self, file_id):
+        return self._client._request("GET", f"{self._path}/{segment(file_id)}")
+
+    def delete(self, file_id):
+        return self._client._request("DELETE", f"{self._path}/{segment(file_id)}")
+
+    def download(self, file_id, destination, *, max_bytes=100 * 1024 * 1024, overwrite=False):
+        return self._client._download_api(f"{self._path}/{segment(file_id)}/content", destination, max_bytes=max_bytes, overwrite=overwrite)
+
+class Artifacts(Resource):
+    def path_map(self, session_id, *, paths=None):
+        return self._client._request("GET", f"sessions/{segment(session_id)}/artifact/path-map", params=fields(path=paths))
+
+    def download(self, session_id, artifact_id, destination, *, max_bytes=100 * 1024 * 1024, overwrite=False):
+        return self._client._download_artifact(session_id, artifact_id, destination, max_bytes=max_bytes, overwrite=overwrite)

dumate/runs.py

@@ -0,0 +1,61 @@
+"""Client-side convenience calls over sessions/events, not a server /runs API."""
+import time
+from ._common import history_messages
+from .errors import ProtocolError, RunTimeoutError, RunFailedError
+from .types import RunResult
+
+
+def correlated_result(session_id, history, baseline_ids, message, request_id):
+    rows = history_messages(history)
+    users = []
+    for row in rows:
+        info = row["info"]
+        if info.get("sessionID") != session_id or info.get("role") != "user" or info.get("id") in baseline_ids:
+            continue
+        text = "\n".join(p.get("text", "") for p in row["parts"] if p.get("type") == "text")
+        if text == message or (request_id and info.get("requestID") == request_id):
+            users.append(info["id"])
+    if len(users) > 1:
+        raise ProtocolError("Multiple matching user messages; serialize sends within a session")
+    if not users:
+        return None
+    user_id = users[0]
+    assistants = [r for r in rows if r["info"].get("sessionID") == session_id
+                  and r["info"].get("role") == "assistant" and r["info"].get("parentID") == user_id]
+    for row in reversed(assistants):
+        info = row["info"]
+        if info.get("error"):
+            raise RunFailedError(session_id)
+        if info.get("finish") != "stop" or not info.get("time", {}).get("completed"):
+            continue
+        texts = [p for p in row["parts"] if p.get("type") == "text" and p.get("phase") in (None, "final_answer")]
+        final = [p for p in texts if p.get("phase") == "final_answer"]
+        output = "\n".join(p.get("text", "") for p in (final or texts)).strip()
+        if output:
+            return RunResult(session_id, user_id, request_id, output, assistants)
+    return None
+
+class Runs:
+    def __init__(self, client):
+        self._client = client
+
+    def run_and_wait(self, *, session_id, message, file_ids=None, timeout=None, poll_interval=2.0):
+        """Poll authoritative history. No event replay, persistence or automatic resubmit.
+
+        One caller at a time per session. Timeout stops waiting, not remote execution.
+        """
+        if poll_interval <= 0 or (timeout is not None and timeout <= 0):
+            raise ValueError("poll_interval and timeout must be positive")
+        baseline = history_messages(self._client.sessions.history(session_id))
+        baseline_ids = {x["info"].get("id") for x in baseline}
+        receipt = self._client.sessions.send(session_id, message=message, file_ids=file_ids)
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            rows = self._client.sessions.history(session_id)
+            result = correlated_result(session_id, rows, baseline_ids, message, receipt.request_id)
+            if result is not None:
+                return result
+            if deadline is not None and time.monotonic() >= deadline:
+                raise RunTimeoutError(session_id)
+            wait = poll_interval if deadline is None else min(poll_interval, max(0, deadline-time.monotonic()))
+            time.sleep(wait)

dumate/types.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass, field
+from typing import Any, TypedDict, Literal
+
+class SkillMount(TypedDict):
+    skillID: str
+    releaseID: str
+    type: Literal["custom", "official"]
+
+class MCPServer(TypedDict):
+    type: Literal["url"]
+    name: str
+    url: str
+
+class FileMount(TypedDict):
+    fileID: str
+
+@dataclass(frozen=True)
+class Event:
+    type: str
+    properties: dict[str, Any] = field(repr=False)
+    raw: dict[str, Any] = field(repr=False)
+    id: str | None = None
+    event: str | None = None
+
+    @property
+    def session_id(self) -> str | None:
+        p = self.properties
+        if isinstance(p.get("sessionID"), str):
+            return p["sessionID"]
+        for key in ("part", "info"):
+            obj = p.get(key)
+            if isinstance(obj, dict) and isinstance(obj.get("sessionID"), str):
+                return obj["sessionID"]
+        if self.type == "session.updated" and isinstance(p.get("info"), dict):
+            return p["info"].get("id")
+        return None
+
+@dataclass(frozen=True)
+class SendReceipt:
+    session_id: str
+    request_id: str | None
+    accepted: bool = True
+
+@dataclass(frozen=True)
+class RunResult:
+    session_id: str
+    user_message_id: str
+    request_id: str | None
+    output_text: str = field(repr=False)
+    messages: list[dict[str, Any]] = field(repr=False)
+    status: str = "completed"