memory-passport 0.2.0__py3-none-any.whl

memory_passport/__init__.py

@@ -0,0 +1,8 @@
+"""memory-passport: a portable, plain-text format for AI assistant memory."""
+
+from memory_passport.model import Fact, MemoryFile, Vault
+
+SPEC_VERSION = "0.1"
+__version__ = "0.2.0"
+
+__all__ = ["SPEC_VERSION", "Fact", "MemoryFile", "Vault", "__version__"]

memory_passport/cli.py

@@ -0,0 +1,383 @@
+"""``passport`` command-line interface."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from memory_passport import __version__
+
+app = typer.Typer(
+    name="passport",
+    help="Portable AI assistant memory: validate, import, export, merge and diff vaults.",
+    no_args_is_help=True,
+    rich_markup_mode=None,
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"memory-passport {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show version.")
+    ] = False,
+) -> None:
+    """memory-passport CLI."""
+
+
+@app.command()
+def validate(
+    vault: Annotated[Path, typer.Argument(help="Vault directory to check.")],
+    strict: Annotated[bool, typer.Option(help="Treat warnings as failures.")] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Machine-readable output.")] = False,
+    stale: Annotated[
+        int | None,
+        typer.Option(help="Warn about observed/inferred facts older than this many days."),
+    ] = None,
+) -> None:
+    """Check a vault against the spec. Exit code 1 on errors (or warnings with --strict)."""
+    from memory_passport.validate import validate_vault
+
+    report = validate_vault(vault, stale_days=stale)
+    if as_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "root": str(report.root),
+                    "files": report.file_count,
+                    "facts": report.fact_count,
+                    "ok": report.ok(strict=strict),
+                    "issues": [i.__dict__ for i in report.issues],
+                },
+                indent=2,
+            )
+        )
+    else:
+        for issue in report.issues:
+            typer.echo(str(issue))
+        summary = (
+            f"{report.file_count} file(s), {report.fact_count} fact(s), "
+            f"{len(report.errors)} error(s), {len(report.warnings)} warning(s)"
+        )
+        typer.echo(("OK  " if report.ok(strict=strict) else "FAIL  ") + summary)
+    raise typer.Exit(code=0 if report.ok(strict=strict) else 1)
+
+
+@app.command("import")
+def import_(
+    source: Annotated[Path, typer.Argument(help="Export file, folder or pasted memory text.")],
+    from_: Annotated[
+        str | None, typer.Option("--from", help="Importer name (see `passport importers`).")
+    ] = None,
+    out: Annotated[Path, typer.Option("--out", "-o", help="Vault directory to write.")] = Path(
+        "passport"
+    ),
+    memory_text: Annotated[
+        Path | None, typer.Option(help="Extra pasted-memory file to combine with the export.")
+    ] = None,
+    route: Annotated[
+        bool, typer.Option(help="Sort facts into people/topics/areas/preferences.")
+    ] = True,
+    allow_health: Annotated[
+        bool, typer.Option(help="Keep health facts and mark the vault as opted in.")
+    ] = False,
+    force: Annotated[bool, typer.Option(help="Write into a non-empty directory.")] = False,
+) -> None:
+    """Build a passport vault from a product's export."""
+    from memory_passport.importers import ImportOptions, get_importer, list_importers
+    from memory_passport.model import VaultError, write_vault
+
+    if not source.exists():
+        typer.echo(f"error: {source} does not exist", err=True)
+        raise typer.Exit(2)
+    if from_ is None:
+        matches = [n for n, cls in list_importers().items() if cls().detect(source)]
+        if len(matches) != 1:
+            typer.echo(
+                f"error: could not tell which importer to use ({', '.join(matches) or 'none'} "
+                "matched); pass --from",
+                err=True,
+            )
+            raise typer.Exit(2)
+        from_ = matches[0]
+    try:
+        importer = get_importer(from_)
+    except KeyError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from None
+    if out.exists() and any(out.iterdir()) and not force:
+        typer.echo(f"error: {out} is not empty; pass --force to write into it", err=True)
+        raise typer.Exit(2)
+    opts = ImportOptions(route=route, allow_health=allow_health, memory_text=memory_text)
+    try:
+        result = importer.load(source, opts)
+    except VaultError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from None
+    write_vault(result.vault, out)
+    for n in result.notes:
+        typer.echo(f"  {n}")
+    for cat, text in result.dropped:
+        typer.echo(f"  dropped ({cat}): {text[:60]}{'…' if len(text) > 60 else ''}")
+    for _, text in result.redacted:
+        typer.echo(f"  redacted: {text[:60]}{'…' if len(text) > 60 else ''}")
+    typer.echo(f"wrote {len(result.vault.files)} file(s), {result.fact_count} fact(s) to {out}")
+
+
+@app.command()
+def export(
+    vault: Annotated[Path, typer.Argument(help="Vault directory.")],
+    to: Annotated[str, typer.Option("--to", help="Exporter name (see `passport exporters`).")],
+    out: Annotated[
+        Path | None,
+        typer.Option(
+            "--out",
+            "-o",
+            help="File or folder to write; default prints or uses the exporter's name.",
+        ),
+    ] = None,
+) -> None:
+    """Render a vault as the text or files a product accepts."""
+    from memory_passport.exporters import get_exporter
+    from memory_passport.model import VaultError, load_vault
+
+    try:
+        exporter = get_exporter(to)
+        v = load_vault(vault)
+    except (KeyError, VaultError) as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from None
+    result = exporter.render(v)
+    for n in result.notes:
+        typer.echo(f"note: {n}", err=True)
+    if result.single is not None and "-" in result.files:
+        if out is None:
+            typer.echo(result.single, nl=False)
+        else:
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_text(result.single, encoding="utf-8")
+            typer.echo(f"wrote {out}", err=True)
+        return
+    target = out or Path(exporter.default_out)
+    target.mkdir(parents=True, exist_ok=True)
+    for rel, content in result.files.items():
+        p = target / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+    typer.echo(f"wrote {len(result.files)} file(s) to {target}", err=True)
+
+
+@app.command()
+def merge(
+    vault_a: Annotated[Path, typer.Argument()],
+    vault_b: Annotated[Path, typer.Argument()],
+    out: Annotated[
+        Path, typer.Option("--out", "-o", help="Directory for the merged vault.")
+    ] = Path("merged"),
+    force: Annotated[bool, typer.Option(help="Write into a non-empty directory.")] = False,
+) -> None:
+    """Merge two vaults. Disagreements get conflict markers; nothing is resolved silently."""
+    from memory_passport.merge import merge_dirs
+    from memory_passport.model import VaultError, write_vault
+
+    if out.exists() and any(out.iterdir()) and not force:
+        typer.echo(f"error: {out} is not empty; pass --force to write into it", err=True)
+        raise typer.Exit(2)
+    try:
+        merged, report = merge_dirs(vault_a, vault_b)
+    except VaultError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from None
+    write_vault(merged, out)
+    typer.echo(f"merged {report.files} file(s), {report.facts} fact(s) into {out}")
+    for path, what in report.conflicts:
+        typer.echo(f"  CONFLICT {path}: {what}")
+    if report.conflicts:
+        typer.echo(
+            f"{len(report.conflicts)} conflict(s) need a human; "
+            "the vault will not validate until resolved"
+        )
+        raise typer.Exit(3)
+
+
+@app.command()
+def diff(
+    vault_a: Annotated[Path, typer.Argument()],
+    vault_b: Annotated[Path, typer.Argument()],
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Show what changed between two vaults, fact by fact. Exit code 1 if they differ."""
+    from memory_passport.diff import diff_dirs
+    from memory_passport.model import VaultError
+
+    try:
+        d = diff_dirs(vault_a, vault_b)
+    except VaultError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from None
+    if as_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "only_a": [str(p) for p in d.only_a],
+                    "only_b": [str(p) for p in d.only_b],
+                    "changed": [
+                        {
+                            "path": str(fd.path),
+                            "added": [f.render() for f in fd.added],
+                            "removed": [f.render() for f in fd.removed],
+                            "retagged": [[a.tag, b.tag, b.text] for a, b in fd.retagged],
+                            "frontmatter": {k: list(v) for k, v in fd.frontmatter.items()},
+                        }
+                        for fd in d.changed
+                    ],
+                },
+                indent=2,
+                default=str,
+            )
+        )
+    else:
+        typer.echo(d.render(), nl=False)
+    raise typer.Exit(0 if d.empty else 1)
+
+
+@app.command()
+def show(
+    vault: Annotated[Path, typer.Argument(help="Vault directory.")],
+    subject: Annotated[
+        str | None, typer.Argument(help="profile, preferences, people/<slug>, a kind, or a name.")
+    ] = None,
+    query: Annotated[str | None, typer.Option("--query", "-q", help="Words to search for.")] = None,
+) -> None:
+    """Print a vault's subjects, one subject, or the facts matching a query."""
+    from memory_passport.model import VaultError, load_vault
+    from memory_passport.store import render_file, render_subjects, search
+
+    try:
+        v = load_vault(vault)
+    except VaultError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from None
+    if query:
+        hits = search(v, query, subject)
+        for mf, f in hits:
+            typer.echo(f"{mf.path}: {f.render()}")
+        typer.echo(f"{len(hits)} fact(s)", err=True)
+        raise typer.Exit(0 if hits else 1)
+    if subject is None:
+        typer.echo(render_subjects(v), nl=False)
+        return
+    matches = [mf for mf in v.files if _matches(mf, subject)]
+    if not matches:
+        typer.echo(f"error: no subject matches '{subject}'", err=True)
+        raise typer.Exit(1)
+    for mf in matches:
+        typer.echo(render_file(mf))
+
+
+def _matches(mf, subject: str) -> bool:
+    from memory_passport.store import _file_matches
+
+    return _file_matches(mf, subject)
+
+
+@app.command()
+def add(
+    vault: Annotated[Path, typer.Argument(help="Vault directory.")],
+    text: Annotated[str, typer.Argument(help="The fact, one sentence.")],
+    to: Annotated[
+        str | None,
+        typer.Option(
+            "--to",
+            help=(
+                "profile, preferences, people/<slug>, person:<Name>, topic:<Name>, "
+                "area:<Name>. Default: routed from the text."
+            ),
+        ),
+    ] = None,
+    tag: Annotated[str, typer.Option(help="stated, observed or inferred.")] = "stated",
+    section: Annotated[str, typer.Option(help="## heading to file it under.")] = "",
+) -> None:
+    """Append one fact to a vault, dated today, with exclusions applied."""
+    from memory_passport.model import VaultError
+    from memory_passport.store import add_fact
+
+    if tag not in ("stated", "observed", "inferred"):
+        typer.echo("error: --tag must be stated, observed or inferred", err=True)
+        raise typer.Exit(2)
+    try:
+        r = add_fact(vault, text, subject=to, tag=tag, section=section)  # type: ignore[arg-type]
+    except VaultError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from None
+    if r.dropped:
+        typer.echo(
+            f"refused: looks like {r.dropped}, which the spec excludes (SPEC.md §7)", err=True
+        )
+        raise typer.Exit(1)
+    if r.duplicate:
+        typer.echo(f"already in {r.path}; nothing written")
+        return
+    typer.echo(f"{'created' if r.created_file else 'updated'} {r.path}: {r.fact.render()}")
+    if r.redacted:
+        typer.echo("  a sensitive span was redacted", err=True)
+
+
+@app.command()
+def forget(
+    vault: Annotated[Path, typer.Argument(help="Vault directory.")],
+    text: Annotated[str, typer.Argument(help="The fact to remove (matched loosely).")],
+) -> None:
+    """Remove a fact from a vault by its text."""
+    from memory_passport.store import remove_fact
+
+    removed = remove_fact(vault, text)
+    if not removed:
+        typer.echo("nothing matched", err=True)
+        raise typer.Exit(1)
+    for p, n in removed:
+        typer.echo(f"removed {p}:{n}")
+
+
+@app.command()
+def inspect(
+    source: Annotated[Path, typer.Argument(help="An export zip, folder or file.")],
+) -> None:
+    """Report what an export contains, without importing it. Paste the output into bug reports."""
+    from memory_passport.inspect_export import inspect_path
+
+    if not source.exists():
+        typer.echo(f"error: {source} does not exist", err=True)
+        raise typer.Exit(2)
+    for line in inspect_path(source):
+        typer.echo(line)
+
+
+@app.command()
+def importers() -> None:
+    """List available importers (built-in and plugins)."""
+    from memory_passport.importers import list_importers
+
+    for name, cls in list_importers().items():
+        typer.echo(f"{name:12} {cls.help}")
+
+
+@app.command()
+def exporters() -> None:
+    """List available exporters (built-in and plugins)."""
+    from memory_passport.exporters import list_exporters
+
+    for name, cls in list_exporters().items():
+        typer.echo(f"{name:12} {cls.help}")
+
+
+if __name__ == "__main__":
+    app()

memory_passport/diff.py

@@ -0,0 +1,81 @@
+"""Compare two vaults fact by fact."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+
+from memory_passport.model import Fact, Vault, load_vault
+
+
+@dataclass
+class FileDiff:
+    path: PurePosixPath
+    added: list[Fact] = field(default_factory=list)
+    removed: list[Fact] = field(default_factory=list)
+    retagged: list[tuple[Fact, Fact]] = field(default_factory=list)
+    frontmatter: dict[str, tuple[object, object]] = field(default_factory=dict)
+
+    @property
+    def empty(self) -> bool:
+        return not (self.added or self.removed or self.retagged or self.frontmatter)
+
+
+@dataclass
+class VaultDiff:
+    only_a: list[PurePosixPath]
+    only_b: list[PurePosixPath]
+    changed: list[FileDiff]
+
+    @property
+    def empty(self) -> bool:
+        return not (self.only_a or self.only_b or self.changed)
+
+    def render(self) -> str:
+        out: list[str] = []
+        for p in self.only_a:
+            out.append(f"--- {p} (only in a)")
+        for p in self.only_b:
+            out.append(f"+++ {p} (only in b)")
+        for fd in self.changed:
+            out.append(f"=== {fd.path}")
+            for k, (a, b) in fd.frontmatter.items():
+                out.append(f"  ~ {k}: {a!r} -> {b!r}")
+            for f in fd.removed:
+                out.append(f"  - [{f.tag}] {f.text}")
+            for f in fd.added:
+                out.append(f"  + [{f.tag}] {f.text}")
+            for a, b in fd.retagged:
+                out.append(f"  ~ [{a.tag}] -> [{b.tag}] {b.text}")
+        return "\n".join(out) + ("\n" if out else "no differences\n")
+
+
+_IGNORED = {"updated"}
+
+
+def diff_vaults(a: Vault, b: Vault) -> VaultDiff:
+    fa = {f.path: f for f in a.files}
+    fb = {f.path: f for f in b.files}
+    changed: list[FileDiff] = []
+    for p in sorted(fa.keys() & fb.keys()):
+        fd = FileDiff(p)
+        ka = {f.key: f for f in fa[p].facts}
+        kb = {f.key: f for f in fb[p].facts}
+        fd.removed = [ka[k] for k in ka if k not in kb]
+        fd.added = [kb[k] for k in kb if k not in ka]
+        fd.retagged = [(ka[k], kb[k]) for k in ka if k in kb and ka[k].tag != kb[k].tag]
+        for key in sorted((set(fa[p].frontmatter) | set(fb[p].frontmatter)) - _IGNORED):
+            va, vb = fa[p].frontmatter.get(key), fb[p].frontmatter.get(key)
+            if isinstance(va, list) and isinstance(vb, list) and set(va) == set(vb):
+                continue
+            if va != vb:
+                fd.frontmatter[key] = (va, vb)
+        if not fd.empty:
+            changed.append(fd)
+    return VaultDiff(
+        only_a=sorted(fa.keys() - fb.keys()), only_b=sorted(fb.keys() - fa.keys()), changed=changed
+    )
+
+
+def diff_dirs(a: Path, b: Path) -> VaultDiff:
+    return diff_vaults(load_vault(a), load_vault(b))

memory_passport/exclusions.py

@@ -0,0 +1,137 @@
+"""Detectors for categories the spec excludes from a passport by default.
+
+Detection is deliberately conservative and heuristic: it exists to stop the
+obvious cases (a card number pasted into a fact line) rather than to be a
+complete data-loss-prevention system. See SPEC.md §7 for the rationale.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+Category = Literal["card-number", "bank-account", "government-id", "secret", "health"]
+
+
+@dataclass(frozen=True)
+class Hit:
+    category: Category
+    detail: str
+
+
+def _luhn_ok(digits: str) -> bool:
+    total, parity = 0, len(digits) % 2
+    for i, ch in enumerate(digits):
+        d = int(ch)
+        if i % 2 == parity:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return total % 10 == 0
+
+
+def _iban_ok(s: str) -> bool:
+    s = s.upper()
+    rearranged = s[4:] + s[:4]
+    numeric = "".join(str(ord(c) - 55) if c.isalpha() else c for c in rearranged)
+    return int(numeric) % 97 == 1
+
+
+_CARD_RE = re.compile(r"(?<![\d-])(?:\d[ -]?){12,18}\d(?![\d-])")
+_IBAN_RE = re.compile(r"\b[A-Z]{2}\d{2}(?:[ ]?[A-Z0-9]{4}){2,7}[ ]?[A-Z0-9]{1,4}\b")
+_UK_SORT_ACCT_RE = re.compile(r"\b\d{2}-\d{2}-\d{2}\b[^\n]{0,20}\b\d{8}\b")
+_US_SSN_RE = re.compile(r"\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b")
+_UK_NINO_RE = re.compile(
+    r"\b(?!BG|GB|NK|KN|TN|NT|ZZ)[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z]\s?\d{2}\s?\d{2}\s?\d{2}\s?[A-D]\b"
+)
+_ID_KEYWORD_RE = re.compile(
+    r"\b(passport|national insurance|social security|driving licence|driver'?s licen[cs]e|"
+    r"nhs|aadhaar|pan card|tax id|ssn|nino)\b\s*(number|no\.?|#|:)?\s*(is\s+)?[:#]?\s*"
+    r"((?=[A-Z -]*\d)[A-Z0-9][A-Z0-9 -]{5,})",
+    re.IGNORECASE,
+)
+_SECRET_RE = re.compile(
+    r"(sk-(?:proj-|ant-)?[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{30,}|"
+    r"xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35}|-----BEGIN [A-Z ]*PRIVATE KEY-----)"
+)
+_PASSWORD_RE = re.compile(
+    r"\b(password|passcode|pin)\b\s*(is|:|=)\s*(?!\[redacted)\S+", re.IGNORECASE
+)
+
+_HEALTH_CONDITIONS = (
+    "adhd|autism|autistic|anxiety disorder|depression|depressive|bipolar|schizophreni|ptsd|ocd|"
+    "eating disorder|anorexi|bulimi|diabet|cancer|tumour|tumor|hiv|aids|hepatitis|epilep|"
+    "asthma|crohn|coeliac|celiac|arthritis|fibromyalgia|dementia|alzheimer|parkinson|"
+    "multiple sclerosis|chronic fatigue|long covid|hypertension|heart disease|stroke|"
+    "pregnan|miscarriage|infertil|erectile|std|sti|herpes|chlamydia"
+)
+_HEALTH_RE = re.compile(
+    r"\b(diagnos(?:ed|is)|prescri(?:bed|ption)|medication|antidepressant|therapist|psychiatrist|"
+    r"\d+\s?mg\b|" + _HEALTH_CONDITIONS + r")",
+    re.IGNORECASE,
+)
+
+
+REDACTABLE: tuple[Category, ...] = ("card-number", "bank-account", "government-id", "secret")
+
+
+def redact(text: str, *, allow_health: bool = False) -> tuple[str, list[Hit]]:
+    """Replace every redactable span with ``[redacted <category>]``.
+
+    Returns the new text and the hits that could *not* be redacted (currently only
+    ``health``, which is a topic rather than a token and so must be dropped instead).
+    """
+    out = text
+    for m in list(_CARD_RE.finditer(out))[::-1]:
+        digits = re.sub(r"\D", "", m.group())
+        if 13 <= len(digits) <= 19 and _luhn_ok(digits):
+            out = out[: m.start()] + "[redacted card-number]" + out[m.end() :]
+    for m in list(_IBAN_RE.finditer(out))[::-1]:
+        compact = m.group().replace(" ", "")
+        if 15 <= len(compact) <= 34 and _iban_ok(compact):
+            out = out[: m.start()] + "[redacted bank-account]" + out[m.end() :]
+    out = _UK_SORT_ACCT_RE.sub("[redacted bank-account]", out)
+    out = _US_SSN_RE.sub("[redacted government-id]", out)
+    out = _UK_NINO_RE.sub("[redacted government-id]", out)
+    out = _ID_KEYWORD_RE.sub(
+        lambda m: m.group(0)[: m.start(4) - m.start(0)] + "[redacted government-id]", out
+    )
+    out = _SECRET_RE.sub("[redacted secret]", out)
+    out = _PASSWORD_RE.sub(lambda m: f"{m.group(1)} {m.group(2)} [redacted secret]", out)
+    return out, scan(out, allow_health=allow_health)
+
+
+def scan(text: str, *, allow_health: bool = False) -> list[Hit]:
+    """Return every exclusion hit in ``text``. Empty list means clean."""
+    hits: list[Hit] = []
+
+    for m in _CARD_RE.finditer(text):
+        digits = re.sub(r"\D", "", m.group())
+        if 13 <= len(digits) <= 19 and _luhn_ok(digits):
+            hits.append(Hit("card-number", f"Luhn-valid {len(digits)}-digit number"))
+
+    for m in _IBAN_RE.finditer(text):
+        compact = m.group().replace(" ", "")
+        if 15 <= len(compact) <= 34 and _iban_ok(compact):
+            hits.append(Hit("bank-account", f"IBAN starting {compact[:4]}"))
+    if _UK_SORT_ACCT_RE.search(text):
+        hits.append(Hit("bank-account", "UK sort code with account number"))
+
+    if _US_SSN_RE.search(text):
+        hits.append(Hit("government-id", "US social security number pattern"))
+    if _UK_NINO_RE.search(text):
+        hits.append(Hit("government-id", "UK national insurance number pattern"))
+    for m in _ID_KEYWORD_RE.finditer(text):
+        hits.append(Hit("government-id", f"'{m.group(1)}' followed by an identifier"))
+
+    if _SECRET_RE.search(text):
+        hits.append(Hit("secret", "API key or private key pattern"))
+    if m := _PASSWORD_RE.search(text):
+        hits.append(Hit("secret", f"'{m.group(1)}' with a value"))
+
+    if not allow_health and (m := _HEALTH_RE.search(text)):
+        hits.append(Hit("health", f"health term '{m.group(1)}'"))
+
+    return hits

memory_passport/exporters/__init__.py

@@ -0,0 +1,6 @@
+"""Exporters render a vault into what a product will accept."""
+
+from memory_passport.exporters.base import Exporter, ExportResult
+from memory_passport.exporters.registry import get_exporter, list_exporters
+
+__all__ = ["ExportResult", "Exporter", "get_exporter", "list_exporters"]

memory_passport/exporters/base.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from memory_passport.model import Fact, MemoryFile, Vault
+
+
+@dataclass
+class ExportResult:
+    files: dict[str, str]
+    """Relative path -> content. A single entry named ``-`` means "print to stdout"."""
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def single(self) -> str | None:
+        return next(iter(self.files.values())) if len(self.files) == 1 else None
+
+
+class Exporter(ABC):
+    name: ClassVar[str]
+    help: ClassVar[str] = ""
+    default_out: ClassVar[str] = "-"
+
+    @abstractmethod
+    def render(self, vault: Vault) -> ExportResult: ...
+
+
+def fact_sentence(fact: Fact, *, hedge: bool = True) -> str:
+    """A fact as plain prose for products with no provenance. Inferred facts are hedged."""
+    if hedge and fact.tag == "inferred":
+        return f"Possibly: {fact.text}"
+    if hedge and fact.tag == "observed":
+        return f"Observed: {fact.text}"
+    return fact.text
+
+
+def ordered(vault: Vault) -> list[MemoryFile]:
+    order = {"profile": 0, "preferences": 1, "person": 2, "area": 3, "topic": 4}
+    return sorted(vault.files, key=lambda f: (order.get(f.kind or "", 9), str(f.path)))