aria-code 0.52.0__py3-none-any.whl

aria_code/clients/openai_image_client.py

@@ -0,0 +1,242 @@
+"""OpenAI image generation/editing client — the execution backend for prompts
+compiled by the `minimal-editorial-poster` / `minimal-editorial-exports`
+skills.
+
+Two capabilities, matching OpenAI's two endpoints (verified against the
+official openai-python SDK source, since the public docs page 403s to
+scrapers):
+    generate_image() -> POST /v1/images/generations (text -> new image)
+    edit_image()     -> POST /v1/images/edits       (existing photo + prompt
+                          -> transformed image; multipart, not JSON)
+
+Both use gpt-image-1, which always returns base64 (no response_format /
+url option for GPT image models, only for dall-e-2/3).
+
+Key resolution mirrors aria_cli.py's _get_provider_key(): env var
+OPENAI_API_KEY first, then providers.json's "llm" then "data" sections
+under "openai" — so a key already set via `/apikey set openai sk-...` for
+chat is reused here, no separate setup needed.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+API_BASE = "https://api.openai.com/v1"
+DEFAULT_MODEL = "gpt-image-1"
+
+# Per-image USD cost by (quality, size), verified against OpenAI's published
+# gpt-image-1 output-token pricing (developers.openai.com/api/docs/guides/
+# image-generation) — output tokens only; input text/image tokens add a few
+# thousandths of a cent and are ignored here as noise.
+_COST_USD: Dict[str, Dict[str, float]] = {
+    "low": {"1024x1024": 0.011, "1024x1536": 0.016, "1536x1024": 0.016},
+    "medium": {"1024x1024": 0.042, "1024x1536": 0.063, "1536x1024": 0.063},
+    "high": {"1024x1024": 0.167, "1024x1536": 0.25, "1536x1024": 0.25},
+}
+
+
+def estimate_cost(size: str = "1024x1536", quality: str = "high") -> Dict[str, Any]:
+    """Rough cost estimate — call before generate_image()/edit_image(),
+    not a live quote. "auto" quality/size can't be priced ahead of time
+    (OpenAI picks the actual value), so it's reported as unknown rather
+    than guessed."""
+    per_image = (_COST_USD.get(quality) or {}).get(size)
+    return {
+        "provider": "openai",
+        "model": DEFAULT_MODEL,
+        "size": size,
+        "quality": quality,
+        "estimated_cost_usd": per_image,
+        "note": (
+            "Illustrative estimate from OpenAI's published per-image pricing; "
+            "verify current pricing at platform.openai.com/docs/pricing."
+            if per_image is not None
+            else "'auto' size/quality is resolved by OpenAI at request time and can't be priced ahead of submission."
+        ),
+    }
+
+
+def _providers_path() -> Path:
+    from apps.cli.config_paths import resolve_paths
+    return resolve_paths().providers_file
+
+
+def _api_key() -> str:
+    env = os.getenv("OPENAI_API_KEY", "").strip()
+    if env:
+        return env
+    path = _providers_path()
+    if not path.exists():
+        return ""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return ""
+    for section in ("llm", "data"):
+        entry = raw.get(section, {}).get("openai", {}) or {}
+        if entry.get("api_key"):
+            return entry["api_key"]
+    return ""
+
+
+def _require_key() -> str:
+    key = _api_key()
+    if not key:
+        raise RuntimeError(
+            "No OpenAI API key found. Set one with `/apikey set openai sk-...` "
+            "or export OPENAI_API_KEY."
+        )
+    return key
+
+
+def _save_b64_image(b64_data: str, dest: Path) -> Path:
+    dest.write_bytes(base64.b64decode(b64_data))
+    return dest
+
+
+def _normalize_image_for_upload(path: Path, *, keep_alpha: bool = False) -> tuple[str, bytes]:
+    """Re-encode an arbitrary local image file into a clean single-frame PNG
+    before uploading to OpenAI's edits endpoint.
+
+    Two real problems this fixes, not just defensive coding — both
+    reproduced directly against real iPhone photos:
+      1. iPhones commonly save JPEGs as MPO (Multi-Picture Object — an
+         embedded-stereo-frame container, not a plain single-frame JPEG)
+         even with a plain .jpg extension. OpenAI's edit endpoint rejects
+         these with a 400 "Invalid image file or mode" even though the
+         extension and declared docs (png/webp/jpg) suggest it should work.
+      2. A portrait photo is commonly stored as landscape pixels plus an
+         EXIF orientation tag telling viewers to rotate on display — the
+         raw bytes, uploaded as-is, are genuinely sideways. Reproduced: a
+         raw PIL open() of a real orientation=6 photo, no exif_transpose,
+         is visibly sideways.
+    Re-saving through PIL with exif_transpose applied produces a single-
+    frame PNG immune to both, regardless of the source container/orientation.
+    """
+    import io
+
+    from PIL import Image, ImageOps
+
+    img = ImageOps.exif_transpose(Image.open(path))
+    img = img.convert("RGBA" if keep_alpha else "RGB")
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return f"{path.stem}.png", buf.getvalue()
+
+
+def generate_image(
+    prompt: str,
+    *,
+    size: str = "1024x1536",
+    quality: str = "high",
+    confirmed: bool = False,
+) -> Dict[str, Any]:
+    """Generate a new image from a text prompt (e.g. minimal-editorial-poster's
+    compiled prompt) via POST /v1/images/generations — real per-call cost,
+    billed by OpenAI the instant this succeeds (see estimate_cost()).
+
+    Blocking (uses requests) — callers on an event loop should run this in
+    an executor, same as every other client in this codebase.
+    """
+    if not confirmed:
+        return {
+            "success": False,
+            "error": (
+                "confirmed must be true to generate a real (paid) image. "
+                "Call estimate_cost() first to see the cost, then resubmit with confirmed=true."
+            ),
+        }
+
+    import requests
+
+    from artifacts import create_user_artifact
+
+    key = _require_key()
+    resp = requests.post(
+        f"{API_BASE}/images/generations",
+        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+        json={"model": DEFAULT_MODEL, "prompt": prompt, "size": size, "quality": quality},
+        timeout=120,
+    )
+    if resp.status_code != 200:
+        return {"success": False, "error": f"OpenAI image generation failed: {resp.status_code} {resp.text[:300]}"}
+    data = (resp.json().get("data") or [{}])[0]
+    b64 = data.get("b64_json")
+    if not b64:
+        return {"success": False, "error": "OpenAI response had no b64_json image data"}
+
+    artifact = create_user_artifact("image", "generated", "poster", ".png")
+    _save_b64_image(b64, artifact.path)
+    return {"success": True, "path": str(artifact.path)}
+
+
+def edit_image(
+    image_path: str,
+    prompt: str,
+    *,
+    size: str = "1024x1536",
+    quality: str = "high",
+    mask_path: Optional[str] = None,
+    confirmed: bool = False,
+) -> Dict[str, Any]:
+    """Transform an existing local photo per `prompt` (e.g. "convert to duotone,
+    simplify background to negative space, add scan-noise texture...") via
+    POST /v1/images/edits — the execution path for a real user-provided photo
+    run through the minimal-editorial-poster skill. Real per-call cost,
+    billed by OpenAI the instant this succeeds (see estimate_cost()).
+
+    Blocking (uses requests) — same threading note as generate_image.
+    """
+    if not confirmed:
+        return {
+            "success": False,
+            "error": (
+                "confirmed must be true to generate a real (paid) image edit. "
+                "Call estimate_cost() first to see the cost, then resubmit with confirmed=true."
+            ),
+        }
+
+    import requests
+
+    from artifacts import create_user_artifact
+
+    src = Path(image_path)
+    if not src.exists():
+        return {"success": False, "error": f"File not found: {image_path}"}
+
+    key = _require_key()
+    try:
+        files = {"image": _normalize_image_for_upload(src)}
+    except Exception as exc:
+        return {"success": False, "error": f"Could not read image_path: {exc}"}
+    if mask_path:
+        mask = Path(mask_path)
+        if not mask.exists():
+            return {"success": False, "error": f"Mask file not found: {mask_path}"}
+        try:
+            files["mask"] = _normalize_image_for_upload(mask, keep_alpha=True)
+        except Exception as exc:
+            return {"success": False, "error": f"Could not read mask_path: {exc}"}
+
+    resp = requests.post(
+        f"{API_BASE}/images/edits",
+        headers={"Authorization": f"Bearer {key}"},
+        data={"model": DEFAULT_MODEL, "prompt": prompt, "size": size, "quality": quality},
+        files=files,
+        timeout=180,
+    )
+    if resp.status_code != 200:
+        return {"success": False, "error": f"OpenAI image edit failed: {resp.status_code} {resp.text[:300]}"}
+    data = (resp.json().get("data") or [{}])[0]
+    b64 = data.get("b64_json")
+    if not b64:
+        return {"success": False, "error": "OpenAI response had no b64_json image data"}
+
+    artifact = create_user_artifact("image", "edited", f"{src.stem}_edited", ".png")
+    _save_b64_image(b64, artifact.path)
+    return {"success": True, "path": str(artifact.path)}

aria_code/clients/runway_video_client.py

@@ -0,0 +1,157 @@
+"""Runway video generation client — Layer 3 (cloud AI generation) of the
+video architecture, one of two provider clients (see also
+kling_video_client.py) behind the same submit/poll shape so
+packages/aria_mcp/server.py can route to either without provider-specific
+logic outside these two files.
+
+Verified against Runway's own generated SDK source
+(github.com/runwayml/sdk-python), not the public docs page (which returned
+an unfetchable error) — same discipline as openai_image_client.py and
+canva_client.py: primary-source field names, not guessed ones.
+
+    base_url: https://api.dev.runwayml.com
+    auth:     Authorization: Bearer {api_key}, X-Runway-Version: 2024-11-06
+    submit:   POST /v1/text_to_video  {model, promptText, ratio, duration?, ...}
+    poll:     GET  /v1/tasks/{id}  -> status PENDING|THROTTLED|RUNNING|FAILED|SUCCEEDED
+              (SUCCEEDED carries `output`: a list of video URLs, valid 24-48h)
+
+Real per-request cost — every submission is a genuine payment. This module
+never gates that itself (no local "confirmed" concept); the MCP server layer
+enforces the confirm-after-estimate gate, matching the broker order-preview
+pattern's reasoning: submission is the moment money is spent, so the caller
+must have deliberately opted in.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+API_BASE = "https://api.dev.runwayml.com"
+API_VERSION = "2024-11-06"
+
+# Rough, illustrative-only pricing — Runway doesn't publish a stable public
+# per-second API rate the way Kling does; verify current pricing on your
+# account dashboard before relying on this for a real cost decision.
+APPROX_COST_PER_SECOND_USD = 0.25
+
+
+def _providers_path() -> Path:
+    from apps.cli.config_paths import resolve_paths
+    return resolve_paths().providers_file
+
+
+def _api_key() -> str:
+    env = os.getenv("RUNWAYML_API_SECRET", "").strip()
+    if env:
+        return env
+    path = _providers_path()
+    if not path.exists():
+        return ""
+    try:
+        import json
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return ""
+    for section in ("llm", "data"):
+        entry = raw.get(section, {}).get("runway", {}) or {}
+        if entry.get("api_key"):
+            return entry["api_key"]
+    return ""
+
+
+def _require_key() -> str:
+    key = _api_key()
+    if not key:
+        raise RuntimeError(
+            "No Runway API key found. Set one with `/apikey set runway <key>` "
+            "or export RUNWAYML_API_SECRET."
+        )
+    return key
+
+
+def _headers() -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {_require_key()}",
+        "X-Runway-Version": API_VERSION,
+        "Content-Type": "application/json",
+    }
+
+
+def estimate_cost(duration: int) -> Dict[str, Any]:
+    """Rough cost estimate — call before submit_video(), not a live quote."""
+    return {
+        "provider": "runway",
+        "duration_sec": duration,
+        "estimated_cost_usd": round(duration * APPROX_COST_PER_SECOND_USD, 2),
+        "note": "Illustrative estimate — verify current pricing on your Runway account dashboard.",
+    }
+
+
+def submit_video(
+    prompt: str,
+    *,
+    model: str = "gen4.5",
+    duration: int = 5,
+    ratio: str = "1280:720",
+) -> Dict[str, Any]:
+    """Submit a text-to-video generation job. Returns immediately with a
+    task id — this does NOT wait for the video, since generation takes
+    minutes; poll with poll_video().
+
+    duration must be 2-10 for gen4.5; ratio must be one of the values that
+    model supports ("1280:720"/"720:1280" for gen4.5; veo3.1/veo3.1_fast
+    additionally support "1080:1920"/"1920:1080" — see Runway's docs for the
+    full per-model matrix, verified in this repo only for gen4.5's basic
+    shape).
+    """
+    import requests
+
+    body = {"model": model, "promptText": prompt, "ratio": ratio, "duration": duration}
+    try:
+        resp = requests.post(f"{API_BASE}/v1/text_to_video", headers=_headers(), json=body, timeout=30)
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+    if resp.status_code not in (200, 201, 202):
+        return {"success": False, "error": f"Runway submission failed: {resp.status_code} {resp.text[:400]}"}
+    data = resp.json()
+    task_id = data.get("id", "")
+    if not task_id:
+        return {"success": False, "error": "Runway did not return a task id"}
+    return {"success": True, "task_id": task_id, "provider": "runway"}
+
+
+def poll_video(task_id: str, *, download: bool = True) -> Dict[str, Any]:
+    """Check a submitted task's status. On SUCCEEDED, optionally downloads
+    the first output video to the artifacts folder."""
+    import requests
+
+    try:
+        resp = requests.get(f"{API_BASE}/v1/tasks/{task_id}", headers=_headers(), timeout=30)
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+    if resp.status_code != 200:
+        return {"success": False, "error": f"Runway task lookup failed: {resp.status_code} {resp.text[:400]}"}
+    data = resp.json()
+    status = data.get("status", "")
+
+    if status == "SUCCEEDED":
+        outputs = data.get("output") or []
+        if not outputs:
+            return {"success": False, "status": status, "error": "SUCCEEDED but no output URLs present"}
+        result = {"success": True, "status": status, "video_url": outputs[0]}
+        if download:
+            from artifacts import create_user_artifact
+
+            video_resp = requests.get(outputs[0], timeout=120)
+            if video_resp.status_code == 200:
+                artifact = create_user_artifact("video", "runway", "runway_video", ".mp4")
+                artifact.path.write_bytes(video_resp.content)
+                result["path"] = str(artifact.path)
+        return result
+
+    if status == "FAILED":
+        return {"success": False, "status": status, "error": data.get("failure", "generation failed")}
+
+    return {"success": True, "status": status, "progress": data.get("progress")}

aria_code/clients/warehouse_erp_client.py

@@ -0,0 +1,105 @@
+"""Read-only client for the warehouse ERP agent snapshot endpoint.
+
+The client intentionally exposes one narrow endpoint instead of a generic ERP
+proxy.  That keeps the agent boundary auditable: the CLI can only retrieve the
+small operational snapshot required for analysis and has no write capability.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote, urlparse
+
+import httpx
+
+
+class WarehouseERPConfigurationError(ValueError):
+    """Raised when the local ERP integration configuration is invalid."""
+
+
+class WarehouseERPRequestError(RuntimeError):
+    """Raised with a safe, user-facing ERP request error."""
+
+
+_DEFAULT_SNAPSHOT_PATH = "/api/v1/warehouses/{warehouse_id}/agent-snapshot"
+_RECORD_LISTS = ("connectors", "inbounds", "skus", "locations")
+
+
+class WarehouseERPClient:
+    """Fetch a minimal, read-only warehouse snapshot over HTTPS or HTTP."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str = "",
+        snapshot_path: str = _DEFAULT_SNAPSHOT_PATH,
+        timeout_seconds: float = 10.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        parsed = urlparse(str(base_url or "").strip())
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise WarehouseERPConfigurationError("ARIA_WAREHOUSE_ERP_URL 必须是完整的 http(s) URL")
+        if not snapshot_path.startswith("/") or "{warehouse_id}" not in snapshot_path:
+            raise WarehouseERPConfigurationError(
+                "ARIA_WAREHOUSE_ERP_SNAPSHOT_PATH 必须是包含 {warehouse_id} 的相对路径"
+            )
+        self.base_url = str(base_url).rstrip("/")
+        self.token = str(token or "").strip()
+        self.snapshot_path = snapshot_path
+        self.timeout_seconds = float(timeout_seconds)
+        self.transport = transport
+
+    @classmethod
+    def from_env(cls) -> "WarehouseERPClient":
+        return cls(
+            base_url=os.environ.get("ARIA_WAREHOUSE_ERP_URL", ""),
+            token=os.environ.get("ARIA_WAREHOUSE_ERP_TOKEN", ""),
+            snapshot_path=os.environ.get("ARIA_WAREHOUSE_ERP_SNAPSHOT_PATH", _DEFAULT_SNAPSHOT_PATH),
+        )
+
+    def _snapshot_url(self, warehouse_id: str) -> str:
+        cleaned = str(warehouse_id or "").strip()
+        if not cleaned:
+            raise WarehouseERPConfigurationError("仓库编号不能为空")
+        return self.base_url + self.snapshot_path.format(warehouse_id=quote(cleaned, safe=""))
+
+    async def fetch_snapshot(self, warehouse_id: str) -> dict[str, Any]:
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=self.timeout_seconds,
+                follow_redirects=False,
+                transport=self.transport,
+            ) as client:
+                response = await client.get(self._snapshot_url(warehouse_id), headers=headers)
+        except httpx.TimeoutException as exc:
+            raise WarehouseERPRequestError("ERP 请求超时，请稍后重试。") from exc
+        except httpx.HTTPError as exc:
+            raise WarehouseERPRequestError("无法连接 ERP 服务，请检查网络或服务状态。") from exc
+
+        if response.status_code != 200:
+            raise WarehouseERPRequestError(f"ERP 服务返回 HTTP {response.status_code}。")
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise WarehouseERPRequestError("ERP 服务返回的不是有效 JSON。") from exc
+        return self._normalise_snapshot(warehouse_id, payload)
+
+    @staticmethod
+    def _normalise_snapshot(warehouse_id: str, payload: Any) -> dict[str, Any]:
+        root = payload.get("data", payload) if isinstance(payload, Mapping) else None
+        if not isinstance(root, Mapping):
+            raise WarehouseERPRequestError("ERP 快照必须是 JSON 对象。")
+
+        snapshot: dict[str, Any] = {
+            "warehouse_id": str(root.get("warehouse_id") or warehouse_id),
+        }
+        for key in _RECORD_LISTS:
+            value = root.get(key, [])
+            snapshot[key] = [dict(item) for item in value if isinstance(item, Mapping)] if isinstance(value, list) else []
+        return snapshot

aria_code/cloud_memory.py

@@ -0,0 +1,181 @@
+"""Cross-platform memory sync for the CLI.
+
+MemoryManager keeps facts in ~/.arthera/memory/ so the CLI works offline and
+without an account. This module carries the durable ones to the same store the
+web, desktop and iOS clients read (`/api/v2/memory/items`), so a preference
+stated in the terminal is not invisible everywhere else.
+
+Local stays the working copy on purpose. Sync is best-effort: an expired token,
+an offline laptop or a backend outage must never cost the user a memory or block
+the turn they are in the middle of. Every call here returns a value instead of
+raising, and the caller treats failure as "not synced yet".
+
+Identity comes from `aria login` (see apps/cli/google_login.py). Without a token
+this module does nothing at all — memory is per-user on the server, and there is
+no sensible anonymous bucket to write into.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT_SECONDS = 8
+_MAX_CONTENT_CHARS = 4_000  # matches MemoryItemCreate.content on the server
+
+
+class CloudMemoryClient:
+    """Thin client over the cross-platform memory API.
+
+    Instantiate with the API base URL and the Firebase ID token stored by
+    `/login`. `available` is False when there is no token, which callers should
+    check rather than relying on every method quietly no-opping.
+    """
+
+    def __init__(self, api_url: str, token: Optional[str]) -> None:
+        self.api_url = (api_url or "").rstrip("/")
+        self.token = (token or "").strip()
+
+    @property
+    def available(self) -> bool:
+        return bool(self.api_url and self.token)
+
+    # ── transport ────────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if not self.available:
+            return None
+
+        url = f"{self.api_url}{path}"
+        if query:
+            pairs = {k: v for k, v in query.items() if v is not None}
+            if pairs:
+                url = f"{url}?{urllib.parse.urlencode(pairs)}"
+
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        request = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                **({"Content-Type": "application/json"} if data else {}),
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=_TIMEOUT_SECONDS) as response:
+                raw = response.read().decode("utf-8")
+            return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as exc:
+            # 401 is the ordinary case of an ID token older than an hour, not an
+            # error worth interrupting the user over. Say so at debug level and
+            # let the next /login refresh it.
+            level = logging.DEBUG if exc.code == 401 else logging.WARNING
+            logger.log(level, "Cloud memory %s %s failed: HTTP %s", method, path, exc.code)
+            return None
+        except Exception as exc:
+            logger.debug("Cloud memory %s %s unreachable: %s", method, path, exc)
+            return None
+
+    # ── items ────────────────────────────────────────────────────────────────
+
+    def push_item(
+        self,
+        content: str,
+        *,
+        kind: str = "durable",
+        scope: str = "user",
+        project_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Optional[str]:
+        """Store one memory server-side. Returns its id, or None if not synced.
+
+        `classification` is left at the server default. Anything the server
+        considers sensitive, financial or connected requires explicit consent
+        there, and a CLI turn is not a place to imply that consent was given.
+        """
+        text = (content or "").strip()
+        if not text:
+            return None
+        if scope == "project" and not project_id:
+            # The server rejects this combination; catching it here keeps a
+            # pointless round trip and a confusing 422 out of the logs.
+            logger.debug("Cloud memory: project scope needs a project_id")
+            return None
+
+        payload: Dict[str, Any] = {
+            "content": text[:_MAX_CONTENT_CHARS],
+            "kind": kind,
+            "scope": scope,
+            "metadata": {"source": "aria-code", **(metadata or {})},
+        }
+        if project_id:
+            payload["project_id"] = project_id
+
+        result = self._request("POST", "/api/v2/memory/items", body=payload)
+        if not isinstance(result, dict):
+            return None
+        item_id = result.get("id") or (result.get("item") or {}).get("id")
+        return str(item_id) if item_id else None
+
+    def list_items(
+        self,
+        *,
+        scope: Optional[str] = None,
+        project_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> List[Dict[str, Any]]:
+        """Return stored memories, newest first. Empty list when unavailable."""
+        result = self._request(
+            "GET",
+            "/api/v2/memory/items",
+            query={
+                "scope": scope,
+                "project_id": project_id,
+                "limit": max(1, min(int(limit), 100)),
+            },
+        )
+        if not isinstance(result, dict):
+            return []
+        items = result.get("items")
+        return items if isinstance(items, list) else []
+
+    # ── preferences ──────────────────────────────────────────────────────────
+
+    def get_preferences(self) -> Dict[str, Any]:
+        result = self._request("GET", "/api/v2/memory/preferences")
+        return result if isinstance(result, dict) else {}
+
+    def put_preferences(self, preferences: Dict[str, str]) -> bool:
+        result = self._request(
+            "PUT", "/api/v2/memory/preferences", body=dict(preferences)
+        )
+        return result is not None
+
+
+def client_from_config(config: Dict[str, Any]) -> CloudMemoryClient:
+    """Build a client from the CLI config written by /login.
+
+    Kept separate from CloudMemoryClient so the class stays testable without a
+    config dict, and so the key names live in one place if they change.
+    """
+    return CloudMemoryClient(
+        api_url=str(config.get("api_url") or ""),
+        token=config.get("auth_token"),
+    )
+
+
+__all__ = ["CloudMemoryClient", "client_from_config"]