anona-memory 0.27.0__py3-none-any.whl

anona/__init__.py

@@ -0,0 +1,26 @@
+from .client import (
+    AnonaClient,
+    AnonaError,
+    RateLimit,
+    ReasonWithReceipt,
+    RetrieveResults,
+    RetrieveWithReceipt,
+)
+
+# `Anona` is what the TypeScript package calls its client, and the two SDKs
+# describing the same API under two different class names is a papercut every
+# reader of both pays. The Python name stays canonical — it is what every
+# existing import and every published example uses — and this is an alias, not
+# a rename, so nothing breaks either way round.
+Anona = AnonaClient
+
+__all__ = [
+    "Anona",
+    "AnonaClient",
+    "AnonaError",
+    "RateLimit",
+    "ReasonWithReceipt",
+    "RetrieveResults",
+    "RetrieveWithReceipt",
+]
+__version__ = "0.27.0"

anona/_record_outcome.py

@@ -0,0 +1,108 @@
+"""What a `record` response actually says happened.
+
+The API answers `201` for a write it accepted, and acceptance is not storage:
+extraction runs over the content and often produces nothing, which is a
+success with an empty result rather than an error. Roughly 44% of short,
+context-free statements come back that way. A caller that reads only the
+status code reports those as stored, which is silent data loss dressed as
+success.
+
+**The verdict is read off the ids, not off `status`** — the same decision the
+server makes, and for the server's own stated reason: the engine has no
+failure shape, so a status field has been wrong about this before and an
+`"stored"` that stored nothing is exactly the bug being guarded against. A
+guard that trusted the status would depend on the server-side fix for it
+being deployed everywhere, which is the one thing it cannot assume. `status:
+"nothing_extracted"` and empty ids always coincide, so believing the ids
+costs nothing and survives a deployment that predates the status.
+
+What the server IS believed about is the **wording**: `message` accompanies
+that status and carries measured advice about what to do, so it is shown
+verbatim where present and only restated here when absent.
+
+This lives on its own, outside `integrations.mcp`, for two reasons. That
+module imports FastMCP, which ships in the optional `[mcp]` extra, so the CLI
+cannot import from it without making an optional dependency mandatory. And
+the question "did this write store anything" has exactly one right answer, so
+the two surfaces that ask it must not each carry their own copy to drift.
+"""
+
+from __future__ import annotations
+
+# Said only when the server said nothing itself. The server sets `message` on
+# exactly this status and its wording is the one to show; this is for a
+# deployment that predates that field, so that an older server still produces
+# an explanation rather than a bare non-zero exit.
+NOTHING_EXTRACTED_FALLBACK = (
+    "Nothing was stored in space '{space_id}': no facts could be extracted from "
+    "that content. Short, context-free statements often extract to nothing — "
+    "re-record it with a sentence of context (what the thing is, or why it "
+    "matters), which usually fixes it."
+)
+
+# Statuses that mean extraction has not run yet, so there is no outcome to
+# report and no ids to name.
+_QUEUED_STATUSES = ("processing", "pending", "queued")
+
+
+def stored_ids(result: object) -> list[str]:
+    """The memory ids a write created, in the order the API returned them.
+
+    ``memory_ids`` is the full set: one item usually produces more than one
+    memory (the raw fact, plus any synthesis built on it), so the singular
+    ``memory_id`` could only ever name part of what happened. It is read as
+    the fallback for an older response that carries only the one.
+
+    Empty for a write that stored nothing **and** for one that is still
+    queued — the two are different outcomes, so ask :func:`is_queued` before
+    reading an empty list as nothing.
+    """
+    if not isinstance(result, dict):
+        return []
+    many = result.get("memory_ids")
+    if isinstance(many, list):
+        ids = [str(item) for item in many if item]
+        if ids:
+            return ids
+    one = result.get("memory_id")
+    return [str(one)] if one else []
+
+
+def is_queued(result: object) -> bool:
+    """Whether the write was accepted for background extraction.
+
+    A queued write has not run extraction yet, so it has no ids and no outcome
+    to report. Reporting it as empty would be wrong in the other direction.
+    """
+    if not isinstance(result, dict):
+        return False
+    return bool(result.get("job_id")) or result.get("status") in _QUEUED_STATUSES
+
+
+def stored_something(result: object) -> bool:
+    """Whether a record persisted a memory, read off the API response.
+
+    The ids decide. `status` is deliberately not consulted: see the module
+    docstring — a status field has been wrong about this, and the ids cannot
+    be. A non-dict is treated as stored: this is a guard against an unexpected
+    response shape, and inventing a failure the API did not report would be
+    worse than the thing it protects against.
+    """
+    if not isinstance(result, dict):
+        return True
+    return bool(stored_ids(result)) or is_queued(result)
+
+
+def nothing_extracted_message(result: object, space_id: str) -> str:
+    """Why nothing was stored, in the server's own words where it gave them.
+
+    The server sets `message` on exactly this outcome and it says what to do.
+    Preferring it means the advice can be improved server-side without a
+    client release, and it keeps this package from carrying another copy of
+    wording the server already owns.
+    """
+    if isinstance(result, dict):
+        message = result.get("message")
+        if isinstance(message, str) and message.strip():
+            return message.strip()
+    return NOTHING_EXTRACTED_FALLBACK.format(space_id=space_id)

anona/cli/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m anona.cli`: the same command as `anona-memory`."""
+
+import sys
+
+from .main import main
+
+sys.exit(main())

anona/cli/completion.py

@@ -0,0 +1,157 @@
+"""`anona-memory completion bash|zsh|fish`: a completion script generated from the parser.
+
+Install:
+    bash  anona-memory completion bash > ~/.local/share/bash-completion/completions/anona-memory
+    zsh   anona-memory completion zsh > "${fpath[1]}/_anona-memory"   (or eval it from ~/.zshrc)
+    fish  anona-memory completion fish > ~/.config/fish/completions/anona-memory.fish
+
+Generated, not hand-written, so a new verb or flag completes the moment it
+exists. Commands and flags complete; flag values do not, except where a flag
+has fixed choices (fish only) -- a filename is offered where nothing else
+fits.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from .introspect import Command, tree
+
+
+def _quote(text: str) -> str:
+    """Single-quoted for sh and fish: no expansion of any kind inside."""
+    return "'" + text.replace("'", "'\\''") + "'"
+
+
+def _paths(root: Command) -> list[Command]:
+    return root.walk()
+
+
+def _key(cmd: Command) -> str:
+    # The root's path is ["anona-memory"]; every other command's path starts at its own name.
+    return "" if cmd.path == ["anona-memory"] else " ".join(cmd.path)
+
+
+def _flags(cmd: Command, root: Command) -> list[str]:
+    flags = [f for o in cmd.options for f in o.flags]
+    # Global flags are accepted after any command too.
+    if cmd is not root:
+        flags += [f for o in root.options for f in o.flags if f != "--version"]
+    flags.append("--help")
+    return flags
+
+
+def bash(parser: argparse.ArgumentParser) -> str:
+    root = tree(parser)
+    children = []
+    options = []
+    for cmd in _paths(root):
+        key = _quote(_key(cmd))
+        if cmd.children:
+            children.append(f"    {key}) echo {_quote(' '.join(c.path[-1] for c in cmd.children))};;")
+        options.append(f"    {key}) echo {_quote(' '.join(_flags(cmd, root)))};;")
+    return "\n".join(
+        [
+            "# anona-memory completion for bash. Generated by `anona-memory completion bash`.",
+            "_anona_memory_children() {",
+            '  case "$1" in',
+            *children,
+            "  esac",
+            "}",
+            "_anona_memory_options() {",
+            '  case "$1" in',
+            *options,
+            "  esac",
+            "}",
+            "_anona_memory() {",
+            '  local cur="${COMP_WORDS[COMP_CWORD]}" path="" w i kids',
+            "  for ((i=1; i<COMP_CWORD; i++)); do",
+            '    w="${COMP_WORDS[i]}"',
+            '    case "$w" in -*) continue;; esac',
+            '    kids=" $(_anona_memory_children "$path") "',
+            '    if [[ "$kids" == *" $w "* ]]; then path="${path:+$path }$w"; fi',
+            "  done",
+            '  if [[ "$cur" == -* ]]; then',
+            '    COMPREPLY=( $(compgen -W "$(_anona_memory_options "$path")" -- "$cur") )',
+            "  else",
+            '    kids="$(_anona_memory_children "$path")"',
+            '    if [[ -n "$kids" ]]; then',
+            '      COMPREPLY=( $(compgen -W "$kids" -- "$cur") )',
+            "    else",
+            '      COMPREPLY=( $(compgen -f -- "$cur") )',
+            "    fi",
+            "  fi",
+            "}",
+            "complete -o default -F _anona_memory anona-memory",
+            "",
+        ]
+    )
+
+
+def zsh(parser: argparse.ArgumentParser) -> str:
+    # zsh runs the bash function through bashcompinit, which ships with zsh.
+    # One generator for two shells means the two cannot disagree.
+    return "\n".join(
+        [
+            "#compdef anona-memory",
+            "# anona-memory completion for zsh. Generated by `anona-memory completion zsh`.",
+            "autoload -U +X bashcompinit && bashcompinit",
+            bash(parser),
+        ]
+    )
+
+
+def fish(parser: argparse.ArgumentParser) -> str:
+    root = tree(parser)
+    lines = ["# anona-memory completion for fish. Generated by `anona-memory completion fish`.", "complete -c anona-memory -f"]
+    top = " ".join(c.path[0] for c in root.children)
+    for cmd in root.children:
+        lines.append(
+            f"complete -c anona-memory -n {_quote('not __fish_seen_subcommand_from ' + top)} "
+            f"-a {_quote(cmd.path[0])} -d {_quote(cmd.help[:80])}"
+        )
+    for opt in root.options:
+        lines.extend(_fish_option(opt, None))
+    for cmd in root.walk():
+        if cmd is root:
+            continue
+        cond = " ; and ".join(f"__fish_seen_subcommand_from {p}" for p in cmd.path)
+        if cmd.children:
+            kids = " ".join(c.path[-1] for c in cmd.children)
+            for child in cmd.children:
+                lines.append(
+                    f"complete -c anona-memory -n {_quote(cond + ' ; and not __fish_seen_subcommand_from ' + kids)} "
+                    f"-a {_quote(child.path[-1])} -d {_quote(child.help[:80])}"
+                )
+        for opt in cmd.options:
+            lines.extend(_fish_option(opt, cond))
+        if any(p.name in ("PATHS", "PATH") or "path" in p.help.lower() or "file" in p.help.lower() for p in cmd.positionals):
+            lines.append(f"complete -c anona-memory -n {_quote(cond)} -F")
+    return "\n".join(lines) + "\n"
+
+
+def _fish_option(opt, cond: str | None) -> list[str]:
+    out = []
+    for flag in opt.flags:
+        if flag.startswith("--"):
+            spec = f"-l {_quote(flag[2:])}"
+        elif flag.startswith("-") and len(flag) == 2:
+            spec = f"-s {_quote(flag[1:])}"
+        else:
+            continue
+        line = "complete -c anona-memory"
+        if cond:
+            line += f" -n {_quote(cond)}"
+        line += f" {spec}"
+        if opt.takes_value:
+            line += " -r"
+            if opt.choices:
+                line += f" -a {_quote(' '.join(opt.choices))}"
+        if opt.help:
+            line += f" -d {_quote(opt.help[:80])}"
+        out.append(line)
+    return out
+
+
+def script(parser: argparse.ArgumentParser, shell: str) -> str:
+    return {"bash": bash, "zsh": zsh, "fish": fish}[shell](parser)

anona/cli/config_env.py

@@ -0,0 +1,75 @@
+"""`~/.anona/config.env`, read as data.
+
+The skill installer (`skills/install.sh`) writes this file for the agent skill
+and for `anona-memory-mcp`: `NAME='value'` lines, single-quoted, with a quote inside a
+value written as '\\''. It is meant to be sourceable by a shell, which is
+exactly why it must never be sourced or executed here: a value is whatever the
+installer was given, and a hand-edited line can hold `$(...)` or backticks.
+So it is parsed the way the installer's own `read_config` parses it -- the
+three names below and nothing else, quoted or unquoted, never expanded.
+
+Separate from `credentials.json` (store.py): this holds an API key, which the
+REST API accepts, and `anona-memory logout` never touches it.
+"""
+
+from __future__ import annotations
+
+import stat
+import sys
+from pathlib import Path
+
+NAMES = ("ANONA_API_KEY", "ANONA_SPACE_ID", "ANONA_BASE_URL")
+
+
+def path() -> Path:
+    # The active profile's (store.anona_dir): ~/.anona/config.env by default.
+    from . import store
+
+    return store.anona_dir() / "config.env"
+
+
+def _unquote(value: str) -> str:
+    # The installer's `shq`: the whole value in single quotes, each embedded
+    # quote as '\''. Older installers wrote it unquoted, which is taken as is.
+    if len(value) >= 2 and value.startswith("'") and value.endswith("'"):
+        return value[1:-1].replace("'\\''", "'")
+    return value
+
+
+def parse(text: str) -> dict[str, str]:
+    """The recognised names in `text`. The first assignment of a name wins,
+    as in the installer's reader; an empty value counts as absent."""
+    found: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.rstrip("\r")
+        if line.startswith("export "):
+            line = line[len("export "):]
+        name, sep, value = line.partition("=")
+        if not sep or name not in NAMES or name in found:
+            continue
+        value = _unquote(value)
+        if value:
+            found[name] = value
+    return found
+
+
+def load() -> dict[str, str]:
+    """The recognised names in config.env, or {} when there is no file.
+
+    Warns on stderr -- naming the file, never a value -- when the file is
+    readable by anyone but its owner: it holds a key with full data-plane
+    reach. The installer writes it 600; this catches a hand-made copy.
+    """
+    p = path()
+    try:
+        text = p.read_text(encoding="utf-8", errors="replace")
+        mode = p.stat().st_mode
+    except OSError:
+        return {}
+    if mode & (stat.S_IRWXG | stat.S_IRWXO):
+        print(
+            f"anona-memory: warning: {p} is readable by other users; "
+            f"run `chmod 600 {p}`.",
+            file=sys.stderr,
+        )
+    return parse(text)

anona/cli/credential.py

@@ -0,0 +1,77 @@
+"""Which API key `record`, `retrieve` and `reason` use, and where it came from.
+
+Highest first: `--api-key`, then ANONA_API_KEY in the environment, then
+ANONA_API_KEY in ~/.anona/config.env. With none of them the verbs fall back to
+the command-line login (`anona-memory login --cli`), then to the stored
+temporary-profile token; memory._token_and_space owns that half.
+
+The MCP login is never one of these. It is MCP-scoped (`typ=mcp_access`) and
+the REST API refuses it by design; MCP and the CLI's data verbs hold separate
+credentials on purpose.
+
+The source travels with the key because it decides where the key may be sent
+(target.for_api_key) and is what `anona-memory status` names. The key itself is
+never printed: `display()` is the only form that reaches output.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+
+_PREFIXES = ("anona_live_", "anona_test_")
+
+
+@dataclass(frozen=True)
+class ApiKey:
+    key: str = field(repr=False)
+    source: str  # "flag", "env" or "config.env"
+
+    def display(self) -> str:
+        """The key's prefix and a few characters, never enough to use it."""
+        for prefix in _PREFIXES:
+            if self.key.startswith(prefix):
+                rest = self.key[len(prefix):]
+                # A short key would give away a large share of itself.
+                return prefix + (rest[:4] if len(rest) >= 16 else "") + "…"
+        return (self.key[:4] if len(self.key) >= 24 else "") + "…"
+
+
+def find_api_key(flag: str | None, config: dict[str, str]) -> ApiKey | None:
+    if flag:
+        return ApiKey(flag, "flag")
+    env = os.environ.get("ANONA_API_KEY")
+    if env:
+        return ApiKey(env, "env")
+    from_file = config.get("ANONA_API_KEY")
+    if from_file:
+        return ApiKey(from_file, "config.env")
+    return None
+
+
+def find_base_url(flag: str | None, config: dict[str, str]) -> tuple[str | None, str | None]:
+    """(base URL, its source), or (None, None) when nothing names one."""
+    if flag:
+        return flag, "flag"
+    env = os.environ.get("ANONA_BASE_URL")
+    if env:
+        return env, "env"
+    from_file = config.get("ANONA_BASE_URL")
+    if from_file:
+        return from_file, "config.env"
+    return None, None
+
+
+def find_space(flag: str | None, config: dict[str, str]) -> str | None:
+    return flag or os.environ.get("ANONA_SPACE_ID") or config.get("ANONA_SPACE_ID") or None
+
+
+# Anything shaped like an Anona credential, wherever it turns up in text we
+# did not write -- argparse echoes unrecognised arguments verbatim, so
+# `anona-memory start --api-key <key>` would otherwise print the key back.
+_CREDENTIAL = re.compile(r"\b(anona_(?:live|test|tmp)_)[A-Za-z0-9_\-]+")
+
+
+def redact(text: str) -> str:
+    return _CREDENTIAL.sub(lambda m: m.group(1) + "…", text)