artificial-intelligence-usage 0.0.1__tar.gz

artificial_intelligence_usage-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "artificial-intelligence-usage"
+version = "0.0.1"
+description = "Analyze recent Codex sessions and report usage information."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Kaizten Analytics" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+artificial-intelligence-usage = "artificial_intelligence_usage:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+py-modules = ["artificial_intelligence_usage"]

artificial_intelligence_usage-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

artificial_intelligence_usage-0.0.1/src/artificial_intelligence_usage.egg-info/PKG-INFO

@@ -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/src/artificial_intelligence_usage.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/artificial_intelligence_usage.py
+src/artificial_intelligence_usage.egg-info/PKG-INFO
+src/artificial_intelligence_usage.egg-info/SOURCES.txt
+src/artificial_intelligence_usage.egg-info/dependency_links.txt
+src/artificial_intelligence_usage.egg-info/entry_points.txt
+src/artificial_intelligence_usage.egg-info/top_level.txt
+tests/test_artificial_intelligence_usage.py
+tests/test_publish_pypi.py

artificial_intelligence_usage-0.0.1/src/artificial_intelligence_usage.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

artificial_intelligence_usage-0.0.1/src/artificial_intelligence_usage.egg-info/entry_points.txt

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

artificial_intelligence_usage-0.0.1/src/artificial_intelligence_usage.egg-info/top_level.txt

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

artificial_intelligence_usage-0.0.1/src/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())

artificial_intelligence_usage-0.0.1/tests/test_artificial_intelligence_usage.py

@@ -0,0 +1,197 @@
+import contextlib
+import io
+import json
+import sys
+import tempfile
+import unittest
+from datetime import date
+from pathlib import Path
+from unittest.mock import patch
+
+
+SRC = Path(__file__).resolve().parents[1] / "src"
+sys.path.insert(0, str(SRC))
+
+import artificial_intelligence_usage
+
+
+class ArtificialIntelligenceUsageTests(unittest.TestCase):
+    def write_session(
+        self,
+        sessions_dir: Path,
+        day: date,
+        name: str,
+        events: list[dict],
+    ) -> Path:
+        target = sessions_dir / f"{day:%Y}" / f"{day:%m}" / f"{day:%d}"
+        target.mkdir(parents=True, exist_ok=True)
+        session_file = target / f"rollout-{name}.jsonl"
+        session_file.write_text(
+            "\n".join(json.dumps(event) for event in events) + "\n",
+            encoding="utf-8",
+        )
+        return session_file
+
+    def token_event(
+        self,
+        tokens: int,
+        five_hour_used: int = 25,
+        weekly_used: int = 40,
+    ) -> dict:
+        return {
+            "timestamp": "2026-10-04T10:00:00Z",
+            "type": "event_msg",
+            "payload": {
+                "type": "token_count",
+                "info": {
+                    "total_token_usage": {"total_tokens": tokens},
+                    "last_token_usage": {"total_tokens": 100},
+                    "model_context_window": 1000,
+                },
+                "rate_limits": {
+                    "plan_type": "team",
+                    "primary": {
+                        "window_minutes": 300,
+                        "used_percent": five_hour_used,
+                        "resets_at": 0,
+                    },
+                    "secondary": {
+                        "window_minutes": 10080,
+                        "used_percent": weekly_used,
+                        "resets_at": 0,
+                    },
+                },
+            },
+        }
+
+    def test_positive_int_accepts_positive_values(self):
+        self.assertEqual(artificial_intelligence_usage.positive_int("7"), 7)
+
+    def test_positive_int_rejects_zero_and_non_integer_values(self):
+        with self.assertRaisesRegex(Exception, "at least 1"):
+            artificial_intelligence_usage.positive_int("0")
+        with self.assertRaisesRegex(Exception, "must be an integer"):
+            artificial_intelligence_usage.positive_int("nope")
+
+    def test_analyze_session_ignores_malformed_lines_and_uses_maximum_tokens(self):
+        with tempfile.TemporaryDirectory() as directory:
+            session_file = Path(directory) / "rollout-test.jsonl"
+            session_file.write_text(
+                "not-json\n"
+                + json.dumps(
+                    {
+                        "type": "response_item",
+                        "payload": {"type": "message", "role": "user"},
+                    }
+                )
+                + "\n"
+                + json.dumps(self.token_event(120))
+                + "\n"
+                + json.dumps(self.token_event(95))
+                + "\n",
+                encoding="utf-8",
+            )
+
+            self.assertEqual(
+                artificial_intelligence_usage.analyze_session(session_file),
+                (1, 120),
+            )
+
+    def test_session_rate_limits_are_selected_by_window(self):
+        with tempfile.TemporaryDirectory() as directory:
+            session_file = Path(directory) / "rollout-test.jsonl"
+            event = self.token_event(100)
+            limits = event["payload"]["rate_limits"]
+            limits["primary"], limits["secondary"] = (
+                limits["secondary"],
+                limits["primary"],
+            )
+            session_file.write_text(json.dumps(event) + "\n", encoding="utf-8")
+
+            self.assertEqual(
+                artificial_intelligence_usage.session_rate_limits(session_file),
+                ("75% remaining", "60% remaining"),
+            )
+
+    def test_empty_directory_prints_status_and_no_sessions_message(self):
+        with tempfile.TemporaryDirectory() as directory:
+            output = io.StringIO()
+            with contextlib.redirect_stdout(output):
+                result = artificial_intelligence_usage.run_report(
+                    Path(directory), days=14, today=date(2026, 10, 4)
+                )
+
+        self.assertEqual(result, 0)
+        self.assertIn("Codex status (latest session)", output.getvalue())
+        self.assertIn("No Codex sessions found in the last 14 days", output.getvalue())
+
+    def test_report_aggregates_sessions_turns_tokens_and_limits(self):
+        with tempfile.TemporaryDirectory() as directory:
+            sessions_dir = Path(directory)
+            session_meta = {
+                "timestamp": "2026-10-04T09:00:00Z",
+                "type": "session_meta",
+                "payload": {"id": "session-1", "cli_version": "1.2.3"},
+            }
+            turn_context = {
+                "timestamp": "2026-10-04T09:01:00Z",
+                "type": "turn_context",
+                "payload": {
+                    "model": "gpt-test",
+                    "effort": "high",
+                    "cwd": "/work",
+                    "sandbox_policy": {"type": "workspace-write"},
+                    "approval_policy": {"on-request": {}},
+                },
+            }
+            user_turn = {
+                "type": "response_item",
+                "payload": {"type": "message", "role": "user"},
+            }
+            self.write_session(
+                sessions_dir,
+                date(2026, 10, 4),
+                "01",
+                [session_meta, turn_context, user_turn, self.token_event(100)],
+            )
+            self.write_session(
+                sessions_dir,
+                date(2026, 10, 4),
+                "02",
+                [user_turn, user_turn, self.token_event(250, 30, 45)],
+            )
+            self.write_session(
+                sessions_dir,
+                date(2026, 9, 1),
+                "old",
+                [user_turn, self.token_event(999)],
+            )
+
+            output = io.StringIO()
+            with contextlib.redirect_stdout(output):
+                result = artificial_intelligence_usage.run_report(
+                    sessions_dir, days=2, today=date(2026, 10, 4)
+                )
+
+        report = output.getvalue()
+        self.assertEqual(result, 0)
+        self.assertRegex(report, r"2026-10-04\s+2\s+3\s+1\.5\s+350")
+        self.assertIn("70% remaining", report)
+        self.assertIn("55% remaining", report)
+        daily_report = report[report.index("Date") :]
+        self.assertNotIn("999", daily_report)
+
+    def test_main_can_be_called_repeatedly(self):
+        with patch.object(
+            artificial_intelligence_usage, "run_report", return_value=0
+        ) as run_report:
+            self.assertEqual(artificial_intelligence_usage.main(["--days", "3"]), 0)
+            self.assertEqual(artificial_intelligence_usage.main(["--days", "5"]), 0)
+
+        self.assertEqual(run_report.call_count, 2)
+        self.assertEqual(run_report.call_args_list[0].args[1], 3)
+        self.assertEqual(run_report.call_args_list[1].args[1], 5)
+
+
+if __name__ == "__main__":
+    unittest.main()

artificial_intelligence_usage-0.0.1/tests/test_publish_pypi.py

@@ -0,0 +1,141 @@
+import os
+import shutil
+import stat
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+class PublishPypiScriptTests(unittest.TestCase):
+    def run_script_with_fake_python(
+        self,
+        fake_python_body: str,
+        create_dist: bool = True,
+        create_artifact: bool = True,
+    ):
+        source_script = Path(__file__).resolve().parents[1] / "publish-pypi.sh"
+
+        directory = tempfile.TemporaryDirectory()
+        self.addCleanup(directory.cleanup)
+        root = Path(directory.name)
+        script = root / "publish-pypi.sh"
+        shutil.copy(source_script, script)
+        script.chmod(script.stat().st_mode | stat.S_IXUSR)
+
+        if create_dist:
+            dist = root / "dist"
+            dist.mkdir()
+            if create_artifact:
+                (dist / "package-0.1.0.tar.gz").write_text(
+                    "artifact", encoding="utf-8"
+                )
+
+        bin_dir = root / "bin"
+        bin_dir.mkdir()
+        fake_python = bin_dir / "python3"
+        fake_python.write_text(fake_python_body, encoding="utf-8")
+        fake_python.chmod(fake_python.stat().st_mode | stat.S_IXUSR)
+
+        env = os.environ.copy()
+        env["PATH"] = f"{bin_dir}{os.pathsep}{env['PATH']}"
+
+        result = subprocess.run(
+            [str(script)],
+            cwd=root,
+            env=env,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return result, root
+
+    def test_reports_already_published_when_twine_returns_duplicate_400(self):
+        result, _root = self.run_script_with_fake_python(
+            """#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "-c" ]]; then exit 0; fi
+if [[ "$1" == "-m" && "$2" == "twine" && "$3" == "upload" ]]; then
+  echo "HTTPError: 400 Bad Request" >&2
+  echo "File already exists" >&2
+  exit 1
+fi
+exit 2
+"""
+        )
+
+        output = result.stdout + result.stderr
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("HTTP 400", output)
+        self.assertIn("already been published", output)
+
+    def test_requires_dist_directory(self):
+        result, _root = self.run_script_with_fake_python(
+            """#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "-c" ]]; then exit 0; fi
+exit 2
+""",
+            create_dist=False,
+        )
+
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("dist/ was not found", result.stderr)
+
+    def test_requires_dist_artifacts(self):
+        result, _root = self.run_script_with_fake_python(
+            """#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "-c" ]]; then exit 0; fi
+exit 2
+""",
+            create_artifact=False,
+        )
+
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("dist/ is empty", result.stderr)
+
+    def test_uploads_generated_dist_artifacts(self):
+        result, root = self.run_script_with_fake_python(
+            """#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "-c" ]]; then exit 0; fi
+if [[ "$1" == "-m" && "$2" == "twine" && "$3" == "upload" ]]; then
+  printf '%s\n' "$@" > upload-args.txt
+  echo "Uploaded"
+  exit 0
+fi
+exit 2
+"""
+        )
+
+        self.assertEqual(result.returncode, 0)
+        self.assertIn("Uploaded", result.stdout)
+        upload_args = (root / "upload-args.txt").read_text(
+            encoding="utf-8"
+        ).splitlines()
+        self.assertEqual(upload_args[:3], ["-m", "twine", "upload"])
+        self.assertIn("dist/package-0.1.0.tar.gz", upload_args)
+        self.assertIn("--verbose", upload_args)
+
+    def test_generic_twine_error_does_not_report_already_published(self):
+        result, _root = self.run_script_with_fake_python(
+            """#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "-c" ]]; then exit 0; fi
+if [[ "$1" == "-m" && "$2" == "twine" && "$3" == "upload" ]]; then
+  echo "HTTPError: 500 Server Error" >&2
+  exit 1
+fi
+exit 2
+"""
+        )
+
+        output = result.stdout + result.stderr
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("500 Server Error", output)
+        self.assertNotIn("already been published", output)
+
+
+if __name__ == "__main__":
+    unittest.main()