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

dumate/_client.py

@@ -0,0 +1,151 @@
+import mimetypes
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from urllib.parse import urljoin
+import httpx
+from . import resources
+from ._common import config, check_response, decode, delay, request_id, segment
+from ._downloads import public_url, select_artifact, AtomicDownload
+from ._sse import SSEDecoder
+from .errors import ConnectionError, ProtocolError, StreamInterruptedError, DownloadError, APIError
+from .types import SendReceipt
+
+class DuMate:
+    def __init__(self, api_key=None, *, base_url=None, timeout=60.0, stream_timeout=60.0,
+                 max_retries=2, max_frame_bytes=4*1024*1024, transport=None):
+        key, base = config(api_key, base_url, max_retries)
+        self.base_url = base
+        self.max_retries = max_retries
+        self.max_frame_bytes = max_frame_bytes
+        self.stream_timeout = stream_timeout
+        self._http = httpx.Client(base_url=base + "/", headers={"Authorization": "Bearer " + key, "User-Agent": "dumate-agent-sdk/0.2.0"}, timeout=timeout, follow_redirects=False, trust_env=False, transport=transport)
+        self._storage = httpx.Client(timeout=timeout, follow_redirects=False, trust_env=False, headers={"Accept-Encoding": "identity"})
+        self.agents = resources.Agents(self, "agents")
+        self.skills = resources.Skills(self, "skills")
+        self.vaults = resources.Vaults(self, "vaults")
+        self.sessions = resources.Sessions(self, "sessions")
+        self.files = resources.Files(self, "files")
+        self.artifacts = resources.Artifacts(self, "")
+        from .runs import Runs
+        self.runs = Runs(self)
+        from .conversation import Conversations
+        from .notebook import Notebook
+        self.conversations = Conversations(self)
+        self.notebook = Notebook(self)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self):
+        self._http.close()
+        self._storage.close()
+
+    def _response(self, method, path, **kwargs):
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if method == "GET" and attempt < self.max_retries:
+                    time.sleep(delay(None, attempt))
+                    continue
+                raise ConnectionError(outcome_unknown=method != "GET") from None
+            if method == "GET" and response.status_code in (429, 500, 502, 503, 504) and attempt < self.max_retries:
+                wait = delay(response, attempt)
+                response.close()
+                time.sleep(wait)
+                continue
+            check_response(response)
+            return response
+        raise AssertionError("Unreachable")
+
+    def _request(self, method, path, **kwargs):
+        response = self._response(method, path, **kwargs)
+        try:
+            return decode(response)
+        finally:
+            response.close()
+
+    def _upload(self, method, path, file, *, data=None):
+        path_file = Path(file)
+        with path_file.open("rb") as handle:
+            return self._request(method, path, data=data, files={"file": (path_file.name, handle, mimetypes.guess_type(path_file.name)[0] or "application/octet-stream")})
+
+    def _send(self, session_id, event):
+        response = self._response("POST", f"sessions/{segment(session_id)}/events", json={"events": [event]})
+        try:
+            return SendReceipt(session_id, request_id(response))
+        finally:
+            response.close()
+
+    @contextmanager
+    def _stream(self, session_id, *, message=None, file_ids=None):
+        try:
+            with self._http.stream("GET", f"sessions/{segment(session_id)}/events/stream", headers={"Accept": "text/event-stream"}, timeout=self.stream_timeout) as response:
+                check_response(response)
+                if "text/event-stream" not in response.headers.get("content-type", "").lower():
+                    raise ProtocolError("Expected text/event-stream")
+                if message is not None:
+                    self.sessions.send(session_id, message=message, file_ids=file_ids)
+                yield self._events(response, session_id)
+        except httpx.TransportError:
+            raise StreamInterruptedError(session_id) from None
+
+    def _events(self, response, session_id):
+        decoder = SSEDecoder(self.max_frame_bytes)
+        try:
+            for chunk in response.iter_bytes():
+                for event in decoder.feed(chunk):
+                    if event.session_id is None or event.session_id == session_id:
+                        yield event
+            decoder.finish()
+        except httpx.TransportError:
+            raise StreamInterruptedError(session_id) from None
+
+    def _save(self, response, destination, *, max_bytes, overwrite):
+        target = AtomicDownload(destination, max_bytes=max_bytes, overwrite=overwrite, headers=response.headers)
+        try:
+            for chunk in response.iter_raw():
+                target.write(chunk)
+            return target.commit()
+        except httpx.TransportError:
+            raise DownloadError("Download interrupted; destination was not committed") from None
+        finally:
+            target.close()
+
+    def _download_api(self, path, destination, *, max_bytes, overwrite):
+        try:
+            with self._http.stream("GET", path, headers={"Accept-Encoding": "identity"}) as response:
+                check_response(response)
+                return self._save(response, destination, max_bytes=max_bytes, overwrite=overwrite)
+        except httpx.TransportError:
+            raise DownloadError("File download connection failed") from None
+
+    def _download_artifact(self, session_id, artifact_id, destination, *, max_bytes, overwrite):
+        for attempt in range(2):
+            row = select_artifact(self.artifacts.path_map(session_id), artifact_id)
+            url = public_url(row.get("downloadUrl"))
+            expired = False
+            try:
+                for hop in range(5):
+                    with self._storage.stream("GET", url) as response:
+                        if response.status_code in (301, 302, 303, 307, 308):
+                            location = response.headers.get("location")
+                            if not location or hop == 4:
+                                raise DownloadError("Artifact redirect limit reached")
+                            url = public_url(urljoin(url, location))
+                            continue
+                        if response.status_code == 403 and attempt == 0:
+                            expired = True
+                            break
+                        if response.status_code != 200:
+                            raise DownloadError(f"Artifact storage HTTP {response.status_code}")
+                        return self._save(response, destination, max_bytes=max_bytes, overwrite=overwrite)
+            except httpx.TransportError:
+                raise DownloadError("Artifact download connection failed") from None
+            if not expired:
+                raise DownloadError("Artifact download failed")
+        raise DownloadError("Artifact download failed after refresh")

dumate/_common.py

@@ -0,0 +1,65 @@
+import math
+import os
+import re
+from pathlib import Path
+from urllib.parse import quote, urlsplit
+from .errors import (APIError, AuthenticationError, PermissionDeniedError,
+                     NotFoundError, ConflictError, RateLimitError, ProtocolError)
+
+BASE_URL = "https://api.dumate.cn/api/v1"
+
+def segment(value: str) -> str:
+    if not isinstance(value, str) or not value or value in (".", ".."):
+        raise ValueError("A non-empty resource ID is required")
+    return quote(value, safe="")
+
+def fields(**values):
+    return {k: v for k, v in values.items() if v is not None}
+
+def config(api_key, base_url, max_retries):
+    key = api_key or os.getenv("DUMATE_API_KEY") or os.getenv("AGENT_API_KEY")
+    if not key or not key.strip():
+        raise ValueError("Set DUMATE_API_KEY or pass api_key")
+    base = (base_url or os.getenv("DUMATE_BASE_URL") or BASE_URL).rstrip("/")
+    u = urlsplit(base)
+    if u.scheme != "https" or not u.hostname or u.username or u.password or u.query or u.fragment:
+        raise ValueError("base_url must be an HTTPS API root without credentials/query/fragment")
+    if not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError("max_retries must be non-negative")
+    return key, base
+
+def check_response(response):
+    if 200 <= response.status_code < 300:
+        return
+    cls = {401: AuthenticationError, 403: PermissionDeniedError, 404: NotFoundError,
+           409: ConflictError, 429: RateLimitError}.get(response.status_code, APIError)
+    raise cls(response.status_code, request_id=request_id(response))
+
+def request_id(response):
+    raw = response.headers.get("x-bce-request-id") or response.headers.get("x-request-id")
+    return raw if raw and re.fullmatch(r"[a-zA-Z0-9_.:-]{1,200}", raw) else None
+
+def decode(response):
+    check_response(response)
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        raise ProtocolError("Expected JSON response") from None
+
+def delay(response, attempt):
+    val = response.headers.get("retry-after", "") if response else ""
+    try:
+        num = float(val)
+        if math.isfinite(num):
+            return max(0.0, min(num, 30.0))
+    except ValueError:
+        pass
+    return min(0.5 * (2 ** attempt), 8.0)
+
+def history_messages(value):
+    rows = value if isinstance(value, list) else value.get("messages") if isinstance(value, dict) else None
+    if not isinstance(rows, list) or any(not isinstance(x, dict) or not isinstance(x.get("info"), dict) or not isinstance(x.get("parts"), list) for x in rows):
+        raise ProtocolError("Invalid history response")
+    return rows

dumate/_downloads.py

@@ -0,0 +1,85 @@
+import hashlib
+import ipaddress
+import os
+import socket
+import tempfile
+from pathlib import Path
+from urllib.parse import urlsplit
+from .errors import DownloadError, ArtifactNotReadyError, ProtocolError
+
+def public_url(url):
+    if not isinstance(url, str):
+        raise DownloadError("Missing artifact download URL")
+    u = urlsplit(url)
+    if u.scheme != "https" or not u.hostname or u.username or u.password or u.fragment or u.port not in (None, 443):
+        raise DownloadError("Artifact URL must use public HTTPS")
+    try:
+        addresses = socket.getaddrinfo(u.hostname, 443, type=socket.SOCK_STREAM)
+        if not addresses or any(not ipaddress.ip_address(a[4][0]).is_global for a in addresses):
+            raise DownloadError("Non-public artifact host rejected")
+    except (OSError, ValueError):
+        raise DownloadError("Cannot validate artifact host") from None
+    return url
+
+def select_artifact(mapping, artifact_id):
+    if not isinstance(mapping, dict):
+        raise ProtocolError("Invalid artifact path map")
+    rows = [x for x in mapping.values() if isinstance(x, dict) and x.get("artifactID") == artifact_id]
+    if len(rows) != 1:
+        raise DownloadError("Artifact is missing or ambiguous in this session")
+    row = rows[0]
+    if row.get("uploadStatus") != "ready":
+        raise ArtifactNotReadyError("Artifact is not ready")
+    return row
+
+class AtomicDownload:
+    def __init__(self, destination, *, max_bytes, overwrite, headers):
+        if max_bytes <= 0:
+            raise ValueError("max_bytes must be positive")
+        self.destination = Path(destination)
+        self.max_bytes, self.overwrite = max_bytes, overwrite
+        self.size = 0
+        self.hash = hashlib.sha256()
+        self.expected = None
+        value = headers.get("content-length")
+        if value is not None:
+            try:
+                self.expected = int(value)
+                if self.expected < 0:
+                    raise ValueError
+            except ValueError:
+                raise DownloadError("Invalid Content-Length") from None
+        if headers.get("content-encoding", "identity").lower() != "identity":
+            raise DownloadError("Encoded downloads are not supported; identity encoding required")
+        if self.expected is not None and self.expected > max_bytes:
+            raise DownloadError("Download exceeds max_bytes")
+        if self.destination.exists() and not overwrite:
+            raise FileExistsError(str(self.destination))
+        self.destination.parent.mkdir(parents=True, exist_ok=True)
+        fd, name = tempfile.mkstemp(prefix=".dumate-", dir=self.destination.parent)
+        self.tmp = Path(name)
+        self.file = os.fdopen(fd, "wb")
+
+    def write(self, data):
+        self.size += len(data)
+        if self.size > self.max_bytes:
+            raise DownloadError("Download exceeds max_bytes")
+        self.hash.update(data)
+        self.file.write(data)
+
+    def commit(self):
+        if self.expected is not None and self.expected != self.size:
+            raise DownloadError("Incomplete download")
+        self.file.flush()
+        os.fsync(self.file.fileno())
+        self.file.close()
+        if self.overwrite:
+            os.replace(self.tmp, self.destination)
+        else:
+            os.link(self.tmp, self.destination)
+            self.tmp.unlink()
+        return {"path": str(self.destination), "bytes": self.size, "sha256": self.hash.hexdigest()}
+
+    def close(self):
+        self.file.close()
+        self.tmp.unlink(missing_ok=True)

dumate/_sse.py

@@ -0,0 +1,86 @@
+import codecs
+import json
+from .errors import ProtocolError
+from .types import Event
+
+class SSEDecoder:
+    """Incremental UTF-8 + CR/LF/CRLF parser with per-frame memory bound."""
+    def __init__(self, max_frame_bytes: int = 4 * 1024 * 1024):
+        if max_frame_bytes <= 0:
+            raise ValueError("max_frame_bytes must be positive")
+        self.max_bytes = max_frame_bytes
+        self.decoder = codecs.getincrementaldecoder("utf-8")("strict")
+        self.line = []
+        self.data = []
+        self.event = None
+        self.id = None
+        self.size = 0
+        self.after_cr = False
+        self.first = True
+
+    def feed(self, chunk: bytes):
+        try:
+            text = self.decoder.decode(chunk)
+        except UnicodeDecodeError:
+            raise ProtocolError("Invalid UTF-8 in SSE") from None
+        result = []
+        for char in text:
+            if self.first:
+                self.first = False
+                if char == "\ufeff":
+                    continue
+            if self.after_cr:
+                self.after_cr = False
+                if char == "\n":
+                    continue
+            self.size += len(char.encode("utf-8"))
+            if self.size > self.max_bytes:
+                raise ProtocolError("SSE frame exceeds max_frame_bytes")
+            if char in "\r\n":
+                item = self._line("".join(self.line))
+                self.line.clear()
+                self.after_cr = char == "\r"
+                if item is not None:
+                    result.append(item)
+            else:
+                self.line.append(char)
+        return result
+
+    def _line(self, line):
+        if not line:
+            item = None
+            if self.data:
+                try:
+                    raw = json.loads("\n".join(self.data))
+                except (ValueError, TypeError):
+                    raise ProtocolError("Invalid JSON in SSE data") from None
+                if not isinstance(raw, dict) or not isinstance(raw.get("type"), str):
+                    raise ProtocolError("SSE data must contain a string type")
+                props = raw.get("properties", {})
+                if not isinstance(props, dict):
+                    raise ProtocolError("SSE properties must be an object")
+                item = Event(raw["type"], props, raw, self.id, self.event)
+            self.data.clear()
+            self.event = None
+            self.size = 0
+            return item
+        if line.startswith(":"):
+            return None
+        key, _, val = line.partition(":")
+        if val.startswith(" "):
+            val = val[1:]
+        if key == "data":
+            self.data.append(val)
+        elif key == "event":
+            self.event = val
+        elif key == "id" and "\x00" not in val:
+            self.id = val
+        return None
+
+    def finish(self):
+        try:
+            self.decoder.decode(b"", final=True)
+        except UnicodeDecodeError:
+            raise ProtocolError("Truncated UTF-8 SSE stream") from None
+        if self.line or self.data:
+            raise ProtocolError("Incomplete SSE frame at EOF")

dumate/conversation.py

@@ -0,0 +1,183 @@
+"""Portable conversation projection shared by backend and notebook consumers."""
+from copy import deepcopy
+from contextlib import contextmanager, asynccontextmanager
+
+
+class ConversationState:
+    def __init__(self, session_id):
+        self.session_id = session_id
+        self.messages = {}
+        self.parts = {}
+        self.status = "unknown"
+        self.revision = 0
+        self._pending = {}
+
+    def apply(self, event):
+        if event.session_id and event.session_id != self.session_id:
+            return
+        p = event.properties
+        if event.type == "message.updated":
+            info = p.get("info", {})
+            if info.get("id"):
+                self.messages[info["id"]] = deepcopy(info)
+        elif event.type == "message.part.updated":
+            part = p.get("part", {})
+            if part.get("id"):
+                self.parts[part["id"]] = deepcopy(part)
+                self._pending.pop(part["id"], None)
+        elif event.type == "message.part.delta":
+            pid, field, delta = p.get("partID"), p.get("field"), p.get("delta")
+            if pid and field == "text" and isinstance(delta, str):
+                if pid in self.parts:
+                    self.parts[pid][field] = self.parts[pid].get(field, "") + delta
+                else:
+                    self._pending[pid] = True
+        elif event.type == "session.status":
+            self.status = p.get("status", {}).get("type", "unknown")
+        elif event.type == "session.idle":
+            self.status = "idle"
+        elif event.type == "session.error":
+            self.status = "error"
+        self.revision += 1
+
+    def restore(self, history):
+        from ._common import history_messages
+        self.messages.clear()
+        self.parts.clear()
+        self._pending.clear()
+        for row in history_messages(history):
+            info = row["info"]
+            if info.get("sessionID") not in (None, self.session_id):
+                continue
+            self.messages[info["id"]] = deepcopy(info)
+            for part in row["parts"]:
+                if part.get("id"):
+                    part = deepcopy(part)
+                    part.setdefault("messageID", info["id"])
+                    self.parts[part["id"]] = part
+        self.revision += 1
+
+    def snapshot(self):
+        rows = []
+        for mid, info in self.messages.items():
+            rows.append({"id": mid, "role": info.get("role"),
+                         "finish": info.get("finish"), "error": deepcopy(info.get("error")),
+                         "parts": [deepcopy(p) for p in self.parts.values() if p.get("messageID") == mid]})
+        return {"schema_version": 1, "session_id": self.session_id,
+                "revision": self.revision, "status": self.status,
+                "needs_history": bool(self._pending), "messages": rows}
+
+
+class Conversations:
+    def __init__(self, client):
+        self.client = client
+
+    def create(self, *, agent_id=None, name="Assistant", skills=None, vault_ids=None, mcp_servers=None):
+        agent = None
+        if agent_id is None:
+            agent = self.client.agents.create(name=name)
+            agent_id = agent["id"]
+        try:
+            session = self.client.sessions.create(agent_id=agent_id, skills=skills,
+                                                 vault_ids=vault_ids, mcp_servers=mcp_servers)
+        except Exception as error:
+            error.created_agent_id = agent_id if agent else None
+            raise
+        return {"agent_id": agent_id, "session_id": session["id"], "created_agent": agent is not None}
+
+    def send(self, session_id, *, message, file_ids=None):
+        """Send one message without subscribing to events."""
+        return self.client.sessions.send(session_id, message=message, file_ids=file_ids)
+
+    def run(self, session_id, *, message, file_ids=None, timeout=300, poll_interval=2.0):
+        """Send once and return the correlated final result."""
+        return self.client.runs.run_and_wait(session_id=session_id, message=message,
+                                             file_ids=file_ids, timeout=timeout,
+                                             poll_interval=poll_interval)
+
+    def save(self, snapshot, path):
+        """Persist a JSON-serializable snapshot for frontend reload or audit."""
+        import json
+        from pathlib import Path
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(json.dumps(snapshot, ensure_ascii=False, indent=2), encoding="utf-8")
+        return target
+
+    def history(self, session_id):
+        state = ConversationState(session_id)
+        state.restore(self.client.sessions.history(session_id))
+        return state.snapshot()
+
+    @contextmanager
+    def stream(self, session_id, *, message=None, file_ids=None):
+        state = ConversationState(session_id)
+        state.restore(self.client.sessions.history(session_id))
+        with self.client.sessions.stream(session_id, message=message, file_ids=file_ids) as events:
+            def updates():
+                try:
+                    for event in events:
+                        state.apply(event)
+                        yield state.snapshot()
+                        if state.status in ("idle", "error"):
+                            break
+                    state.restore(self.client.sessions.history(session_id))
+                    yield state.snapshot()
+                except Exception:
+                    state.status = "interrupted"
+                    raise
+            yield updates()
+
+
+class AsyncConversations:
+    def __init__(self, client):
+        self.client = client
+
+    async def create(self, *, agent_id=None, name="Assistant", skills=None, vault_ids=None, mcp_servers=None):
+        agent = None
+        if agent_id is None:
+            agent = await self.client.agents.create(name=name)
+            agent_id = agent["id"]
+        try:
+            session = await self.client.sessions.create(agent_id=agent_id, skills=skills,
+                                                       vault_ids=vault_ids, mcp_servers=mcp_servers)
+        except Exception as error:
+            error.created_agent_id = agent_id if agent else None
+            raise
+        return {"agent_id": agent_id, "session_id": session["id"], "created_agent": agent is not None}
+
+    async def send(self, session_id, *, message, file_ids=None):
+        return await self.client.sessions.send(session_id, message=message, file_ids=file_ids)
+
+    async def run(self, session_id, *, message, file_ids=None, timeout=300, poll_interval=2.0):
+        return await self.client.runs.run_and_wait(session_id=session_id, message=message,
+                                                   file_ids=file_ids, timeout=timeout,
+                                                   poll_interval=poll_interval)
+
+    async def save(self, snapshot, path):
+        import json
+        from pathlib import Path
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(json.dumps(snapshot, ensure_ascii=False, indent=2), encoding="utf-8")
+        return target
+
+    async def history(self, session_id):
+        state = ConversationState(session_id)
+        state.restore(await self.client.sessions.history(session_id))
+        return state.snapshot()
+
+    @asynccontextmanager
+    async def stream(self, session_id, *, message=None, file_ids=None):
+        state = ConversationState(session_id)
+        state.restore(await self.client.sessions.history(session_id))
+        async with self.client.sessions.stream(session_id, message=message, file_ids=file_ids) as events:
+            async def updates():
+                async for event in events:
+                    state.apply(event)
+                    yield state.snapshot()
+                    if state.status in ("idle", "error"):
+                        break
+                state.restore(await self.client.sessions.history(session_id))
+                yield state.snapshot()
+            yield updates()

dumate/errors.py

@@ -0,0 +1,58 @@
+"""Errors deliberately exclude request bodies, credentials and signed URLs."""
+
+class DuMateError(Exception):
+    pass
+
+class APIError(DuMateError):
+    def __init__(self, status_code: int, *, request_id: str | None = None):
+        self.status_code = status_code
+        self.request_id = request_id
+        super().__init__(f"DuMate HTTP {status_code}")
+
+class AuthenticationError(APIError):
+    pass
+
+class PermissionDeniedError(APIError):
+    pass
+
+class NotFoundError(APIError):
+    pass
+
+class ConflictError(APIError):
+    pass
+
+class RateLimitError(APIError):
+    pass
+
+class ConnectionError(DuMateError):
+    def __init__(self, *, outcome_unknown: bool):
+        self.outcome_unknown = outcome_unknown
+        super().__init__("Request failed; write outcome is unknown, do not blindly resubmit."
+                         if outcome_unknown else "DuMate connection failed.")
+
+class ProtocolError(DuMateError):
+    pass
+
+class PaginationError(ProtocolError):
+    pass
+
+class StreamInterruptedError(DuMateError):
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        super().__init__("Event stream interrupted. Query session history before deciding next action.")
+
+class RunTimeoutError(DuMateError):
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        super().__init__("Wait deadline reached; the remote task has NOT been cancelled.")
+
+class RunFailedError(DuMateError):
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        super().__init__("Remote session reported an error; inspect authorized session history.")
+
+class DownloadError(DuMateError):
+    pass
+
+class ArtifactNotReadyError(DownloadError):
+    pass

dumate/notebook.py

@@ -0,0 +1,48 @@
+"""Optional IPython adapter. Values are escaped before rendering."""
+import json
+from html import escape
+
+
+def render(snapshot):
+    blocks = ["<div style='font:14px/1.6 system-ui;max-width:960px'>",
+              "<div>" + escape(snapshot["status"]) + "</div>"]
+    for message in snapshot["messages"]:
+        if message["role"] != "assistant":
+            continue
+        for part in message["parts"]:
+            kind = part.get("type")
+            if kind == "text":
+                blocks.append("<div style='white-space:pre-wrap;margin:12px 0'>" + escape(part.get("text", "")) + "</div>")
+            elif kind == "reasoning":
+                blocks.append("<details><summary>思考</summary><pre style='white-space:pre-wrap'>" + escape(part.get("text", "")) + "</pre></details>")
+            elif kind == "tool":
+                state = part.get("state") or {}
+                blocks.append("<details open><summary>" + escape(str(part.get("tool", "工具"))) + " · " + escape(str(state.get("status", ""))) + "</summary>")
+                for key in ("input", "output", "error"):
+                    if key in state:
+                        value = state[key]
+                        text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, indent=2)
+                        blocks.append("<b>" + key + "</b><pre style='white-space:pre-wrap;max-height:300px;overflow:auto'>" + escape(text) + "</pre>")
+                blocks.append("</details>")
+    return "".join(blocks) + "</div>"
+
+
+class Notebook:
+    def __init__(self, client):
+        self.client = client
+
+    def stream(self, session_id, *, message, file_ids=None):
+        try:
+            from IPython.display import HTML, display
+        except ImportError:
+            raise ImportError('Install dumate-agent-sdk[notebook] to use notebook.stream') from None
+        panel = display(HTML("连接中…"), display_id=True)
+        final = None
+        try:
+            with self.client.conversations.stream(session_id, message=message, file_ids=file_ids) as updates:
+                for final in updates:
+                    panel.update(HTML(render(final)))
+        except Exception:
+            panel.update(HTML((render(final) if final else "") + "<p>连接或执行异常。请查询历史，勿重复发送。</p>"))
+            raise
+        return final