msg-summarizer 0.1.0__py3-none-any.whl

msg_summarizer/advisor.py

@@ -0,0 +1,125 @@
+from typing import Iterator
+
+import anthropic
+
+from .models import Conversation
+from .summarizer import (
+    _DEFAULT_TOKENS_PER_MINUTE,
+    _RESPONSE_TOKENS,
+    _chunk_budget,
+    fit_recent,
+    format_transcript,
+    make_client,
+    _MODEL,
+)
+
+_SYSTEM_TEMPLATE = """\
+You are a thoughtful, candid assistant helping the user navigate their iMessage conversations.
+
+You have full access to the message history between the user and {contact} \
+({count} messages, {start} to {end}). Use it to answer questions, offer honest \
+advice on how to respond, interpret tone and intent, and draft replies when asked.
+
+Be concise and direct. When suggesting a response, offer specific wording. \
+When you notice patterns in the other person's communication style, point them out.
+
+--- CONVERSATION ({count} messages, {start} to {end}) ---
+{transcript}
+--- END OF CONVERSATION ---\
+"""
+
+
+def prepare_chat(
+    conversation: Conversation,
+    tokens_per_minute: int = _DEFAULT_TOKENS_PER_MINUTE,
+) -> tuple[str, int, int, str, str]:
+    """Trim *conversation* to fit the rate limit and build the chat system prompt.
+
+    Returns (system_prompt, used_count, dropped_count, start, end). An interactive
+    session can't be chunked, so the most recent messages that fit are kept.
+    """
+    kept, dropped = fit_recent(conversation.messages, _chunk_budget(tokens_per_minute))
+    convo = Conversation(conversation.contact, kept)
+    start = convo.messages[0].timestamp.strftime("%Y-%m-%d")
+    end = convo.messages[-1].timestamp.strftime("%Y-%m-%d")
+    system_prompt = _SYSTEM_TEMPLATE.format(
+        contact=convo.contact,
+        count=len(kept),
+        start=start,
+        end=end,
+        transcript=format_transcript(convo),
+    )
+    return system_prompt, len(kept), dropped, start, end
+
+
+def stream_chat(
+    client: anthropic.Anthropic,
+    system_prompt: str,
+    history: list[dict],
+) -> Iterator[str]:
+    """Stream a reply for *history* given the cached *system_prompt*, yielding text."""
+    with client.messages.stream(
+        model=_MODEL,
+        max_tokens=_RESPONSE_TOKENS,
+        system=[
+            {
+                "type": "text",
+                "text": system_prompt,
+                # Cache the transcript — stable for the whole session
+                "cache_control": {"type": "ephemeral"},
+            }
+        ],
+        messages=history,
+    ) as stream:
+        yield from stream.text_stream
+
+
+def run_chat(
+    conversation: Conversation,
+    tokens_per_minute: int = _DEFAULT_TOKENS_PER_MINUTE,
+) -> None:
+    """Start an interactive Q&A session about *conversation*. Streams responses."""
+    if not conversation.messages:
+        print("No messages to chat about.")
+        return
+
+    client = make_client(max_retries=8)
+    system_prompt, used, dropped, start, end = prepare_chat(conversation, tokens_per_minute)
+
+    if dropped:
+        print(
+            f"Note: this conversation is large — loaded the most recent "
+            f"{used:,} of {len(conversation.messages):,} messages to stay within "
+            f"the rate limit.\n"
+        )
+
+    history: list[dict] = []
+
+    print(
+        f"Loaded {used} messages with {conversation.contact} "
+        f"({start} → {end}).\n"
+        "Ask anything about the conversation. Type 'quit' or press Ctrl+C to exit.\n"
+    )
+
+    while True:
+        try:
+            user_input = input("> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        if not user_input:
+            continue
+        if user_input.lower() in {"quit", "exit", "q"}:
+            break
+
+        history.append({"role": "user", "content": user_input})
+
+        print()
+        full_response = ""
+        for text in stream_chat(client, system_prompt, history):
+            print(text, end="", flush=True)
+            full_response += text
+
+        print("\n")
+        history.append({"role": "assistant", "content": full_response})

msg_summarizer/backfill.py

@@ -0,0 +1,112 @@
+"""Backfill stored per-month summaries for past months on demand.
+
+For each past month without a stored summary (in chronological order):
+load the messages for that month, gather any earlier-stored summaries as
+cross-month context, run summarize(), and persist the result. The current
+month is intentionally skipped (it's still growing).
+"""
+
+import threading
+from collections import defaultdict
+
+from .models import Conversation, Message
+from .stats import bucket_of, current_bucket
+from .store import get_notes, list_summaries, save_summary
+from .summarizer import EventHook, _MODEL, Cancelled, summarize
+
+
+def backfill_summaries(
+    target_kind: str,
+    target_id: str,
+    contact_name: str,
+    messages: list[Message],
+    tokens_per_minute: int,
+    on_event: EventHook | None = None,
+    cancel_event: threading.Event | None = None,
+) -> None:
+    """Generate and persist any missing past-month summaries for *target*.
+
+    Emits structured events via *on_event*:
+      * backfill_start, total_existing, total_missing, missing_buckets
+      * bucket_start, bucket, index, total
+      * status, bucket, message              (relayed from per-bucket summarize)
+      * bucket_done, bucket, text
+      * cancelled
+      * backfill_done
+    """
+    cur = current_bucket()
+
+    by_bucket: dict[str, list[Message]] = defaultdict(list)
+    for m in messages:
+        by_bucket[bucket_of(m.timestamp)].append(m)
+
+    existing = list_summaries(target_kind, target_id)
+    missing = [b for b in sorted(by_bucket) if b != cur and b not in existing]
+
+    if on_event is not None:
+        on_event(
+            {
+                "type": "backfill_start",
+                "total_existing": len(existing),
+                "total_missing": len(missing),
+                "missing_buckets": missing,
+            }
+        )
+
+    if not missing:
+        if on_event is not None:
+            on_event({"type": "backfill_done"})
+        return
+
+    def notes_provider() -> str:
+        return get_notes(target_kind, target_id)
+
+    for i, bucket in enumerate(missing, 1):
+        if cancel_event is not None and cancel_event.is_set():
+            if on_event is not None:
+                on_event({"type": "cancelled"})
+            return
+
+        if on_event is not None:
+            on_event(
+                {"type": "bucket_start", "bucket": bucket, "index": i, "total": len(missing)}
+            )
+
+        # Gather prior-stored summaries (chronological order, oldest first).
+        prior_map = list_summaries(target_kind, target_id)
+        priors: list[tuple[str, str]] = sorted(
+            (b, t) for b, t in prior_map.items() if b < bucket
+        )
+
+        conv = Conversation(contact=contact_name, messages=by_bucket[bucket])
+
+        # Relay only status events from the inner summarize, tagged by bucket;
+        # suppress per-chunk part events to avoid flooding the backfill stream.
+        def bucket_event_hook(ev: dict, _b: str = bucket) -> None:
+            if on_event is None:
+                return
+            if ev.get("type") == "status":
+                on_event({"type": "status", "bucket": _b, "message": ev["message"]})
+
+        try:
+            summary = summarize(
+                conv,
+                verbose=False,
+                tokens_per_minute=tokens_per_minute,
+                on_event=bucket_event_hook,
+                notes_provider=notes_provider,
+                cancel_event=cancel_event,
+                prior_summaries=priors,
+            )
+        except Cancelled:
+            if on_event is not None:
+                on_event({"type": "cancelled", "bucket": bucket})
+            return
+
+        save_summary(target_kind, target_id, bucket, summary, notes_provider(), _MODEL)
+
+        if on_event is not None:
+            on_event({"type": "bucket_done", "bucket": bucket, "text": summary})
+
+    if on_event is not None:
+        on_event({"type": "backfill_done"})

msg_summarizer/cli.py

@@ -0,0 +1,394 @@
+import datetime
+import pathlib
+import sys
+
+import anthropic
+import click
+
+from .advisor import run_chat
+from .config import load_user_env
+from .db import DB_PATH, fetch_messages, list_contacts
+from .summarizer import _DEFAULT_TOKENS_PER_MINUTE, MissingAPIKey, summarize
+
+# Load ~/.msg-summarizer/.env into os.environ before anything reads it.
+load_user_env()
+
+
+def _resolve_date_range(
+    days: int | None,
+    from_date: str | None,
+    to_date: str | None,
+) -> tuple[datetime.datetime | None, datetime.datetime | None]:
+    """Resolve --days/--from/--to into UTC bounds; any bound may be None (unbounded).
+
+    With no options at all, returns (None, None) — i.e. the full history.
+    """
+    if days is not None and (from_date or to_date):
+        raise click.UsageError("Use --days OR --from/--to, not both.")
+
+    if days is not None:
+        now = datetime.datetime.now(tz=datetime.timezone.utc)
+        return now - datetime.timedelta(days=days), now
+
+    start = end = None
+    if from_date:
+        start = datetime.datetime.strptime(from_date, "%Y-%m-%d").replace(
+            tzinfo=datetime.timezone.utc
+        )
+    if to_date:
+        end = datetime.datetime.strptime(to_date, "%Y-%m-%d").replace(
+            tzinfo=datetime.timezone.utc
+        ) + datetime.timedelta(days=1, seconds=-1)
+    return start, end
+
+
+def _range_label(
+    start: datetime.datetime | None, end: datetime.datetime | None
+) -> str:
+    """Human-readable description of a (possibly open-ended) date range."""
+    if start is None and end is None:
+        return "all time"
+    lo = start.date().isoformat() if start else "start"
+    hi = end.date().isoformat() if end else "now"
+    return f"{lo} → {hi}"
+
+
+@click.group()
+def main() -> None:
+    """Summarize iMessage conversations using Claude AI."""
+
+
+@main.command("list-contacts")
+@click.option(
+    "--db", "db_path", default=None, help=f"Path to chat.db (default: {DB_PATH})."
+)
+@click.option("--limit", default=50, show_default=True, help="Max contacts to show.")
+def list_contacts_cmd(db_path: str | None, limit: int) -> None:
+    """List contacts found in the iMessage database.
+
+    Use the HANDLE ID column as the CONTACT argument to 'summarize'.
+    """
+    resolved_db = pathlib.Path(db_path) if db_path else DB_PATH
+    try:
+        contacts = list_contacts(db_path=resolved_db, limit=limit)
+    except PermissionError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    if not contacts:
+        click.echo("No contacts found in the database.")
+        return
+
+    col1 = max(len(h) for h, _, _ in contacts)
+    col2 = max((len(d) for _, d, _ in contacts), default=0)
+    col1 = max(col1, 9)   # min width for "HANDLE ID"
+    col2 = max(col2, 12)  # min width for "DISPLAY NAME"
+
+    header = f"{'HANDLE ID':<{col1}}  {'DISPLAY NAME':<{col2}}  MESSAGES"
+    click.echo(header)
+    click.echo("-" * len(header))
+    for handle_id, display_name, msg_count in contacts:
+        click.echo(f"{handle_id:<{col1}}  {display_name:<{col2}}  {msg_count}")
+
+
+@main.command("messages")
+@click.argument("contact")
+@click.option("--days", type=int, default=None, help="Only the last N days.")
+@click.option(
+    "--from", "from_date", default=None, metavar="YYYY-MM-DD", help="Start date (inclusive, UTC)."
+)
+@click.option(
+    "--to", "to_date", default=None, metavar="YYYY-MM-DD", help="End date (inclusive, UTC)."
+)
+@click.option(
+    "--db", "db_path", default=None, help=f"Path to chat.db (default: {DB_PATH})."
+)
+def messages_cmd(
+    contact: str,
+    days: int | None,
+    from_date: str | None,
+    to_date: str | None,
+    db_path: str | None,
+) -> None:
+    """Print the message history with CONTACT as plain text.
+
+    CONTACT is matched as a substring against phone numbers, email addresses,
+    and chat names. Each line is "[local timestamp] sender: text". With no date
+    options the full history is printed; --days/--from/--to narrow the range.
+    Run 'list-contacts' first to find the right identifier.
+
+    \b
+    Examples:
+      msg-summarizer messages "+15551234567"
+      msg-summarizer messages "+15551234567" --days 30
+      msg-summarizer messages "alice@example.com" --from 2025-01-01 --to 2025-06-30
+    """
+    try:
+        start, end = _resolve_date_range(days, from_date, to_date)
+    except ValueError as exc:
+        raise click.UsageError(f"Invalid date format: {exc}") from exc
+
+    resolved_db = pathlib.Path(db_path) if db_path else DB_PATH
+
+    click.echo(
+        f"Loading messages with '{contact}' ({_range_label(start, end)})…", err=True
+    )
+
+    try:
+        conversation = fetch_messages(contact, db_path=resolved_db, start=start, end=end)
+    except PermissionError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    if not conversation.messages:
+        click.echo(
+            "No messages found. Run 'msg-summarizer list-contacts' to see available identifiers.",
+            err=True,
+        )
+        sys.exit(0)
+
+    for msg in conversation.messages:
+        local_ts = msg.timestamp.astimezone()
+        click.echo(f"[{local_ts:%Y-%m-%d %H:%M}] {msg.sender}: {msg.text}")
+
+
+@main.command("summarize")
+@click.argument("contact")
+@click.option("--days", type=int, default=None, help="Summarize the last N days.")
+@click.option(
+    "--from", "from_date", default=None, metavar="YYYY-MM-DD", help="Start date (inclusive)."
+)
+@click.option(
+    "--to", "to_date", default=None, metavar="YYYY-MM-DD", help="End date (inclusive)."
+)
+@click.option(
+    "--db", "db_path", default=None, help=f"Path to chat.db (default: {DB_PATH})."
+)
+@click.option(
+    "--tokens-per-minute",
+    "tokens_per_minute",
+    type=int,
+    default=_DEFAULT_TOKENS_PER_MINUTE,
+    show_default=True,
+    help="Your account's input-tokens/min rate limit. Chunks are sized and paced "
+    "to stay under it; raise it if you're on a higher tier.",
+)
+@click.option("--verbose", is_flag=True, help="Show message count and cache stats.")
+def summarize_cmd(
+    contact: str,
+    days: int | None,
+    from_date: str | None,
+    to_date: str | None,
+    db_path: str | None,
+    tokens_per_minute: int,
+    verbose: bool,
+) -> None:
+    """Summarize iMessage conversations with CONTACT using Claude AI.
+
+    CONTACT is matched as a substring against phone numbers, email addresses,
+    and chat names in the iMessage database. Run 'list-contacts' first to find
+    the right identifier. With no date options, the entire history is
+    summarized; --days/--from/--to narrow the range.
+
+    \b
+    Examples:
+      msg-summarizer summarize "+15551234567"
+      msg-summarizer summarize "+15551234567" --days 7
+      msg-summarizer summarize "alice@example.com" --from 2024-12-01 --to 2024-12-31
+    """
+    try:
+        start, end = _resolve_date_range(days, from_date, to_date)
+    except ValueError as exc:
+        raise click.UsageError(f"Invalid date format: {exc}") from exc
+
+    resolved_db = pathlib.Path(db_path) if db_path else DB_PATH
+
+    click.echo(
+        f"Fetching messages with '{contact}' ({_range_label(start, end)})…",
+        err=True,
+    )
+
+    try:
+        conversation = fetch_messages(contact, db_path=resolved_db, start=start, end=end)
+    except PermissionError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    if not conversation.messages:
+        click.echo(
+            "No messages found. Run 'msg-summarizer list-contacts' to see available identifiers.",
+            err=True,
+        )
+        sys.exit(0)
+
+    if verbose:
+        click.echo(f"Found {len(conversation.messages)} messages. Summarizing…", err=True)
+    else:
+        click.echo("Summarizing…", err=True)
+
+    try:
+        summary = summarize(conversation, verbose=verbose, tokens_per_minute=tokens_per_minute)
+    except MissingAPIKey as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+    except anthropic.APIError as exc:
+        click.echo(f"\nError from the Claude API: {exc}", err=True)
+        click.echo(
+            "Any completed parts were saved to the temp file noted above. "
+            "Try a narrower range (--days/--from/--to), a lower --tokens-per-minute, "
+            "or raise your tier.",
+            err=True,
+        )
+        sys.exit(1)
+    click.echo(summary)
+
+
+@main.command("chat")
+@click.argument("contact")
+@click.option("--days", type=int, default=None, help="Load the last N days of messages.")
+@click.option(
+    "--from", "from_date", default=None, metavar="YYYY-MM-DD", help="Start date (inclusive)."
+)
+@click.option(
+    "--to", "to_date", default=None, metavar="YYYY-MM-DD", help="End date (inclusive)."
+)
+@click.option(
+    "--db", "db_path", default=None, help=f"Path to chat.db (default: {DB_PATH})."
+)
+@click.option(
+    "--tokens-per-minute",
+    "tokens_per_minute",
+    type=int,
+    default=_DEFAULT_TOKENS_PER_MINUTE,
+    show_default=True,
+    help="Your account's input-tokens/min rate limit. A large history is trimmed "
+    "to the most recent messages that fit under it.",
+)
+def chat_cmd(
+    contact: str,
+    days: int | None,
+    from_date: str | None,
+    to_date: str | None,
+    db_path: str | None,
+    tokens_per_minute: int,
+) -> None:
+    """Chat interactively about a conversation — ask questions, get advice, draft replies.
+
+    With no date options, the entire history is loaded; --days/--from/--to
+    narrow the range.
+
+    \b
+    Examples:
+      msg-summarizer chat "+15551234567"
+      msg-summarizer chat "+15551234567" --days 30
+      msg-summarizer chat "alice@example.com" --from 2025-01-01 --to 2025-05-27
+    """
+    try:
+        start, end = _resolve_date_range(days, from_date, to_date)
+    except ValueError as exc:
+        raise click.UsageError(f"Invalid date format: {exc}") from exc
+
+    resolved_db = pathlib.Path(db_path) if db_path else DB_PATH
+
+    click.echo(
+        f"Loading messages with '{contact}' ({_range_label(start, end)})…",
+        err=True,
+    )
+
+    try:
+        conversation = fetch_messages(contact, db_path=resolved_db, start=start, end=end)
+    except PermissionError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    if not conversation.messages:
+        click.echo(
+            "No messages found. Run 'msg-summarizer list-contacts' to see available identifiers.",
+            err=True,
+        )
+        sys.exit(0)
+
+    try:
+        run_chat(conversation, tokens_per_minute=tokens_per_minute)
+    except MissingAPIKey as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+    except anthropic.APIError as exc:
+        click.echo(f"\nError from the Claude API: {exc}", err=True)
+        sys.exit(1)
+
+
+@main.command("setup")
+def setup_cmd() -> None:
+    """Walk through first-run setup: API key + Full Disk Access check."""
+    import sqlite3
+
+    from . import config
+    from .db import DB_PATH
+
+    click.echo("msg-summarizer setup")
+    click.echo("====================\n")
+
+    # --- API key ---
+    have_key = bool(
+        __import__("os").environ.get("ANTHROPIC_API_KEY")
+        or __import__("os").environ.get("ANTHROPIC_AUTH_TOKEN")
+    )
+    if have_key:
+        click.echo("✓ Anthropic API key already set in the environment.")
+    else:
+        click.echo("Anthropic API key not set.")
+        click.echo("Get one at https://console.anthropic.com/")
+        key = click.prompt("Paste your key (or press Enter to skip)", default="", show_default=False)
+        key = key.strip()
+        if not key:
+            click.echo("  Skipped. Summary and Chat will be disabled until set.")
+        elif not key.startswith(("sk-ant-", "sk-")):
+            click.echo("  That doesn't look like an Anthropic key (expected to start with sk-ant-).")
+            click.echo("  Skipped.")
+        else:
+            try:
+                config.save_env_var("ANTHROPIC_API_KEY", key)
+                click.echo(f"✓ Saved to {config.USER_ENV_FILE} (mode 0600).")
+            except OSError as exc:
+                click.echo(f"  Couldn't write: {exc}")
+    click.echo("")
+
+    # --- Full Disk Access ---
+    fda_ok = False
+    try:
+        sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True).close()
+        fda_ok = True
+    except sqlite3.OperationalError:
+        pass
+
+    if fda_ok:
+        click.echo(f"✓ Full Disk Access OK — {DB_PATH} is readable.")
+    else:
+        click.echo("✗ Can't open ~/Library/Messages/chat.db.")
+        click.echo("  Grant Full Disk Access to the app you'll run msg-summarizer from:")
+        click.echo("    1. System Settings → Privacy & Security → Full Disk Access.")
+        click.echo("    2. Click + and add your terminal app (Terminal, iTerm, Warp, VS Code, …).")
+        click.echo("    3. Quit and reopen that app, then run msg-summarizer again.")
+    click.echo("")
+
+    if have_key or fda_ok:
+        click.echo("Done. Try `msg-summarizer serve` to launch the app.")
+
+
+@main.command("serve")
+@click.option("--host", default="127.0.0.1", show_default=True, help="Host to bind.")
+@click.option("--port", default=8765, show_default=True, type=int, help="Port to bind.")
+@click.option("--no-browser", is_flag=True, help="Don't open a browser automatically.")
+def serve_cmd(host: str, port: int, no_browser: bool) -> None:
+    """Launch the web app (API + UI) and open it in your browser."""
+    import threading
+    import webbrowser
+
+    import uvicorn
+
+    url = f"http://{host}:{port}"
+    if not no_browser:
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+    click.echo(f"Serving msg-summarizer at {url}  (Ctrl+C to stop)…", err=True)
+    uvicorn.run("msg_summarizer.web.app:app", host=host, port=port, log_level="info")

msg_summarizer/config.py

@@ -0,0 +1,57 @@
+"""User-level configuration: ~/.msg-summarizer/.env for persistent settings.
+
+Loading order (highest priority wins, anything already set is kept):
+  1. Existing environment variables (explicit `export` or shell config).
+  2. ~/.msg-summarizer/.env (the set-it-and-forget-it persistent store).
+
+So a user can `export ANTHROPIC_API_KEY=...` for a one-off override without
+touching the file, and the UI can write to the file once for "next time".
+"""
+
+import os
+import pathlib
+
+from dotenv import load_dotenv
+
+USER_CONFIG_DIR = pathlib.Path.home() / ".msg-summarizer"
+USER_ENV_FILE = USER_CONFIG_DIR / ".env"
+
+
+def load_user_env() -> None:
+    """Merge ~/.msg-summarizer/.env into os.environ; existing vars take priority."""
+    if USER_ENV_FILE.exists():
+        load_dotenv(USER_ENV_FILE, override=False)
+
+
+def save_env_var(key: str, value: str) -> None:
+    """Persist a key=value pair to ~/.msg-summarizer/.env and update os.environ now.
+
+    Replaces an existing line for the same key (or appends one if absent).
+    Creates the file with mode 0600 the first time — it holds secrets.
+    """
+    if not key.replace("_", "").isalnum():
+        raise ValueError(f"invalid env key: {key!r}")
+
+    USER_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = USER_ENV_FILE.read_text().splitlines() if USER_ENV_FILE.exists() else []
+
+    found = False
+    out: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if "=" in stripped and not stripped.startswith("#"):
+            existing_key = stripped.split("=", 1)[0].strip()
+            if existing_key == key:
+                out.append(f"{key}={value}")
+                found = True
+                continue
+        out.append(line)
+    if not found:
+        out.append(f"{key}={value}")
+
+    USER_ENV_FILE.write_text("\n".join(out) + "\n")
+    try:
+        USER_ENV_FILE.chmod(0o600)
+    except OSError:
+        pass  # filesystem may not support chmod (e.g. exFAT); best-effort
+    os.environ[key] = value