code-meter 0.1.0__py3-none-any.whl

code_meter/__init__.py

@@ -0,0 +1,3 @@
+"""code-meter: Local AI coding token usage tracker and cost estimator."""
+
+__version__ = "0.1.0"

code_meter/analytics/__init__.py

@@ -0,0 +1,7 @@
+"""Analytics engine package."""
+
+from code_meter.analytics.tokens import TokenAnalytics
+from code_meter.analytics.costs import CostAnalytics
+from code_meter.analytics.reports import ReportGenerator
+
+__all__ = ["TokenAnalytics", "CostAnalytics", "ReportGenerator"]

code_meter/analytics/costs.py

@@ -0,0 +1,43 @@
+"""Cost analytics computations."""
+
+from typing import List, Optional, Tuple
+from code_meter.models.usage import UsageRecord
+from code_meter.pricing.engine import PricingEngine
+
+
+class CostAnalytics:
+    """Calculates cumulative and per-record estimated costs."""
+
+    @staticmethod
+    def compute_record_costs(
+        records: List[UsageRecord],
+        pricing_engine: PricingEngine,
+    ) -> Tuple[List[Optional[float]], Optional[float], int]:
+        """
+        Compute cost for each record.
+        Returns (costs_list, total_cost_usd, unpriced_count).
+        """
+        costs: List[Optional[float]] = []
+        total_cost: float = 0.0
+        has_any_priced = False
+        unpriced_count = 0
+
+        for r in records:
+            c = pricing_engine.calculate_cost(
+                provider=r.provider,
+                model=r.model,
+                input_tokens=r.input_tokens,
+                output_tokens=r.output_tokens,
+                cache_read_tokens=r.cache_read_tokens,
+                cache_write_tokens=r.cache_write_tokens,
+                timestamp=r.timestamp,
+            )
+            costs.append(c)
+            if c is not None:
+                total_cost += c
+                has_any_priced = True
+            else:
+                unpriced_count += 1
+
+        final_total = round(total_cost, 4) if has_any_priced else None
+        return costs, final_total, unpriced_count

code_meter/analytics/reports.py

@@ -0,0 +1,357 @@
+"""Report generator for aggregating records by model, project, session, day, and exporting."""
+
+import csv
+import json
+from collections import defaultdict
+from datetime import datetime, timezone
+from io import StringIO
+from typing import Any, Dict, List, Optional
+
+from code_meter.analytics.costs import CostAnalytics
+from code_meter.analytics.tokens import TokenAnalytics
+from code_meter.models.project import (
+    AggregateSummary,
+    DailyStats,
+    ModelStats,
+    ProjectStats,
+    SessionStats,
+)
+from code_meter.models.usage import UsageRecord
+from code_meter.pricing.engine import PricingEngine
+
+
+class ReportGenerator:
+    """Generates structured summaries and export formats from raw UsageRecords."""
+
+    def __init__(self, pricing_engine: PricingEngine):
+        self.pricing_engine = pricing_engine
+
+    def generate_summary(
+        self,
+        records: List[UsageRecord],
+        filter_date_str: Optional[str] = None,
+    ) -> AggregateSummary:
+        """Build complete AggregateSummary from a list of UsageRecords."""
+        if not records:
+            return AggregateSummary()
+
+        inp, out, read, write, total_tokens = TokenAnalytics.calculate_totals(records)
+        record_costs, total_cost, unpriced_count = CostAnalytics.compute_record_costs(
+            records, self.pricing_engine
+        )
+
+        tokens_per_hr, tokens_per_day, cost_per_hr, cost_per_day = TokenAnalytics.calculate_burn_rate(
+            records, total_tokens, total_cost
+        )
+
+        by_model = self.aggregate_by_model(records, record_costs)
+        by_project = self.aggregate_by_project(records, record_costs)
+
+        today_date = filter_date_str or datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        today_records_with_costs = [
+            (r, c) for r, c in zip(records, record_costs)
+            if r.timestamp.strftime("%Y-%m-%d") == today_date
+        ]
+        today_summary = None
+        if today_records_with_costs:
+            today_records = [rc[0] for rc in today_records_with_costs]
+            t_inp, t_out, t_read, t_write, t_total = TokenAnalytics.calculate_totals(today_records)
+            t_costs = [rc[1] for rc in today_records_with_costs if rc[1] is not None]
+            t_cost_val = round(sum(t_costs), 4) if t_costs else None
+
+            today_summary = DailyStats(
+                date_str=today_date,
+                request_count=len(today_records),
+                input_tokens=t_inp,
+                output_tokens=t_out,
+                cache_read_tokens=t_read,
+                cache_write_tokens=t_write,
+                total_tokens=t_total,
+                estimated_cost_usd=t_cost_val,
+            )
+
+        return AggregateSummary(
+            total_requests=len(records),
+            input_tokens=inp,
+            output_tokens=out,
+            cache_read_tokens=read,
+            cache_write_tokens=write,
+            total_tokens=total_tokens,
+            estimated_cost_usd=total_cost,
+            unpriced_requests=unpriced_count,
+            tokens_per_hour=tokens_per_hr,
+            tokens_per_day=tokens_per_day,
+            cost_per_hour=cost_per_hr,
+            cost_per_day=cost_per_day,
+            by_model=by_model,
+            by_project=by_project,
+            today_summary=today_summary,
+        )
+
+    def aggregate_by_model(
+        self, records: List[UsageRecord], record_costs: List[Optional[float]]
+    ) -> List[ModelStats]:
+        """Aggregate stats grouped by AI model."""
+        groups: Dict[str, Dict[str, Any]] = defaultdict(
+            lambda: {
+                "request_count": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cache_read_tokens": 0,
+                "cache_write_tokens": 0,
+                "cost": 0.0,
+                "has_priced": False,
+            }
+        )
+
+        for r, cost in zip(records, record_costs):
+            g = groups[r.model]
+            g["request_count"] += 1
+            g["input_tokens"] += r.input_tokens
+            g["output_tokens"] += r.output_tokens
+            g["cache_read_tokens"] += r.cache_read_tokens
+            g["cache_write_tokens"] += r.cache_write_tokens
+            if cost is not None:
+                g["cost"] += cost
+                g["has_priced"] = True
+
+        result: List[ModelStats] = []
+        for model, g in groups.items():
+            tot = g["input_tokens"] + g["output_tokens"] + g["cache_read_tokens"] + g["cache_write_tokens"]
+            c_val = round(g["cost"], 4) if g["has_priced"] else None
+            result.append(
+                ModelStats(
+                    model=model,
+                    request_count=g["request_count"],
+                    input_tokens=g["input_tokens"],
+                    output_tokens=g["output_tokens"],
+                    cache_read_tokens=g["cache_read_tokens"],
+                    cache_write_tokens=g["cache_write_tokens"],
+                    total_tokens=tot,
+                    estimated_cost_usd=c_val,
+                )
+            )
+
+        result.sort(key=lambda x: x.total_tokens, reverse=True)
+        return result
+
+    def aggregate_by_project(
+        self, records: List[UsageRecord], record_costs: List[Optional[float]]
+    ) -> List[ProjectStats]:
+        """Aggregate stats grouped by project/directory."""
+        groups: Dict[str, Dict[str, Any]] = defaultdict(
+            lambda: {
+                "project_path": None,
+                "request_count": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cache_read_tokens": 0,
+                "cache_write_tokens": 0,
+                "cost": 0.0,
+                "has_priced": False,
+            }
+        )
+
+        for r, cost in zip(records, record_costs):
+            p_name = r.project_id or "Default/Unknown"
+            g = groups[p_name]
+            if not g["project_path"] and r.project_path:
+                g["project_path"] = r.project_path
+            g["request_count"] += 1
+            g["input_tokens"] += r.input_tokens
+            g["output_tokens"] += r.output_tokens
+            g["cache_read_tokens"] += r.cache_read_tokens
+            g["cache_write_tokens"] += r.cache_write_tokens
+            if cost is not None:
+                g["cost"] += cost
+                g["has_priced"] = True
+
+        result: List[ProjectStats] = []
+        for p_name, g in groups.items():
+            tot = g["input_tokens"] + g["output_tokens"] + g["cache_read_tokens"] + g["cache_write_tokens"]
+            c_val = round(g["cost"], 4) if g["has_priced"] else None
+            result.append(
+                ProjectStats(
+                    project_name=p_name,
+                    project_path=g["project_path"],
+                    request_count=g["request_count"],
+                    input_tokens=g["input_tokens"],
+                    output_tokens=g["output_tokens"],
+                    cache_read_tokens=g["cache_read_tokens"],
+                    cache_write_tokens=g["cache_write_tokens"],
+                    total_tokens=tot,
+                    estimated_cost_usd=c_val,
+                )
+            )
+
+        result.sort(key=lambda x: x.total_tokens, reverse=True)
+        return result
+
+    def aggregate_by_session(
+        self, records: List[UsageRecord], record_costs: List[Optional[float]]
+    ) -> List[SessionStats]:
+        """Aggregate stats grouped by session ID."""
+        groups: Dict[str, Dict[str, Any]] = defaultdict(
+            lambda: {
+                "project_name": "Unknown",
+                "project_path": None,
+                "models": defaultdict(int),
+                "request_count": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cache_read_tokens": 0,
+                "cache_write_tokens": 0,
+                "cost": 0.0,
+                "has_priced": False,
+                "first_seen": None,
+                "last_seen": None,
+            }
+        )
+
+        for r, cost in zip(records, record_costs):
+            s_id = r.session_id or "unknown_session"
+            g = groups[s_id]
+
+            if r.project_id:
+                g["project_name"] = r.project_id
+            if r.project_path:
+                g["project_path"] = r.project_path
+
+            g["models"][r.model] += 1
+            g["request_count"] += 1
+            g["input_tokens"] += r.input_tokens
+            g["output_tokens"] += r.output_tokens
+            g["cache_read_tokens"] += r.cache_read_tokens
+            g["cache_write_tokens"] += r.cache_write_tokens
+
+            if cost is not None:
+                g["cost"] += cost
+                g["has_priced"] = True
+
+            ts_str = r.timestamp.isoformat()
+            if not g["first_seen"] or ts_str < g["first_seen"]:
+                g["first_seen"] = ts_str
+            if not g["last_seen"] or ts_str > g["last_seen"]:
+                g["last_seen"] = ts_str
+
+        result: List[SessionStats] = []
+        for s_id, g in groups.items():
+            primary_model = max(g["models"].items(), key=lambda x: x[1])[0] if g["models"] else "Unknown"
+            tot = g["input_tokens"] + g["output_tokens"] + g["cache_read_tokens"] + g["cache_write_tokens"]
+            c_val = round(g["cost"], 4) if g["has_priced"] else None
+            result.append(
+                SessionStats(
+                    session_id=s_id,
+                    project_name=g["project_name"],
+                    project_path=g["project_path"],
+                    primary_model=primary_model,
+                    request_count=g["request_count"],
+                    input_tokens=g["input_tokens"],
+                    output_tokens=g["output_tokens"],
+                    cache_read_tokens=g["cache_read_tokens"],
+                    cache_write_tokens=g["cache_write_tokens"],
+                    total_tokens=tot,
+                    estimated_cost_usd=c_val,
+                    first_seen=g["first_seen"],
+                    last_seen=g["last_seen"],
+                )
+            )
+
+        result.sort(key=lambda x: x.last_seen or "", reverse=True)
+        return result
+
+    def aggregate_by_day(
+        self, records: List[UsageRecord], record_costs: List[Optional[float]]
+    ) -> List[DailyStats]:
+        """Aggregate stats grouped by day (YYYY-MM-DD)."""
+        groups: Dict[str, Dict[str, Any]] = defaultdict(
+            lambda: {
+                "request_count": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cache_read_tokens": 0,
+                "cache_write_tokens": 0,
+                "cost": 0.0,
+                "has_priced": False,
+            }
+        )
+
+        for r, cost in zip(records, record_costs):
+            d_str = r.timestamp.strftime("%Y-%m-%d")
+            g = groups[d_str]
+            g["request_count"] += 1
+            g["input_tokens"] += r.input_tokens
+            g["output_tokens"] += r.output_tokens
+            g["cache_read_tokens"] += r.cache_read_tokens
+            g["cache_write_tokens"] += r.cache_write_tokens
+            if cost is not None:
+                g["cost"] += cost
+                g["has_priced"] = True
+
+        result: List[DailyStats] = []
+        for d_str, g in groups.items():
+            tot = g["input_tokens"] + g["output_tokens"] + g["cache_read_tokens"] + g["cache_write_tokens"]
+            c_val = round(g["cost"], 4) if g["has_priced"] else None
+            result.append(
+                DailyStats(
+                    date_str=d_str,
+                    request_count=g["request_count"],
+                    input_tokens=g["input_tokens"],
+                    output_tokens=g["output_tokens"],
+                    cache_read_tokens=g["cache_read_tokens"],
+                    cache_write_tokens=g["cache_write_tokens"],
+                    total_tokens=tot,
+                    estimated_cost_usd=c_val,
+                )
+            )
+
+        result.sort(key=lambda x: x.date_str, reverse=True)
+        return result
+
+    def export_records(self, records: List[UsageRecord], fmt: str) -> str:
+        """Export UsageRecords to CSV or JSON format string."""
+        record_costs, _, _ = CostAnalytics.compute_record_costs(records, self.pricing_engine)
+
+        if fmt.lower() == "json":
+            export_list = []
+            for r, cost in zip(records, record_costs):
+                item = r.model_dump()
+                item["timestamp"] = r.timestamp.isoformat()
+                item["estimated_cost_usd"] = cost
+                export_list.append(item)
+            return json.dumps(export_list, indent=2)
+
+        output = StringIO()
+        writer = csv.writer(output)
+        writer.writerow([
+            "timestamp",
+            "provider",
+            "request_id",
+            "session_id",
+            "project",
+            "project_path",
+            "model",
+            "input_tokens",
+            "output_tokens",
+            "cache_read_tokens",
+            "cache_write_tokens",
+            "estimated_cost_usd",
+        ])
+
+        for r, cost in zip(records, record_costs):
+            writer.writerow([
+                r.timestamp.isoformat(),
+                r.provider,
+                r.request_id or "",
+                r.session_id or "",
+                r.project_id or "",
+                r.project_path or "",
+                r.model,
+                r.input_tokens,
+                r.output_tokens,
+                r.cache_read_tokens,
+                r.cache_write_tokens,
+                f"{cost:.6f}" if cost is not None else "",
+            ])
+
+        return output.getvalue()

code_meter/analytics/tokens.py

@@ -0,0 +1,51 @@
+"""Token analytics calculations (totals, burn rates, averages)."""
+
+from typing import List, Optional, Tuple
+from code_meter.models.usage import UsageRecord
+
+
+class TokenAnalytics:
+    """Utility methods for calculating token totals and burn rates."""
+
+    @staticmethod
+    def calculate_totals(records: List[UsageRecord]) -> Tuple[int, int, int, int, int]:
+        """Return (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, total_tokens)."""
+        inp = sum(r.input_tokens for r in records)
+        out = sum(r.output_tokens for r in records)
+        read = sum(r.cache_read_tokens for r in records)
+        write = sum(r.cache_write_tokens for r in records)
+        total = inp + out + read + write
+        return inp, out, read, write, total
+
+    @staticmethod
+    def calculate_burn_rate(
+        records: List[UsageRecord],
+        total_tokens: int,
+        total_cost: Optional[float],
+    ) -> Tuple[Optional[float], Optional[float], Optional[float], Optional[float]]:
+        """
+        Calculate burn rates:
+        Returns (tokens_per_hour, tokens_per_day, cost_per_hour, cost_per_day).
+        Returns None for values if there are fewer than 2 records or duration is 0.
+        """
+        if len(records) < 2:
+            return None, None, None, None
+
+        sorted_records = sorted(records, key=lambda r: r.timestamp)
+        first_ts = sorted_records[0].timestamp
+        last_ts = sorted_records[-1].timestamp
+
+        duration_seconds = (last_ts - first_ts).total_seconds()
+        if duration_seconds <= 60:
+            return None, None, None, None
+
+        duration_hours = duration_seconds / 3600.0
+        duration_days = duration_seconds / 86400.0
+
+        tokens_per_hour = round(total_tokens / duration_hours, 2)
+        tokens_per_day = round(total_tokens / duration_days, 2)
+
+        cost_per_hour = round(total_cost / duration_hours, 4) if total_cost is not None else None
+        cost_per_day = round(total_cost / duration_days, 4) if total_cost is not None else None
+
+        return tokens_per_hour, tokens_per_day, cost_per_hour, cost_per_day