work-recall 0.1.0__py3-none-any.whl

recall/__init__.py

@@ -0,0 +1,3 @@
+"""Recall — local-first AI chief of staff for engineers."""
+
+__version__ = "0.1.0"

recall/cli.py

@@ -0,0 +1,418 @@
+"""Recall CLI entry point. Only orchestration lives here."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import typer
+
+from recall import __version__
+from recall.config.secrets import get_secret, redact, set_secret
+from recall.config.settings import load_config, save_config
+from recall.constants import (
+    CONFIG_PATH,
+    DB_PATH,
+    LOG_DIR,
+    LOG_PATH,
+    RECALL_HOME,
+)
+from recall.output.console import console
+from recall.output.formatters import (
+    render_followups,
+    render_meeting_prep,
+    render_risks,
+    render_standup,
+    render_sync_summary,
+    render_timeline,
+    render_today,
+)
+from recall.storage import ensure_schema, get_connection
+from recall.storage import sync_state as sync_state_repo
+
+app = typer.Typer(help="Recall — local-first AI chief of staff for engineers.", no_args_is_help=True)
+config_app = typer.Typer(help="Manage local config.")
+connect_app = typer.Typer(help="Connect a data source.")
+schedule_app = typer.Typer(help="Local scheduler.")
+app.add_typer(config_app, name="config")
+app.add_typer(connect_app, name="connect")
+app.add_typer(schedule_app, name="schedule")
+
+
+# ---------------------------------------------------------------------------
+# global setup
+# ---------------------------------------------------------------------------
+def _setup_logging() -> None:
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        handlers=[logging.FileHandler(LOG_PATH), logging.StreamHandler(sys.stderr)],
+    )
+    # Quiet down third-party noise
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("apscheduler").setLevel(logging.WARNING)
+
+
+def _open_db():
+    conn = get_connection()
+    ensure_schema(conn)
+    return conn
+
+
+# ---------------------------------------------------------------------------
+# init / doctor
+# ---------------------------------------------------------------------------
+@app.command()
+def init() -> None:
+    """Initialize Recall: create ~/.recall and run migrations."""
+    RECALL_HOME.mkdir(parents=True, exist_ok=True)
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    _setup_logging()
+    if not CONFIG_PATH.exists():
+        save_config(load_config())
+    conn = _open_db()
+    conn.close()
+    console.print(f"[green]✓[/] Initialized [bold]{RECALL_HOME}[/]")
+    console.print(f"  • DB:     {DB_PATH}")
+    console.print(f"  • Config: {CONFIG_PATH}")
+    console.print(f"  • Logs:   {LOG_PATH}")
+    console.print()
+    console.print("Next steps:")
+    console.print("  [cyan]recall config set OPENAI_API_KEY <key>[/]")
+    console.print("  [cyan]recall config set COMPOSIO_API_KEY <key>[/]")
+    console.print("  [cyan]recall sync --sample[/]  (try the demo data)")
+    console.print("  [cyan]recall connect slack[/]  (or gmail/calendar/linear)")
+
+
+@app.command()
+def doctor() -> None:
+    """Check the local setup."""
+    _setup_logging()
+    cfg = load_config()
+    console.print(f"[bold]Recall {__version__}[/]")
+
+    def _check(label: str, ok: bool, detail: str = "") -> None:
+        mark = "[green]✓[/]" if ok else "[red]✗[/]"
+        console.print(f"  {mark} {label}{(' — ' + detail) if detail else ''}")
+
+    _check("Home dir", RECALL_HOME.exists(), str(RECALL_HOME))
+    _check("Config file", CONFIG_PATH.exists(), str(CONFIG_PATH))
+    _check("Database", DB_PATH.exists(), str(DB_PATH))
+    _check("OpenAI key", bool(cfg.openai_api_key), redact(cfg.openai_api_key))
+    _check("Composio key", bool(cfg.composio_api_key), redact(cfg.composio_api_key))
+
+    # Try opening the DB and loading sqlite-vec
+    try:
+        conn = _open_db()
+        from recall.storage.db import try_load_sqlite_vec
+
+        vec_ok = try_load_sqlite_vec(conn)
+        conn.close()
+        _check("sqlite-vec", vec_ok, "vector search enabled" if vec_ok else "extension not loadable")
+    except Exception as exc:
+        _check("Database open", False, str(exc))
+
+    for source, state in [(s.source, s) for s in _list_sync_states()]:
+        last = state.last_synced_at.isoformat() if state.last_synced_at else "never"
+        console.print(f"  • {source}: {state.status or 'idle'} (last sync: {last})")
+
+
+def _list_sync_states():
+    conn = _open_db()
+    try:
+        return sync_state_repo.list_all(conn)
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# config
+# ---------------------------------------------------------------------------
+@config_app.command("set")
+def config_set(key: str, value: str) -> None:
+    """Set a config key. Supported keys: OPENAI_API_KEY, COMPOSIO_API_KEY."""
+    upper = key.strip().upper()
+    if upper in ("OPENAI_API_KEY", "COMPOSIO_API_KEY"):
+        set_secret(upper, value)  # type: ignore[arg-type]
+        console.print(f"[green]✓[/] {upper} updated.")
+        # Force the OpenAI client cache to rebuild on next use.
+        try:
+            from recall.llm.openai_client import reset_client_cache
+
+            reset_client_cache()
+        except Exception:
+            pass
+        return
+    # Generic fall-through into the "extra" bag
+    cfg = load_config()
+    cfg.extra[key] = value
+    save_config(cfg)
+    console.print(f"[green]✓[/] {key} = {value}")
+
+
+@config_app.command("get")
+def config_get(key: str) -> None:
+    """Read a config key."""
+    upper = key.strip().upper()
+    if upper in ("OPENAI_API_KEY", "COMPOSIO_API_KEY"):
+        console.print(redact(get_secret(upper)))  # type: ignore[arg-type]
+        return
+    cfg = load_config()
+    console.print(cfg.extra.get(key, "(not set)"))
+
+
+@config_app.command("list")
+def config_list() -> None:
+    """List config keys."""
+    cfg = load_config()
+    console.print("[bold]Secrets[/]")
+    console.print(f"  OPENAI_API_KEY  = {redact(cfg.openai_api_key)}")
+    console.print(f"  COMPOSIO_API_KEY = {redact(cfg.composio_api_key)}")
+    console.print("[bold]Schedule[/]")
+    console.print(f"  enabled     = {cfg.schedule.enabled}")
+    console.print(f"  every_hours = {cfg.schedule.every_hours}")
+    console.print("[bold]Connectors[/]")
+    for source in ("slack", "gmail", "calendar", "linear"):
+        state = getattr(cfg.connectors, source)
+        console.print(
+            f"  {source:9s} connected={state.connected} "
+            f"id={state.connection_id or '—'}"
+        )
+    if cfg.extra:
+        console.print("[bold]Extra[/]")
+        for k, v in cfg.extra.items():
+            console.print(f"  {k} = {v}")
+
+
+# ---------------------------------------------------------------------------
+# connect
+# ---------------------------------------------------------------------------
+def _connect_source(source: str) -> None:
+    _setup_logging()
+    from recall.connectors import CONNECTORS
+    from recall.connectors.composio_client import ComposioKeyMissing
+
+    connector = CONNECTORS[source]
+    try:
+        handshake = connector.connect()
+    except ComposioKeyMissing as exc:
+        console.print(f"[red]✗[/] {exc}")
+        raise typer.Exit(code=1)
+    except Exception as exc:
+        console.print(f"[red]✗[/] OAuth start failed: {exc}")
+        raise typer.Exit(code=1)
+
+    if handshake.redirect_url:
+        console.print(f"Open this URL to authorize {source}:")
+        console.print(f"  [cyan]{handshake.redirect_url}[/]")
+    cfg = load_config()
+    state = getattr(cfg.connectors, source)
+    state.connected = True
+    state.connection_id = handshake.connection_id
+    save_config(cfg)
+    console.print(f"[green]✓[/] {source} connected (id={handshake.connection_id}).")
+
+
+@connect_app.command("slack")
+def connect_slack() -> None:
+    _connect_source("slack")
+
+
+@connect_app.command("gmail")
+def connect_gmail() -> None:
+    _connect_source("gmail")
+
+
+@connect_app.command("calendar")
+def connect_calendar() -> None:
+    _connect_source("calendar")
+
+
+@connect_app.command("linear")
+def connect_linear() -> None:
+    _connect_source("linear")
+
+
+# ---------------------------------------------------------------------------
+# sync
+# ---------------------------------------------------------------------------
+@app.command()
+def sync(
+    sample: bool = typer.Option(False, "--sample", help="Use bundled sample data."),
+    source: str | None = typer.Option(
+        None, "--source", help="Sync only one source (slack|gmail|calendar|linear)."
+    ),
+    full: bool = typer.Option(False, "--full", help="Ignore checkpoints and refetch the last 30 days."),
+) -> None:
+    """Run an incremental sync."""
+    _setup_logging()
+    from recall.sync.runner import run_sync, run_sync_sample
+
+    conn = _open_db()
+    try:
+        if sample:
+            summary = run_sync_sample(conn)
+        else:
+            sources = [source] if source else None
+            summary = run_sync(conn, sources, full=full)
+    finally:
+        conn.close()
+    render_sync_summary(summary.to_dict())
+
+
+# ---------------------------------------------------------------------------
+# intelligence
+# ---------------------------------------------------------------------------
+@app.command()
+def today() -> None:
+    """Today's meetings, blockers, focus items."""
+    _setup_logging()
+    from recall.intelligence.today import build_today
+
+    conn = _open_db()
+    try:
+        brief = build_today(conn)
+    finally:
+        conn.close()
+    render_today(brief)
+
+
+@app.command()
+def prep(meeting: str = typer.Argument(..., help="Meeting title or keyword.")) -> None:
+    """Prepare for an upcoming meeting."""
+    _setup_logging()
+    from recall.intelligence.meeting_prep import build_meeting_prep
+
+    conn = _open_db()
+    try:
+        data = build_meeting_prep(conn, meeting)
+    finally:
+        conn.close()
+    render_meeting_prep(data)
+
+
+@app.command()
+def risks() -> None:
+    """At-risk projects, blockers, overdue commitments."""
+    _setup_logging()
+    from recall.intelligence.risks import build_risks
+
+    conn = _open_db()
+    try:
+        data = build_risks(conn)
+    finally:
+        conn.close()
+    render_risks(data)
+
+
+@app.command()
+def followups(
+    actor: str | None = typer.Option(None, "--for", help="Filter to a specific person.")
+) -> None:
+    """Open commitments."""
+    _setup_logging()
+    from recall.intelligence.followups import build_followups
+
+    conn = _open_db()
+    try:
+        data = build_followups(conn, actor=actor)
+    finally:
+        conn.close()
+    render_followups(data)
+
+
+@app.command()
+def timeline(project: str = typer.Argument(..., help="Project name or slug.")) -> None:
+    """Chronological timeline for a project."""
+    _setup_logging()
+    from recall.intelligence.timeline import build_timeline
+
+    conn = _open_db()
+    try:
+        data = build_timeline(conn, project)
+    finally:
+        conn.close()
+    render_timeline(data)
+
+
+@app.command()
+def standup() -> None:
+    """Standup brief: yesterday, today, blockers."""
+    _setup_logging()
+    from recall.intelligence.standup import build_standup
+
+    conn = _open_db()
+    try:
+        data = build_standup(conn)
+    finally:
+        conn.close()
+    render_standup(data)
+
+
+# ---------------------------------------------------------------------------
+# schedule
+# ---------------------------------------------------------------------------
+@schedule_app.command("enable")
+def schedule_enable(
+    every: str | None = typer.Option(None, "--every", help="Interval like '4h'."),
+) -> None:
+    """Enable the local scheduler."""
+    from recall.sync.scheduler import set_enabled
+
+    hours: int | None = None
+    if every:
+        every = every.strip().lower()
+        if every.endswith("h"):
+            hours = int(every[:-1])
+        else:
+            hours = int(every)
+    set_enabled(True, every_hours=hours)
+    console.print(
+        f"[green]✓[/] Scheduler enabled (every {hours or 'default'} hours). "
+        "Run `recall schedule run` to start it."
+    )
+
+
+@schedule_app.command("disable")
+def schedule_disable() -> None:
+    """Disable the local scheduler."""
+    from recall.sync.scheduler import set_enabled
+
+    set_enabled(False)
+    console.print("[green]✓[/] Scheduler disabled.")
+
+
+@schedule_app.command("status")
+def schedule_status() -> None:
+    """Show scheduler status."""
+    from recall.sync.scheduler import status
+
+    s = status()
+    console.print(f"enabled={s['enabled']} every_hours={s['every_hours']}")
+
+
+@schedule_app.command("run")
+def schedule_run() -> None:
+    """Start the scheduler in the foreground (blocks)."""
+    _setup_logging()
+    from recall.sync.scheduler import run_blocking
+
+    try:
+        run_blocking()
+    except RuntimeError as exc:
+        console.print(f"[red]✗[/] {exc}")
+        raise typer.Exit(code=1)
+
+
+# ---------------------------------------------------------------------------
+# version
+# ---------------------------------------------------------------------------
+@app.command()
+def version() -> None:
+    """Print the Recall version."""
+    console.print(__version__)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

recall/config/__init__.py

@@ -0,0 +1,5 @@
+"""Config + secrets for Recall."""
+
+from recall.config.settings import RecallConfig, load_config, save_config
+
+__all__ = ["RecallConfig", "load_config", "save_config"]

recall/config/secrets.py

@@ -0,0 +1,44 @@
+"""Read/write API keys via load_config/save_config.
+
+Keys live in `~/.recall/config.yaml`. `.env` variables are honored as a
+development fallback, but the config file is the source of truth.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from recall.config.settings import RecallConfig, load_config, save_config
+
+SecretName = Literal["OPENAI_API_KEY", "COMPOSIO_API_KEY"]
+
+_FIELDS = {
+    "OPENAI_API_KEY": "openai_api_key",
+    "COMPOSIO_API_KEY": "composio_api_key",
+}
+
+
+def _env_fallback(name: SecretName) -> str | None:
+    return os.environ.get(name)
+
+
+def get_secret(name: SecretName, *, config: RecallConfig | None = None) -> str | None:
+    cfg = config or load_config()
+    field = _FIELDS[name]
+    value = getattr(cfg, field, None)
+    return value or _env_fallback(name)
+
+
+def set_secret(name: SecretName, value: str) -> None:
+    cfg = load_config()
+    setattr(cfg, _FIELDS[name], value.strip() or None)
+    save_config(cfg)
+
+
+def redact(value: str | None) -> str:
+    if not value:
+        return "(not set)"
+    if len(value) <= 8:
+        return "***"
+    return f"{value[:4]}…{value[-4:]}"

recall/config/settings.py

@@ -0,0 +1,70 @@
+"""YAML-backed configuration at ~/.recall/config.yaml."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field
+
+from recall.constants import CONFIG_PATH, DEFAULT_SCHEDULE_HOURS, RECALL_HOME
+
+
+class ScheduleConfig(BaseModel):
+    enabled: bool = False
+    every_hours: int = DEFAULT_SCHEDULE_HOURS
+
+
+class ConnectorState(BaseModel):
+    connected: bool = False
+    connection_id: str | None = None
+    account_label: str | None = None
+
+
+class Connectors(BaseModel):
+    slack: ConnectorState = Field(default_factory=ConnectorState)
+    gmail: ConnectorState = Field(default_factory=ConnectorState)
+    calendar: ConnectorState = Field(default_factory=ConnectorState)
+    linear: ConnectorState = Field(default_factory=ConnectorState)
+
+
+class RecallConfig(BaseModel):
+    openai_api_key: str | None = None
+    composio_api_key: str | None = None
+    schedule: ScheduleConfig = Field(default_factory=ScheduleConfig)
+    connectors: Connectors = Field(default_factory=Connectors)
+
+    # Free-form bag for forward compatibility
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+def _ensure_home() -> None:
+    RECALL_HOME.mkdir(parents=True, exist_ok=True)
+
+
+def _restrict_perms(path: Path) -> None:
+    """Best-effort `chmod 600` on POSIX so secrets aren't world-readable."""
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def load_config(path: Path = CONFIG_PATH) -> RecallConfig:
+    """Load config from YAML, returning defaults if the file is missing."""
+    if not path.exists():
+        return RecallConfig()
+    with path.open("r") as f:
+        data = yaml.safe_load(f) or {}
+    return RecallConfig.model_validate(data)
+
+
+def save_config(config: RecallConfig, path: Path = CONFIG_PATH) -> None:
+    """Persist config to YAML with restricted permissions."""
+    _ensure_home()
+    data = config.model_dump(mode="json")
+    with path.open("w") as f:
+        yaml.safe_dump(data, f, sort_keys=False)
+    _restrict_perms(path)

recall/connectors/__init__.py

@@ -0,0 +1,16 @@
+"""Source connectors. Real fetchers go through Composio; sample mode bypasses
+them and reads JSON from disk."""
+
+from recall.connectors.calendar import CalendarConnector
+from recall.connectors.gmail import GmailConnector
+from recall.connectors.linear import LinearConnector
+from recall.connectors.slack import SlackConnector
+
+CONNECTORS = {
+    "slack": SlackConnector(),
+    "gmail": GmailConnector(),
+    "calendar": CalendarConnector(),
+    "linear": LinearConnector(),
+}
+
+__all__ = ["CONNECTORS", "CalendarConnector", "GmailConnector", "LinearConnector", "SlackConnector"]

recall/connectors/calendar.py

@@ -0,0 +1,65 @@
+"""Google Calendar connector via Composio."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from datetime import datetime, timedelta
+
+from recall.connectors.composio_client import execute_action, start_oauth
+
+logger = logging.getLogger(__name__)
+
+
+class CalendarConnector:
+    source = "calendar"
+    composio_app = "googlecalendar"
+
+    def connect(self):
+        return start_oauth(self.composio_app)
+
+    def fetch_since(self, since: datetime) -> Iterable[dict]:
+        time_min = since.isoformat()
+        # Look 14 days ahead so we capture upcoming meetings for `today`/`prep`.
+        time_max = (datetime.utcnow() + timedelta(days=14)).isoformat() + "Z"
+        page_token: str | None = None
+        while True:
+            params = {
+                "calendarId": "primary",
+                "timeMin": time_min,
+                "timeMax": time_max,
+                "singleEvents": True,
+                "orderBy": "startTime",
+                "maxResults": 250,
+            }
+            if page_token:
+                params["pageToken"] = page_token
+            try:
+                resp = execute_action("GOOGLECALENDAR_LIST_EVENTS", params)
+            except Exception as exc:
+                logger.warning("Calendar list failed: %s", exc)
+                break
+            data = resp.get("data") or resp
+            for ev in data.get("items") or []:
+                yield self._reshape(ev)
+            page_token = data.get("nextPageToken")
+            if not page_token:
+                break
+
+    @staticmethod
+    def _reshape(ev: dict) -> dict:
+        start = (ev.get("start") or {}).get("dateTime") or (ev.get("start") or {}).get("date")
+        end = (ev.get("end") or {}).get("dateTime") or (ev.get("end") or {}).get("date")
+        return {
+            "id": ev.get("id"),
+            "title": ev.get("summary") or "",
+            "description": ev.get("description") or "",
+            "organizer": (ev.get("organizer") or {}).get("email"),
+            "attendees": [a.get("email") for a in (ev.get("attendees") or []) if a.get("email")],
+            "start": start,
+            "end": end,
+            "status": ev.get("status"),
+            "location": ev.get("location"),
+            "meeting_link": ev.get("hangoutLink"),
+            "occurred_at": start,
+        }

recall/connectors/composio_client.py

@@ -0,0 +1,71 @@
+"""Thin wrapper around the Composio SDK.
+
+We expose two operations the sync layer needs:
+  - `start_oauth(app)` for `recall connect <source>`.
+  - `execute_action(action, params)` for paged fetches inside each source's
+    connector module.
+
+Composio is imported lazily so the rest of the CLI works without the SDK
+installed (sample mode does not require it).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any
+
+from recall.config.secrets import get_secret
+
+logger = logging.getLogger(__name__)
+
+
+class ComposioKeyMissing(RuntimeError):
+    """Raised when COMPOSIO_API_KEY is not configured."""
+
+
+@dataclass(slots=True)
+class OAuthHandshake:
+    redirect_url: str
+    connection_id: str
+
+
+@lru_cache(maxsize=1)
+def get_toolset():
+    """Return a cached Composio toolset client."""
+    try:
+        from composio import ComposioToolSet  # type: ignore
+    except ImportError as exc:  # pragma: no cover - optional dep
+        raise RuntimeError(
+            "composio-core is not installed. Run `pip install composio-core`."
+        ) from exc
+
+    api_key = get_secret("COMPOSIO_API_KEY")
+    if not api_key:
+        raise ComposioKeyMissing(
+            "COMPOSIO_API_KEY is not set. Run `recall config set COMPOSIO_API_KEY <key>`."
+        )
+    return ComposioToolSet(api_key=api_key)
+
+
+def start_oauth(app: str) -> OAuthHandshake:
+    """Initiate OAuth for the given Composio app slug (slack, gmail, …)."""
+    toolset = get_toolset()
+    entity = toolset.get_entity(id="default")
+    request = entity.initiate_connection(app_name=app)
+    return OAuthHandshake(
+        redirect_url=getattr(request, "redirectUrl", ""),
+        connection_id=getattr(request, "connectedAccountId", ""),
+    )
+
+
+def execute_action(action: str, params: dict[str, Any]) -> Any:
+    """Invoke a Composio action by name (e.g. SLACK_FETCH_CONVERSATION_HISTORY)."""
+    toolset = get_toolset()
+    return toolset.execute_action(action=action, params=params)
+
+
+def reset_cache() -> None:
+    """Force a fresh Composio client (call after a config change)."""
+    get_toolset.cache_clear()