memorysync-cli 1.0.2__py3-none-any.whl

memorysync_cli/__init__.py

@@ -0,0 +1,13 @@
+"""MemorySync command-line interface.
+
+A Python implementation of the same CLI as the npm package ``memorysync-cli``,
+with the same commands, flags, output formats and exit codes. The two are
+interchangeable: whichever is on PATH behaves identically, so you only need one.
+
+Both read their command surface from one generated declaration, so ``help --json``
+is byte-identical between them rather than kept aligned by review.
+"""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

memorysync_cli/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m memorysync_cli`` alongside the installed console scripts.
+
+Useful during development and in environments where a wheel's scripts directory is
+not on PATH, which is common inside CI containers.
+"""
+
+from .main import run
+
+run()

memorysync_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.2"

memorysync_cli/args.py

@@ -0,0 +1,220 @@
+"""Argument parsing.
+
+Hand-rolled rather than using argparse, and deliberately so.
+
+The grammar is small, but it has to match the Node CLI token for token, because
+the two CLIs are interchangeable and a script must not behave differently
+depending on which one is on PATH. argparse has its own opinions - about prefix
+matching, about how it reports errors, about exiting with code 2 on its own terms
+- and bending it into agreement would be more work than owning ninety lines.
+
+Owning it also means `--help`, `help --json` and the completion scripts all come
+from the shared registry rather than from a library's internal state, which is how
+they stay consistent with what the parser actually accepts.
+
+The grammar, matching ``sdk/cli/src/args.mjs``:
+
+    --flag value   --flag=value   -f value   -f=value   --no-flag
+    Bundled booleans: -qv. A valued short flag may only come last, as in getopt.
+    Everything after ``--`` is positional, so text containing dashes survives.
+    Unknown flags are refused, never ignored.
+
+That last rule earns its keep: silently dropping a misspelled ``--user`` would
+scope memory to the wrong person, and the caller would not find out.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import usage_error
+
+# Flags that take a value. Everything else is boolean. Kept in step with the
+# Node CLI's VALUED set; the parity test asserts every registry flag is known
+# here, so a flag added there cannot go unhandled.
+VALUED = {
+    "profile",
+    "api-key",
+    "base-url",
+    "user",
+    "project",
+    "output",
+    "timeout",
+    "metadata",
+    "file",
+    "source",
+    "limit",
+    "importance",
+    "batch-size",
+    "out",
+    "format",
+    "query",
+}
+
+SHORT = {
+    "p": "profile",
+    "u": "user",
+    "o": "output",
+    "y": "yes",
+    "q": "quiet",
+    "v": "verbose",
+    "h": "help",
+    "m": "metadata",
+    "f": "file",
+    "k": "limit",
+}
+
+
+def _key(name: str) -> str:
+    """Flag name to dict key.
+
+    ``--dry-run`` becomes ``dry_run``. The Node CLI uses ``dryRun``; the surface
+    both expose is the flag itself, so each side reads naturally in its own
+    language. Only the command-line spelling has to agree.
+    """
+    return name.replace("-", "_")
+
+
+def parse_args(argv: list[str]) -> tuple[list[str], dict[str, Any]]:
+    """Split argv into positionals and flags.
+
+    Returns them separately rather than as one namespace so the dispatcher can
+    tell ``memorysync add --user x`` from ``memorysync --user x add`` without
+    re-parsing.
+    """
+    positionals: list[str] = []
+    flags: dict[str, Any] = {}
+    passthrough = False
+
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+
+        if passthrough:
+            positionals.append(token)
+            index += 1
+            continue
+
+        if token == "--":
+            passthrough = True
+            index += 1
+            continue
+
+        if token.startswith("--"):
+            name = token[2:]
+            value: str | None = None
+
+            if "=" in name:
+                name, _, value = name.partition("=")
+
+            if name.startswith("no-") and value is None:
+                positive = name[3:]
+                if positive in VALUED:
+                    raise usage_error(
+                        f"--{name} is not a flag. --{positive} takes a value."
+                    )
+                flags[_key(positive)] = False
+                index += 1
+                continue
+
+            if name in VALUED:
+                if value is None:
+                    following = argv[index + 1] if index + 1 < len(argv) else None
+                    if following is None or following.startswith("-"):
+                        raise usage_error(f"--{name} needs a value.")
+                    value = following
+                    index += 1
+                flags[_key(name)] = value
+                index += 1
+                continue
+
+            if value is not None:
+                # `--verbose=true` is accepted so a script generating flags
+                # programmatically does not have to special-case booleans.
+                flags[_key(name)] = value not in {"false", "0"}
+                index += 1
+                continue
+
+            flags[_key(name)] = True
+            index += 1
+            continue
+
+        if len(token) > 1 and token.startswith("-"):
+            body = token[1:]
+            letters, _, inline = body.partition("=")
+            has_inline = "=" in body
+
+            for position, letter in enumerate(letters):
+                long = SHORT.get(letter)
+                if long is None:
+                    raise usage_error(f"Unknown flag -{letter}.")
+
+                is_last = position == len(letters) - 1
+
+                if long in VALUED:
+                    if not is_last:
+                        raise usage_error(
+                            f"-{letter} takes a value, so it must come last in -{letters}."
+                        )
+                    if has_inline:
+                        value = inline
+                    else:
+                        following = argv[index + 1] if index + 1 < len(argv) else None
+                        if following is None or following.startswith("-"):
+                            raise usage_error(f"-{letter} needs a value.")
+                        value = following
+                        index += 1
+                    if value == "":
+                        raise usage_error(f"-{letter} needs a value.")
+                    flags[_key(long)] = value
+                else:
+                    flags[_key(long)] = True
+
+            index += 1
+            continue
+
+        positionals.append(token)
+        index += 1
+
+    return positionals, flags
+
+
+def levenshtein(left: str, right: str) -> int:
+    """Edit distance, for "did you mean". Inputs are command names, so the naive
+    row-by-row version is more than fast enough."""
+    if left == right:
+        return 0
+    if not left:
+        return len(right)
+    if not right:
+        return len(left)
+
+    previous = list(range(len(right) + 1))
+    for i, lc in enumerate(left, start=1):
+        current = [i]
+        for j, rc in enumerate(right, start=1):
+            current.append(
+                min(
+                    previous[j] + 1,
+                    current[j - 1] + 1,
+                    previous[j - 1] + (0 if lc == rc else 1),
+                )
+            )
+        previous = current
+    return previous[-1]
+
+
+def suggest(unknown: str, candidates: list[str]) -> str | None:
+    """Closest candidate, when one is close enough to be worth offering.
+
+    A third of the length is the threshold: close enough to catch a typo, far
+    enough that ``memorysync foo`` is not answered with a confident wrong guess.
+    """
+    best, best_distance = None, None
+    for candidate in candidates:
+        distance = levenshtein(unknown, candidate)
+        if best_distance is None or distance < best_distance:
+            best, best_distance = candidate, distance
+    if best is None or best_distance is None:
+        return None
+    return best if best_distance <= max(1, len(unknown) // 3) else None

memorysync_cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""Command implementations, grouped the same way the Node CLI groups them.
+
+The split mirrors ``sdk/cli/src/commands/`` file for file - memory, admin, init,
+source, tooling - so that a change on one side has an obvious counterpart on the
+other. Parity is easier to keep when the two trees look alike in review.
+"""

memorysync_cli/commands/admin.py

@@ -0,0 +1,354 @@
+"""quota, status, doctor, whoami, project, event, config.
+
+``quota`` and ``doctor`` are the two none of the competitors have. Both exist
+because of one API behaviour: over a plan limit the API returns success with an
+empty result rather than an error, so that an assistant never narrates billing
+state to an end user. That is right for the API and unhelpful in a terminal, where
+"nothing came back" and "you are out of quota" need to be distinguishable before
+someone spends an afternoon debugging an empty search.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+import time
+from typing import Any
+
+from .. import config as config_module
+from .. import credentials
+from .._version import __version__
+from ..errors import usage_error
+from ..output import render_table, style
+
+
+def _percent(used: Any, limit: Any) -> str:
+    if not isinstance(used, (int, float)) or not isinstance(limit, (int, float)) or limit <= 0:
+        return "-"
+    return f"{min(100, round(used / limit * 100))}%"
+
+
+def quota(ctx: dict) -> dict:
+    """Plan usage, with headroom made explicit.
+
+    The one command that turns the API's deliberate silence into a number. None of
+    Mem0, Supermemory or Zep expose this from their CLI.
+    """
+    api = ctx["api"]
+    summary = api.usage_summary() or {}
+    metrics = [m for m in (summary.get("metrics") or []) if isinstance(m, dict)]
+
+    rows = [
+        {
+            "metric": entry.get("metric"),
+            "used": entry.get("used"),
+            "limit": entry.get("limit"),
+            "remaining": (
+                entry["limit"] - entry["used"]
+                if isinstance(entry.get("limit"), (int, float))
+                and isinstance(entry.get("used"), (int, float))
+                else None
+            ),
+            "percent": _percent(entry.get("used"), entry.get("limit")),
+        }
+        for entry in metrics
+    ]
+
+    def render() -> str:
+        if not rows:
+            return style.dim("No usage reported for this billing cycle.")
+        table = render_table(
+            ["metric", "used", "limit", "remaining", "used %"],
+            [
+                [
+                    row["metric"],
+                    row["used"],
+                    "unlimited" if row["limit"] in (None, 0) else row["limit"],
+                    "-" if row["remaining"] is None else row["remaining"],
+                    row["percent"],
+                ]
+                for row in rows
+            ],
+        )
+        exhausted = [r["metric"] for r in rows if r["remaining"] == 0]
+        if exhausted:
+            warning = style.yellow(
+                "At the limit: " + ", ".join(str(m) for m in exhausted) + "."
+            )
+            note = style.dim(
+                "Writes and reads return empty rather than failing, so check here "
+                "before assuming memory is missing."
+            )
+            return f"{table}\n\n{warning}\n{note}"
+        return table
+
+    return {"data": rows, "text": render}
+
+
+def status(ctx: dict) -> dict:
+    """Reachability and identity in one call."""
+    api = ctx["api"]
+    started = time.monotonic()
+    plan = api.current_plan() or {}
+    latency = int((time.monotonic() - started) * 1000)
+
+    payload = {
+        "api": ctx["settings"]["base_url"],
+        "reachable": True,
+        "latency_ms": latency,
+        "plan": plan.get("plan") or plan.get("name"),
+        "cycle_ends": plan.get("current_period_end") or plan.get("cycle_ends"),
+    }
+
+    def render() -> str:
+        return "\n".join(
+            [
+                f"{style.dim('api        ')} {payload['api']}",
+                f"{style.dim('reachable  ')} {style.green('yes')} ({latency}ms)",
+                f"{style.dim('plan       ')} {payload['plan'] or '-'}",
+                f"{style.dim('cycle ends ')} {payload['cycle_ends'] or '-'}",
+            ]
+        )
+
+    return {"data": payload, "text": render}
+
+
+def whoami(ctx: dict) -> dict:
+    """Who this credential is, without printing the credential."""
+    settings = ctx["settings"]
+    api = ctx["api"]
+    plan = api.current_plan() or {}
+
+    payload = {
+        "profile": settings["profile_name"],
+        "base_url": settings["base_url"],
+        "user": settings.get("user"),
+        "project": settings.get("project"),
+        "plan": plan.get("plan") or plan.get("name"),
+        "credential_source": credentials.describe_storage(),
+    }
+
+    def render() -> str:
+        return "\n".join(
+            f"{style.dim(key.ljust(18))} {value if value not in (None, '') else '-'}"
+            for key, value in payload.items()
+        )
+
+    return {"data": payload, "text": render}
+
+
+def doctor(ctx: dict) -> dict:
+    """Diagnose a broken setup and exit 0 either way.
+
+    Exiting 0 even when checks fail is deliberate: this is a diagnostic, and a
+    non-zero exit would make it useless inside `set -e` scripts, which is exactly
+    where someone reaches for it.
+    """
+    settings = ctx["settings"]
+    api = ctx.get("api")
+    checks: list[dict[str, Any]] = []
+
+    def add(name: str, ok: bool | None, detail: str, hint: str | None = None) -> None:
+        checks.append(
+            {
+                "check": name,
+                "status": "pass" if ok else ("warn" if ok is None else "fail"),
+                "detail": detail,
+                **({"hint": hint} if hint else {}),
+            }
+        )
+
+    version_ok = sys.version_info >= (3, 9)
+    add(
+        "python",
+        version_ok,
+        platform.python_version(),
+        None if version_ok else "MemorySync needs Python 3.9 or newer.",
+    )
+    add("cli", True, f"memorysync-cli {__version__}")
+    add("config", True, str(config_module.config_path()))
+    add("credential store", True, credentials.describe_storage())
+
+    key = credentials.read_key(settings["profile_name"])
+    add(
+        "api key",
+        bool(key),
+        f"found ({key[:8]}...)" if key else "not found",
+        None if key else "Run `memorysync init`, or set MEMORYSYNC_API_KEY.",
+    )
+    add(
+        "end user",
+        bool(settings.get("user")) or None,
+        settings.get("user") or "not set",
+        None if settings.get("user") else "Memory calls need --user or a stored default.",
+    )
+
+    if api is not None:
+        started = time.monotonic()
+        try:
+            api.current_plan()
+            add("api reachable", True, f"{settings['base_url']} in {int((time.monotonic() - started) * 1000)}ms")
+        except Exception as error:  # noqa: BLE001 - a diagnostic reports, never raises
+            add("api reachable", False, str(error), "Check the network, the base URL and the key.")
+    else:
+        add("api reachable", None, "skipped, no credential", "Store a key first.")
+
+    def render() -> str:
+        marks = {"pass": style.green("ok  "), "warn": style.yellow("warn"), "fail": style.red("fail")}
+        lines = []
+        for entry in checks:
+            lines.append(f"{marks[entry['status']]} {entry['check'].ljust(18)} {entry['detail']}")
+            if entry.get("hint"):
+                lines.append(f"     {style.dim(entry['hint'])}")
+        failures = sum(1 for entry in checks if entry["status"] == "fail")
+        summary = (
+            style.green("Everything checks out.")
+            if failures == 0
+            else style.yellow(f"{failures} check(s) need attention.")
+        )
+        return "\n".join([*lines, "", summary])
+
+    return {"data": checks, "text": render}
+
+
+def project(ctx: dict) -> dict:
+    """List projects, or show the one in scope."""
+    positionals, api = ctx["positionals"], ctx["api"]
+    sub = positionals[0] if positionals else "list"
+
+    if sub not in {"list", "show"}:
+        raise usage_error(f'Unknown subcommand "{sub}".', "Try list or show.")
+
+    raw = api.projects()
+    entries = raw if isinstance(raw, list) else (raw or {}).get("projects") or []
+    projects = [
+        {
+            "id": entry.get("id") or entry.get("project_id"),
+            "name": entry.get("name"),
+            "tenant_id": entry.get("tenant_id"),
+            "is_default": entry.get("is_default"),
+        }
+        for entry in entries
+        if isinstance(entry, dict)
+    ]
+
+    if sub == "show":
+        current = ctx["settings"].get("project")
+        match = next((p for p in projects if p["id"] == current), None) or (
+            projects[0] if projects else None
+        )
+        return {
+            "data": match,
+            "text": lambda: (
+                "\n".join(f"{style.dim(k.ljust(12))} {v}" for k, v in (match or {}).items())
+                if match
+                else style.dim("No projects found.")
+            ),
+        }
+
+    def render() -> str:
+        if not projects:
+            return style.dim("No projects found.")
+        return render_table(
+            ["id", "name", "tenant", "default"],
+            [[p["id"], p["name"], p["tenant_id"], "yes" if p["is_default"] else ""] for p in projects],
+        )
+
+    return {"data": projects, "text": render}
+
+
+def event(ctx: dict) -> dict:
+    """Ingestion state for one memory.
+
+    Named `event` to match the Node CLI and Mem0, both of which use it for
+    background processing state.
+    """
+    from .memory import _numeric_id
+
+    positionals, api = ctx["positionals"], ctx["api"]
+    sub = positionals[0] if positionals else None
+
+    if sub != "status":
+        raise usage_error(
+            "Which event?",
+            "memorysync event status m_60632",
+        )
+    if len(positionals) < 2:
+        raise usage_error("Which memory?", "memorysync event status m_60632")
+
+    payload = api.memory_status(_numeric_id(positionals[1])) or {}
+
+    def render() -> str:
+        return "\n".join(
+            f"{style.dim(key.ljust(24))} {'-' if value is None else value}"
+            for key, value in payload.items()
+        )
+
+    return {"data": payload, "text": render}
+
+
+def config_command(ctx: dict) -> dict:
+    """Read and write the local config file.
+
+    ``set`` never accepts an api_key: keys go to the keychain through `init`, and
+    accepting one here would write a credential into a file people paste into bug
+    reports.
+    """
+    positionals = ctx["positionals"]
+    sub = positionals[0] if positionals else "show"
+
+    if sub == "show":
+        data = config_module.redacted()
+        return {
+            "data": data,
+            "text": lambda: "\n".join(
+                [
+                    f"{style.dim('path')} {data['path']}",
+                    *(
+                        f"{style.dim(('  ' + name).ljust(18))} "
+                        + ", ".join(f"{k}={v}" for k, v in entry.items())
+                        for name, entry in data["profiles"].items()
+                    ),
+                ]
+            ),
+        }
+
+    if sub == "get":
+        if len(positionals) < 2:
+            raise usage_error("Which key?", "memorysync config get user")
+        key = positionals[1]
+        settings = config_module.resolve(ctx["flags"])
+        value = settings.get(key)
+        return {"data": {key: value}, "text": lambda: "" if value is None else str(value)}
+
+    if sub == "set":
+        if len(positionals) < 3:
+            raise usage_error("What to set?", "memorysync config set user alice")
+        key, value = positionals[1], positionals[2]
+        if key in {"api_key", "apikey", "key"}:
+            raise usage_error(
+                "Keys are not stored in the config file.",
+                "Run `memorysync init --api-key <key>`; it goes to the OS keychain.",
+            )
+        allowed = {"user", "project", "base_url", "timeout"}
+        if key not in allowed:
+            raise usage_error(
+                f'Cannot set "{key}".',
+                f"One of: {', '.join(sorted(allowed))}.",
+            )
+
+        profile_name = ctx["settings"]["profile_name"]
+        data = config_module.load()
+        data.setdefault("profiles", {}).setdefault(profile_name, {})[key] = value
+        path = config_module.save(data)
+        return {
+            "data": {"profile": profile_name, key: value, "path": str(path)},
+            "text": lambda: f"{style.green('Set')} {key} = {value} in profile {profile_name}",
+        }
+
+    if sub == "path":
+        path = str(config_module.config_path())
+        return {"data": {"path": path}, "text": lambda: path}
+
+    raise usage_error(f'Unknown subcommand "{sub}".', "Try show, get, set or path.")