onetool-mcp 1.0.0b1__py3-none-any.whl

ot/stats/__init__.py

@@ -0,0 +1,35 @@
+"""Runtime statistics collection for OneTool.
+
+Two-level statistics:
+- Run-level: Tracks run() calls, durations, and calculates context savings estimates.
+- Tool-level: Tracks actual tool invocations at the executor dispatch level.
+
+Records are stored in a single JSONL file with a 'type' field discriminator.
+"""
+
+from ot.stats.html import generate_html_report
+from ot.stats.jsonl_writer import (
+    JsonlStatsWriter,
+    get_client_name,
+    get_stats_writer,
+    record_tool_stats,
+    set_client_name,
+    set_stats_writer,
+)
+from ot.stats.reader import AggregatedStats, Period, StatsReader, ToolStats
+from ot.stats.timing import timed_tool_call
+
+__all__ = [
+    "AggregatedStats",
+    "JsonlStatsWriter",
+    "Period",
+    "StatsReader",
+    "ToolStats",
+    "generate_html_report",
+    "get_client_name",
+    "get_stats_writer",
+    "record_tool_stats",
+    "set_client_name",
+    "set_stats_writer",
+    "timed_tool_call",
+]

ot/stats/html.py

@@ -0,0 +1,250 @@
+"""HTML report generation for OneTool statistics.
+
+Generates self-contained HTML reports with inline CSS, no JS dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ot.support import (
+    KOFI_URL,
+    SUPPORT_HTML_BUTTON_TEXT,
+    SUPPORT_HTML_MESSAGE,
+    SUPPORT_HTML_TITLE,
+)
+
+if TYPE_CHECKING:
+    from ot.stats.reader import AggregatedStats
+
+
+def generate_html_report(stats: AggregatedStats) -> str:
+    """Generate a self-contained HTML report from aggregated stats.
+
+    Args:
+        stats: Aggregated statistics from StatsReader
+
+    Returns:
+        Complete HTML document as string
+    """
+    # Format time saved in human-readable format
+    time_saved_seconds = stats.time_saved_ms / 1000
+    if time_saved_seconds >= 3600:
+        time_saved_str = f"{time_saved_seconds / 3600:.1f} hours"
+    elif time_saved_seconds >= 60:
+        time_saved_str = f"{time_saved_seconds / 60:.1f} minutes"
+    else:
+        time_saved_str = f"{time_saved_seconds:.1f} seconds"
+
+    # Format context saved
+    if stats.context_saved >= 1_000_000:
+        context_saved_str = f"{stats.context_saved / 1_000_000:.1f}M tokens"
+    elif stats.context_saved >= 1_000:
+        context_saved_str = f"{stats.context_saved / 1_000:.1f}K tokens"
+    else:
+        context_saved_str = f"{stats.context_saved} tokens"
+
+    # Format savings estimate with coffee equivalent
+    if stats.savings_usd >= 1.0:
+        savings_str = f"${stats.savings_usd:.2f}"
+    elif stats.savings_usd >= 0.01:
+        savings_str = f"${stats.savings_usd:.3f}"
+    else:
+        savings_str = f"${stats.savings_usd:.4f}"
+
+    # Coffee equivalent (whole number)
+    coffees = int(stats.coffees)
+    coffees_str = f"{coffees} coffee{'s' if coffees != 1 else ''}"
+
+    coffees_display = f"☕ {coffees_str}"
+
+    # Group tools by pack (prefix before the dot)
+    from collections import defaultdict
+
+    packs: dict[str, list] = defaultdict(list)
+    for tool in stats.tools:
+        pack_name = tool.tool.split(".")[0] if "." in tool.tool else "other"
+        packs[pack_name].append(tool)
+
+    # Build tool rows grouped by pack
+    tool_rows = ""
+    for pack_name in sorted(packs.keys()):
+        pack_tools = packs[pack_name]
+        pack_calls = sum(t.total_calls for t in pack_tools)
+        tool_rows += f"""
+            <tr class="pack-header">
+                <td><strong>{pack_name}</strong></td>
+                <td class="num"><strong>{pack_calls:,}</strong></td>
+                <td class="num"></td>
+                <td class="num"></td>
+            </tr>"""
+        for tool in pack_tools:
+            # Show just the function name (after the dot)
+            func_name = tool.tool.split(".", 1)[1] if "." in tool.tool else tool.tool
+            avg_duration = f"{tool.avg_duration_ms:.0f}ms"
+            tool_rows += f"""
+            <tr>
+                <td class="tool-name">{func_name}</td>
+                <td class="num">{tool.total_calls}</td>
+                <td class="num">{tool.success_rate:.1f}%</td>
+                <td class="num">{avg_duration}</td>
+            </tr>"""
+
+    # Period display
+    period_display = stats.period.capitalize()
+    if stats.start_time and stats.end_time:
+        # Extract just the date portion
+        start_date = stats.start_time[:10]
+        end_date = stats.end_time[:10]
+        if start_date == end_date:
+            period_display = f"{period_display} ({start_date})"
+        else:
+            period_display = f"{period_display} ({start_date} to {end_date})"
+
+    html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>OneTool Statistics Report</title>
+    <style>
+        :root {{
+            --bg: #f8f9fa;
+            --card-bg: #ffffff;
+            --text: #212529;
+            --text-muted: #6c757d;
+            --border: #dee2e6;
+            --primary: #0d6efd;
+            --success: #198754;
+            --warning: #ffc107;
+            --kofi: #ff5e5b;
+        }}
+        * {{ box-sizing: border-box; margin: 0; padding: 0; }}
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            background: var(--bg);
+            color: var(--text);
+            line-height: 1.5;
+            padding: 2rem;
+        }}
+        .container {{ max-width: 1200px; margin: 0 auto; }}
+        h1 {{ margin-bottom: 0.5rem; }}
+        .subtitle {{ color: var(--text-muted); margin-bottom: 2rem; }}
+        .cards {{
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+            gap: 1rem;
+            margin-bottom: 2rem;
+        }}
+        .card {{
+            background: var(--card-bg);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+            padding: 1.5rem;
+        }}
+        .card-label {{ color: var(--text-muted); font-size: 0.875rem; margin-bottom: 0.25rem; }}
+        .card-value {{ font-size: 1.75rem; font-weight: 600; }}
+        .card-value.success {{ color: var(--success); }}
+        .card-value.primary {{ color: var(--primary); }}
+        .card-value.warning {{ color: var(--warning); }}
+        .card-sub {{ color: var(--text-muted); font-size: 0.875rem; margin-top: 0.25rem; }}
+        .card-sub.success {{ color: var(--success); }}
+        table {{
+            width: 100%;
+            background: var(--card-bg);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+            border-collapse: collapse;
+            overflow: hidden;
+        }}
+        th, td {{ padding: 0.75rem 1rem; text-align: left; border-bottom: 1px solid var(--border); }}
+        th {{ background: var(--bg); font-weight: 600; }}
+        tr:last-child td {{ border-bottom: none; }}
+        .num {{ text-align: right; font-variant-numeric: tabular-nums; }}
+        .pack-header {{ background: var(--bg); }}
+        .tool-name {{ padding-left: 2rem; }}
+        .empty {{ color: var(--text-muted); text-align: center; padding: 2rem; }}
+        .support {{
+            margin-top: 2rem;
+            padding: 1.5rem;
+            background: var(--card-bg);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+            text-align: center;
+        }}
+        .support h3 {{ margin-bottom: 0.5rem; font-size: 1rem; }}
+        .support p {{ color: var(--text-muted); font-size: 0.875rem; margin-bottom: 1rem; }}
+        .kofi-btn {{
+            display: inline-block;
+            background: var(--kofi);
+            color: white;
+            text-decoration: none;
+            padding: 0.5rem 1rem;
+            border-radius: 6px;
+            font-weight: 500;
+            font-size: 0.875rem;
+        }}
+        .kofi-btn:hover {{ opacity: 0.9; }}
+        footer {{ margin-top: 2rem; color: var(--text-muted); font-size: 0.875rem; text-align: center; }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>OneTool Statistics</h1>
+        <p class="subtitle">Period: {period_display}</p>
+
+        <div class="cards">
+            <div class="card">
+                <div class="card-label">Total Calls</div>
+                <div class="card-value">{stats.total_calls:,}</div>
+            </div>
+            <div class="card">
+                <div class="card-label">Call Success Rate</div>
+                <div class="card-value success">{stats.success_rate:.1f}%</div>
+            </div>
+            <div class="card">
+                <div class="card-label">Tokens Saved</div>
+                <div class="card-value primary">{context_saved_str}</div>
+            </div>
+            <div class="card">
+                <div class="card-label">Time Saved</div>
+                <div class="card-value primary">{time_saved_str}</div>
+            </div>
+            <div class="card">
+                <div class="card-label">Money Saved</div>
+                <div class="card-value success">{savings_str}</div>
+                <div class="card-sub success">{coffees_display}</div>
+            </div>
+        </div>
+
+        <h2 style="margin-bottom: 1rem;">Per-Tool Breakdown</h2>
+        <table>
+            <thead>
+                <tr>
+                    <th>Tool</th>
+                    <th class="num">Calls</th>
+                    <th class="num">Success Rate</th>
+                    <th class="num">Avg Duration</th>
+                </tr>
+            </thead>
+            <tbody>
+                {tool_rows if tool_rows else '<tr><td colspan="4" class="empty">No data available</td></tr>'}
+            </tbody>
+        </table>
+
+        <div class="support">
+            <h3>{SUPPORT_HTML_TITLE}</h3>
+            <p>{SUPPORT_HTML_MESSAGE}</p>
+            <a href="{KOFI_URL}" class="kofi-btn" target="_blank" rel="noopener">
+                {SUPPORT_HTML_BUTTON_TEXT}
+            </a>
+        </div>
+
+        <footer>
+            Generated by OneTool &middot; {stats.end_time[:19] if stats.end_time else 'N/A'}
+        </footer>
+    </div>
+</body>
+</html>"""
+
+    return html

ot/stats/jsonl_writer.py

@@ -0,0 +1,283 @@
+"""Unified JSONL stats writer for run-level and tool-level records.
+
+Records are buffered in memory and flushed to JSONL at configurable intervals.
+Data loss is tolerable - stats are nice-to-have, not critical.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Literal
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+RecordType = Literal["run", "tool"]
+
+
+def _create_run_record(
+    client: str,
+    chars_in: int,
+    chars_out: int,
+    duration_ms: int,
+    success: bool,
+    error_type: str | None = None,
+) -> dict[str, Any]:
+    """Create a run-level stats record.
+
+    Args:
+        client: MCP client name (e.g., "Claude Desktop")
+        chars_in: Input character count
+        chars_out: Output character count
+        duration_ms: Execution time in milliseconds
+        success: Whether the run succeeded
+        error_type: Exception class name if failed
+
+    Returns:
+        Record dict ready for JSONL serialization
+    """
+    record: dict[str, Any] = {
+        "ts": datetime.now(UTC).isoformat(),
+        "type": "run",
+        "client": client,
+        "chars_in": chars_in,
+        "chars_out": chars_out,
+        "duration_ms": duration_ms,
+        "success": success,
+    }
+    if error_type:
+        record["error_type"] = error_type
+    return record
+
+
+def _create_tool_record(
+    client: str,
+    tool: str,
+    duration_ms: int,
+    success: bool,
+    error_type: str | None = None,
+) -> dict[str, Any]:
+    """Create a tool-level stats record.
+
+    Args:
+        client: MCP client name (e.g., "Claude Desktop")
+        tool: Fully qualified tool name (e.g., "brave.search")
+        duration_ms: Execution time in milliseconds
+        success: Whether the tool call succeeded
+        error_type: Exception class name if failed
+
+    Returns:
+        Record dict ready for JSONL serialization
+    """
+    record: dict[str, Any] = {
+        "ts": datetime.now(UTC).isoformat(),
+        "type": "tool",
+        "client": client,
+        "tool": tool,
+        "duration_ms": duration_ms,
+        "success": success,
+    }
+    if error_type:
+        record["error_type"] = error_type
+    return record
+
+
+class JsonlStatsWriter:
+    """Unified async batched JSONL writer for statistics.
+
+    Handles both run-level and tool-level records in a single file,
+    discriminated by the 'type' field.
+
+    Usage:
+        writer = JsonlStatsWriter(path, flush_interval=30)
+        await writer.start()
+
+        # Record run stats
+        writer.record_run(client="Claude", chars_in=500, ...)
+
+        # Record tool stats
+        writer.record_tool(client="Claude", tool="brave.search", ...)
+
+        # On shutdown
+        await writer.stop()
+    """
+
+    def __init__(self, path: Path, flush_interval: int = 30) -> None:
+        """Initialize writer.
+
+        Args:
+            path: Path to JSONL file
+            flush_interval: Seconds between flushes
+        """
+        self._path = path
+        self._flush_interval = flush_interval
+        self._buffer: list[dict[str, Any]] = []
+        self._lock = asyncio.Lock()
+        self._task: asyncio.Task[None] | None = None
+        self._running = False
+
+    @property
+    def path(self) -> Path:
+        """Get the JSONL file path."""
+        return self._path
+
+    def record_run(
+        self,
+        client: str,
+        chars_in: int,
+        chars_out: int,
+        duration_ms: int,
+        success: bool,
+        error_type: str | None = None,
+    ) -> None:
+        """Record a run-level stats event (non-blocking)."""
+        record = _create_run_record(
+            client=client,
+            chars_in=chars_in,
+            chars_out=chars_out,
+            duration_ms=duration_ms,
+            success=success,
+            error_type=error_type,
+        )
+        self._buffer.append(record)
+
+    def record_tool(
+        self,
+        client: str,
+        tool: str,
+        duration_ms: int,
+        success: bool,
+        error_type: str | None = None,
+    ) -> None:
+        """Record a tool-level stats event (non-blocking)."""
+        record = _create_tool_record(
+            client=client,
+            tool=tool,
+            duration_ms=duration_ms,
+            success=success,
+            error_type=error_type,
+        )
+        self._buffer.append(record)
+
+    async def start(self) -> None:
+        """Start the background flush task."""
+        if self._running:
+            return
+
+        self._running = True
+        self._task = asyncio.create_task(self._flush_loop())
+        logger.debug(f"JSONL stats writer started: {self._path}")
+
+    async def stop(self) -> None:
+        """Stop the writer and flush remaining records."""
+        self._running = False
+
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+
+        # Final flush
+        await self._flush()
+        logger.debug("JSONL stats writer stopped")
+
+    async def _flush_loop(self) -> None:
+        """Background task that flushes buffer periodically."""
+        while self._running:
+            try:
+                await asyncio.sleep(self._flush_interval)
+                await self._flush()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                # Log but don't crash - stats are not critical
+                logger.warning(f"JSONL stats flush error: {e}")
+
+    async def _flush(self) -> None:
+        """Flush buffer to JSONL file."""
+        async with self._lock:
+            if not self._buffer:
+                return
+
+            records = self._buffer.copy()
+
+        try:
+            await self._write_records(records)
+            # Clear buffer only after successful write to prevent data loss
+            async with self._lock:
+                del self._buffer[: len(records)]
+            logger.debug(f"Flushed {len(records)} JSONL stats records")
+        except Exception as e:
+            # Log but don't crash - stats are not critical
+            # Buffer NOT cleared; records will retry on next flush
+            logger.warning(f"Failed to write JSONL stats: {e}")
+
+    async def _write_records(self, records: Sequence[dict[str, Any]]) -> None:
+        """Write records to JSONL file."""
+        # Ensure parent directory exists
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Run blocking I/O in thread pool
+        await asyncio.to_thread(self._write_jsonl, records)
+
+    def _write_jsonl(self, records: Sequence[dict[str, Any]]) -> None:
+        """Sync JSONL write (called from thread pool)."""
+        with self._path.open("a") as f:
+            for record in records:
+                f.write(json.dumps(record, separators=(",", ":")) + "\n")
+
+
+# Global stats writer instance (set by server on startup)
+_stats_writer: JsonlStatsWriter | None = None
+_client_name: str = "unknown"
+
+
+def get_stats_writer() -> JsonlStatsWriter | None:
+    """Get the global stats writer instance."""
+    return _stats_writer
+
+
+def set_stats_writer(writer: JsonlStatsWriter | None) -> None:
+    """Set the global stats writer instance."""
+    global _stats_writer
+    _stats_writer = writer
+
+
+def get_client_name() -> str:
+    """Get the current MCP client name."""
+    return _client_name
+
+
+def set_client_name(name: str) -> None:
+    """Set the current MCP client name."""
+    global _client_name
+    _client_name = name
+
+
+def record_tool_stats(
+    tool: str,
+    duration_ms: int,
+    success: bool,
+    error_type: str | None = None,
+) -> None:
+    """Record tool-level stats if writer is available.
+
+    Convenience function for use from executor dispatch points.
+    Uses the global client name set during MCP initialization.
+    """
+    writer = get_stats_writer()
+    if writer is not None:
+        writer.record_tool(
+            client=get_client_name(),
+            tool=tool,
+            duration_ms=duration_ms,
+            success=success,
+            error_type=error_type,
+        )