tokenjam 0.2.0__py3-none-any.whl

tokenjam/utils/formatting.py

@@ -0,0 +1,43 @@
+from rich.console import Console
+from rich.table import Table
+from rich import box
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def severity_colour(severity: str) -> str:
+    return {"critical": "red", "warning": "yellow", "info": "blue"}.get(severity, "white")
+
+
+def status_icon(status: str) -> str:
+    return {
+        "ok": "\u2713",
+        "error": "\u2717",
+        "active": "\u25cf",
+        "idle": "\u25cb",
+        "completed": "\u25cf",
+        "stale": "\u25cb",
+    }.get(status, "?")
+
+
+def format_cost(usd: float) -> str:
+    if usd < 0.001:
+        return f"${usd:.6f}"
+    return f"${usd:.4f}"
+
+
+def format_tokens(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n/1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n/1_000:.1f}k"
+    return str(n)
+
+
+def make_table(*headers: str, box_style=box.SIMPLE) -> Table:
+    """Create a pre-styled Rich table."""
+    t = Table(box=box_style, show_header=True, header_style="bold dim")
+    for h in headers:
+        t.add_column(h)
+    return t

tokenjam/utils/ids.py

@@ -0,0 +1,15 @@
+import uuid
+
+
+def new_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def new_trace_id() -> str:
+    """Generate a 32-char hex trace ID (OTel format)."""
+    return uuid.uuid4().hex
+
+
+def new_span_id() -> str:
+    """Generate a 16-char hex span ID (OTel format)."""
+    return uuid.uuid4().hex[:16]

tokenjam/utils/time_parse.py

@@ -0,0 +1,54 @@
+from datetime import datetime, timedelta, timezone
+import re
+
+
+_RELATIVE_PATTERN = re.compile(r"^(\d+)([mhd])$")
+
+
+def parse_since(value: str) -> datetime:
+    """
+    Parse a --since value and return the corresponding UTC datetime.
+    Raises ValueError with a descriptive message for unrecognised formats.
+
+    Supported formats:
+    - 30m, 1h, 12h, 1d, 7d  (relative)
+    - 2026-03-01             (date, treated as start of day UTC)
+    - 2026-03-01T10:00:00Z   (ISO datetime)
+    """
+    value = value.strip()
+
+    match = _RELATIVE_PATTERN.match(value)
+    if match:
+        amount = int(match.group(1))
+        unit = match.group(2)
+        if amount == 0:
+            raise ValueError(f"Invalid --since value: {value!r} (amount must be > 0)")
+        delta_map = {"m": "minutes", "h": "hours", "d": "days"}
+        delta = timedelta(**{delta_map[unit]: amount})
+        return utcnow() - delta
+
+    # Try ISO datetime with timezone
+    try:
+        dt = datetime.fromisoformat(value)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+    except ValueError:
+        pass
+
+    # Try date-only format
+    try:
+        dt = datetime.strptime(value, "%Y-%m-%d")
+        return dt.replace(tzinfo=timezone.utc)
+    except ValueError:
+        pass
+
+    raise ValueError(
+        f"Unrecognised --since format: {value!r}. "
+        f"Expected: 30m, 1h, 7d, 2026-03-01, or 2026-03-01T10:00:00Z"
+    )
+
+
+def utcnow() -> datetime:
+    """Return current UTC time, timezone-aware."""
+    return datetime.now(tz=timezone.utc)