taskclf 0.1.0__py3-none-any.whl

taskclf/README.md

@@ -0,0 +1,20 @@
+# src/taskclf/
+
+Main package.
+
+## Design principles
+- **Adapters** isolate unstable platform/tool integrations.
+- **Core** defines contracts, validation, and data/model IO.
+- **Pipelines** compose pure transforms into repeatable runs.
+- **CLI** is the stable interface for humans and automation.
+
+## Subpackages
+- `core/` — schemas, validation, storage primitives, model IO, metrics, drift detection, telemetry
+- `adapters/` — ActivityWatch + input collectors
+- `features/` — feature computation (event -> bucketed features, rolling windows, sessions)
+- `labels/` — label span formats, import/export, projection onto feature windows, active labeling queue, weak label rules
+- `train/` — dataset construction, splits, training, evaluation, calibration, retraining pipeline
+- `infer/` — batch and online inference, rule-based baseline, smoothing, calibration, taxonomy mapping, drift monitoring
+- `report/` — daily summaries and exports (JSON/CSV/Parquet)
+- `cli/` — Typer entrypoint and commands
+- `ui/` — labeling UI (Streamlit)

taskclf/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from taskclf!")

taskclf/adapters/README.md

@@ -0,0 +1,41 @@
+# adapters/
+
+Integrations with external tools or OS APIs.
+
+## Subpackages
+
+### `activitywatch/`
+- `types.py` -- `AWEvent` (window events) and `AWInputEvent` (keyboard/mouse
+  aggregate counts from `aw-watcher-input`).
+- `mapping.py` -- App-name normalization, browser/editor/terminal classification,
+  and semantic `app_category` assignment (browser, editor, terminal, chat, email,
+  meeting, docs, design, devtools, media, file_manager, utilities, project_mgmt,
+  other).
+- `client.py` -- AW JSON export parser and REST API client.  Supports both
+  `currentwindow` (window watcher) and `os.hid.input` (input watcher) bucket
+  types for file-based and REST-based ingestion.
+
+### `input/`
+- Optional OS-specific input aggregators (counts only, not yet implemented).
+  The `aw-watcher-input` integration in `activitywatch/` covers the same
+  signals when ActivityWatch is running.
+
+## Invariants
+- Adapters must output normalized events satisfying the `core.types.Event` protocol.
+- Raw window titles are never persisted -- they are replaced with salted hashes.
+- App names are mapped to reverse-domain identifiers via the known-app registry.
+- Input events carry only aggregate counts (presses, clicks, movement, scroll)
+  -- never individual key identities.
+- Keep adapter-specific quirks out of `core/`.
+- Adapters should be swappable without changing feature or model code.
+
+## Event Protocol
+The `Event` protocol (`core.types.Event`) defines the minimal attribute set
+that any adapter event must expose.  `AWEvent` satisfies this protocol
+structurally (no inheritance required).  New adapters should likewise expose
+`timestamp`, `duration_seconds`, `app_id`, `window_title_hash`, `is_browser`,
+`is_editor`, `is_terminal`, and `app_category`.
+
+`AWInputEvent` is a separate type that does not implement the `Event` protocol
+-- it feeds into the feature builder as a supplementary data source via the
+`input_events` parameter of `build_features_from_aw_events()`.

taskclf/adapters/activitywatch/client.py

@@ -0,0 +1,296 @@
+"""ActivityWatch data access: JSON export parsing and REST API client.
+
+Provides two data-ingestion paths:
+
+* **File-based** -- :func:`parse_aw_export` reads an AW JSON export
+  (the format produced by *Export all buckets as JSON* in the AW web UI
+  or ``GET /api/0/export``).
+* **REST-based** -- :func:`fetch_aw_events` queries a running
+  ``aw-server`` instance for events in a time range.
+
+Both paths normalize application names via
+:func:`~taskclf.adapters.activitywatch.mapping.normalize_app` and
+replace raw window titles with salted hashes so that no sensitive text
+is ever persisted.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from taskclf.adapters.activitywatch.mapping import normalize_app
+from taskclf.adapters.activitywatch.types import AWEvent, AWInputEvent
+from taskclf.core.defaults import DEFAULT_AW_TIMEOUT_SECONDS
+from taskclf.core.hashing import salted_hash
+
+logger = logging.getLogger(__name__)
+
+_CURRENTWINDOW_TYPE = "currentwindow"
+_INPUT_TYPE = "os.hid.input"
+
+
+def _parse_timestamp(raw: str) -> datetime:
+    """Parse an ISO-8601 timestamp from AW into a naive-UTC datetime."""
+    ts = datetime.fromisoformat(raw)
+    if ts.tzinfo is not None:
+        ts = ts.astimezone(timezone.utc).replace(tzinfo=None)
+    return ts
+
+
+def _raw_event_to_aw_event(raw: dict[str, Any], *, title_salt: str) -> AWEvent:
+    """Convert a single raw AW event dict into a normalized :class:`AWEvent`."""
+    data = raw.get("data", {})
+    app_name = data.get("app", "unknown")
+    title = data.get("title", "")
+
+    app_id, is_browser, is_editor, is_terminal, app_category = normalize_app(app_name)
+    title_hash = salted_hash(title, salt=title_salt)
+
+    return AWEvent(
+        timestamp=_parse_timestamp(raw["timestamp"]),
+        duration_seconds=float(raw.get("duration", 0)),
+        app_id=app_id,
+        window_title_hash=title_hash,
+        is_browser=is_browser,
+        is_editor=is_editor,
+        is_terminal=is_terminal,
+        app_category=app_category,
+    )
+
+
+# ---------------------------------------------------------------------------
+# File-based ingestion
+# ---------------------------------------------------------------------------
+
+
+def parse_aw_export(path: Path, *, title_salt: str) -> list[AWEvent]:
+    """Parse an ActivityWatch JSON export file into normalized events.
+
+    Filters for buckets of type ``currentwindow`` (i.e.
+    ``aw-watcher-window`` data).  Each event's application name is
+    normalized and its window title is replaced with a salted hash.
+
+    Args:
+        path: Path to the AW export JSON file.
+        title_salt: Salt used for hashing window titles.
+
+    Returns:
+        Sorted (by timestamp) list of :class:`AWEvent` instances.
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+        KeyError: If the JSON structure is missing expected keys.
+    """
+    raw = json.loads(path.read_text(encoding="utf-8"))
+
+    buckets: dict[str, Any] = raw.get("buckets", raw)
+
+    events: list[AWEvent] = []
+    for bucket_id, bucket in buckets.items():
+        bucket_type = bucket.get("type", "")
+        if bucket_type != _CURRENTWINDOW_TYPE:
+            logger.debug("Skipping bucket %s (type=%s)", bucket_id, bucket_type)
+            continue
+
+        logger.info(
+            "Processing bucket %s (%d events)",
+            bucket_id,
+            len(bucket.get("events", [])),
+        )
+        for raw_event in bucket.get("events", []):
+            events.append(_raw_event_to_aw_event(raw_event, title_salt=title_salt))
+
+    events.sort(key=lambda e: e.timestamp)
+    return events
+
+
+def _raw_to_input_event(raw: dict[str, Any]) -> AWInputEvent:
+    """Convert a single raw AW input event dict into an :class:`AWInputEvent`."""
+    data = raw.get("data", {})
+    return AWInputEvent(
+        timestamp=_parse_timestamp(raw["timestamp"]),
+        duration_seconds=float(raw.get("duration", 0)),
+        presses=int(data.get("presses", 0)),
+        clicks=int(data.get("clicks", 0)),
+        delta_x=int(data.get("deltaX", 0)),
+        delta_y=int(data.get("deltaY", 0)),
+        scroll_x=int(data.get("scrollX", 0)),
+        scroll_y=int(data.get("scrollY", 0)),
+    )
+
+
+def parse_aw_input_export(path: Path) -> list[AWInputEvent]:
+    """Parse ``aw-watcher-input`` events from an AW JSON export.
+
+    Filters for buckets of type ``os.hid.input``.  These events carry
+    only aggregate counts (key presses, mouse clicks, movement, scroll)
+    and contain no sensitive payload.
+
+    Args:
+        path: Path to the AW export JSON file.
+
+    Returns:
+        Sorted (by timestamp) list of :class:`AWInputEvent` instances.
+        Empty if no ``os.hid.input`` bucket exists in the export.
+    """
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    buckets: dict[str, Any] = raw.get("buckets", raw)
+
+    events: list[AWInputEvent] = []
+    for bucket_id, bucket in buckets.items():
+        bucket_type = bucket.get("type", "")
+        if bucket_type != _INPUT_TYPE:
+            continue
+
+        logger.info(
+            "Processing input bucket %s (%d events)",
+            bucket_id,
+            len(bucket.get("events", [])),
+        )
+        for raw_event in bucket.get("events", []):
+            events.append(_raw_to_input_event(raw_event))
+
+    events.sort(key=lambda e: e.timestamp)
+    return events
+
+
+# ---------------------------------------------------------------------------
+# REST API helpers
+# ---------------------------------------------------------------------------
+
+
+def _api_get(url: str) -> Any:
+    """Issue a GET request and return the parsed JSON body."""
+    req = urllib.request.Request(url, headers={"Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=DEFAULT_AW_TIMEOUT_SECONDS) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def list_aw_buckets(host: str) -> dict[str, dict]:
+    """List all buckets from a running AW server.
+
+    Args:
+        host: Base URL of the AW server (e.g. ``"http://localhost:5600"``).
+
+    Returns:
+        Dict mapping bucket IDs to their metadata.
+    """
+    url = f"{host.rstrip('/')}/api/0/buckets/"
+    return _api_get(url)
+
+
+def find_window_bucket_id(host: str) -> str:
+    """Auto-discover the ``aw-watcher-window`` bucket on *host*.
+
+    Args:
+        host: Base URL of the AW server.
+
+    Returns:
+        The bucket ID whose ``type`` is ``currentwindow``.
+
+    Raises:
+        ValueError: If no ``currentwindow`` bucket exists on the server.
+    """
+    buckets = list_aw_buckets(host)
+    for bucket_id, meta in buckets.items():
+        if meta.get("type") == _CURRENTWINDOW_TYPE:
+            return bucket_id
+    raise ValueError(
+        f"No bucket with type={_CURRENTWINDOW_TYPE!r} found on {host}. "
+        f"Available: {list(buckets.keys())}"
+    )
+
+
+def find_input_bucket_id(host: str) -> str | None:
+    """Auto-discover the ``aw-watcher-input`` bucket on *host*.
+
+    Unlike :func:`find_window_bucket_id`, this returns ``None`` when no
+    input bucket exists because ``aw-watcher-input`` is an optional
+    watcher that many users don't run.
+
+    Args:
+        host: Base URL of the AW server.
+
+    Returns:
+        The bucket ID whose ``type`` is ``os.hid.input``, or ``None``.
+    """
+    buckets = list_aw_buckets(host)
+    for bucket_id, meta in buckets.items():
+        if meta.get("type") == _INPUT_TYPE:
+            return bucket_id
+    return None
+
+
+def fetch_aw_events(
+    host: str,
+    bucket_id: str,
+    start: datetime,
+    end: datetime,
+    *,
+    title_salt: str,
+) -> list[AWEvent]:
+    """Fetch events from the AW REST API for a time range.
+
+    Args:
+        host: Base URL of the AW server (e.g. ``"http://localhost:5600"``).
+        bucket_id: Bucket to query (e.g. ``"aw-watcher-window_myhostname"``).
+        start: Inclusive start of the query window (UTC).
+        end: Exclusive end of the query window (UTC).
+        title_salt: Salt used for hashing window titles.
+
+    Returns:
+        Sorted list of :class:`AWEvent` instances.
+    """
+    base = host.rstrip("/")
+    start_iso = start.isoformat() + "Z" if start.tzinfo is None else start.isoformat()
+    end_iso = end.isoformat() + "Z" if end.tzinfo is None else end.isoformat()
+
+    url = (
+        f"{base}/api/0/buckets/{bucket_id}/events"
+        f"?start={start_iso}&end={end_iso}"
+    )
+    raw_events: list[dict] = _api_get(url)
+
+    events = [
+        _raw_event_to_aw_event(e, title_salt=title_salt) for e in raw_events
+    ]
+    events.sort(key=lambda e: e.timestamp)
+    return events
+
+
+def fetch_aw_input_events(
+    host: str,
+    bucket_id: str,
+    start: datetime,
+    end: datetime,
+) -> list[AWInputEvent]:
+    """Fetch input events from the AW REST API for a time range.
+
+    Args:
+        host: Base URL of the AW server.
+        bucket_id: Input bucket to query (e.g.
+            ``"aw-watcher-input_myhostname"``).
+        start: Inclusive start of the query window (UTC).
+        end: Exclusive end of the query window (UTC).
+
+    Returns:
+        Sorted list of :class:`AWInputEvent` instances.
+    """
+    base = host.rstrip("/")
+    start_iso = start.isoformat() + "Z" if start.tzinfo is None else start.isoformat()
+    end_iso = end.isoformat() + "Z" if end.tzinfo is None else end.isoformat()
+
+    url = (
+        f"{base}/api/0/buckets/{bucket_id}/events"
+        f"?start={start_iso}&end={end_iso}"
+    )
+    raw_events: list[dict] = _api_get(url)
+
+    events = [_raw_to_input_event(e) for e in raw_events]
+    events.sort(key=lambda e: e.timestamp)
+    return events

taskclf/adapters/activitywatch/mapping.py

@@ -0,0 +1,178 @@
+"""App-name normalization, classification, and category assignment.
+
+ActivityWatch reports the foreground application as a human-readable
+name (e.g. ``"Firefox"``, ``"Code"``).  This module maps those names
+to reverse-domain identifiers, boolean flags, and a semantic category
+consumed by :class:`~taskclf.core.types.FeatureRow`.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+AppInfo = tuple[str, bool, bool, bool, str]
+# (app_id, is_browser, is_editor, is_terminal, app_category)
+
+# ---- known application registry ------------------------------------------------
+# (reverse_domain_id, is_browser, is_editor, is_terminal, app_category)
+
+_BROWSERS: Final[dict[str, AppInfo]] = {
+    "firefox": ("org.mozilla.firefox", True, False, False, "browser"),
+    "google chrome": ("com.google.Chrome", True, False, False, "browser"),
+    "google-chrome": ("com.google.Chrome", True, False, False, "browser"),
+    "chrome": ("com.google.Chrome", True, False, False, "browser"),
+    "chromium": ("org.chromium.Chromium", True, False, False, "browser"),
+    "chromium-browser": ("org.chromium.Chromium", True, False, False, "browser"),
+    "safari": ("com.apple.Safari", True, False, False, "browser"),
+    "arc": ("company.thebrowser.Browser", True, False, False, "browser"),
+    "brave browser": ("com.brave.Browser", True, False, False, "browser"),
+    "brave-browser": ("com.brave.Browser", True, False, False, "browser"),
+    "microsoft edge": ("com.microsoft.edgemac", True, False, False, "browser"),
+    "msedge": ("com.microsoft.edgemac", True, False, False, "browser"),
+    "vivaldi": ("com.vivaldi.Vivaldi", True, False, False, "browser"),
+    "opera": ("com.operasoftware.Opera", True, False, False, "browser"),
+    "zen browser": ("io.github.nicothin.zen", True, False, False, "browser"),
+}
+
+_EDITORS: Final[dict[str, AppInfo]] = {
+    "code": ("com.microsoft.VSCode", False, True, False, "editor"),
+    "visual studio code": ("com.microsoft.VSCode", False, True, False, "editor"),
+    "code - insiders": ("com.microsoft.VSCodeInsiders", False, True, False, "editor"),
+    "cursor": ("com.todesktop.cursor", False, True, False, "editor"),
+    "intellij idea": ("com.jetbrains.intellij", False, True, False, "editor"),
+    "idea": ("com.jetbrains.intellij", False, True, False, "editor"),
+    "pycharm": ("com.jetbrains.pycharm", False, True, False, "editor"),
+    "webstorm": ("com.jetbrains.webstorm", False, True, False, "editor"),
+    "goland": ("com.jetbrains.goland", False, True, False, "editor"),
+    "clion": ("com.jetbrains.clion", False, True, False, "editor"),
+    "rustrover": ("com.jetbrains.rustrover", False, True, False, "editor"),
+    "sublime text": ("com.sublimetext.4", False, True, False, "editor"),
+    "sublime_text": ("com.sublimetext.4", False, True, False, "editor"),
+    "vim": ("org.vim.Vim", False, True, False, "editor"),
+    "gvim": ("org.vim.Vim", False, True, False, "editor"),
+    "neovim": ("io.neovim.nvim", False, True, False, "editor"),
+    "nvim": ("io.neovim.nvim", False, True, False, "editor"),
+    "emacs": ("org.gnu.emacs", False, True, False, "editor"),
+    "xcode": ("com.apple.dt.Xcode", False, True, False, "editor"),
+    "android studio": ("com.google.android.studio", False, True, False, "editor"),
+    "zed": ("dev.zed.Zed", False, True, False, "editor"),
+}
+
+_TERMINALS: Final[dict[str, AppInfo]] = {
+    "terminal": ("com.apple.Terminal", False, False, True, "terminal"),
+    "iterm2": ("com.googlecode.iterm2", False, False, True, "terminal"),
+    "iterm": ("com.googlecode.iterm2", False, False, True, "terminal"),
+    "alacritty": ("org.alacritty", False, False, True, "terminal"),
+    "kitty": ("net.kovidgoyal.kitty", False, False, True, "terminal"),
+    "wezterm": ("org.wezfurlong.wezterm", False, False, True, "terminal"),
+    "wezterm-gui": ("org.wezfurlong.wezterm", False, False, True, "terminal"),
+    "gnome-terminal": ("org.gnome.Terminal", False, False, True, "terminal"),
+    "konsole": ("org.kde.konsole", False, False, True, "terminal"),
+    "hyper": ("co.zeit.hyper", False, False, True, "terminal"),
+    "ghostty": ("com.mitchellh.ghostty", False, False, True, "terminal"),
+    "rio": ("io.raphamorim.rio", False, False, True, "terminal"),
+    "warp": ("dev.warp.Warp", False, False, True, "terminal"),
+    "tabby": ("org.tabby.Tabby", False, False, True, "terminal"),
+}
+
+_EMAIL: Final[dict[str, AppInfo]] = {
+    "mail": ("com.apple.mail", False, False, False, "email"),
+    "thunderbird": ("org.mozilla.thunderbird", False, False, False, "email"),
+    "outlook": ("com.microsoft.Outlook", False, False, False, "email"),
+}
+
+_CHAT: Final[dict[str, AppInfo]] = {
+    "slack": ("com.tinyspeck.slackmacgap", False, False, False, "chat"),
+    "discord": ("com.discordapp.Discord", False, False, False, "chat"),
+    "microsoft teams": ("com.microsoft.teams2", False, False, False, "chat"),
+    "teams": ("com.microsoft.teams2", False, False, False, "chat"),
+    "messages": ("com.apple.MobileSMS", False, False, False, "chat"),
+}
+
+_MEETING: Final[dict[str, AppInfo]] = {
+    "zoom": ("us.zoom.xos", False, False, False, "meeting"),
+    "zoom.us": ("us.zoom.xos", False, False, False, "meeting"),
+    "facetime": ("com.apple.FaceTime", False, False, False, "meeting"),
+}
+
+_DOCS: Final[dict[str, AppInfo]] = {
+    "notes": ("com.apple.Notes", False, False, False, "docs"),
+    "obsidian": ("md.obsidian", False, False, False, "docs"),
+    "notion": ("notion.id", False, False, False, "docs"),
+}
+
+_DESIGN: Final[dict[str, AppInfo]] = {
+    "figma": ("com.figma.Desktop", False, False, False, "design"),
+}
+
+_DEVTOOLS: Final[dict[str, AppInfo]] = {
+    "postman": ("com.postmanlabs.mac", False, False, False, "devtools"),
+    "docker desktop": ("com.docker.docker", False, False, False, "devtools"),
+}
+
+_MEDIA: Final[dict[str, AppInfo]] = {
+    "spotify": ("com.spotify.client", False, False, False, "media"),
+}
+
+_FILE_MANAGER: Final[dict[str, AppInfo]] = {
+    "finder": ("com.apple.finder", False, False, False, "file_manager"),
+    "nautilus": ("org.gnome.Nautilus", False, False, False, "file_manager"),
+    "files": ("org.gnome.Nautilus", False, False, False, "file_manager"),
+}
+
+_UTILITIES: Final[dict[str, AppInfo]] = {
+    "preview": ("com.apple.Preview", False, False, False, "utilities"),
+    "system preferences": ("com.apple.systempreferences", False, False, False, "utilities"),
+    "system settings": ("com.apple.systempreferences", False, False, False, "utilities"),
+    "activity monitor": ("com.apple.ActivityMonitor", False, False, False, "utilities"),
+    "1password": ("com.1password.1password", False, False, False, "utilities"),
+    "bitwarden": ("com.bitwarden.desktop", False, False, False, "utilities"),
+}
+
+_PROJECT_MGMT: Final[dict[str, AppInfo]] = {
+    "linear": ("com.linear", False, False, False, "project_mgmt"),
+}
+
+KNOWN_APPS: Final[dict[str, AppInfo]] = {
+    **_BROWSERS,
+    **_EDITORS,
+    **_TERMINALS,
+    **_EMAIL,
+    **_CHAT,
+    **_MEETING,
+    **_DOCS,
+    **_DESIGN,
+    **_DEVTOOLS,
+    **_MEDIA,
+    **_FILE_MANAGER,
+    **_UTILITIES,
+    **_PROJECT_MGMT,
+}
+
+APP_CATEGORIES: Final[frozenset[str]] = frozenset({
+    "browser", "editor", "terminal", "email", "chat", "meeting",
+    "docs", "design", "devtools", "media", "file_manager",
+    "utilities", "project_mgmt", "other",
+})
+
+
+def normalize_app(app_name: str) -> AppInfo:
+    """Map an AW application name to a reverse-domain ID, flags, and category.
+
+    Performs a case-insensitive lookup in :data:`KNOWN_APPS`.  Unknown
+    applications fall back to ``"unknown.<sanitized_name>"`` with all
+    flags set to ``False`` and category ``"other"``.
+
+    Args:
+        app_name: Application name as reported by ActivityWatch
+            (e.g. ``"Firefox"``).
+
+    Returns:
+        A ``(app_id, is_browser, is_editor, is_terminal, app_category)``
+        tuple.
+    """
+    key = app_name.strip().lower()
+    if key in KNOWN_APPS:
+        return KNOWN_APPS[key]
+    sanitized = key.replace(" ", "_").replace("/", "_")
+    return (f"unknown.{sanitized}", False, False, False, "other")

taskclf/adapters/activitywatch/types.py

@@ -0,0 +1,48 @@
+"""Privacy-safe normalized event types for ActivityWatch data."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class AWEvent(BaseModel, frozen=True):
+    """A single ActivityWatch window event, normalized and privacy-scrubbed.
+
+    Raw ``app`` names are mapped to reverse-domain identifiers via
+    :func:`~taskclf.adapters.activitywatch.mapping.normalize_app`.
+    Raw ``title`` strings are replaced with a salted hash via
+    :func:`~taskclf.core.hashing.salted_hash` -- the original title
+    is never persisted.
+    """
+
+    timestamp: datetime = Field(description="Event start (UTC).")
+    duration_seconds: float = Field(ge=0, description="Duration in seconds.")
+    app_id: str = Field(description="Reverse-domain app identifier.")
+    window_title_hash: str = Field(description="Salted SHA-256 of the window title.")
+    is_browser: bool = Field(description="True if the app is a web browser.")
+    is_editor: bool = Field(description="True if the app is a code editor.")
+    is_terminal: bool = Field(description="True if the app is a terminal emulator.")
+    app_category: str = Field(description="Semantic app category (e.g. 'editor', 'chat').")
+
+
+class AWInputEvent(BaseModel, frozen=True):
+    """Aggregated keyboard/mouse activity from ``aw-watcher-input``.
+
+    Each event covers a short polling interval (typically 5 s) and
+    carries only aggregate counts -- never individual key identities.
+    This makes the type privacy-safe by construction.
+
+    The upstream AW fields ``deltaX``/``deltaY`` and ``scrollX``/``scrollY``
+    are mapped to snake_case for consistency with project conventions.
+    """
+
+    timestamp: datetime = Field(description="Interval start (UTC).")
+    duration_seconds: float = Field(ge=0, description="Duration in seconds.")
+    presses: int = Field(ge=0, description="Key presses in this interval.")
+    clicks: int = Field(ge=0, description="Mouse clicks in this interval.")
+    delta_x: int = Field(ge=0, description="Absolute horizontal mouse movement (px).")
+    delta_y: int = Field(ge=0, description="Absolute vertical mouse movement (px).")
+    scroll_x: int = Field(ge=0, description="Absolute horizontal scroll delta.")
+    scroll_y: int = Field(ge=0, description="Absolute vertical scroll delta.")

taskclf/adapters/input/macos.py

@@ -0,0 +1 @@
+# optional: HID events aggregator

taskclf/cli/README.md

@@ -0,0 +1,54 @@
+# cli/
+
+Human-facing command surface area (stable).
+
+## Command Groups
+
+### `ingest`
+- `aw` — ingest ActivityWatch JSON export into privacy-safe events
+
+### `features`
+- `build` — build per-minute feature rows for a date
+
+### `labels`
+- `import` — import label spans from CSV
+- `add-block` — create a manual label block for a time range
+- `show-queue` — show pending items in the active labeling queue
+- `project` — project label blocks onto feature windows
+
+### `train`
+- `build-dataset` — build training dataset (join features + labels, split)
+- `lgbm` — train a LightGBM multiclass model
+- `evaluate` — run full evaluation (metrics, calibration, acceptance checks)
+- `tune-reject` — sweep reject thresholds and recommend best
+- `calibrate` — fit per-user probability calibrators
+- `retrain` — run full retrain pipeline (train, evaluate, gate-check, promote)
+- `check-retrain` — check if retraining or calibrator update is due
+
+### `taxonomy`
+- `validate` — validate a taxonomy YAML file
+- `show` — display taxonomy mapping as a Rich table
+- `init` — generate default taxonomy YAML
+
+### `infer`
+- `batch` — batch inference (predict, smooth, segmentize)
+- `online` — online inference loop (poll ActivityWatch)
+- `baseline` — rule-based baseline inference (no ML model)
+- `compare` — compare baseline vs ML model on labeled data
+
+### `report`
+- `daily` — generate daily report from segments JSON
+
+### `monitor`
+- `drift-check` — run drift detection comparing reference vs current
+- `telemetry` — compute telemetry snapshot and append to store
+- `show` — display recent telemetry snapshots
+
+## Responsibilities
+- Typer app entrypoint
+- Commands call pipeline functions (thin wrapper)
+- Provide consistent flags and defaults (via `core.defaults`)
+
+## Invariants
+- CLI should remain backward compatible whenever possible.
+- Keep business logic out of CLI; delegate to packages.