multichat-sdk 0.2.0__py3-none-any.whl

multichat/__init__.py

@@ -0,0 +1,30 @@
+"""multiChat for Python: change one import and your OpenAI or Anthropic code keeps calling the
+provider directly with your own key, while every turn is recorded in a durable conversation
+store, with failover to a backup model and the planner's savings shown before they are applied.
+
+    from multichat import OpenAI          # instead of: from openai import OpenAI
+"""
+
+from ._clients import Anthropic, AsyncAnthropic, AsyncOpenAI, Engine, OpenAI
+from ._errors import BackupUnavailableError, MultiChatError, NotLoggedInError, ServiceError
+from ._recorder import Conversation, KeepAlive, TurnInfo
+from ._version import VERSION
+from .convert import ANTHROPIC, OPENAI, convert_request, convert_response
+from .failover import Backup, is_failover_error
+from .files import Files
+from .guardrails import GuardrailError, Guardrails
+from .helpers import Messages, Model, Session, Turn, messages, session, turn
+from .services import Services
+from . import workspace
+from .workspace import Workspace
+
+__version__ = VERSION
+
+__all__ = [
+    "OpenAI", "AsyncOpenAI", "Anthropic", "AsyncAnthropic", "Engine",
+    "Backup", "KeepAlive", "Conversation", "TurnInfo",
+    "Session", "Messages", "Model", "Turn", "session", "messages", "turn",
+    "convert_request", "convert_response", "OPENAI", "ANTHROPIC", "is_failover_error",
+    "Services", "Files", "Guardrails", "GuardrailError", "Workspace", "workspace", "MultiChatError", "NotLoggedInError", "ServiceError", "BackupUnavailableError",
+    "VERSION", "__version__",
+]

multichat/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

multichat/_clients.py

@@ -0,0 +1,506 @@
+"""Drop-in OpenAI and Anthropic clients: the official clients, calling the provider directly with
+your key, with each turn recorded in the multiChat store, optional failover, and the planner's
+proposals shown (or applied with ``optimise=True``)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from functools import cached_property
+from typing import Any, Callable, Dict, Optional, Union
+
+from . import _config
+from . import convert as cv
+from ._errors import NotLoggedInError
+from ._recorder import TRANSPORT_KEYS, Conversation, KeepAlive, Recorder, TurnInfo, request_body
+from ._streams import (AsyncRecordingStream, RecordingStream, achain, alist, chain, event_object, response_object,
+                       stream_events)
+from .failover import (Backup, _Primed, backup_request, queue_base_url, queue_task, queue_waiter_async, queue_waiter_sync,
+                       run_async, run_sync)
+from .files import Files
+from .guardrails import Guard, Guardrails, stable_tools
+from .services import Services
+
+log = logging.getLogger("multichat")
+
+_no_account_logged = False
+
+
+def _no_account_once() -> None:
+    global _no_account_logged
+    if not _no_account_logged:
+        _no_account_logged = True
+        log.warning("multichat: no multiChat credential (MULTICHAT_API_KEY or `multichat login`): calls go straight "
+                    "to the provider, without recording or multiChat features")
+
+Optimise = Union[bool, str]
+
+
+class Engine:
+    """What a drop-in client adds, reachable as ``client.multichat``.
+
+    - ``conversation(session_id=None)``: a conversation handle to pass as ``conversation=``
+      (a new one, or an existing session to continue).
+    - ``last``: the last turn's :class:`TurnInfo` (session, answered_by, usage, what was sent,
+      the planner's ``changes``).
+    - ``flush(timeout)``: waits until the store has everything recorded so far.
+    - ``files``: upload files and get signed links (:class:`multichat.files.Files`).
+    """
+
+    def __init__(self, fmt: str, *, failover: Optional[Backup], optimise: Optimise, keepalive: Optional[KeepAlive],
+                 record: bool, multichat_api_key: Optional[str], services: Optional[Services],
+                 provider_key: Callable[[], Optional[str]], provider_base_url: Optional[Callable[[], Optional[str]]] = None,
+                 record_files: bool = True, guardrails: Optional[Guardrails] = None, stable_tools: bool = False):
+        if optimise not in (True, False, "preview"):
+            raise ValueError('optimise must be True, False or "preview"')
+        if keepalive is True:
+            keepalive = KeepAlive()
+        self.fmt = fmt
+        self.stable_tools = stable_tools
+        self.guardrails = guardrails
+        self.keepalive = keepalive or None
+        self.failover = failover
+        self.optimise = optimise
+        self.services: Optional[Services] = None
+        self.recorder: Optional[Recorder] = None
+        if record and services is None:
+            cred = _config.find_credential(multichat_api_key)
+            if cred:
+                services = Services(cred)
+            else:
+                # No multiChat account: never break the developer's app (decision 0008). The client
+                # is the provider's own, unrecorded; said once per process.
+                _no_account_once()
+                record = False
+        if record:
+            self.services = services
+            self.recorder = Recorder(services, keepalive=keepalive or None, provider_key=provider_key,
+                                     provider_base_url=provider_base_url, record_files=record_files)
+            if guardrails is not None:
+                self.recorder.guard = Guard(guardrails, services, self.recorder._worker.submit)
+        elif services is not None:
+            self.services = services
+        if guardrails is not None and self.recorder is None:
+            log.warning("multichat: guardrails need recording (record=True); they are not checked")
+
+    # ---------------------------------------------------------------- advice (docs/v2/advice.md)
+
+    def _sid(self, conversation: Union[Conversation, str, None]) -> str:
+        if isinstance(conversation, str):
+            return conversation
+        self.flush()
+        sid = getattr(conversation, "session_id", None) if conversation is not None else \
+            (self.recorder.last.session_id if self.recorder is not None and self.recorder.last else None)
+        if not sid:
+            raise ValueError("no recorded conversation yet: pass conversation= or a session ID")
+        return sid
+
+    def advice(self, conversation: Union[Conversation, str, None] = None) -> Dict[str, Any]:
+        """What the conversation (default: the last one) has cost and what is costing more than it
+        needs to: ``{spend, findings: [{id, title, cost_usd, saving_usd, fixes}], saving_usd}``."""
+        if self.services is None:
+            raise NotLoggedInError()
+        return self.services.advice(self._sid(conversation))
+
+    def spend(self, conversation: Union[Conversation, str, None] = None, scope: Optional[str] = None,
+              since: Optional[int] = None) -> Dict[str, Any]:
+        """``POST /v2/spend`` for the conversation (default: the last one)."""
+        if self.services is None:
+            raise NotLoggedInError()
+        limits = None
+        g = self.guardrails
+        if g is not None:
+            limits = {k: v for k, v in (("session_usd", g.max_session_usd), ("turn_usd", g.max_turn_usd),
+                                        ("account_usd", g.max_account_usd),
+                                        ("context_tokens", g.max_context_tokens if isinstance(g.max_context_tokens, int) else None))
+                      if v is not None}
+            if scope == "account" and since is None:
+                since = g.since_ms()
+        return self.services.spend(self._sid(conversation), scope=scope, since=since, limits=limits or None)
+
+    def apply_fix(self, fix: Dict[str, Any], conversation: Union[Conversation, str, None] = None) -> Optional[Conversation]:
+        """Applies one of an advice finding's ``fixes``: an ``sdk_option`` is set on this client
+        (``optimise``, ``stable_tools``, ``keepalive``); a ``fork`` starts a fork of the
+        conversation with the fix's settings and returns it to pass as ``conversation=``. A
+        ``code`` fix is yours to make (ValueError)."""
+        kind = fix.get("kind")
+        if kind == "sdk_option":
+            opt, value = fix.get("option"), fix.get("value")
+            if opt == "optimise":
+                self.optimise = value
+            elif opt == "stable_tools":
+                self.stable_tools = bool(value)
+            elif opt == "keepalive":
+                ka = KeepAlive() if value is True else (value or None)
+                self.keepalive = ka
+                if self.recorder is not None:
+                    self.recorder.keepalive = ka
+            else:
+                raise ValueError("unknown SDK option %r" % opt)
+            return None
+        if kind == "fork":
+            if self.services is None:
+                raise NotLoggedInError()
+            out = self.services.fork(self._sid(conversation), fix.get("settings"))  # type: ignore[arg-type]
+            return self.conversation(out["session_id"])
+        raise ValueError("this fix is a change in your code: %s" % fix.get("label"))
+
+    # ---------------------------------------------------------------- public
+
+    def conversation(self, session_id: Optional[str] = None) -> Conversation:
+        if self.recorder is None:
+            return Conversation(session_id, self.fmt)
+        c = self.recorder.conversation(session_id)
+        c.fmt = self.fmt
+        return c
+
+    @property
+    def files(self) -> Files:
+        if self.services is None:
+            raise NotLoggedInError()
+        return Files(self.services)
+
+    @property
+    def last(self) -> Optional[TurnInfo]:
+        return self.recorder.last if self.recorder else None
+
+    @property
+    def conversations(self):
+        return list(self.recorder.conversations.values()) if self.recorder else []
+
+    def flush(self, timeout: float = 10.0) -> bool:
+        return self.recorder.flush(timeout) if self.recorder else True
+
+    # ---------------------------------------------------------------- one call
+
+    def _split(self, kwargs: Dict[str, Any]):
+        handle = kwargs.pop("conversation", None)
+        if self.stable_tools and isinstance(kwargs.get("tools"), list):
+            kwargs["tools"] = stable_tools(kwargs)["tools"]
+        fo = kwargs.pop("failover", self.failover)
+        opt = kwargs.pop("optimise", self.optimise)
+        return kwargs, fo, opt, handle
+
+    def _begin(self, kwargs: Dict[str, Any]):
+        kwargs, fo, opt, handle = self._split(kwargs)
+        prep = self.recorder.begin(self.fmt, request_body(kwargs), handle) if self.recorder else None
+        return kwargs, fo, opt, prep
+
+    async def _abegin(self, kwargs: Dict[str, Any]):
+        kwargs, fo, opt, handle = self._split(kwargs)
+        if self.recorder is None:
+            return kwargs, fo, opt, None
+        body = request_body(kwargs)
+        if isinstance(handle, str) or (isinstance(handle, Conversation) and not handle.loaded):
+            # Continuing a stored session reads it first: off the event loop.
+            prep = await asyncio.get_running_loop().run_in_executor(None, self.recorder.begin, self.fmt, body, handle)
+        else:
+            prep = self.recorder.begin(self.fmt, body, handle)
+        return kwargs, fo, opt, prep
+
+    def _merge(self, kwargs: Dict[str, Any], assembled: Dict[str, Any]) -> Dict[str, Any]:
+        send = {k: v for k, v in kwargs.items() if k in TRANSPORT_KEYS}
+        send.update(assembled)
+        for k in ("stream", "stream_options"):
+            if k in kwargs:
+                send[k] = kwargs[k]
+            else:
+                send.pop(k, None)
+        return send
+
+    def _finish(self, prep, resp: Dict[str, Any], sent: Dict[str, Any], opt: Optimise, answered_by: str = "primary",
+                fmt: Optional[str] = None) -> None:
+        if self.recorder is not None:
+            self.recorder.finish(prep, resp, answered_by=answered_by, fmt=fmt, sent=sent, preview=opt == "preview")
+
+    def _queue_setup(self, fo: Backup, prep, breq: Dict[str, Any]):
+        """Queue mode: posts the backup task; returns (sid, name) or None to use the timer instead."""
+        if self.recorder is None or prep is None or self.services is None:
+            log.warning("multichat: queue failover needs recording; using the in-process timer")
+            return None
+        sid = self.recorder.ensure_session(prep)
+        if sid is None:
+            log.warning("multichat: queue failover: no session; using the in-process timer")
+            return None
+        name = self.recorder.new_name("backup", prep)
+        try:
+            self.services.post_task(queue_task(fo, name, sid, prep.turn, breq))
+        except Exception as e:
+            log.warning("multichat: queue failover unavailable, using the in-process timer: %s", e)
+            return None
+        return sid, name
+
+    def _first_token(self, sid: str, turn: int, name: str) -> None:
+        """The primary answered: cancel the queued backup, and tell the scheduler directly."""
+        try:
+            self.services.cancel_task(name)
+        except Exception as e:
+            log.warning("multichat: could not cancel the queued backup %s: %s", name, e)
+        try:
+            self.services.signal(sid, turn, "first_token")
+        except Exception as e:
+            log.debug("multichat: signal not sent: %s", e)
+
+    def _backup_result(self, out, fo: Backup, stream: bool, send: Dict[str, Any], prep, opt: Optimise, sent: Dict[str, Any]):
+        prim = cv.convert_response(out.backup_response, fo.format, self.fmt)
+        self._finish(prep, out.backup_response, sent, opt, "backup", fo.format)
+        if stream:
+            include_usage = bool((send.get("stream_options") or {}).get("include_usage"))
+            return [event_object(e, self.fmt) for e in stream_events(prim, self.fmt, include_usage)]
+        return response_object(prim, self.fmt)
+
+    def call_sync(self, raw: Callable[..., Any], raw_noretry: Callable[[], Callable[..., Any]], kwargs: Dict[str, Any]) -> Any:
+        kwargs, fo, opt, prep = self._begin(dict(kwargs))
+        send = kwargs
+        if opt is True and prep is not None:
+            assembled = self.recorder.optimised(prep)  # type: ignore[union-attr]
+            if assembled:
+                send = self._merge(kwargs, assembled)
+        sent = request_body(send)
+        stream = bool(send.get("stream"))
+        done = lambda resp: self._finish(prep, resp, sent, opt)  # noqa: E731
+        if not fo:
+            r = raw(**send)
+            if stream:
+                return RecordingStream(r, self.fmt, done, underlying=r)
+            done(cv.plain(r))
+            return r
+        breq = backup_request(fo, sent, self.fmt, self.services)
+        queue_wait, on_first = None, None
+        if fo.mode == "queue":
+            q = self._queue_setup(fo, prep, breq)
+            if q:
+                sid, name = q
+                queue_wait = queue_waiter_sync(self.services, sid, prep.turn, fo)
+                on_first = lambda: self.recorder._worker.submit(lambda: self._first_token(sid, prep.turn, name))  # noqa: E731
+        create = raw_noretry()
+        out = run_sync(lambda: create(**send), fo, breq, stream=stream, primary_fmt=self.fmt, queue_wait=queue_wait,
+                       on_first_token=on_first)
+        if out.answered_by == "primary":
+            if stream:
+                p: _Primed = out.value
+                return RecordingStream(chain(p.first, p.it), self.fmt, done, underlying=p.stream)
+            done(cv.plain(out.value))
+            return out.value
+        res = self._backup_result(out, fo, stream, send, prep, opt, sent)
+        return RecordingStream(iter(res), self.fmt, lambda _: None) if stream else res
+
+    async def call_async(self, raw: Callable[..., Any], raw_noretry: Callable[[], Callable[..., Any]], kwargs: Dict[str, Any]) -> Any:
+        kwargs, fo, opt, prep = await self._abegin(dict(kwargs))
+        send = kwargs
+        loop = asyncio.get_running_loop()
+        if opt is True and prep is not None:
+            assembled = await loop.run_in_executor(None, self.recorder.optimised, prep)  # type: ignore[union-attr]
+            if assembled:
+                send = self._merge(kwargs, assembled)
+        sent = request_body(send)
+        stream = bool(send.get("stream"))
+        done = lambda resp: self._finish(prep, resp, sent, opt)  # noqa: E731
+        if not fo:
+            r = await raw(**send)
+            if stream:
+                return AsyncRecordingStream(r.__aiter__(), self.fmt, done, underlying=r)
+            done(cv.plain(r))
+            return r
+        breq = await loop.run_in_executor(None, backup_request, fo, sent, self.fmt, self.services)
+        queue_wait, on_first = None, None
+        if fo.mode == "queue":
+            q = await loop.run_in_executor(None, self._queue_setup, fo, prep, breq)
+            if q:
+                sid, name = q
+                queue_wait = queue_waiter_async(self.services, sid, prep.turn, fo)
+                on_first = lambda: self.recorder._worker.submit(lambda: self._first_token(sid, prep.turn, name))  # noqa: E731
+        create = raw_noretry()
+        out = await run_async(lambda: create(**send), fo, breq, stream=stream, primary_fmt=self.fmt,
+                              queue_wait=queue_wait, on_first_token=on_first)
+        if out.answered_by == "primary":
+            if stream:
+                p: _Primed = out.value
+                return AsyncRecordingStream(achain(p.first, p.it), self.fmt, done, underlying=p.stream)
+            done(cv.plain(out.value))
+            return out.value
+        res = self._backup_result(out, fo, stream, send, prep, opt, sent)
+        return AsyncRecordingStream(alist(res), self.fmt, lambda _: None) if stream else res
+
+    # ---------------------------------------------------------------- Anthropic's stream() helper
+
+    def stream_manager(self, raw_stream: Callable[..., Any], kwargs: Dict[str, Any], is_async: bool):
+        kwargs, _fo, opt, prep = self._begin(dict(kwargs))
+        sent = request_body(kwargs)
+        mgr = raw_stream(**kwargs)
+        done = lambda resp: self._finish(prep, resp, sent, opt)  # noqa: E731
+        return (_AsyncStreamManager if is_async else _StreamManager)(mgr, done)
+
+
+class _StreamManager:
+    """``messages.stream()``: the official helper; the final message is recorded on a clean exit."""
+
+    def __init__(self, mgr: Any, done: Callable[[Dict[str, Any]], None]):
+        self._mgr, self._done, self._stream = mgr, done, None
+
+    def __enter__(self):
+        self._stream = self._mgr.__enter__()
+        return self._stream
+
+    def __exit__(self, *exc):
+        try:
+            if exc[0] is None and self._stream is not None:
+                self._done(cv.plain(self._stream.get_final_message()))
+        finally:
+            return self._mgr.__exit__(*exc)
+
+    def __getattr__(self, name):
+        return getattr(self._mgr, name)
+
+
+class _AsyncStreamManager(_StreamManager):
+    async def __aenter__(self):
+        self._stream = await self._mgr.__aenter__()
+        return self._stream
+
+    async def __aexit__(self, *exc):
+        try:
+            if exc[0] is None and self._stream is not None:
+                self._done(cv.plain(await self._stream.get_final_message()))
+        finally:
+            return await self._mgr.__aexit__(*exc)
+
+
+class _Resource:
+    """A wrapped resource: ``create`` (and ``stream``) recorded; everything else is the official one."""
+
+    def __init__(self, client: Any, raw: Any, is_async: bool):
+        self._client, self._raw, self._async = client, raw, is_async
+
+    def create(self, **kwargs):
+        noretry = lambda: self._client._mc_raw(0).create  # noqa: E731
+        if self._async:
+            return self._client._mc.call_async(self._raw.create, noretry, kwargs)
+        return self._client._mc.call_sync(self._raw.create, noretry, kwargs)
+
+    def __getattr__(self, name):
+        return getattr(self._raw, name)
+
+
+class _AnthropicMessages(_Resource):
+    def stream(self, **kwargs):
+        return self._client._mc.stream_manager(self._raw.stream, kwargs, self._async)
+
+
+class _Chat:
+    def __init__(self, client: Any, raw: Any, is_async: bool):
+        self._raw = raw
+        self.completions = _Resource(client, raw.completions, is_async)
+
+    def __getattr__(self, name):
+        return getattr(self._raw, name)
+
+
+def _mc_kwargs(kwargs: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: kwargs.pop(k) for k in ("failover", "optimise", "keepalive", "record", "multichat_api_key", "services", "record_files",
+                                     "guardrails", "stable_tools")
+            if k in kwargs}
+
+
+def _make(base: Any, fmt: str, resource: str, is_async: bool):
+    """A subclass of the official client ``base`` with ``resource`` (chat or messages) recorded."""
+
+    def __init__(self, *, failover: Optional[Backup] = None, optimise: Optimise = "preview",
+                 keepalive: Union[KeepAlive, bool, None] = None, record: bool = True,
+                 multichat_api_key: Optional[str] = None, services: Optional[Services] = None,
+                 record_files: bool = True, guardrails: Optional[Guardrails] = None, stable_tools: bool = False,
+                 _mc_engine: Optional[Engine] = None, **kwargs: Any) -> None:
+        base.__init__(self, **kwargs)
+        self._mc_noretry = None
+        if _mc_engine is not None:
+            self._mc = _mc_engine
+            return
+        def key():
+            k = getattr(self, "api_key", None)
+            return k() if callable(k) else k
+        self._mc = Engine(fmt, failover=failover, optimise=optimise, keepalive=keepalive, record=record,
+                          multichat_api_key=multichat_api_key, services=services, provider_key=key,
+                          provider_base_url=lambda: queue_base_url(self, fmt), record_files=record_files,
+                          guardrails=guardrails, stable_tools=stable_tools)
+
+    def copy(self, **kwargs: Any):
+        extra = dict(kwargs.pop("_extra_kwargs", {}) or {})
+        extra["_mc_engine"] = self._mc
+        return base.copy(self, _extra_kwargs=extra, **kwargs)
+
+    def _raw_resource(self):
+        r = base.__dict__[resource].func(self)
+        return r.completions if resource == "chat" else r
+
+    def _mc_raw(self, max_retries: Optional[int] = None):
+        if max_retries is None or max_retries == self.max_retries:
+            return _raw_resource(self)
+        if self._mc_noretry is None:
+            self._mc_noretry = base.copy(self, max_retries=max_retries, _extra_kwargs={"_mc_engine": self._mc})
+        return _raw_resource(self._mc_noretry)
+
+    def multichat(self) -> Engine:
+        return self._mc
+
+    if resource == "chat":
+        def wrapped(self):
+            return _Chat(self, base.__dict__["chat"].func(self), is_async)
+    else:
+        def wrapped(self):
+            return _AnthropicMessages(self, base.__dict__["messages"].func(self), is_async)
+    wrapped.__name__ = resource
+
+    ns = {"__init__": __init__, "copy": copy, "with_options": copy, "_mc_raw": _mc_raw,
+          "multichat": property(multichat, doc=Engine.__doc__), resource: cached_property(wrapped),
+          "__doc__": "``%s.%s`` calling the provider directly with your key; each turn is recorded in the "
+                     "multiChat store. Extra arguments: failover, optimise, keepalive, record, record_files, guardrails, stable_tools, multichat_api_key."
+                     % (base.__module__.split(".")[0], base.__name__),
+          "__module__": "multichat"}
+    if is_async:
+        async def close(self) -> None:
+            if self._mc.recorder is not None:
+                await asyncio.get_running_loop().run_in_executor(None, self._mc.flush)
+            await base.close(self)
+    else:
+        def close(self) -> None:
+            self._mc.flush()
+            base.close(self)
+    ns["close"] = close
+    cls = type(base.__name__, (base,), ns)
+    cls.__qualname__ = base.__name__
+    cls.__init__.__wrapped__ = base.__init__  # type: ignore[attr-defined]
+    return cls
+
+
+def _missing(name: str, extra: str):
+    class Missing:
+        def __init__(self, *a: Any, **k: Any) -> None:
+            raise ImportError("multichat.%s needs the %s package: pip install 'multichat-sdk[%s]'" % (name, extra, extra))
+    Missing.__name__ = name
+    return Missing
+
+
+try:
+    import openai as _openai
+except ImportError:  # pragma: no cover
+    _openai = None  # type: ignore[assignment]
+
+try:
+    import anthropic as _anthropic
+except ImportError:  # pragma: no cover
+    _anthropic = None  # type: ignore[assignment]
+
+if _openai is not None:
+    OpenAI = _make(_openai.OpenAI, cv.OPENAI, "chat", False)
+    AsyncOpenAI = _make(_openai.AsyncOpenAI, cv.OPENAI, "chat", True)
+else:  # pragma: no cover
+    OpenAI = _missing("OpenAI", "openai")
+    AsyncOpenAI = _missing("AsyncOpenAI", "openai")
+
+if _anthropic is not None:
+    Anthropic = _make(_anthropic.Anthropic, cv.ANTHROPIC, "messages", False)
+    AsyncAnthropic = _make(_anthropic.AsyncAnthropic, cv.ANTHROPIC, "messages", True)
+else:  # pragma: no cover
+    Anthropic = _missing("Anthropic", "anthropic")
+    AsyncAnthropic = _missing("AsyncAnthropic", "anthropic")

multichat/_config.py

@@ -0,0 +1,68 @@
+"""Credentials and service addresses.
+
+Credential, first found: the ``multichat_api_key`` argument, ``MULTICHAT_API_KEY`` (an API key
+from the portal), ``MULTICHAT_TOKEN``, or the sign-in token ``multichat login`` saved in
+``~/.multichat/credentials.json``. Addresses: ``MULTICHAT_STORE_URL``, ``MULTICHAT_QUEUE_URL``,
+``MULTICHAT_PLANNER_URL``, ``MULTICHAT_PORTAL_URL``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+STORE_URL = "https://store.multichat.io"
+QUEUE_URL = "https://queue.multichat.io"
+PLANNER_URL = "https://planner.multichat.io"
+PORTAL_URL = "https://portal.multichat.io"
+
+
+def store_url() -> str:
+    return os.environ.get("MULTICHAT_STORE_URL") or STORE_URL
+
+
+def queue_url() -> str:
+    return os.environ.get("MULTICHAT_QUEUE_URL") or QUEUE_URL
+
+
+def planner_url() -> str:
+    return os.environ.get("MULTICHAT_PLANNER_URL") or PLANNER_URL
+
+
+def portal_url() -> str:
+    return os.environ.get("MULTICHAT_PORTAL_URL") or PORTAL_URL
+
+
+def config_dir() -> Path:
+    return Path(os.path.expanduser("~")) / ".multichat"
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials.json"
+
+
+def find_credential(explicit: Optional[str] = None) -> Optional[str]:
+    if explicit:
+        return explicit
+    for var in ("MULTICHAT_API_KEY", "MULTICHAT_TOKEN"):
+        if os.environ.get(var):
+            return os.environ[var]
+    try:
+        with open(credentials_path(), encoding="utf-8") as f:
+            data = json.load(f)
+        tok = data.get("token") if isinstance(data, dict) else None
+        return tok or None
+    except (OSError, ValueError):
+        return None
+
+
+def save_token(token: str) -> Path:
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump({"token": token}, f)
+    os.chmod(path, 0o600)
+    return path

multichat/_errors.py

@@ -0,0 +1,26 @@
+"""Errors raised by the multiChat SDK itself. Provider errors are the provider SDK's own."""
+
+
+class MultiChatError(Exception):
+    """An error from the SDK or one of the multiChat services."""
+
+    def __init__(self, message, status_code=None, code=None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+
+
+class NotLoggedInError(MultiChatError):
+    def __init__(self, message=None, status_code=None, code=None):
+        super().__init__(message or (
+            "No multiChat credential. Set MULTICHAT_API_KEY (an API key from the portal), run "
+            "`multichat login`, or pass record=False to call the provider without recording."), status_code, code)
+
+
+class ServiceError(MultiChatError):
+    """A multiChat service (store, queue, planner) answered with an error."""
+
+
+class BackupUnavailableError(MultiChatError):
+    """Queue-mode failover: the backup's answer did not arrive in time."""