activity-frames 0.1.0__py3-none-any.whl

activity_frames/__init__.py

@@ -0,0 +1,129 @@
+"""activity-frames: episodic memory for AI agents.
+
+Compiles raw screen-capture data (a local capture database) into
+structured, deterministic activity frames that any agent can consume.
+No LLM in the loop: same input, same output, every time.
+
+Quickstart:
+
+    from activity_frames import ActivityLog
+
+    log = ActivityLog()                    # finds the local capture DB
+    doc = log.day()                        # today's activity frames
+    print(log.context(hours=2))            # paste-ready agent context
+"""
+from __future__ import annotations
+
+from .db import Database, RecorderDBNotFound, find_default_db
+from .emit import context_block, to_json, to_markdown, to_yaml
+from .entities import PageRef, parse_url
+from .frames import (
+    SCHEMA_VERSION,
+    ActivityDocument,
+    ActivityFrame,
+    build_day,
+    build_frames,
+    build_recent,
+)
+from .patterns import WorkPattern, detect as detect_patterns
+from .sessionize import Coverage, Segment, app_ledger, coverage, segments
+
+__version__ = "0.1.0"
+__all__ = [
+    "ActivityLog",
+    "ActivityDocument",
+    "ActivityFrame",
+    "Coverage",
+    "Database",
+    "PageRef",
+    "RecorderDBNotFound",
+    "SCHEMA_VERSION",
+    "Segment",
+    "WorkPattern",
+    "app_ledger",
+    "build_day",
+    "build_frames",
+    "build_recent",
+    "context_block",
+    "coverage",
+    "detect_patterns",
+    "find_default_db",
+    "parse_url",
+    "segments",
+    "to_json",
+    "to_markdown",
+    "to_yaml",
+]
+
+
+class ActivityLog:
+    """High-level facade over a local capture database."""
+
+    def __init__(
+        self,
+        db_path: str | None = None,
+        *,
+        layout: str | dict | None = None,
+        min_minutes: float = 0.5,
+    ):
+        self.db = Database(db_path)
+        self.layout = layout
+        self.min_minutes = min_minutes
+
+    # ---- documents ----
+
+    def day(self, day: str | None = None, **kwargs) -> ActivityDocument:
+        """Activity frames for a local calendar day ("YYYY-MM-DD", default today)."""
+        kwargs.setdefault("min_minutes", self.min_minutes)
+        kwargs.setdefault("layout", self.layout)
+        return build_day(self.db, day, **kwargs)
+
+    def recent(self, hours: float = 2.0, **kwargs) -> ActivityDocument:
+        """Activity frames for the last N hours."""
+        kwargs.setdefault("min_minutes", self.min_minutes)
+        kwargs.setdefault("layout", self.layout)
+        return build_recent(self.db, hours, **kwargs)
+
+    def window(self, start_utc: str, end_utc: str, **kwargs) -> ActivityDocument:
+        """Activity frames for an explicit UTC window."""
+        kwargs.setdefault("min_minutes", self.min_minutes)
+        kwargs.setdefault("layout", self.layout)
+        return build_frames(self.db, start_utc, end_utc, **kwargs)
+
+    # ---- agent-ready strings ----
+
+    def context(self, hours: float = 2.0, *, max_frames: int = 40, **kwargs) -> str:
+        """Compact plaintext context block for the last N hours."""
+        return context_block(self.recent(hours, **kwargs), max_frames=max_frames)
+
+    def day_context(self, day: str | None = None, *, max_frames: int = 40, **kwargs) -> str:
+        """Compact plaintext context block for a local day."""
+        return context_block(self.day(day, **kwargs), max_frames=max_frames)
+
+    # ---- extras ----
+
+    def patterns(self, days: int = 7, *, include_text: bool = False) -> list[WorkPattern]:
+        """Repetitive workflow patterns over the last N days.
+
+        include_text enables the repeated-text detector, whose labels
+        quote raw typed content. Off by default.
+        """
+        from datetime import datetime, timedelta, timezone
+
+        from ._time import utc_string
+
+        now = datetime.now(timezone.utc)
+        return detect_patterns(
+            self.db, utc_string(now - timedelta(days=days)), utc_string(now),
+            include_text=include_text,
+        )
+
+    def apps(self, day: str | None = None):
+        """Per-app usage ledger for a local day."""
+        from ._time import local_day_string, local_day_window_utc
+
+        start, end = local_day_window_utc(day or local_day_string())
+        return app_ledger(self.db, start, end)
+
+    def close(self) -> None:
+        self.db.close()

activity_frames/_time.py

@@ -0,0 +1,86 @@
+"""Timestamp helpers.
+
+The capture engine stores UTC ISO timestamps like
+"2026-07-04T23:10:43.399302+00:00" in both `frames` and `ui_events`.
+All window boundaries we pass to SQL are plain "YYYY-MM-DDTHH:MM:SS"
+prefixes, which compare correctly against the stored strings.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+
+def parse_epoch(ts: str) -> float:
+    """Parse a recorder timestamp to epoch seconds. Returns 0.0 on garbage.
+
+    Handles "2026-07-04T23:10:43", with optional fractional seconds and
+    optional "+00:00"/"Z" suffix. Timestamps are always UTC.
+    """
+    if not ts or len(ts) < 19:
+        return 0.0
+    base = ts[:19]
+    try:
+        dt = datetime.strptime(base, "%Y-%m-%dT%H:%M:%S").replace(tzinfo=timezone.utc)
+    except ValueError:
+        return 0.0
+    epoch = dt.timestamp()
+    if len(ts) > 20 and ts[19] == ".":
+        frac = ""
+        for ch in ts[20:]:
+            if ch.isdigit():
+                frac += ch
+            else:
+                break
+        if frac:
+            epoch += float("0." + frac)
+    return epoch
+
+
+def utc_string(dt: datetime) -> str:
+    """Format a datetime as the recorder's comparable UTC prefix."""
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+
+
+def now_utc_string() -> str:
+    return utc_string(datetime.now(timezone.utc))
+
+
+def local_day_string(dt: datetime | None = None) -> str:
+    """Local calendar day "YYYY-MM-DD" for a datetime (default: now)."""
+    d = dt if dt is not None else datetime.now()
+    return d.astimezone().strftime("%Y-%m-%d")
+
+
+def local_day_window_utc(day: str) -> tuple[str, str]:
+    """UTC window [start, end) covering a local calendar day.
+
+    Each boundary gets the local UTC offset in effect ON THAT DATE
+    (naive .astimezone() applies the platform's timezone rules per
+    date), so past days across a DST change and 23/25-hour transition
+    days are handled correctly.
+
+    Raises ValueError on a malformed day string.
+    """
+    start_naive = datetime.strptime(day, "%Y-%m-%d")
+    start_local = start_naive.astimezone()
+    end_local = (start_naive + timedelta(days=1)).astimezone()
+    return utc_string(start_local), utc_string(end_local)
+
+
+def hours_ago_window_utc(hours: float) -> tuple[str, str]:
+    """UTC window [now - hours, now]."""
+    now = datetime.now(timezone.utc)
+    return utc_string(now - timedelta(hours=hours)), utc_string(now)
+
+
+def fmt_local_hm(epoch: float) -> str:
+    """Format an epoch as local "HH:MM"."""
+    if epoch <= 0:
+        return "?"
+    return datetime.fromtimestamp(epoch).astimezone().strftime("%H:%M")
+
+
+def fmt_local_hms(epoch: float) -> str:
+    if epoch <= 0:
+        return "?"
+    return datetime.fromtimestamp(epoch).astimezone().strftime("%H:%M:%S")

activity_frames/capture.py

@@ -0,0 +1,251 @@
+"""Built-in capture management: give the system its eyes.
+
+`aframes record` provisions and runs a local, open-source capture engine
+(event-driven screen + accessibility-tree + input recording into SQLite).
+The engine binary is fetched once, pinned to a known MIT-licensed
+version for reproducibility, and runs entirely on-device. Audio capture
+is OFF by default.
+
+The compilation layer (the rest of this package) is recorder-agnostic;
+this module just makes the default pipeline self-contained:
+
+    pip install activity-frames
+    aframes record          # start capturing
+    aframes context         # your last 2 hours, agent-ready
+"""
+from __future__ import annotations
+
+import os
+import platform
+import signal
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+from pathlib import Path
+
+HOME_DIR = Path("~/.activity-frames").expanduser()
+BIN_DIR = HOME_DIR / "bin"
+PID_FILE = HOME_DIR / "recorder.pid"
+LOG_FILE = HOME_DIR / "recorder.log"
+
+# Pinned engine: screenpipe v0.3.324, the last MIT-licensed npm release.
+# Each platform tarball is verified against its npm dist integrity hash
+# (sha512) before extraction; a mismatch aborts the install.
+_ENGINE_VERSION = "0.3.324"
+_ENGINE_PACKAGES = {
+    ("darwin", "arm64"): (
+        "cli-darwin-arm64",
+        "uWdkCmGxO8jPHT8A91PzPQe7paFHQZmZHIqIRtW3Ikeb5G2H/XLUHmq6CYMpgUio"
+        "GAr8dSvIEbc00Tx9/qYYQg==",
+    ),
+    ("darwin", "x86_64"): (
+        "cli-darwin-x64",
+        "OpbKGyL5i7ep1IXG2wFrVlB5075hHeSjyrQh3ytfdMOz5DaqAsMAC6eLbQ2TnrGh"
+        "K3EGPDqgn1pgLvA2RcmL3A==",
+    ),
+    ("linux", "x86_64"): (
+        "cli-linux-x64",
+        "gdEu4RWpTtn92LK6ySNRurmH27lYsbR0bfvWRWb0DDOC3HLn4yumII49PxhZ1dSU"
+        "bNTKM1tBkCoHieY8iPLf2g==",
+    ),
+}
+_REGISTRY = "https://registry.npmjs.org/@screenpipe/{pkg}/-/{pkg}-{ver}.tgz"
+
+
+class CaptureError(RuntimeError):
+    pass
+
+
+def _platform_key() -> tuple[str, str]:
+    sysname = platform.system().lower()
+    machine = platform.machine().lower()
+    if machine in ("aarch64",):
+        machine = "arm64"
+    if machine in ("amd64",):
+        machine = "x86_64"
+    return sysname, machine
+
+
+def engine_path() -> Path:
+    # The engine keeps its real name: it is a pinned screenpipe build.
+    return BIN_DIR / "screenpipe"
+
+
+def _find_system_engine() -> str | None:
+    """An already-installed engine on PATH also works."""
+    from shutil import which
+
+    return which("screenpipe")
+
+
+def _verify_sha512(path: Path, expected_b64: str) -> None:
+    import base64
+    import hashlib
+
+    h = hashlib.sha512()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    actual = base64.b64encode(h.digest()).decode()
+    if actual != expected_b64:
+        raise CaptureError(
+            "Engine download failed integrity verification "
+            f"(expected sha512-{expected_b64[:16]}..., got sha512-{actual[:16]}...). "
+            "Refusing to install. Retry, or install screenpipe yourself and "
+            "re-run; anything named 'screenpipe' on PATH is used as-is."
+        )
+
+
+def ensure_engine(quiet: bool = False) -> str:
+    """Return a runnable capture-engine binary, fetching it if needed.
+
+    Downloads are pinned to a specific version AND verified against its
+    published sha512 before anything is extracted or executed.
+    """
+    local = engine_path()
+    if local.exists() and os.access(local, os.X_OK):
+        return str(local)
+    system = _find_system_engine()
+    if system:
+        return system
+
+    key = _platform_key()
+    entry = _ENGINE_PACKAGES.get(key)
+    if not entry:
+        raise CaptureError(
+            f"No prebuilt capture engine for {key[0]}/{key[1]} yet. "
+            "You can point activity-frames at any existing capture database "
+            "via $AFRAMES_DB instead."
+        )
+    pkg, sha512_b64 = entry
+    url = _REGISTRY.format(pkg=pkg, ver=_ENGINE_VERSION)
+    if not quiet:
+        print(f"Fetching capture engine (screenpipe {_ENGINE_VERSION}, "
+              f"{key[0]}/{key[1]}, one-time, ~50MB)...", file=sys.stderr)
+    BIN_DIR.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory() as td:
+        tgz = Path(td) / "engine.tgz"
+        urllib.request.urlretrieve(url, tgz)
+        _verify_sha512(tgz, sha512_b64)
+        with tarfile.open(tgz) as tf:
+            member = next(
+                (m for m in tf.getmembers() if m.name.endswith("bin/screenpipe")),
+                None,
+            )
+            # Regular files only: symlinks/hardlinks in an archive could
+            # otherwise redirect the extract or the chmod below.
+            if member is None or not member.isreg():
+                raise CaptureError("Unexpected engine archive layout.")
+            member.name = "screenpipe"
+            try:
+                tf.extract(member, BIN_DIR, filter="data")  # Python 3.12+
+            except TypeError:
+                tf.extract(member, BIN_DIR)
+    local.chmod(0o755)
+    if not quiet:
+        print(f"Capture engine installed at {local}", file=sys.stderr)
+    return str(local)
+
+
+def _pid_is_engine(pid: int) -> bool:
+    """Verify the PID actually belongs to the capture engine, so a stale
+    pidfile after reboot/PID-reuse never points us at an innocent process."""
+    try:
+        out = subprocess.run(
+            ["ps", "-p", str(pid), "-o", "comm="],
+            capture_output=True, text=True, timeout=5,
+        ).stdout.strip()
+    except Exception:
+        return True  # cannot verify: fail open for status, stop() re-checks
+    return "screenpipe" in out or "capture-engine" in out
+
+
+def _read_pid() -> int | None:
+    try:
+        pid = int(PID_FILE.read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        PID_FILE.unlink(missing_ok=True)  # stale
+        return None
+    if not _pid_is_engine(pid):
+        PID_FILE.unlink(missing_ok=True)  # PID reused by another process
+        return None
+    return pid
+
+
+def _last_frame_age_s() -> float | None:
+    """Seconds since the most recent captured frame, or None if unknown."""
+    try:
+        from ._time import parse_epoch
+        from .db import Database
+
+        db = Database()
+        ts = db.scalar("SELECT MAX(timestamp) FROM frames", default=None)
+        db.close()
+        if not ts:
+            return None
+        import time
+
+        return max(0.0, time.time() - parse_epoch(ts))
+    except Exception:
+        return None
+
+
+def status() -> str:
+    pid = _read_pid()
+    if not pid:
+        return "not recording"
+    age = _last_frame_age_s()
+    base = f"recording (pid {pid}, log: {LOG_FILE})"
+    if age is None:
+        return (base + "\nwarning: no capture database found yet. If this "
+                "persists, grant Screen Recording and Accessibility permission "
+                "(System Settings > Privacy & Security) and restart capture.")
+    if age > 300:
+        return (base + f"\nwarning: last captured frame is {int(age/60)} min old. "
+                "The engine may lack Screen Recording / Accessibility permission "
+                "(System Settings > Privacy & Security), or the screen is idle.")
+    return base + f" - healthy, last frame {int(age)}s ago"
+
+
+def start(*, audio: bool = False, foreground: bool = False) -> None:
+    if _read_pid():
+        print(f"Already {status()}", file=sys.stderr)
+        return
+    binary = ensure_engine()
+    args = [binary, "record"]
+    args += ["--audio-chunk-duration", "300"] if audio else ["--disable-audio"]
+
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    if foreground:
+        os.execv(binary, args)
+
+    log = open(LOG_FILE, "ab")
+    proc = subprocess.Popen(
+        args, stdout=log, stderr=log,
+        start_new_session=True,
+    )
+    PID_FILE.write_text(str(proc.pid))
+    hint = ""
+    if platform.system() == "Darwin":
+        hint = ("\nmacOS: the engine needs Screen Recording and Accessibility "
+                "permission (System Settings > Privacy & Security). Check with: "
+                "aframes record --status")
+    print(f"Capture started (pid {proc.pid}). Audio: {'on' if audio else 'off'}.\n"
+          f"Data stays on this machine. Stop with: aframes record --stop{hint}",
+          file=sys.stderr)
+
+
+def stop() -> None:
+    pid = _read_pid()
+    if not pid:
+        print("Not recording.", file=sys.stderr)
+        return
+    os.kill(pid, signal.SIGTERM)
+    PID_FILE.unlink(missing_ok=True)
+    print("Capture stopped.", file=sys.stderr)

activity_frames/cli.py

@@ -0,0 +1,155 @@
+"""aframes: command-line interface.
+
+  aframes today                       today's frames (yaml)
+  aframes day 2026-07-04 -f json      a specific day
+  aframes context --hours 3           paste-ready agent context block
+  aframes apps                        per-app ledger for today
+  aframes patterns --days 7           repetitive workflows
+  aframes mcp                         run the MCP stdio server
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import ActivityLog, __version__
+from .db import RecorderDBNotFound
+from .emit import context_block, to_json, to_markdown, to_yaml
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--db", help="path to the capture SQLite database")
+    p.add_argument("-f", "--format", choices=["yaml", "json", "md", "context"],
+                   default="yaml", help="output format (default yaml)")
+    p.add_argument("--min-minutes", type=float, default=0.5,
+                   help="drop frames shorter than this (default 0.5)")
+    p.add_argument("--include-text", action="store_true",
+                   help="include typed text snippets (off by default)")
+    p.add_argument("--layout", default=None,
+                   help="keyboard layout decode map (e.g. azerty)")
+
+
+def _emit(doc, fmt: str, include_text: bool) -> str:
+    if fmt == "json":
+        return to_json(doc, include_input_text=include_text)
+    if fmt == "md":
+        return to_markdown(doc, include_input_text=include_text)
+    if fmt == "context":
+        return context_block(doc)
+    try:
+        return to_yaml(doc, include_input_text=include_text)
+    except ImportError:
+        print("note: PyYAML not installed, emitting JSON "
+              "(pip install activity-frames[yaml])", file=sys.stderr)
+        return to_json(doc, include_input_text=include_text)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="aframes",
+        description="activity-frames: episodic memory for AI agents. "
+        "Compiles screen capture into structured activity frames.",
+    )
+    parser.add_argument("--version", action="version", version=f"aframes {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+
+    p_today = sub.add_parser("today", help="activity frames for today")
+    _add_common(p_today)
+
+    p_day = sub.add_parser("day", help="activity frames for a local day")
+    p_day.add_argument("date", help="YYYY-MM-DD")
+    _add_common(p_day)
+
+    p_ctx = sub.add_parser("context", help="compact agent context block")
+    p_ctx.add_argument("--hours", type=float, default=2.0,
+                       help="how many hours back (default 2)")
+    p_ctx.add_argument("--max-frames", type=int, default=40)
+    _add_common(p_ctx)
+
+    p_apps = sub.add_parser("apps", help="per-app usage ledger")
+    p_apps.add_argument("date", nargs="?", help="YYYY-MM-DD (default today)")
+    _add_common(p_apps)
+
+    p_pat = sub.add_parser("patterns", help="repetitive workflow patterns")
+    p_pat.add_argument("--days", type=int, default=7)
+    _add_common(p_pat)
+
+    p_mcp = sub.add_parser("mcp", help="run the MCP stdio server")
+    p_mcp.add_argument("--db", help="path to the capture SQLite database")
+    p_mcp.add_argument("--layout", default=None)
+
+    p_rec = sub.add_parser("record", help="start/stop the built-in capture engine")
+    p_rec.add_argument("--stop", action="store_true", help="stop capturing")
+    p_rec.add_argument("--status", action="store_true", help="show capture status")
+    p_rec.add_argument("--audio", action="store_true",
+                       help="also capture audio (off by default)")
+    p_rec.add_argument("--foreground", action="store_true",
+                       help="run in the foreground instead of detaching")
+
+    args = parser.parse_args(argv)
+    if not args.cmd:
+        parser.print_help()
+        return 1
+
+    if args.cmd == "record":
+        from . import capture
+
+        try:
+            if args.stop:
+                capture.stop()
+            elif args.status:
+                print(capture.status())
+            else:
+                capture.start(audio=args.audio, foreground=args.foreground)
+        except capture.CaptureError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+        return 0
+
+    if args.cmd == "mcp":
+        from .mcp_server import MCPServer
+
+        MCPServer(args.db, args.layout).serve()
+        return 0
+
+    if getattr(args, "layout", None):
+        from .enrich import LAYOUTS
+
+        if args.layout not in LAYOUTS:
+            known = ", ".join(sorted(LAYOUTS))
+            print(f"error: unknown layout '{args.layout}' (known: {known})",
+                  file=sys.stderr)
+            return 2
+
+    try:
+        log = ActivityLog(args.db, layout=args.layout, min_minutes=args.min_minutes)
+    except RecorderDBNotFound as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    kw = dict(min_minutes=args.min_minutes, include_text=args.include_text)
+
+    try:
+        if args.cmd == "today":
+            print(_emit(log.day(**kw), args.format, args.include_text))
+        elif args.cmd == "day":
+            print(_emit(log.day(args.date, **kw), args.format, args.include_text))
+        elif args.cmd == "context":
+            doc = log.recent(args.hours, **kw)
+            print(context_block(doc, max_frames=args.max_frames))
+        elif args.cmd == "apps":
+            for a in log.apps(args.date):
+                wins = f"  ({'; '.join(a.top_windows[:2])})" if a.top_windows else ""
+                print(f"{a.minutes:8.1f} min  {a.app}  "
+                      f"[{a.sessions} sessions, longest {a.longest_session_min}m]{wins}")
+        elif args.cmd == "patterns":
+            for p in log.patterns(args.days, include_text=args.include_text):
+                print(f"[{p.kind}] {p.label}")
+    except ValueError as e:
+        print(f"error: {e} (dates are YYYY-MM-DD)", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())