artificial-intelligence-usage 0.0.1__py3-none-any.whl

artificial_intelligence_usage-0.0.1.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: artificial-intelligence-usage
+Version: 0.0.1
+Summary: Analyze recent Codex sessions and report usage information.
+Author: Kaizten Analytics
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Artificial Intelligence Usage
+
+`artificial-intelligence-usage` analyzes local Codex session rollouts and prints a summary of the
+latest session followed by daily session, turn, token, and rate-limit usage.
+
+## Behavior
+
+- Reads rollout files below `~/.codex/sessions`.
+- Shows status details from the most recently modified session.
+- Reports sessions from the last 14 calendar days by default, including today.
+- Counts user turns and cumulative tokens for each session.
+- Shows the remaining five-hour and weekly allowance recorded in each day's
+  last session.
+- Ignores malformed JSON lines and incomplete status events.
+
+The tool only reads local session files and does not modify them.
+
+## Requirements
+
+- Python 3.10 or newer
+
+## Building
+
+### Testing
+
+Run the unit tests from the project root:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+### Package artifact
+
+Build and validate the package artifacts:
+
+```bash
+./build-package.sh
+```
+
+This creates the wheel and source distribution under `dist/` and checks the
+package metadata with Twine.
+
+### Publish artifact
+
+Publish the generated artifacts to PyPI:
+
+```bash
+./publish-pypi.sh
+```
+
+The publish script checks that Twine is available, creates a local `.venv` for
+Twine when needed, verifies that `dist/` contains generated artifacts, and then
+uploads them. If PyPI rejects a version that was already published, increment
+the version in `pyproject.toml`, rebuild, and publish again.
+
+### Install artifact
+
+Install the package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install artificial-intelligence-usage
+```
+
+## Usage
+
+After installation, run:
+
+```bash
+artificial-intelligence-usage
+```
+
+Choose a different reporting window with `--days`:
+
+```bash
+artificial-intelligence-usage --days 30
+```
+
+From a source checkout, `./artificial-intelligence-usage.py` is the canonical launcher and
+`./script-sessions.py` remains available for compatibility.
+
+### Help
+
+```text
+usage: artificial-intelligence-usage [-h] [--days DAYS]
+
+Analyze recent Codex sessions.
+
+options:
+  -h, --help   show this help message and exit
+  --days DAYS  number of calendar days to analyze, including today (default: 14)
+```

artificial_intelligence_usage-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+artificial_intelligence_usage.py,sha256=EU0cZYMuPCmiSsxmjCGHeAq_hH1YY1Wm5XLnMXnBIB0,11833
+artificial_intelligence_usage-0.0.1.dist-info/METADATA,sha256=6n7Kzz9ekTTB19s0i8Nacka6d9bSDjygYqwW_ViIDf4,2603
+artificial_intelligence_usage-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+artificial_intelligence_usage-0.0.1.dist-info/entry_points.txt,sha256=fRIVhzZwrPaY8XgzLcvJJzEeE4XIcpieUMVIrGyDNik,85
+artificial_intelligence_usage-0.0.1.dist-info/top_level.txt,sha256=tw7aL5OTKRgpxRL_BKQXOQgb8OHoT7NE9yK6fhpD0kU,30
+artificial_intelligence_usage-0.0.1.dist-info/RECORD,,

artificial_intelligence_usage-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

artificial_intelligence_usage-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+artificial-intelligence-usage = artificial_intelligence_usage:main

artificial_intelligence_usage-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+artificial_intelligence_usage

artificial_intelligence_usage.py

@@ -0,0 +1,359 @@
+#!/usr/bin/env python3
+"""Analyze recent Codex sessions and report usage information."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter, defaultdict
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_DAYS = 14
+
+
+def positive_int(value: str) -> int:
+    """Return value as a positive integer for command-line arguments."""
+    try:
+        number = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("must be an integer") from error
+
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+
+    return number
+
+
+def format_timestamp(value: str | int | float | None) -> str:
+    """Format an ISO or Unix timestamp in the local timezone."""
+    try:
+        if isinstance(value, str):
+            timestamp = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        elif isinstance(value, (int, float)):
+            timestamp = datetime.fromtimestamp(value).astimezone()
+        else:
+            return "unknown"
+
+        return timestamp.astimezone().strftime("%Y-%m-%d %H:%M %Z")
+    except (OverflowError, OSError, ValueError):
+        return "unknown"
+
+
+def format_window(minutes: Any) -> str:
+    """Return a compact label for a rate-limit window."""
+    if not isinstance(minutes, (int, float)):
+        return "Rate limit"
+    if minutes % (7 * 24 * 60) == 0:
+        return f"{minutes / (7 * 24 * 60):g}w limit"
+    if minutes % (24 * 60) == 0:
+        return f"{minutes / (24 * 60):g}d limit"
+    if minutes % 60 == 0:
+        return f"{minutes / 60:g}h limit"
+    return f"{minutes:g}m limit"
+
+
+def read_status(session_file: Path | None) -> dict[str, Any]:
+    """Read the latest status-related values from a Codex rollout."""
+    status: dict[str, Any] = {
+        "session": {},
+        "context": {},
+        "token_count": {},
+        "updated_at": None,
+    }
+
+    if session_file is None:
+        return status
+
+    try:
+        with session_file.open("r", encoding="utf-8") as file_handle:
+            for line in file_handle:
+                try:
+                    event = json.loads(line)
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    continue
+
+                status["updated_at"] = event.get("timestamp") or status["updated_at"]
+                payload = event.get("payload") or {}
+
+                if event.get("type") == "session_meta":
+                    status["session"] = payload
+                elif event.get("type") == "turn_context":
+                    status["context"] = payload
+                elif (
+                    event.get("type") == "event_msg"
+                    and payload.get("type") == "token_count"
+                ):
+                    status["token_count"] = payload
+    except (OSError, UnicodeError):
+        pass
+
+    return status
+
+
+def print_rate_limit(limit: Any, fallback_label: str) -> None:
+    """Print one rate-limit window from a token-count event."""
+    if not isinstance(limit, dict):
+        print(f"{fallback_label + ':':<16} unknown")
+        return
+
+    label = format_window(limit.get("window_minutes"))
+    used_percent = limit.get("used_percent")
+    remaining = (
+        max(0.0, 100.0 - float(used_percent))
+        if isinstance(used_percent, (int, float))
+        else None
+    )
+    availability = f"{remaining:g}% remaining" if remaining is not None else "unknown"
+    reset = format_timestamp(limit.get("resets_at"))
+    print(f"{label + ':':<16} {availability} (resets {reset})")
+
+
+def format_remaining(limit: Any) -> str:
+    """Return the remaining allowance for one rate-limit window."""
+    if not isinstance(limit, dict):
+        return "unknown"
+
+    used_percent = limit.get("used_percent")
+    if not isinstance(used_percent, (int, float)):
+        return "unknown"
+
+    remaining = min(100.0, max(0.0, 100.0 - float(used_percent)))
+    return f"{remaining:g}% remaining"
+
+
+def session_rate_limits(session_file: Path) -> tuple[str, str]:
+    """Return the 5-hour and weekly limits recorded by one session."""
+    token_count = read_status(session_file)["token_count"]
+    rate_limits = token_count.get("rate_limits") or {}
+    limits = [rate_limits.get("primary"), rate_limits.get("secondary")]
+
+    five_hour = next(
+        (
+            limit
+            for limit in limits
+            if isinstance(limit, dict) and limit.get("window_minutes") == 5 * 60
+        ),
+        rate_limits.get("primary"),
+    )
+    weekly = next(
+        (
+            limit
+            for limit in limits
+            if isinstance(limit, dict)
+            and limit.get("window_minutes") == 7 * 24 * 60
+        ),
+        rate_limits.get("secondary"),
+    )
+
+    return format_remaining(five_hour), format_remaining(weekly)
+
+
+def print_status(session_file: Path | None) -> None:
+    """Print a /status-like summary for the latest Codex session."""
+    status = read_status(session_file)
+    session = status["session"]
+    context = status["context"]
+    token_count = status["token_count"]
+    info = token_count.get("info") or {}
+    total_usage = info.get("total_token_usage") or {}
+    last_usage = info.get("last_token_usage") or {}
+    rate_limits = token_count.get("rate_limits") or {}
+
+    model = context.get("model") or "unknown"
+    effort = context.get("effort")
+    if effort:
+        model = f"{model} ({effort})"
+
+    sandbox = (context.get("sandbox_policy") or {}).get("type") or "unknown"
+    approval_policy = context.get("approval_policy") or {}
+    approval = next(iter(approval_policy), "unknown")
+
+    current_tokens = last_usage.get("total_tokens")
+    context_window = info.get("model_context_window")
+    if isinstance(current_tokens, (int, float)) and isinstance(
+        context_window, (int, float)
+    ):
+        context_percent = min(100.0, current_tokens / context_window * 100)
+        context_value = (
+            f"{int(current_tokens):,} / {int(context_window):,} tokens "
+            f"({context_percent:.1f}% used)"
+        )
+    else:
+        context_value = "unknown"
+
+    total_tokens = total_usage.get("total_tokens")
+    total_value = (
+        f"{int(total_tokens):,}"
+        if isinstance(total_tokens, (int, float))
+        else "unknown"
+    )
+
+    print("Codex status (latest session)")
+    print("-" * 57)
+    print(f"{'Updated:':<16} {format_timestamp(status['updated_at'])}")
+    print(
+        f"{'Session:':<16} "
+        f"{session.get('session_id') or session.get('id') or 'unknown'}"
+    )
+    print(f"{'Codex CLI:':<16} {session.get('cli_version') or 'unknown'}")
+    print(f"{'Model:':<16} {model}")
+    print(
+        f"{'Workspace:':<16} "
+        f"{context.get('cwd') or session.get('cwd') or 'unknown'}"
+    )
+    print(f"{'Permissions:':<16} {sandbox} (approval: {approval})")
+    print(f"{'Context:':<16} {context_value}")
+    print(f"{'Session tokens:':<16} {total_value}")
+    print(f"{'Plan:':<16} {rate_limits.get('plan_type') or 'unknown'}")
+    print_rate_limit(rate_limits.get("primary"), "Primary limit")
+    print_rate_limit(rate_limits.get("secondary"), "Secondary limit")
+    print()
+
+
+def analyze_session(session_file: Path) -> tuple[int, int]:
+    """Return ``(user_turns, total_tokens)`` for one Codex session."""
+    turns = 0
+    total_tokens = 0
+
+    with session_file.open("r", encoding="utf-8") as file_handle:
+        for line in file_handle:
+            try:
+                event = json.loads(line)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                continue
+
+            payload = event.get("payload") or {}
+
+            if (
+                event.get("type") == "response_item"
+                and payload.get("type") == "message"
+                and payload.get("role") == "user"
+            ):
+                turns += 1
+
+            if (
+                event.get("type") == "event_msg"
+                and payload.get("type") == "token_count"
+            ):
+                info = payload.get("info") or {}
+                usage = info.get("total_token_usage") or {}
+                value = usage.get("total_tokens")
+
+                if isinstance(value, (int, float)):
+                    total_tokens = max(total_tokens, int(value))
+
+    return turns, total_tokens
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = argparse.ArgumentParser(description="Analyze recent Codex sessions.")
+    parser.add_argument(
+        "--days",
+        type=positive_int,
+        default=DEFAULT_DAYS,
+        help=f"number of calendar days to analyze, including today (default: {DEFAULT_DAYS})",
+    )
+    return parser
+
+
+def run_report(sessions_dir: Path, days: int, today: date | None = None) -> int:
+    """Analyze sessions and print the status and daily usage report."""
+    current_day = today or date.today()
+    first_day = current_day - timedelta(days=days - 1)
+    session_counts: Counter[str] = Counter()
+    turn_counts: defaultdict[str, list[int]] = defaultdict(list)
+    token_counts: Counter[str] = Counter()
+    last_session_by_date: dict[str, Path] = {}
+
+    all_session_files = list(sessions_dir.glob("*/*/*/rollout-*.jsonl"))
+    latest_session = (
+        max(all_session_files, key=lambda path: path.stat().st_mtime)
+        if all_session_files
+        else None
+    )
+    print_status(latest_session)
+
+    for session_file in all_session_files:
+        relative = session_file.relative_to(sessions_dir)
+        year, month, day = relative.parts[:3]
+        date_label = f"{year}-{month}-{day}"
+
+        try:
+            session_date = date.fromisoformat(date_label)
+        except ValueError:
+            continue
+
+        if not first_day <= session_date <= current_day:
+            continue
+
+        turns, tokens = analyze_session(session_file)
+        session_counts[date_label] += 1
+        turn_counts[date_label].append(turns)
+        token_counts[date_label] += tokens
+
+        previous_last = last_session_by_date.get(date_label)
+        if previous_last is None or session_file.name > previous_last.name:
+            last_session_by_date[date_label] = session_file
+
+    if not session_counts:
+        print(f"No Codex sessions found in the last {days} days in {sessions_dir}")
+        return 0
+
+    print(
+        f"{'Date':<12} "
+        f"{'Sessions':>8} "
+        f"{'Turns':>8} "
+        f"{'Avg turns':>10} "
+        f"{'Tokens':>15} "
+        f"{'5h last session':>17} "
+        f"{'Weekly last session':>20}"
+    )
+    print("-" * 96)
+
+    for date_label in sorted(session_counts):
+        sessions = session_counts[date_label]
+        total_turns = sum(turn_counts[date_label])
+        avg_turns = total_turns / sessions
+        tokens = token_counts[date_label]
+        five_hour, weekly = session_rate_limits(last_session_by_date[date_label])
+
+        print(
+            f"{date_label:<12} "
+            f"{sessions:>8} "
+            f"{total_turns:>8} "
+            f"{avg_turns:>10.1f} "
+            f"{tokens:>15,} "
+            f"{five_hour:>17} "
+            f"{weekly:>20}"
+        )
+
+    total_sessions = sum(session_counts.values())
+    total_turns = sum(sum(turns) for turns in turn_counts.values())
+    total_tokens = sum(token_counts.values())
+    overall_average = total_turns / total_sessions
+
+    print("-" * 96)
+    print(
+        f"{'Total':<12} "
+        f"{total_sessions:>8} "
+        f"{total_turns:>8} "
+        f"{overall_average:>10.1f} "
+        f"{total_tokens:>15,} "
+        f"{'-':>17} "
+        f"{'-':>20}"
+    )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the artificial-intelligence-usage command."""
+    args = build_parser().parse_args(argv)
+    return run_report(Path.home() / ".codex" / "sessions", args.days)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())