coding-agent-roi 0.1.0__py3-none-any.whl

agent_roi/core/pricing.py

@@ -0,0 +1,79 @@
+"""Per-model token pricing, used to turn token counts into USD cost.
+
+Prices are USD per 1M tokens. This table is intentionally simple and easy to
+edit; keep it current as providers change pricing. Unknown models fall back to a
+zero price so usage is still tracked (cost just shows as 0).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agent_roi.core.models import Interaction, ModelPricing
+
+
+@dataclass(frozen=True)
+class ModelPrice:
+    input: float
+    output: float
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+
+
+# Prices in USD per 1,000,000 tokens. Extend freely.
+PRICES: dict[str, ModelPrice] = {
+    "claude-opus-4-8": ModelPrice(input=15.0, output=75.0, cache_read=1.5, cache_write=18.75),
+    "claude-sonnet-4-6": ModelPrice(input=3.0, output=15.0, cache_read=0.3, cache_write=3.75),
+    "claude-haiku-4-5": ModelPrice(input=0.8, output=4.0, cache_read=0.08, cache_write=1.0),
+    "gpt-4o": ModelPrice(input=2.5, output=10.0),
+    "gpt-4o-mini": ModelPrice(input=0.15, output=0.6),
+    # Codex normalizes "gpt-5.5" -> "gpt-5-5". Pricing is approximate; edit to match
+    # your plan (see docs/configuration — pricing is user-verifiable).
+    "gpt-5-5": ModelPrice(input=1.25, output=10.0, cache_read=0.125),
+    "gpt-5": ModelPrice(input=1.25, output=10.0, cache_read=0.125),
+    # Gemini API list prices. Edit to match your plan; prefix-matched, so
+    # "gemini-2.5-pro" / "gemini-3-flash-preview" resolve to the right tier.
+    "gemini-3-pro": ModelPrice(input=2.0, output=12.0, cache_read=0.2),
+    "gemini-3-flash": ModelPrice(input=0.3, output=2.5, cache_read=0.03),
+    "gemini-2.5-pro": ModelPrice(input=1.25, output=10.0, cache_read=0.125),
+    "gemini-2.5-flash": ModelPrice(input=0.3, output=2.5, cache_read=0.03),
+    "gemini-2.0-flash": ModelPrice(input=0.1, output=0.4, cache_read=0.025),
+    "gemini": ModelPrice(input=0.3, output=2.5, cache_read=0.03),
+}
+
+_UNKNOWN = ModelPrice(input=0.0, output=0.0)
+
+
+def price_for(model: str) -> ModelPrice:
+    """Resolve a price by exact match, then by longest known prefix."""
+    if model in PRICES:
+        return PRICES[model]
+    candidates = [name for name in PRICES if model.startswith(name)]
+    if candidates:
+        return PRICES[max(candidates, key=len)]
+    return _UNKNOWN
+
+
+def all_prices() -> list[ModelPricing]:
+    """Return the full pricing table, so users can verify cost = usage x price."""
+    return [
+        ModelPricing(
+            model=name,
+            input=p.input,
+            output=p.output,
+            cache_read=p.cache_read,
+            cache_write=p.cache_write,
+        )
+        for name, p in sorted(PRICES.items())
+    ]
+
+
+def cost_of(interaction: Interaction) -> float:
+    """Compute the USD cost of a single interaction."""
+    p = price_for(interaction.model)
+    return (
+        interaction.input_tokens * p.input
+        + interaction.output_tokens * p.output
+        + interaction.cache_read_tokens * p.cache_read
+        + interaction.cache_write_tokens * p.cache_write
+    ) / 1_000_000

agent_roi/core/project.py

@@ -0,0 +1,52 @@
+"""Derive a coarse 'project' label from a working directory.
+
+This is only a *grouping hint* (the semantic topic still comes from the
+classifier). We map a cwd to the nearest meaningful root so that subfolders of
+one repo (``/repo`` and ``/repo/web``) collapse to the same project. Because
+collectors run over historical logs, the original directory may no longer exist,
+so we can't always stat ``.git`` — we fall back to a path heuristic.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Workspace parents whose immediate child is the actual project (e.g. the folder
+# under ~/Desktop or ~/projects is the project, not Desktop itself).
+_WORKSPACE_PARENTS = {"desktop", "documents", "projects", "code", "src", "repos", "dev", "work"}
+
+
+def project_for(cwd: str) -> str:
+    """Return a short project label for a working directory.
+
+    Empty or root cwds yield ``"unknown"``.
+    """
+    if not cwd or cwd in ("/", "."):
+        return "unknown"
+
+    path = Path(cwd)
+
+    # If the directory still exists, prefer a real git root.
+    git_root = _git_root(path)
+    if git_root is not None:
+        return git_root.name
+
+    # Otherwise: walk up until the parent looks like a workspace container, and
+    # take the child of that container as the project root.
+    parts = [p for p in path.parts if p not in ("/", "")]
+    for i, part in enumerate(parts):
+        if part.lower() in _WORKSPACE_PARENTS and i + 1 < len(parts):
+            return parts[i + 1]
+
+    # Fall back to the last path segment.
+    return path.name or "unknown"
+
+
+def _git_root(path: Path) -> Path | None:
+    try:
+        for candidate in (path, *path.parents):
+            if (candidate / ".git").exists():
+                return candidate
+    except OSError:
+        return None
+    return None

agent_roi/core/service.py

@@ -0,0 +1,172 @@
+"""High-level orchestration used by both the CLI and the API.
+
+Keeps the wiring of collectors -> storage -> classifier in one place so the CLI
+and REST layers stay thin.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from agent_roi.classify import SessionDoc, get_classifier
+from agent_roi.classify.base import UNCATEGORIZED
+from agent_roi.collectors import get_collectors
+from agent_roi.core.config import Config
+from agent_roi.core.models import (
+    CollectorStatus,
+    ModelPricing,
+    Rollup,
+    SessionDetail,
+    SessionSummary,
+    TimeSeriesBundle,
+    TopicBreakdown,
+)
+from agent_roi.core.pricing import all_prices
+from agent_roi.storage import Database
+
+
+class Service:
+    def __init__(self, config: Config | None = None) -> None:
+        self.config = config or Config.load()
+        self.db = Database(self.config.db_path)
+
+    def ingest(self) -> int:
+        """Collect interactions from all enabled tools and store them.
+
+        Returns the number of interactions processed.
+        """
+        collectors = get_collectors(self.config.collectors.enabled)
+        total = 0
+        for collector in collectors:
+            if not collector.is_available():
+                continue
+            total += self.db.upsert_many(collector.collect())
+        return total
+
+    def classify(self, limit: int | None = None, reclassify: bool = True) -> int:
+        """Group whole sessions into topics and apply them.
+
+        A session is one continuous piece of work, so we classify sessions as a
+        unit (not each interaction) and apply the discovered topic to all of a
+        session's rows. The classifier looks at all sessions together so it can
+        group the ones about the same kind of work — e.g. several sessions across
+        different repos that are all "auth refactor" — into one topic.
+
+        With ``reclassify`` (the default) every session is re-labeled, which keeps
+        the clustering globally consistent. Set it to False to only label sessions
+        that have no topic yet.
+
+        Returns the number of interactions newly classified.
+        """
+        if reclassify:
+            self.db.clear_topics()
+        sessions = (
+            self.db.all_sessions(limit=limit)
+            if reclassify
+            else self.db.unclassified_sessions(limit=limit)
+        )
+        if not sessions:
+            return 0
+        classifier = get_classifier(self.config.classifier)
+        docs = [
+            SessionDoc(session_id=s.session_id, project=s.project, summary=s.summary)
+            for s in sessions
+        ]
+        labels = classifier.label_sessions(docs)
+        updated = 0
+        for sess in sessions:
+            topic = labels.get(sess.session_id, UNCATEGORIZED)
+            updated += self.db.set_session_topic(sess.session_id, topic)
+        return updated
+
+    def refresh(self) -> dict[str, int]:
+        """Ingest fresh logs and re-classify everything in one step.
+
+        This is the one-button flow for the dashboard: pull new interactions from
+        every tool, then rebuild topics across the whole corpus.
+        """
+        ingested = self.ingest()
+        classified = self.classify()
+        return {"ingested": ingested, "classified": classified}
+
+    def report(
+        self,
+        dimension: str = "topic",
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> list[Rollup]:
+        """Aggregate usage/cost by 'topic', 'tool', or 'model' over a window."""
+        return self.db.rollup(dimension, start=start, end=end)
+
+    def topic_breakdown(
+        self,
+        topic: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> TopicBreakdown:
+        """Drill into one topic: how its tokens split across tools and models."""
+        return self.db.topic_breakdown(topic, start=start, end=end)
+
+    def sessions(
+        self,
+        topic: str | None = None,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[SessionSummary]:
+        """Per-session breakdown, optionally scoped to one topic and window."""
+        return self.db.sessions(topic=topic, start=start, end=end, limit=limit)
+
+    def session_detail(self, session_id: str) -> SessionDetail | None:
+        """One session's aggregate plus its individual interactions."""
+        return self.db.session_detail(session_id)
+
+    def timeseries(
+        self,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        granularity: str = "day",
+    ) -> TimeSeriesBundle:
+        """Usage trends for charts (day / week / month buckets)."""
+        return self.db.timeseries(start=start, end=end, granularity=granularity)
+
+    def pricing(self) -> list[ModelPricing]:
+        """The pricing table behind every cost figure (for verification)."""
+        return all_prices()
+
+    def sources(self) -> list[CollectorStatus]:
+        """Diagnostics for every enabled collector: where it looked, what it
+        found on disk, and how much is already in the database.
+
+        This is what makes detection transparent — users can see exactly why a
+        tool shows up (or doesn't) instead of guessing.
+        """
+        by_tool = {r.key: r for r in self.db.rollup("tool")}
+        statuses: list[CollectorStatus] = []
+        for collector in get_collectors(self.config.collectors.enabled):
+            available = collector.is_available()
+            files = collector.count_files()
+            roll = by_tool.get(collector.tool.value)
+            interactions = roll.interactions if roll else 0
+
+            note = collector.note()
+            if not note:
+                if not available:
+                    note = "No logs found on this machine."
+                elif files and interactions == 0:
+                    note = "Logs found but not ingested yet — run a refresh."
+
+            statuses.append(
+                CollectorStatus(
+                    name=collector.name,
+                    tool=collector.tool.value,
+                    available=available,
+                    search_paths=[str(p) for p in collector.search_paths()],
+                    log_files=files,
+                    interactions=interactions,
+                    tokens=roll.total_tokens if roll else 0,
+                    cost_usd=roll.cost_usd if roll else 0.0,
+                    note=note,
+                )
+            )
+        return statuses

agent_roi/core/timeframe.py

@@ -0,0 +1,76 @@
+"""Parse user-supplied time-window strings into datetimes.
+
+Accepts:
+- ISO dates: ``2026-05-01``
+- ISO datetimes: ``2026-05-01T12:00``
+- Shorthands: ``today``, ``7d`` (last 7 days), ``24h`` (last 24 hours),
+  ``30m`` (last 30 minutes), ``8w`` (last 8 weeks).
+
+Returns ``None`` for an empty string (meaning "no lower bound").
+
+``parse_until`` is the upper bound (exclusive): an ISO date includes that whole
+calendar day; ``today`` means through end of today.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta, timezone
+
+_SHORTHAND = re.compile(r"^(\d+)\s*([mhdw])$", re.IGNORECASE)
+_UNIT_TO_DELTA = {
+    "m": lambda n: timedelta(minutes=n),
+    "h": lambda n: timedelta(hours=n),
+    "d": lambda n: timedelta(days=n),
+    "w": lambda n: timedelta(weeks=n),
+}
+
+
+def parse_since(value: str, *, now: datetime | None = None) -> datetime | None:
+    """Parse a window-start string. Raises ``ValueError`` on bad input."""
+    value = value.strip()
+    if not value:
+        return None
+    now = now or datetime.now(tz=timezone.utc)
+
+    if value.lower() == "today":
+        return now.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    match = _SHORTHAND.match(value)
+    if match:
+        amount = int(match.group(1))
+        unit = match.group(2).lower()
+        return now - _UNIT_TO_DELTA[unit](amount)
+
+    # Fall back to ISO date / datetime.
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(
+            f"Could not parse time '{value}'. Use a date (YYYY-MM-DD) or 7d/24h/today."
+        ) from exc
+
+
+def parse_until(value: str, *, now: datetime | None = None) -> datetime | None:
+    """Parse a window-end string (exclusive). Raises ``ValueError`` on bad input."""
+    value = value.strip()
+    if not value:
+        return None
+    now = now or datetime.now(tz=timezone.utc)
+
+    if value.lower() == "today":
+        start_today = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        return start_today + timedelta(days=1)
+
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(
+            f"Could not parse end time '{value}'. Use a date (YYYY-MM-DD) or today."
+        ) from exc
+
+    # Bare YYYY-MM-DD → include the full calendar day.
+    if re.fullmatch(r"\d{4}-\d{2}-\d{2}", value):
+        d = date.fromisoformat(value)
+        return datetime(d.year, d.month, d.day) + timedelta(days=1)
+    return parsed

agent_roi/core/tokens.py

@@ -0,0 +1,30 @@
+"""Token estimation for tools that don't report real usage.
+
+Some tools (notably GitHub Copilot) log the conversation text but not the token
+counts. For those, we estimate counts so cost can still be *approximated* and
+compared across tools. Estimated interactions are flagged
+(``Interaction.estimated = True``) so reports never present them as exact.
+
+The estimator is a dependency-free heuristic so it works fully offline (this is
+a local-first tool). It blends a character-based and word-based estimate, which
+tracks real BPE token counts closely enough for reporting — typically within
+~10-15% for mixed English/code text. We deliberately avoid pulling a tokenizer
+that downloads model files at runtime.
+"""
+
+from __future__ import annotations
+
+# Empirically, English + code averages ~4 characters per token, and tokens run
+# ~1.3x the whitespace-delimited word count. Averaging the two estimates is more
+# robust than either alone across prose, code, and JSON-heavy text.
+_CHARS_PER_TOKEN = 4.0
+_TOKENS_PER_WORD = 1.3
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate the number of tokens in a piece of text (offline heuristic)."""
+    if not text:
+        return 0
+    char_estimate = len(text) / _CHARS_PER_TOKEN
+    word_estimate = len(text.split()) * _TOKENS_PER_WORD
+    return max(1, round((char_estimate + word_estimate) / 2))

agent_roi/storage/__init__.py

@@ -0,0 +1,5 @@
+"""Storage layer."""
+
+from agent_roi.storage.db import Database
+
+__all__ = ["Database"]