highhxpack 0.1.0__py3-none-any.whl

highhxpack/__init__.py

@@ -0,0 +1,106 @@
+"""HighHXPack: a local-first memory and context engine for AI applications.
+
+Quick start::
+
+    from highhxpack import Memory
+
+    memory = Memory()
+    memory.remember("user_123", "I prefer Python for AI development.")
+    for result in memory.recall("user_123", "What language do I prefer for AI?"):
+        print(result.score, result.content)
+
+Everything importable from this module is public API and follows semantic
+versioning.  Submodules are internal unless documented otherwise.
+"""
+
+from highhxpack.__version__ import __version__
+from highhxpack.consolidation.conflict import ConflictPolicy
+from highhxpack.core.config import Config
+from highhxpack.core.memory import Memory
+from highhxpack.embeddings.base import EmbeddingProvider
+from highhxpack.embeddings.local import HashingEmbedding
+from highhxpack.embeddings.providers import CallableEmbedding
+from highhxpack.exceptions import (
+    ConfigurationError,
+    ConflictNotFoundError,
+    EmbeddingError,
+    ExportError,
+    ExtractionError,
+    HighHXPackError,
+    MemoryImportError,
+    MemoryNotFoundError,
+    MigrationError,
+    ProviderError,
+    ProviderNotAvailableError,
+    StorageError,
+    ValidationError,
+)
+from highhxpack.models import (
+    Conflict,
+    ConflictStatus,
+    ConsolidationReport,
+    EventKind,
+    ExportReport,
+    ImportReport,
+    MemoryEvent,
+    MemoryRecord,
+    MemoryStats,
+    MemoryStatus,
+    MemoryType,
+    RecallResult,
+    Relationship,
+    RememberAction,
+    RememberResult,
+    ScoreBreakdown,
+    UserSummary,
+)
+from highhxpack.providers.base import LLMProvider
+from highhxpack.providers.custom import CallableProvider
+from highhxpack.retrieval.ranking import ScoringConfig
+from highhxpack.retrieval.retriever import Strategy
+from highhxpack.storage.base import StorageBackend
+
+__all__ = [
+    "CallableEmbedding",
+    "CallableProvider",
+    "Config",
+    "ConfigurationError",
+    "Conflict",
+    "ConflictNotFoundError",
+    "ConflictPolicy",
+    "ConflictStatus",
+    "ConsolidationReport",
+    "EmbeddingError",
+    "EmbeddingProvider",
+    "EventKind",
+    "ExportError",
+    "ExportReport",
+    "ExtractionError",
+    "HashingEmbedding",
+    "HighHXPackError",
+    "ImportReport",
+    "LLMProvider",
+    "Memory",
+    "MemoryEvent",
+    "MemoryImportError",
+    "MemoryNotFoundError",
+    "MemoryRecord",
+    "MemoryStats",
+    "MemoryStatus",
+    "MemoryType",
+    "MigrationError",
+    "ProviderError",
+    "ProviderNotAvailableError",
+    "RecallResult",
+    "Relationship",
+    "RememberAction",
+    "RememberResult",
+    "ScoreBreakdown",
+    "ScoringConfig",
+    "StorageBackend",
+    "StorageError",
+    "Strategy",
+    "UserSummary",
+    "ValidationError",
+    "__version__",
+]

highhxpack/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m highhxpack``."""
+
+from highhxpack.cli.main import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()

highhxpack/__version__.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

highhxpack/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface.  The entry point is :func:`highhxpack.cli.main.main`."""

highhxpack/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommands.  Each module exposes ``register(subparsers, common)``."""

highhxpack/cli/commands/consolidate.py

@@ -0,0 +1,92 @@
+"""``highhxpack consolidate``, ``highhxpack conflicts`` and ``highhxpack resolve``."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from highhxpack.cli.context import EXIT_OK, Context
+from highhxpack.cli.display import format_time
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    consolidate = subparsers.add_parser(
+        "consolidate",
+        parents=[common],
+        help="merge duplicates, archive expired memories and apply the conflict policy",
+    )
+    consolidate.add_argument("--dry-run", action="store_true", help="show what would change")
+    consolidate.add_argument(
+        "--summarize", action="store_true", help="also add summaries of related memories"
+    )
+    consolidate.set_defaults(handler=run_consolidate)
+
+    conflicts = subparsers.add_parser(
+        "conflicts", parents=[common], help="list contradictory memories"
+    )
+    conflicts.add_argument("--all", action="store_true", help="include resolved conflicts")
+    conflicts.set_defaults(handler=run_conflicts)
+
+    resolve = subparsers.add_parser(
+        "resolve", parents=[common], help="resolve a conflict by choosing the memory to keep"
+    )
+    resolve.add_argument("conflict_id", help="conflict id (from `highhxpack conflicts`)")
+    resolve.add_argument("--keep", required=True, help="id or prefix of the memory to keep")
+    resolve.set_defaults(handler=run_resolve)
+
+
+def run_consolidate(args: argparse.Namespace, ctx: Context) -> int:
+    report = ctx.memory.consolidate(ctx.user, dry_run=args.dry_run, summarize=args.summarize)
+    console = ctx.console
+    if console.json_mode:
+        console.json(report.to_dict())
+        return EXIT_OK
+    if not report.actions:
+        console.info("Nothing to consolidate.")
+        return EXIT_OK
+    prefix = "Would " if report.dry_run else ""
+    for action in report.actions:
+        console.info(f"  {prefix}{action}" if prefix else f"  {action}")
+    console.success(
+        f"{'Planned' if report.dry_run else 'Done'}: {len(report.merged)} merged, "
+        f"{len(report.superseded)} superseded, {report.conflicts_detected} conflicts, "
+        f"{len(report.expired_archived)} expired archived, "
+        f"{len(report.summaries_created)} summaries."
+    )
+    return EXIT_OK
+
+
+def run_conflicts(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    conflicts = memory.conflicts(ctx.explicit_user, status=None if args.all else "open")
+    console = ctx.console
+    if console.json_mode:
+        console.json([c.to_dict() for c in conflicts])
+        return EXIT_OK
+    if not conflicts:
+        console.info("No conflicts." if args.all else "No open conflicts.")
+        return EXIT_OK
+    records = memory.storage.get_memories([i for c in conflicts for i in (c.memory_id, c.other_id)])
+    for c in conflicts:
+        newer, older = records.get(c.memory_id), records.get(c.other_id)
+        console.print(
+            console.style(f"{c.id}", "bold") + f"  {c.kind}  {c.status}  "
+            f"{format_time(c.created_at)}  user={c.user_id}"
+        )
+        if newer:
+            console.print(f"  newer {newer.short_id} [{newer.status}]: {newer.content}")
+        if older:
+            console.print(f"  older {older.short_id} [{older.status}]: {older.content}")
+        if c.resolution:
+            console.print(console.style(f"  {c.resolution}", "dim"))
+    return EXIT_OK
+
+
+def run_resolve(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    conflict = memory.resolve_conflict(args.conflict_id, keep=memory.resolve_id(args.keep))
+    if ctx.console.json_mode:
+        ctx.console.json(conflict.to_dict())
+    else:
+        ctx.console.success(f"Resolved: {conflict.resolution}")
+    return EXIT_OK

highhxpack/cli/commands/export.py

@@ -0,0 +1,34 @@
+"""``highhxpack export``."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from highhxpack.cli.context import EXIT_OK, Context
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    parser = subparsers.add_parser(
+        "export",
+        parents=[common],
+        help="export memories to a JSON file (all users unless --user is given)",
+        description="Write memories, history, relationships and conflicts to a JSON file "
+        "readable only by you.",
+    )
+    parser.add_argument("file", help="destination file, e.g. memories.json")
+    parser.add_argument("-f", "--force", action="store_true", help="overwrite an existing file")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace, ctx: Context) -> int:
+    report = ctx.memory.export(args.file, user_id=ctx.explicit_user, overwrite=args.force)
+    if ctx.console.json_mode:
+        ctx.console.json(report.to_dict())
+    else:
+        ctx.console.success(
+            f"Exported {report.memories} memories, {report.events} history events, "
+            f"{report.relationships} relationships and {report.conflicts} conflicts "
+            f"to {report.path}"
+        )
+    return EXIT_OK

highhxpack/cli/commands/forget.py

@@ -0,0 +1,75 @@
+"""``highhxpack forget`` and ``highhxpack restore``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from highhxpack.cli.context import EXIT_ERROR, EXIT_OK, Context
+from highhxpack.exceptions import ValidationError
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    forget = subparsers.add_parser(
+        "forget",
+        parents=[common],
+        help="archive (or permanently delete) a memory",
+        description="Archive a memory so it is no longer recalled; it stays in history and "
+        "can be restored. With --permanent the memory and its history are erased.",
+    )
+    forget.add_argument("memory_id", help="memory id or unique prefix (at least 4 characters)")
+    forget.add_argument("--permanent", action="store_true", help="erase instead of archiving")
+    forget.add_argument("-y", "--yes", action="store_true", help="do not ask for confirmation")
+    forget.set_defaults(handler=run_forget)
+
+    restore = subparsers.add_parser(
+        "restore",
+        parents=[common],
+        help="make an archived or superseded memory active again",
+    )
+    restore.add_argument("memory_id", help="memory id or unique prefix")
+    restore.set_defaults(handler=run_restore)
+
+
+def run_forget(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    memory_id = memory.resolve_id(args.memory_id)
+    record = memory.get(memory_id)
+    if args.permanent and not args.yes:
+        if not sys.stdin.isatty() or ctx.console.json_mode:
+            # Never erase data without an explicit confirmation.
+            raise ValidationError(
+                "Refusing to permanently erase a memory without confirmation.",
+                hint="Pass --yes to confirm when running non-interactively.",
+            )
+        answer = input(f"Permanently erase {record.short_id} ({record.content!r})? [y/N] ")
+        if answer.strip().lower() not in {"y", "yes"}:
+            ctx.console.info("Cancelled.")
+            return EXIT_ERROR
+    if args.permanent:
+        memory.delete(memory_id)
+        if ctx.console.json_mode:
+            ctx.console.json({"id": memory_id, "deleted": True})
+        else:
+            ctx.console.success(f"Erased {record.short_id}.")
+        return EXIT_OK
+    archived = memory.forget(memory_id)
+    if ctx.console.json_mode:
+        ctx.console.json(archived.to_dict())
+    else:
+        ctx.console.success(
+            f"Forgot {archived.short_id}. It is archived; undo with "
+            f"`highhxpack restore {archived.short_id}`."
+        )
+    return EXIT_OK
+
+
+def run_restore(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    restored = memory.restore(memory.resolve_id(args.memory_id))
+    if ctx.console.json_mode:
+        ctx.console.json(restored.to_dict())
+    else:
+        ctx.console.success(f"Restored {restored.short_id}: {restored.content}")
+    return EXIT_OK

highhxpack/cli/commands/import_.py

@@ -0,0 +1,46 @@
+"""``highhxpack import``."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from highhxpack.cli.context import EXIT_OK, Context
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    parser = subparsers.add_parser(
+        "import",
+        parents=[common],
+        help="import memories from a JSON export",
+        description="Import a file created by `highhxpack export`. Every record is validated; "
+        "invalid records are skipped and reported. With --user, all imported data is assigned "
+        "to that user.",
+    )
+    parser.add_argument("file", help="file created by `highhxpack export`")
+    parser.add_argument(
+        "--replace", action="store_true", help="replace memories whose id already exists"
+    )
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace, ctx: Context) -> int:
+    report = ctx.memory.import_(
+        args.file,
+        user_id=ctx.explicit_user,
+        on_existing="replace" if args.replace else "skip",
+    )
+    console = ctx.console
+    if console.json_mode:
+        console.json(report.to_dict())
+        return EXIT_OK
+    console.success(
+        f"Imported {report.imported} memories ({report.replaced} replaced, "
+        f"{report.skipped} skipped), {report.events} history events and "
+        f"{report.relationships} relationships."
+    )
+    for error in report.errors[:20]:
+        console.warn(error)
+    if len(report.errors) > 20:
+        console.warn(f"{console.sym('more')} {len(report.errors) - 20} more problems (use --json)")
+    return EXIT_OK

highhxpack/cli/commands/init.py

@@ -0,0 +1,84 @@
+"""``highhxpack init`` and ``highhxpack config``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Any
+
+from highhxpack.cli.context import EXIT_OK, Context
+from highhxpack.core.config import CONFIG_FILENAME, write_config_template
+from highhxpack.utils.validation import validate_path
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    init = subparsers.add_parser(
+        "init",
+        parents=[common],
+        help="create the data directory, configuration file and database",
+        description="Create the data directory, a commented configuration file and the "
+        "database. Safe to run more than once.",
+    )
+    init.add_argument("--force", action="store_true", help="overwrite an existing config file")
+    init.set_defaults(handler=run_init)
+
+    config = subparsers.add_parser(
+        "config",
+        parents=[common],
+        help="show the resolved configuration",
+        description="Show the effective configuration after applying the config file, "
+        "environment variables and command-line options. Secrets are masked.",
+    )
+    config.set_defaults(handler=run_config)
+
+
+def run_init(args: argparse.Namespace, ctx: Context) -> int:
+    created_config = False
+    # A config file requested with --config / $HIGHHXPACK_CONFIG may not exist yet:
+    # creating it is exactly what `init` is for.
+    requested = getattr(args, "config", None) or os.environ.get("HIGHHXPACK_CONFIG")
+    if requested:
+        target = validate_path(requested, field="config")
+        if not target.exists() or args.force:
+            write_config_template(target, overwrite=args.force)
+            created_config = True
+    config = ctx.config
+    config_path = config.config_file or config.home / CONFIG_FILENAME
+    if not requested and (not config_path.exists() or args.force):
+        write_config_template(config_path, overwrite=args.force)
+        created_config = True
+    memory = ctx.memory  # creates the database and applies migrations
+    data = {
+        "home": str(config.home),
+        "config_file": str(config_path),
+        "config_created": created_config,
+        "storage_path": memory.location,
+        "schema_version": memory.storage.schema_version,
+        "default_user": config.default_user,
+    }
+    if ctx.console.json_mode:
+        ctx.console.json(data)
+        return EXIT_OK
+    console = ctx.console
+    console.success("HighHXPack is ready.")
+    console.print(f"  config:   {config_path}" + ("" if created_config else " (existing, kept)"))
+    console.print(f"  database: {memory.location}")
+    console.print(f"  user:     {config.default_user}")
+    console.print()
+    console.print('Try:  highhxpack remember "I prefer Python for AI development"')
+    console.print('      highhxpack recall "programming language"')
+    return EXIT_OK
+
+
+def run_config(args: argparse.Namespace, ctx: Context) -> int:
+    data = ctx.config.to_dict(redact=True)
+    if ctx.console.json_mode:
+        ctx.console.json(data)
+        return EXIT_OK
+    scoring = data.pop("scoring")
+    for key, value in data.items():
+        ctx.console.print(f"{key:<18} {value if value is not None else '-'}")
+    ctx.console.print(ctx.console.style("scoring", "bold"))
+    for key, value in scoring.items():
+        ctx.console.print(f"  {key:<24} {value}")
+    return EXIT_OK

highhxpack/cli/commands/inspect.py

@@ -0,0 +1,99 @@
+"""``highhxpack inspect`` (a user) and ``highhxpack history`` (a memory)."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from highhxpack.cli.context import EXIT_OK, Context
+from highhxpack.cli.display import format_time
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    inspect = subparsers.add_parser(
+        "inspect",
+        parents=[common],
+        help="summarize everything stored for a user",
+    )
+    inspect.add_argument("user_id", nargs="?", help="user to inspect (default: current user)")
+    inspect.set_defaults(handler=run_inspect)
+
+    history = subparsers.add_parser(
+        "history",
+        aliases=["show"],
+        parents=[common],
+        help="show a memory and its change history",
+    )
+    history.add_argument("memory_id", help="memory id or unique prefix")
+    history.set_defaults(handler=run_history)
+
+
+def run_inspect(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    user = args.user_id or ctx.user
+    summary = memory.inspect(user)
+    edges = memory.graph.edges(user)
+    console = ctx.console
+    if console.json_mode:
+        console.json({**summary.to_dict(), "graph": [e.to_dict() for e in edges]})
+        return EXIT_OK
+    console.print(console.style(f"User {summary.user_id}", "bold"))
+    console.print(f"  memories:   {summary.active} active / {summary.total} total")
+    if summary.by_type:
+        types = ", ".join(f"{k} {v}" for k, v in summary.by_type.items())
+        console.print(f"  by type:    {types}")
+    if summary.by_status:
+        statuses = ", ".join(f"{k} {v}" for k, v in summary.by_status.items())
+        console.print(f"  by status:  {statuses}")
+    console.print(f"  conflicts:  {summary.open_conflicts} open")
+    console.print(
+        f"  first/last: {format_time(summary.first_memory_at)} / "
+        f"{format_time(summary.last_memory_at)}"
+    )
+    if edges:
+        console.print(console.style("Knowledge graph", "bold"))
+        for edge in edges[:50]:
+            arrow = f"{console.sym('dash')}{edge.relation}{console.sym('arrow')}"
+            console.print(f"  {edge.source} {arrow} {edge.target}")
+        if len(edges) > 50:
+            more = f"  {console.sym('more')} {len(edges) - 50} more (use --json)"
+            console.print(console.style(more, "dim"))
+    return EXIT_OK
+
+
+def run_history(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    record = memory.get(memory.resolve_id(args.memory_id))
+    events = memory.history(record.id)
+    console = ctx.console
+    if console.json_mode:
+        console.json({"memory": record.to_dict(), "history": [e.to_dict() for e in events]})
+        return EXIT_OK
+    console.print(console.style(record.id, "bold"))
+    console.print(f"  content:     {record.content}")
+    console.print(f"  user:        {record.user_id}")
+    console.print(f"  type/status: {record.memory_type} / {record.status}")
+    console.print(f"  importance:  {record.importance:.2f}   confidence: {record.confidence:.2f}")
+    console.print(
+        f"  version:     {record.version}   mentions: {record.mention_count}   "
+        f"recalls: {record.access_count}"
+    )
+    console.print(
+        f"  created:     {format_time(record.created_at)}   "
+        f"updated: {format_time(record.updated_at)}"
+    )
+    if record.expires_at:
+        console.print(f"  expires:     {format_time(record.expires_at)}")
+    if record.superseded_by:
+        console.print(f"  replaced by: {record.superseded_by}")
+    if record.metadata:
+        console.print(f"  metadata:    {record.metadata}")
+    console.print(console.style("History", "bold"))
+    for event in events:
+        extra = f" {console.sym('arrow')} {event.related_id[:8]}" if event.related_id else ""
+        reason = f" ({event.reason})" if event.reason else ""
+        console.print(
+            f"  {format_time(event.created_at)}  v{event.version}  {event.kind}{extra}{reason}"
+        )
+        console.print(console.style(f"      {event.content}", "dim"))
+    return EXIT_OK

highhxpack/cli/commands/memories.py

@@ -0,0 +1,92 @@
+"""``highhxpack memories``."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from highhxpack.cli.context import EXIT_OK, Context
+from highhxpack.cli.display import format_time
+
+
+def register(subparsers: Any, common: argparse.ArgumentParser) -> None:
+    parser = subparsers.add_parser(
+        "memories",
+        aliases=["list"],
+        parents=[common],
+        help="list stored memories",
+        description="List the current user's memories (newest first).",
+    )
+    parser.add_argument("-t", "--type", dest="memory_type", action="append", help="only this type")
+    parser.add_argument(
+        "--status",
+        default="active",
+        help="active, superseded, merged, archived or any (default: active)",
+    )
+    parser.add_argument("-n", "--limit", type=int, default=50, help="maximum rows (default: 50)")
+    parser.add_argument("--offset", type=int, default=0, help="skip this many rows")
+    parser.add_argument(
+        "--order",
+        choices=("newest", "oldest", "importance", "updated"),
+        default="newest",
+        help="sort order (default: newest)",
+    )
+    parser.add_argument("--all-users", action="store_true", help="list memories of every user")
+    parser.add_argument("--include-expired", action="store_true", help="include expired memories")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace, ctx: Context) -> int:
+    memory = ctx.memory
+    user = None if args.all_users else ctx.user
+    records = memory.list(
+        user,
+        memory_type=args.memory_type,
+        status=args.status,
+        limit=args.limit,
+        offset=args.offset,
+        order=args.order,
+        include_expired=args.include_expired,
+    )
+    console = ctx.console
+    if console.json_mode:
+        console.json([r.to_dict() for r in records])
+        return EXIT_OK
+    if not records:
+        scope = "any user" if user is None else f"user {user!r}"
+        console.info(f'No memories for {scope}. Add one with: highhxpack remember "..."')
+        return EXIT_OK
+    show_user = user is None
+    show_status = args.status != "active"
+    headers = [
+        "ID",
+        *(["USER"] if show_user else []),
+        "TYPE",
+        *(["STATUS"] if show_status else []),
+        "IMP",
+        "CREATED",
+        "CONTENT",
+    ]
+    rows = [
+        [
+            r.short_id,
+            *([r.user_id] if show_user else []),
+            r.memory_type,
+            *([r.status] if show_status else []),
+            f"{r.importance:.2f}",
+            format_time(r.created_at),
+            r.content,
+        ]
+        for r in records
+    ]
+    console.table(headers, rows, flex=len(headers) - 1)
+    total = memory.count(
+        user, memory_type=args.memory_type, status=args.status, include_expired=args.include_expired
+    )
+    if total > args.offset + len(records):
+        console.info(
+            console.style(
+                f"Showing {len(records)} of {total}. Use --offset/--limit to see more.", "dim"
+            )
+        )
+    return EXIT_OK