usage-cli 0.29.32__py3-none-any.whl

analyzer/insights.py

@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+from math import sqrt
+from typing import Any, cast
+
+INSIGHT_CHANGE_HEADLINE = "change_headline"
+INSIGHT_SPIKE = "spike"
+INSIGHT_SHIFT = "shift"
+INSIGHT_ACTION = "action"
+
+# Insights are anomaly-only: every component below stays silent unless its
+# threshold trips, and an empty list is a valid (common) result — the report
+# renders a quiet "nothing unusual" line instead of padding with filler.
+_SPIKE_MULTIPLIER_THRESHOLD = 3.0
+_CHANGE_SURGE_PCT = 50
+
+
+def build_insights(data: dict[str, Any]) -> list[dict[str, Any]]:
+    components: list[dict[str, Any]] = []
+
+    change = _build_change_headline(data)
+    if change is not None:
+        components.append(change)
+
+    spike = _find_spike(data.get("daily_trend"))
+    if spike is not None:
+        components.append(
+            {
+                "type": INSIGHT_SPIKE,
+                "key": "insights_spike_v2",
+                "date": spike["date"],
+                "tokens": spike["tokens"],
+                "mean_multiplier": spike["mean_multiplier"],
+            }
+        )
+
+    shift = _build_shift(data)
+    if shift is not None:
+        components.append(shift)
+
+    action = _build_action(change, spike, data)
+    if action is not None:
+        components.append(action)
+
+    return components[:5]
+
+
+def _build_change_headline(data: dict[str, Any]) -> dict[str, Any] | None:
+    comparison = _mapping_value(data.get("comparison"))
+    if comparison is None or not bool(comparison.get("has_prev")):
+        return None
+
+    prev_tokens = _int_value(comparison.get("prev_tokens"))
+    if prev_tokens <= 0:
+        return None
+
+    summary = _mapping_value(data.get("summary"))
+    if summary is None:
+        return None
+
+    cur_tokens = _int_value(summary.get("total_tokens"))
+    delta_pct = round((cur_tokens - prev_tokens) / prev_tokens * 100)
+    if delta_pct < _CHANGE_SURGE_PCT:
+        return None
+
+    return {
+        "type": INSIGHT_CHANGE_HEADLINE,
+        "key": "insights_change_up",
+        "tokens": cur_tokens,
+        "cost_usd": _round_cost(_float_value(summary.get("cost_usd"))),
+        "pct": abs(delta_pct),
+        "direction": "up",
+        "delta_pct": delta_pct,
+    }
+
+
+def _build_shift(data: dict[str, Any]) -> dict[str, Any] | None:
+    return _build_new_project_shift(data) or _build_model_shift(data)
+
+
+def _build_new_project_shift(data: dict[str, Any]) -> dict[str, Any] | None:
+    comparison = _mapping_value(data.get("comparison"))
+    if comparison is None or not bool(comparison.get("has_prev")):
+        return None
+
+    prev_projects = {
+        _str_value(project, "")
+        for project in _list_value(comparison.get("prev_projects"))
+    }
+    for project in _list_value(data.get("by_project")):
+        item = _mapping_value(project)
+        if item is None:
+            continue
+        name = _str_value(item.get("project"), "unknown")
+        pct = _float_value(item.get("pct"))
+        if pct >= 15.0 and name not in prev_projects:
+            return {
+                "type": INSIGHT_SHIFT,
+                "key": "insights_shift_new_project",
+                "project": name,
+                "pct": _round_pct(pct),
+            }
+    return None
+
+
+def _build_model_shift(data: dict[str, Any]) -> dict[str, Any] | None:
+    comparison = _mapping_value(data.get("comparison"))
+    if comparison is None or not bool(comparison.get("has_prev")):
+        return None
+
+    top_model = _first_mapping(data.get("by_model"))
+    prev_model_share = _mapping_value(comparison.get("prev_model_share"))
+    if top_model is None or prev_model_share is None:
+        return None
+
+    model = _str_value(top_model.get("model"), "unknown")
+    pct = _float_value(top_model.get("pct"))
+    prev_pct = _float_value(prev_model_share.get(model))
+    if pct - prev_pct < 10.0:
+        return None
+
+    top_project = _str_value(top_model.get("top_project"), "")
+    if top_project and top_project != "unknown":
+        return {
+            "type": INSIGHT_SHIFT,
+            "key": "insights_shift_model_up",
+            "model": model,
+            "prev_pct": _round_pct(prev_pct),
+            "pct": _round_pct(pct),
+            "project": top_project,
+        }
+    return {
+        "type": INSIGHT_SHIFT,
+        "key": "insights_shift_model_up_plain",
+        "model": model,
+        "prev_pct": _round_pct(prev_pct),
+        "pct": _round_pct(pct),
+    }
+
+
+def _build_action(
+    change: dict[str, Any] | None,
+    spike: dict[str, Any] | None,
+    data: dict[str, Any],
+) -> dict[str, Any] | None:
+    if (
+        change is not None
+        and change.get("direction") == "up"
+        and _int_value(change.get("delta_pct")) >= 50
+    ):
+        return {"type": INSIGHT_ACTION, "key": "insights_action_watch_quota"}
+
+    if spike is not None:
+        summary = _mapping_value(data.get("summary"))
+        total_tokens = _int_value(summary.get("total_tokens")) if summary else 0
+        spike_tokens = _int_value(spike.get("tokens"))
+        if total_tokens <= 0:
+            return None
+        return {
+            "type": INSIGHT_ACTION,
+            "key": "insights_action_spike_share",
+            "date": spike["date"],
+            "share": round(spike_tokens / total_tokens * 100),
+        }
+    return None
+
+
+def _find_spike(raw_daily: object) -> dict[str, Any] | None:
+    daily = _daily_points(raw_daily)
+    if len(daily) < 2:
+        return None
+
+    token_values = [point["tokens"] for point in daily]
+    mean = sum(token_values) / len(token_values)
+    if mean <= 0.0:
+        return None
+
+    variance = sum((tokens - mean) ** 2 for tokens in token_values) / len(token_values)
+    stdev = sqrt(variance)
+    threshold = mean + stdev
+
+    candidates = [
+        point
+        for point in daily
+        if point["tokens"] > threshold
+        and point["tokens"] >= mean * _SPIKE_MULTIPLIER_THRESHOLD
+    ]
+    if not candidates:
+        return None
+
+    spike = sorted(candidates, key=lambda point: (-point["tokens"], point["date"]))[0]
+    return {
+        "date": spike["date"],
+        "tokens": spike["tokens"],
+        "cost_usd": _round_cost(spike["cost"]),
+        "mean_tokens": round(mean, 1),
+        "stdev_tokens": round(stdev, 1),
+        "mean_multiplier": round(spike["tokens"] / mean, 2),
+    }
+
+
+def _daily_points(raw_daily: object) -> list[dict[str, Any]]:
+    daily = _list_value(raw_daily)
+    points: list[dict[str, Any]] = []
+    for raw_point in daily:
+        point = _mapping_value(raw_point)
+        if point is None:
+            continue
+        date = _str_value(point.get("date"), "")
+        tokens = _int_value(point.get("tokens"))
+        if not date or tokens < 0:
+            continue
+        points.append(
+            {
+                "date": date,
+                "tokens": tokens,
+                "cost": _float_value(point.get("cost")),
+            }
+        )
+    return points
+
+
+def _first_mapping(value: object) -> dict[str, Any] | None:
+    items = _list_value(value)
+    if not items:
+        return None
+    return _mapping_value(items[0])
+
+
+def _mapping_value(value: object) -> dict[str, Any] | None:
+    if isinstance(value, dict):
+        return cast(dict[str, Any], value)
+    return None
+
+
+def _list_value(value: object) -> list[object]:
+    if isinstance(value, list):
+        return value
+    return []
+
+
+def _str_value(value: object, default: str) -> str:
+    if isinstance(value, str):
+        return value
+    return default
+
+
+def _int_value(value: object) -> int:
+    if isinstance(value, bool):
+        return 0
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    return 0
+
+
+def _float_value(value: object) -> float:
+    if isinstance(value, bool):
+        return 0.0
+    if isinstance(value, int | float):
+        return float(value)
+    return 0.0
+
+
+def _round_cost(value: float) -> float:
+    return round(value, 4)
+
+
+def _round_pct(value: float) -> float:
+    return round(value, 1)

analyzer/persona_loader.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from jsonl_utils import iter_jsonl_dicts
+from project_resolver import project_from_encoded_path, resolve_project_name
+from time_utils import parse_optional_iso8601_utc
+
+logger = logging.getLogger(__name__)
+
+CLAUDE_PROJECTS_DIR = Path(os.path.expanduser("~/.claude/projects"))
+_CACHE_TTL_SECONDS = 300.0
+_cache: dict[int, tuple[float, PersonaProfile]] = {}
+
+
+@dataclass(slots=True)
+class PersonaProfile:
+    hour_histogram: list[int]
+    top_projects: list[tuple[str, int]]
+    recent_titles: list[str]
+    total_sessions: int
+    total_messages: int
+    titles_by_session: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class _MetadataLine:
+    type: str
+    timestamp: datetime | None
+    session_id: str
+    cwd: str
+    title: str
+
+
+def load_profile(days_back: int = 30) -> PersonaProfile:
+    now = time.time()
+    cached = _cache.get(days_back)
+    if cached is not None:
+        cached_at, cached_profile = cached
+        if now - cached_at < _CACHE_TTL_SECONDS:
+            return cached_profile
+
+    profile = _load_profile_uncached(days_back)
+    _cache[days_back] = (now, profile)
+    return profile
+
+
+def _reset_cache() -> None:
+    _cache.clear()
+
+
+def _load_profile_uncached(days_back: int) -> PersonaProfile:
+    histogram = [0] * 24
+    sessions_by_project: dict[str, set[str]] = {}
+    message_sessions: set[str] = set()
+    session_last_message_at: dict[str, datetime] = {}
+    titles_by_session: dict[str, str] = {}
+    total_messages = 0
+
+    cutoff = datetime.now(UTC) - timedelta(days=max(0, days_back))
+    cutoff_ts = cutoff.timestamp()
+
+    if not CLAUDE_PROJECTS_DIR.is_dir():
+        return _empty_profile()
+
+    for jsonl_path in CLAUDE_PROJECTS_DIR.rglob("*.jsonl"):
+        try:
+            if jsonl_path.stat().st_mtime < cutoff_ts:
+                continue
+        except OSError as exc:
+            logger.warning("failed to stat Claude project log %s: %s", jsonl_path, exc)
+            continue
+
+        fallback_project = _project_from_path(jsonl_path)
+        try:
+            for data in iter_jsonl_dicts(jsonl_path, errors="replace"):
+                parsed = _parse_metadata_line(data)
+                if parsed is None:
+                    continue
+
+                session_id = parsed.session_id
+                if session_id:
+                    title = parsed.title.strip()
+                    if parsed.type == "ai-title" and title:
+                        titles_by_session[session_id] = title
+
+                timestamp = parsed.timestamp
+                if timestamp is None or timestamp < cutoff:
+                    continue
+
+                is_message = parsed.type in {"user", "assistant"}
+                if is_message:
+                    histogram[timestamp.astimezone().hour] += 1
+                    total_messages += 1
+
+                if session_id and is_message:
+                    project = _project_from_cwd(parsed.cwd) or fallback_project
+                    sessions_by_project.setdefault(project, set()).add(session_id)
+                    message_sessions.add(session_id)
+                    current_last = session_last_message_at.get(session_id)
+                    if current_last is None or timestamp > current_last:
+                        session_last_message_at[session_id] = timestamp
+        except OSError as exc:
+            logger.warning("failed to read Claude project log %s: %s", jsonl_path, exc)
+
+    project_counts = Counter(
+        {project: len(session_ids) for project, session_ids in sessions_by_project.items()}
+    )
+    top_projects = sorted(project_counts.items(), key=lambda item: (-item[1], item[0]))[:5]
+    recent_titles = _recent_unique_titles(titles_by_session, session_last_message_at)
+
+    return PersonaProfile(
+        hour_histogram=histogram,
+        top_projects=top_projects,
+        recent_titles=recent_titles,
+        total_sessions=len(message_sessions),
+        total_messages=total_messages,
+        titles_by_session=titles_by_session,
+    )
+
+
+def _empty_profile() -> PersonaProfile:
+    return PersonaProfile(
+        hour_histogram=[0] * 24,
+        top_projects=[],
+        recent_titles=[],
+        total_sessions=0,
+        total_messages=0,
+        titles_by_session={},
+    )
+
+
+def _parse_metadata_line(data: dict[str, Any]) -> _MetadataLine | None:
+    return _MetadataLine(
+        type=_as_str(data.get("type")),
+        timestamp=_parse_timestamp(data.get("timestamp")),
+        session_id=_as_str(data.get("sessionId") or data.get("session_id")),
+        cwd=_as_str(data.get("cwd")),
+        title=_as_str(data.get("aiTitle")),
+    )
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+    return parse_optional_iso8601_utc(value)
+
+
+def _project_from_cwd(cwd: str) -> str:
+    if not cwd:
+        return ""
+    return resolve_project_name(cwd)
+
+
+def _project_from_path(jsonl_path: Path) -> str:
+    return project_from_encoded_path(jsonl_path, CLAUDE_PROJECTS_DIR)
+
+
+def _recent_unique_titles(
+    titles_by_session: dict[str, str],
+    session_last_message_at: dict[str, datetime],
+) -> list[str]:
+    titles: list[str] = []
+    seen: set[str] = set()
+    ordered_sessions = sorted(
+        titles_by_session,
+        key=lambda session_id: session_last_message_at.get(
+            session_id,
+            datetime.min.replace(tzinfo=UTC),
+        ),
+        reverse=True,
+    )
+    for session_id in ordered_sessions:
+        if session_id not in session_last_message_at:
+            continue
+        title = titles_by_session[session_id]
+        normalized = title.strip()
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        titles.append(normalized)
+        if len(titles) >= 8:
+            break
+    return titles
+
+
+def _as_str(value: Any) -> str:
+    return value if isinstance(value, str) else ""