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

agent_roi/__init__.py

@@ -0,0 +1,3 @@
+"""Agent-ROI: track the cost, usage, and ROI of AI coding agents across tools."""
+
+__version__ = "0.1.0"

agent_roi/api/__init__.py

@@ -0,0 +1 @@
+"""REST API package."""

agent_roi/api/app.py

@@ -0,0 +1,179 @@
+"""REST API for the web dashboard.
+
+Thin layer over :class:`Service`. If a built web UI exists at ``web/dist`` it is
+served as static files so ``agent-roi serve`` gives a single-URL experience.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from agent_roi import __version__
+from agent_roi.core.platform import platform_label
+from agent_roi.core.service import Service
+from agent_roi.core.timeframe import parse_since, parse_until
+
+
+def create_app(service: Service | None = None) -> FastAPI:
+    svc: Service = service or Service()
+    app = FastAPI(title="Agent-ROI", version=__version__)
+
+    # Allow the React dev server (vite default port) during development.
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:5173"],
+        allow_methods=["GET", "POST"],
+        allow_headers=["*"],
+    )
+
+    @app.get("/api/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    @app.get("/api/report")
+    def report(
+        group_by: str = "topic",
+        since: str = "",
+        until: str = "",
+    ) -> list[dict[str, object]]:
+        """Usage/cost grouped by 'topic' | 'tool' | 'model', optionally windowed."""
+        if group_by not in ("topic", "tool", "model", "project"):
+            raise HTTPException(400, f"Invalid group_by: {group_by}")
+        start, end = _window(since, until)
+        return [
+            r.model_dump() | {"total_tokens": r.total_tokens}
+            for r in svc.report(dimension=group_by, start=start, end=end)
+        ]
+
+    @app.get("/api/report/topic/{topic}")
+    def topic_breakdown(topic: str, since: str = "", until: str = "") -> dict[str, object]:
+        """Drill into one topic: split by tool and by model."""
+        start, end = _window(since, until)
+        bd = svc.topic_breakdown(topic, start=start, end=end)
+        return {
+            "topic": bd.topic,
+            "total": bd.total.model_dump() | {"total_tokens": bd.total.total_tokens},
+            "by_tool": [r.model_dump() | {"total_tokens": r.total_tokens} for r in bd.by_tool],
+            "by_model": [r.model_dump() | {"total_tokens": r.total_tokens} for r in bd.by_model],
+        }
+
+    @app.get("/api/sessions")
+    def sessions(topic: str = "", since: str = "", until: str = "") -> list[dict[str, object]]:
+        """Per-session rows, optionally scoped to one topic and time window."""
+        start, end = _window(since, until)
+        rows = svc.sessions(topic=topic or None, start=start, end=end)
+        return [s.model_dump() | {"total_tokens": s.total_tokens} for s in rows]
+
+    @app.get("/api/sessions/{session_id}")
+    def session_detail(session_id: str) -> dict[str, object]:
+        """One session's aggregate plus the interactions (conversation turns)."""
+        detail = svc.session_detail(session_id)
+        if detail is None:
+            raise HTTPException(404, f"No session {session_id!r}")
+        return {
+            "session": detail.session.model_dump()
+            | {"total_tokens": detail.session.total_tokens},
+            "interactions": [
+                i.model_dump() | {"total_tokens": i.total_tokens}
+                for i in detail.interactions
+            ],
+        }
+
+    @app.get("/api/timeseries")
+    def timeseries(
+        since: str = "",
+        until: str = "",
+        granularity: str = "day",
+    ) -> dict[str, object]:
+        """Token/cost trends plus splits by tool and model."""
+        if granularity not in ("day", "week", "month"):
+            raise HTTPException(400, f"Invalid granularity: {granularity}")
+        start, end = _window(since, until)
+        bundle = svc.timeseries(start=start, end=end, granularity=granularity)
+        return {
+            "granularity": granularity,
+            "totals": [p.model_dump() | {"total_tokens": p.total_tokens} for p in bundle.totals],
+            "by_tool": [r.model_dump() for r in bundle.by_tool],
+            "by_model": [r.model_dump() for r in bundle.by_model],
+            "tool_keys": bundle.tool_keys,
+            "model_keys": bundle.model_keys,
+        }
+
+    @app.get("/api/pricing")
+    def pricing() -> list[dict[str, object]]:
+        """The pricing table behind every cost figure."""
+        return [p.model_dump() for p in svc.pricing()]
+
+    @app.get("/api/sources")
+    def sources() -> dict[str, object]:
+        """Collector diagnostics: which tools were detected and where."""
+        return {
+            "platform": platform_label(),
+            "collectors": [s.model_dump() for s in svc.sources()],
+        }
+
+    @app.post("/api/ingest")
+    def ingest() -> dict[str, int]:
+        return {"ingested": svc.ingest()}
+
+    @app.post("/api/classify")
+    def classify() -> dict[str, int]:
+        return {"classified": svc.classify()}
+
+    @app.post("/api/refresh")
+    def refresh() -> dict[str, int]:
+        """Ingest new logs and re-discover topics in one step."""
+        return svc.refresh()
+
+    _mount_web_ui(app)
+    return app
+
+
+def _since(value: str) -> datetime | None:
+    try:
+        return parse_since(value)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+def _until(value: str) -> datetime | None:
+    try:
+        return parse_until(value)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+def _window(since: str, until: str) -> tuple[datetime | None, datetime | None]:
+    start = _since(since)
+    end = _until(until)
+    if start is not None and end is not None and start >= end:
+        raise HTTPException(400, "since must be before until")
+    return start, end
+
+
+def _mount_web_ui(app: FastAPI) -> None:
+    dist = _web_dist()
+    if dist is not None:
+        app.mount("/", StaticFiles(directory=str(dist), html=True), name="web")
+
+
+def _web_dist() -> Path | None:
+    """Locate the built web UI.
+
+    Prefers the copy bundled inside the installed package (so a pip/uv install
+    can serve the dashboard), then falls back to the dev build at ``web/dist``.
+    """
+    here = Path(__file__).resolve()
+    candidates = [
+        here.parent.parent / "webui",  # packaged: src/agent_roi/webui
+        here.parents[3] / "web" / "dist",  # dev checkout
+    ]
+    for candidate in candidates:
+        if candidate.is_dir():
+            return candidate
+    return None

agent_roi/classify/__init__.py

@@ -0,0 +1,26 @@
+"""Classifier factory."""
+
+from __future__ import annotations
+
+from agent_roi.classify.base import Classifier, SessionDoc
+from agent_roi.core.config import ClassifierConfig
+
+
+def get_classifier(config: ClassifierConfig) -> Classifier:
+    """Build the classifier described by config.
+
+    Only the model-free ``semantic`` provider exists: it discovers topics locally
+    from session text, so there is nothing to install, no server to run, and no
+    tokens to spend.
+    """
+    if config.provider == "semantic":
+        from agent_roi.classify.semantic import SemanticClassifier
+
+        return SemanticClassifier(
+            similarity_threshold=config.similarity_threshold,
+            label_terms=config.label_terms,
+        )
+    raise ValueError(f"Unknown classifier provider: {config.provider!r}")
+
+
+__all__ = ["Classifier", "SessionDoc", "get_classifier"]

agent_roi/classify/base.py

@@ -0,0 +1,44 @@
+"""Topic classifier interface.
+
+A classifier looks at whole *sessions* (one continuous piece of agent work) and
+groups the ones that are about the same thing, assigning each group a short topic
+label such as "auth refactor" or "ci pipeline". Topics are how Agent-ROI
+aggregates token cost per *subject* rather than per request, which is the whole
+point of measuring agent ROI.
+
+Classification is deliberately model-free: it discovers topics from the text of
+the sessions themselves (semantic similarity), so it runs fully offline, costs
+nothing, and never sends anything to an external service.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+UNCATEGORIZED = "uncategorized"
+
+
+@dataclass
+class SessionDoc:
+    """One session handed to the classifier for topic discovery.
+
+    ``summary`` is a compact, combined snippet of the session's interactions;
+    ``project`` is the coarse repo/folder grouping derived from the cwd.
+    """
+
+    session_id: str
+    project: str
+    summary: str
+
+
+class Classifier(ABC):
+    """Base class for topic classifiers.
+
+    Implementations look at all the given sessions together so they can group
+    similar ones, rather than labeling each session in isolation.
+    """
+
+    @abstractmethod
+    def label_sessions(self, sessions: list[SessionDoc]) -> dict[str, str]:
+        """Return a ``{session_id: topic}`` mapping for the given sessions."""

agent_roi/classify/semantic.py

@@ -0,0 +1,197 @@
+"""Model-free semantic topic discovery.
+
+Groups sessions that are about the same kind of work, without any LLM or external
+service. The pipeline mirrors classic "local embedding + community detection"
+setups, but uses lightweight, dependency-free building blocks so it runs anywhere
+and costs nothing:
+
+1. Each session's combined summary is tokenized and turned into a TF-IDF vector
+   (a cheap, deterministic stand-in for an embedding).
+2. Sessions whose vectors are close enough (cosine similarity) are linked, and
+   the connected components of that graph become topic clusters — the same idea
+   as graph community detection, kept simple with union-find.
+3. Each cluster is labeled from its most distinctive shared terms.
+
+Sessions with no meaningful text fall back to ``uncategorized`` rather than being
+force-fit into a topic.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import defaultdict
+
+from agent_roi.classify.base import UNCATEGORIZED, Classifier, SessionDoc
+
+# Generic words that carry no topic signal in coding-assistant chatter. Kept
+# short and intentionally conservative — real topic terms should survive.
+_STOPWORDS = frozenset(
+    {
+        "the", "a", "an", "and", "or", "but", "if", "then", "else", "for", "of",
+        "to", "in", "on", "at", "by", "is", "are", "was", "were", "be", "been",
+        "this", "that", "these", "those", "it", "its", "as", "with", "from",
+        "into", "out", "up", "down", "so", "not", "no", "yes", "can", "will",
+        "would", "should", "could", "do", "does", "did", "have", "has", "had",
+        "i", "you", "we", "they", "he", "she", "me", "my", "your", "our",
+        "please", "help", "want", "need", "make", "let", "lets", "use", "using",
+        "add", "added", "adding", "fix", "fixed", "fixing", "update", "updated",
+        "change", "changed", "create", "created", "new", "code", "file", "files",
+        "function", "error", "errors", "issue", "issues", "problem", "try",
+        "trying", "now", "also", "like", "just", "get", "got", "set", "run",
+        "running", "here", "there", "what", "how", "why", "when", "which",
+        "user", "assistant", "message", "okay", "ok", "thanks", "thank",
+    }
+)
+
+_TOKEN_RE = re.compile(r"[a-z][a-z0-9_]{2,}")
+
+
+class SemanticClassifier(Classifier):
+    """Discover topics by clustering semantically similar sessions."""
+
+    def __init__(
+        self,
+        similarity_threshold: float = 0.18,
+        label_terms: int = 3,
+    ) -> None:
+        # Cosine similarity at/above which two sessions are treated as the same
+        # topic. Higher = stricter (more, smaller topics).
+        self.similarity_threshold = similarity_threshold
+        # How many distinctive terms make up a generated topic label.
+        self.label_terms = label_terms
+
+    def label_sessions(self, sessions: list[SessionDoc]) -> dict[str, str]:
+        if not sessions:
+            return {}
+
+        token_lists = [_tokenize(s.summary) for s in sessions]
+        vectors = _tfidf_vectors(token_lists)
+
+        clusters = _cluster(vectors, self.similarity_threshold)
+
+        labels: dict[str, str] = {}
+        used: dict[str, int] = {}
+        for members in clusters:
+            label = _label_for(members, vectors, self.label_terms)
+            # Disambiguate identical labels from distinct clusters.
+            if label != UNCATEGORIZED and label in used:
+                used[label] += 1
+                label = f"{label} {used[label]}"
+            else:
+                used.setdefault(label, 1)
+            for idx in members:
+                labels[sessions[idx].session_id] = label
+        return labels
+
+
+def _tokenize(text: str) -> list[str]:
+    return [t for t in _TOKEN_RE.findall(text.lower()) if t not in _STOPWORDS]
+
+
+def _tfidf_vectors(token_lists: list[list[str]]) -> list[dict[str, float]]:
+    """Build L2-normalized TF-IDF vectors so dot product == cosine similarity."""
+    n_docs = len(token_lists)
+    doc_freq: dict[str, int] = defaultdict(int)
+    for tokens in token_lists:
+        for term in set(tokens):
+            doc_freq[term] += 1
+
+    idf = {
+        term: math.log((n_docs + 1) / (df + 1)) + 1.0
+        for term, df in doc_freq.items()
+    }
+
+    vectors: list[dict[str, float]] = []
+    for tokens in token_lists:
+        term_freq: dict[str, int] = defaultdict(int)
+        for term in tokens:
+            term_freq[term] += 1
+        vec = {term: tf * idf[term] for term, tf in term_freq.items()}
+        norm = math.sqrt(sum(w * w for w in vec.values()))
+        if norm > 0:
+            vec = {term: w / norm for term, w in vec.items()}
+        vectors.append(vec)
+    return vectors
+
+
+def _cosine(a: dict[str, float], b: dict[str, float]) -> float:
+    # Vectors are unit-normalized, so cosine is just the dot product. Iterate the
+    # smaller vector for speed.
+    if len(a) > len(b):
+        a, b = b, a
+    return sum(weight * b.get(term, 0.0) for term, weight in a.items())
+
+
+def _cluster(vectors: list[dict[str, float]], threshold: float) -> list[list[int]]:
+    """Greedy centroid clustering: assign each session to the cluster whose mean
+    vector it is most similar to (above ``threshold``), else start a new cluster.
+
+    Centroid linkage resists the "chaining" failure of single-linkage/connected
+    components, where one borderline pair can merge unrelated work into a single
+    giant topic. Empty vectors (no meaningful tokens) are returned as their own
+    singletons so they can be labeled ``uncategorized`` downstream.
+    """
+    centroids: list[dict[str, float]] = []
+    sizes: list[int] = []
+    members: list[list[int]] = []
+    empties: list[list[int]] = []
+
+    for i, vec in enumerate(vectors):
+        if not vec:
+            empties.append([i])
+            continue
+
+        best, best_sim = -1, threshold
+        for c, centroid in enumerate(centroids):
+            sim = _cosine(vec, centroid)
+            if sim >= best_sim:
+                best, best_sim = c, sim
+
+        if best == -1:
+            centroids.append(dict(vec))
+            sizes.append(1)
+            members.append([i])
+        else:
+            members[best].append(i)
+            sizes[best] += 1
+            centroids[best] = _merge_centroid(centroids[best], sizes[best], vec)
+
+    return members + empties
+
+
+def _merge_centroid(
+    centroid: dict[str, float], size: int, vec: dict[str, float]
+) -> dict[str, float]:
+    """Fold ``vec`` into a centroid as a running mean, then re-normalize."""
+    merged = dict(centroid)
+    weight = 1.0 / size
+    for term, w in centroid.items():
+        merged[term] = w * (size - 1) * weight
+    for term, w in vec.items():
+        merged[term] = merged.get(term, 0.0) + w * weight
+    norm = math.sqrt(sum(x * x for x in merged.values()))
+    if norm > 0:
+        merged = {term: x / norm for term, x in merged.items()}
+    return merged
+
+
+def _label_for(
+    members: list[int],
+    vectors: list[dict[str, float]],
+    max_terms: int,
+) -> str:
+    """Name a cluster from the highest-weighted terms shared by its sessions."""
+    scores: dict[str, float] = defaultdict(float)
+    for idx in members:
+        for term, weight in vectors[idx].items():
+            scores[term] += weight
+
+    if not scores:
+        return UNCATEGORIZED
+
+    ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))
+    # Singletons get a slightly shorter label; multi-session topics a bit longer.
+    n_terms = max(1, max_terms if len(members) > 1 else max_terms - 1)
+    top = [term for term, _ in ranked[:n_terms]]
+    return " ".join(top) if top else UNCATEGORIZED

agent_roi/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

agent_roi/cli/main.py

@@ -0,0 +1,200 @@
+"""Agent-ROI command-line interface."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from agent_roi.core.platform import platform_label
+from agent_roi.core.service import Service
+from agent_roi.core.timeframe import parse_since
+
+app = typer.Typer(
+    name="agent-roi",
+    help="Track the cost, usage, and ROI of your AI coding agents across every tool.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+
+
+def _parse_since(value: str) -> datetime | None:
+    try:
+        return parse_since(value)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+
+@app.command()
+def ingest(
+    classify: bool = typer.Option(
+        True, help="Also discover topics after ingesting (recommended)."
+    ),
+) -> None:
+    """Collect interactions from all enabled tools, then discover topics."""
+    service = Service()
+    with console.status("Ingesting logs..."):
+        count = service.ingest()
+    console.print(f"[green]Ingested {count} interactions.[/green]")
+    if classify:
+        with console.status("Discovering topics..."):
+            labeled = service.classify()
+        console.print(f"[green]Classified {labeled} interactions into topics.[/green]")
+
+
+@app.command()
+def classify(
+    limit: int = typer.Option(0, help="Max sessions to classify (0 = all)."),
+) -> None:
+    """Re-discover topics across all sessions."""
+    service = Service()
+    with console.status("Discovering topics..."):
+        count = service.classify(limit=limit or None)
+    console.print(f"[green]Classified {count} interactions.[/green]")
+
+
+@app.command()
+def report(
+    by: str = typer.Option("topic", help="Grouping dimension: topic | tool | model | project."),
+    since: str = typer.Option(
+        "", help="Time window start: a date (YYYY-MM-DD) or shorthand like 7d, 24h, today."
+    ),
+) -> None:
+    """Show a token/cost breakdown, grouped and optionally time-windowed."""
+    if by not in ("topic", "tool", "model", "project"):
+        console.print(f"[red]Unsupported grouping: {by} (use topic|tool|model|project)[/red]")
+        raise typer.Exit(1)
+
+    start = _parse_since(since)
+    service = Service()
+    rollups = service.report(dimension=by, start=start)
+    if not rollups:
+        console.print("[yellow]No data in range. Run 'agent-roi ingest' first.[/yellow]")
+        return
+
+    title = f"Token Cost by {by.capitalize()}"
+    if start is not None:
+        title += f"  (since {start.date()})"
+    table = Table(title=title)
+    table.add_column(by.capitalize(), style="cyan", no_wrap=True)
+    table.add_column("Interactions", justify="right")
+    table.add_column("Input", justify="right")
+    table.add_column("Output", justify="right")
+    table.add_column("Total Tokens", justify="right")
+    table.add_column("Cost (USD)", justify="right", style="green")
+    table.add_column("Src", justify="center")
+
+    for r in rollups:
+        table.add_row(
+            r.key,
+            str(r.interactions),
+            f"{r.input_tokens:,}",
+            f"{r.output_tokens:,}",
+            f"{r.total_tokens:,}",
+            f"${r.cost_usd:,.4f}",
+            "~est" if r.estimated else "exact",
+        )
+    console.print(table)
+    if any(r.estimated for r in rollups):
+        console.print("[dim]~est = token counts estimated (tool doesn't report usage).[/dim]")
+
+
+@app.command()
+def topic(
+    name: str = typer.Argument(..., help="Topic to drill into."),
+    since: str = typer.Option("", help="Time window start (date or 7d/24h/today)."),
+) -> None:
+    """Drill into one topic: how its tokens split across tools and models."""
+    start = _parse_since(since)
+    service = Service()
+    bd = service.topic_breakdown(name, start=start)
+    if bd.total.interactions == 0:
+        console.print(f"[yellow]No interactions for topic '{name}' in range.[/yellow]")
+        return
+
+    console.print(
+        f"[bold]{name}[/bold] — {bd.total.interactions} interactions, "
+        f"{bd.total.total_tokens:,} tokens, [green]${bd.total.cost_usd:,.4f}[/green]"
+    )
+
+    for label, rows in (("By Tool", bd.by_tool), ("By Model", bd.by_model)):
+        table = Table(title=label)
+        table.add_column(label.split()[-1], style="cyan")
+        table.add_column("Interactions", justify="right")
+        table.add_column("Total Tokens", justify="right")
+        table.add_column("Cost (USD)", justify="right", style="green")
+        table.add_column("Share", justify="right")
+        for r in rows:
+            share = (r.cost_usd / bd.total.cost_usd * 100) if bd.total.cost_usd else 0.0
+            table.add_row(
+                r.key,
+                str(r.interactions),
+                f"{r.total_tokens:,}",
+                f"${r.cost_usd:,.4f}",
+                f"{share:.0f}%",
+            )
+        console.print(table)
+
+
+@app.command()
+def pricing() -> None:
+    """Show the pricing table behind every cost figure (USD per 1M tokens)."""
+    service = Service()
+    table = Table(title="Model Pricing (USD per 1M tokens)")
+    table.add_column("Model", style="cyan")
+    table.add_column("Input", justify="right")
+    table.add_column("Output", justify="right")
+    table.add_column("Cache Read", justify="right")
+    table.add_column("Cache Write", justify="right")
+    for p in service.pricing():
+        table.add_row(
+            p.model, f"${p.input}", f"${p.output}", f"${p.cache_read}", f"${p.cache_write}"
+        )
+    console.print(table)
+    console.print("[dim]cost = (input x in + output x out + cache_read x cr + ...) / 1e6[/dim]")
+
+
+@app.command()
+def doctor() -> None:
+    """Show which tools were detected, where Agent-ROI looked, and what it found."""
+    service = Service()
+    console.print(f"[bold]Platform:[/bold] {platform_label()}")
+    table = Table(title="Data Sources")
+    table.add_column("Tool", style="cyan")
+    table.add_column("Detected", justify="center")
+    table.add_column("Log Files", justify="right")
+    table.add_column("Interactions", justify="right")
+    table.add_column("Cost (USD)", justify="right", style="green")
+    table.add_column("Notes")
+    for s in service.sources():
+        table.add_row(
+            s.name,
+            "[green]yes[/green]" if s.available else "[red]no[/red]",
+            str(s.log_files),
+            f"{s.interactions:,}",
+            f"${s.cost_usd:,.2f}",
+            s.note,
+        )
+    console.print(table)
+    for s in service.sources():
+        if s.search_paths:
+            console.print(f"[dim]{s.name} searched:[/dim] {', '.join(s.search_paths)}")
+
+
+@app.command()
+def serve(
+    host: str = typer.Option("127.0.0.1", help="Bind host."),
+    port: int = typer.Option(8000, help="Bind port."),
+) -> None:
+    """Run the REST API (and serve the built web UI if present)."""
+    import uvicorn
+
+    uvicorn.run("agent_roi.api.app:create_app", host=host, port=port, factory=True)
+
+
+if __name__ == "__main__":
+    app()