onetool-mcp 1.0.0b1__py3-none-any.whl

ot/stats/reader.py

@@ -0,0 +1,354 @@
+"""Stats reader with aggregation and filtering.
+
+Reads JSONL stats and aggregates by period with savings calculations.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any, Literal
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+Period = Literal["day", "week", "month", "all"]
+
+
+@dataclass
+class ToolStats:
+    """Aggregated statistics for a single tool."""
+
+    tool: str
+    total_calls: int
+    success_count: int
+    error_count: int
+    total_chars_in: int
+    total_chars_out: int
+    total_duration_ms: int
+    avg_duration_ms: float
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate as percentage."""
+        if self.total_calls == 0:
+            return 0.0
+        return (self.success_count / self.total_calls) * 100
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "tool": self.tool,
+            "total_calls": self.total_calls,
+            "success_count": self.success_count,
+            "error_count": self.error_count,
+            "success_rate": round(self.success_rate, 1),
+            "total_chars_in": self.total_chars_in,
+            "total_chars_out": self.total_chars_out,
+            "total_duration_ms": self.total_duration_ms,
+            "avg_duration_ms": round(self.avg_duration_ms, 1),
+        }
+
+
+# Cost per coffee for savings display (hardcoded)
+COFFEE_COST_USD = 5.0
+
+
+@dataclass
+class AggregatedStats:
+    """Aggregated statistics summary."""
+
+    period: Period
+    start_time: str | None
+    end_time: str | None
+    total_calls: int
+    success_count: int
+    error_count: int
+    total_chars_in: int
+    total_chars_out: int
+    total_duration_ms: int
+    context_saved: int
+    time_saved_ms: int
+    tools: list[ToolStats]
+    model: str = ""
+    cost_estimate_usd: float = 0.0
+    savings_usd: float = 0.0
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate overall success rate as percentage."""
+        if self.total_calls == 0:
+            return 0.0
+        return (self.success_count / self.total_calls) * 100
+
+    @property
+    def coffees(self) -> float:
+        """Calculate coffee equivalent of savings."""
+        return self.savings_usd / COFFEE_COST_USD
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "period": self.period,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "total_calls": self.total_calls,
+            "success_count": self.success_count,
+            "error_count": self.error_count,
+            "success_rate": round(self.success_rate, 1),
+            "total_chars_in": self.total_chars_in,
+            "total_chars_out": self.total_chars_out,
+            "total_duration_ms": self.total_duration_ms,
+            "context_saved": self.context_saved,
+            "time_saved_ms": self.time_saved_ms,
+            "model": self.model,
+            "cost_estimate_usd": round(self.cost_estimate_usd, 4),
+            "savings_usd": round(self.savings_usd, 2),
+            "coffees": round(self.coffees, 1),
+            "tools": [t.to_dict() for t in self.tools],
+        }
+
+
+class StatsReader:
+    """Reads and aggregates statistics from JSONL.
+
+    Usage:
+        reader = StatsReader(path, context_per_call=30000, time_overhead_ms=4000)
+        stats = reader.read(period="week", tool="brave.search")
+    """
+
+    def __init__(
+        self,
+        path: Path,
+        context_per_call: int = 30000,
+        time_overhead_per_call_ms: int = 4000,
+        model: str = "anthropic/claude-opus-4.5",
+        cost_per_million_input_tokens: float = 15.0,
+        cost_per_million_output_tokens: float = 75.0,
+        chars_per_token: float = 4.0,
+    ) -> None:
+        """Initialize reader.
+
+        Args:
+            path: Path to JSONL file
+            context_per_call: Context tokens saved per consolidated call
+            time_overhead_per_call_ms: Time overhead in ms saved per call
+            model: Model name for cost estimation
+            cost_per_million_input_tokens: Cost in USD per million input tokens
+            cost_per_million_output_tokens: Cost in USD per million output tokens
+            chars_per_token: Average characters per token for estimation
+        """
+        self._path = path
+        self._context_per_call = context_per_call
+        self._time_overhead_ms = time_overhead_per_call_ms
+        self._model = model
+        self._cost_per_m_input = cost_per_million_input_tokens
+        self._cost_per_m_output = cost_per_million_output_tokens
+        self._chars_per_token = chars_per_token
+
+    def read(
+        self,
+        period: Period = "all",
+        tool: str | None = None,
+    ) -> AggregatedStats:
+        """Read and aggregate stats.
+
+        Args:
+            period: Time period to filter (day/week/month/all)
+            tool: Optional tool name filter
+
+        Returns:
+            Aggregated statistics
+        """
+        records = self._load_records()
+        filtered = self._filter_records(records, period, tool)
+        return self._aggregate(filtered, period)
+
+    def _load_records(self) -> list[dict[str, Any]]:
+        """Load all records from JSONL."""
+        if not self._path.exists():
+            logger.debug(f"Stats file not found: {self._path}")
+            return []
+
+        records: list[dict[str, Any]] = []
+        try:
+            with self._path.open() as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        try:
+                            records.append(json.loads(line))
+                        except json.JSONDecodeError:
+                            logger.debug(f"Skipping malformed JSON line: {line[:50]}")
+        except Exception as e:
+            logger.warning(f"Failed to read stats: {e}")
+            return []
+
+        return records
+
+    def _filter_records(
+        self,
+        records: list[dict[str, Any]],
+        period: Period,
+        tool: str | None,
+    ) -> list[dict[str, Any]]:
+        """Filter records by period and tool."""
+        if not records:
+            return []
+
+        # Calculate period cutoff
+        cutoff = self._get_period_cutoff(period)
+
+        filtered: list[dict[str, Any]] = []
+        for record in records:
+            # Filter by period
+            if cutoff is not None:
+                try:
+                    ts = datetime.fromisoformat(record["ts"])
+                    if ts < cutoff:
+                        continue
+                except (KeyError, ValueError):
+                    continue
+
+            # Filter by tool (only applies to tool-type records)
+            if (
+                tool is not None
+                and record.get("type") == "tool"
+                and record.get("tool") != tool
+            ):
+                continue
+
+            filtered.append(record)
+
+        return filtered
+
+    def _get_period_cutoff(self, period: Period) -> datetime | None:
+        """Get cutoff datetime for period."""
+        if period == "all":
+            return None
+
+        now = datetime.now(UTC)
+        if period == "day":
+            return now - timedelta(days=1)
+        elif period == "week":
+            return now - timedelta(weeks=1)
+        elif period == "month":
+            return now - timedelta(days=30)
+
+        return None
+
+    def _aggregate(
+        self, records: list[dict[str, Any]], period: Period
+    ) -> AggregatedStats:
+        """Aggregate records into summary stats.
+
+        Records are split by type:
+        - "run" records: contain chars_in/chars_out, used for run counts and savings
+        - "tool" records: contain tool name, used for per-tool breakdown
+        """
+        if not records:
+            return AggregatedStats(
+                period=period,
+                start_time=None,
+                end_time=None,
+                total_calls=0,
+                success_count=0,
+                error_count=0,
+                total_chars_in=0,
+                total_chars_out=0,
+                total_duration_ms=0,
+                context_saved=0,
+                time_saved_ms=0,
+                tools=[],
+            )
+
+        # Separate run-level and tool-level records
+        run_records: list[dict[str, Any]] = []
+        tool_records_by_name: dict[str, list[dict[str, Any]]] = {}
+        timestamps: list[str] = []
+
+        for record in records:
+            record_type = record.get("type", "run")
+            ts = record.get("ts")
+            if ts:
+                timestamps.append(ts)
+
+            if record_type == "run":
+                run_records.append(record)
+            elif record_type == "tool":
+                tool_name = record.get("tool", "unknown")
+                if tool_name not in tool_records_by_name:
+                    tool_records_by_name[tool_name] = []
+                tool_records_by_name[tool_name].append(record)
+
+        # Sort timestamps for range
+        timestamps.sort()
+
+        # Aggregate run-level stats
+        run_count = len(run_records)
+        run_success = sum(1 for r in run_records if r.get("success") is True)
+        run_error = run_count - run_success
+        total_chars_in = sum(int(r.get("chars_in", 0)) for r in run_records)
+        total_chars_out = sum(int(r.get("chars_out", 0)) for r in run_records)
+        run_duration = sum(int(r.get("duration_ms", 0)) for r in run_records)
+
+        # Aggregate per-tool stats
+        tool_stats: list[ToolStats] = []
+        total_tool_duration = 0
+
+        for tool_name, tool_records in sorted(tool_records_by_name.items()):
+            calls = len(tool_records)
+            success = sum(1 for r in tool_records if r.get("success") is True)
+            errors = calls - success
+            duration = sum(int(r.get("duration_ms", 0)) for r in tool_records)
+
+            tool_stats.append(
+                ToolStats(
+                    tool=tool_name,
+                    total_calls=calls,
+                    success_count=success,
+                    error_count=errors,
+                    total_chars_in=0,  # Tool records don't have chars
+                    total_chars_out=0,
+                    total_duration_ms=duration,
+                    avg_duration_ms=duration / calls if calls > 0 else 0,
+                )
+            )
+
+            total_tool_duration += duration
+
+        # Calculate savings (context and time saved by consolidating run calls)
+        context_saved = run_count * self._context_per_call
+        time_saved = run_count * self._time_overhead_ms
+
+        # Calculate cost estimate (actual cost of tokens used)
+        input_tokens = total_chars_in / self._chars_per_token
+        output_tokens = total_chars_out / self._chars_per_token
+        cost_estimate = (
+            (input_tokens / 1_000_000) * self._cost_per_m_input
+            + (output_tokens / 1_000_000) * self._cost_per_m_output
+        )
+
+        # Calculate savings estimate (cost of context overhead avoided)
+        savings_usd = (context_saved / 1_000_000) * self._cost_per_m_input
+
+        return AggregatedStats(
+            period=period,
+            start_time=timestamps[0] if timestamps else None,
+            end_time=timestamps[-1] if timestamps else None,
+            total_calls=run_count,
+            success_count=run_success,
+            error_count=run_error,
+            total_chars_in=total_chars_in,
+            total_chars_out=total_chars_out,
+            total_duration_ms=run_duration,
+            context_saved=context_saved,
+            time_saved_ms=time_saved,
+            tools=tool_stats,
+            model=self._model,
+            cost_estimate_usd=cost_estimate,
+            savings_usd=savings_usd,
+        )

ot/stats/timing.py

@@ -0,0 +1,57 @@
+"""Timing context manager for tool call statistics.
+
+Provides a reusable context manager that handles timing, success/error
+tracking, and stats recording for tool calls.
+"""
+
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from ot.stats.jsonl_writer import get_client_name, record_tool_stats
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+@contextmanager
+def timed_tool_call(tool_name: str, client: str | None = None) -> Iterator[None]:
+    """Context manager for timing tool calls and recording stats.
+
+    Measures execution time, tracks success/failure, and records stats
+    to the global stats writer.
+
+    Args:
+        tool_name: Fully qualified tool name (e.g., "brave.search")
+        client: MCP client name. If None, uses global client name.
+
+    Yields:
+        None
+
+    Example:
+        with timed_tool_call("brave.search"):
+            result = brave.search(query="test")
+    """
+    if client is None:
+        client = get_client_name()
+
+    start_time = time.monotonic()
+    error_type: str | None = None
+    success = True
+
+    try:
+        yield
+    except Exception as e:
+        success = False
+        error_type = type(e).__name__
+        raise
+    finally:
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        record_tool_stats(
+            tool=tool_name,
+            duration_ms=duration_ms,
+            success=success,
+            error_type=error_type,
+        )

ot/support.py

@@ -0,0 +1,63 @@
+"""Centralized support information for OneTool.
+
+Single source of truth for donation/support links, messages, and version.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+# Support URLs
+KOFI_URL = "https://ko-fi.com/beycom"
+KOFI_HANDLE = "beycom"
+
+# Support messages
+SUPPORT_MESSAGE = "If you find OneTool useful, please consider supporting development!"
+SUPPORT_MESSAGE_SHORT = "Support OneTool development"
+
+# For HTML reports
+SUPPORT_HTML_TITLE = "Support OneTool"
+SUPPORT_HTML_MESSAGE = "If you find this project useful, please consider buying me a coffee!"
+SUPPORT_HTML_BUTTON_TEXT = "Buy me a coffee on Ko-fi"
+
+
+def get_support_dict() -> dict[str, str]:
+    """Get support info as a dictionary for JSON output.
+
+    Returns:
+        Dict with support URLs and messages
+    """
+    return {
+        "message": SUPPORT_MESSAGE,
+        "kofi_url": KOFI_URL,
+    }
+
+
+def get_startup_message() -> str:
+    """Get support message for server startup logs.
+
+    Returns:
+        Formatted startup message with support link
+    """
+    return f"{SUPPORT_MESSAGE_SHORT}: {KOFI_URL}"
+
+
+def get_support_banner() -> str:
+    """Get Rich-formatted support message for CLI banners.
+
+    Returns:
+        Rich markup string for console.print()
+    """
+    return f"[yellow]☕ Please buy me a coffee:[/yellow] [link={KOFI_URL}]{KOFI_URL}[/link]"
+
+
+def get_version() -> str:
+    """Get OneTool package version.
+
+    Returns:
+        Version string, or "dev" if not installed as a package.
+    """
+    try:
+        return version("onetool")
+    except PackageNotFoundError:
+        return "dev"

ot/tools.py

@@ -0,0 +1,114 @@
+"""Inter-tool calling API for bundled and extension tools.
+
+Provides functions for calling other tools programmatically:
+- call_tool(): Call a tool by its full pack.function name
+- get_pack(): Get a pack proxy for calling multiple functions
+
+Example usage in an extension tool:
+
+    from ot.tools import call_tool, get_pack
+
+    # Call a single tool by name
+    result = call_tool("llm.transform", input=text, prompt="Summarize")
+
+    # Get a pack for multiple calls
+    brave = get_pack("brave")
+    results = brave.search(query="test")
+
+Note: These functions are only available in bundled and extension tools.
+Isolated tools (subprocess with PEP 723) cannot use this API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def call_tool(name: str, **kwargs: Any) -> Any:
+    """Call another tool by its full name.
+
+    Args:
+        name: Full tool name with pack prefix (e.g., "llm.transform", "brave.search").
+              Must contain a dot separator.
+        **kwargs: Keyword arguments to pass to the tool function.
+
+    Returns:
+        The result from the tool function.
+
+    Raises:
+        ValueError: If name doesn't contain a dot separator.
+        KeyError: If the pack or function is not found.
+
+    Example:
+        result = call_tool("llm.transform", input="Hello", prompt="Translate to Spanish")
+    """
+    if "." not in name:
+        raise ValueError(
+            f"Tool name must include pack prefix (e.g., 'pack.function'), got: {name}"
+        )
+
+    from ot.executor.tool_loader import load_tool_registry
+
+    registry = load_tool_registry()
+
+    if name not in registry.functions:
+        pack_name, func_name = name.rsplit(".", 1)
+
+        if pack_name not in registry.packs:
+            available_packs = ", ".join(sorted(registry.packs.keys()))
+            raise KeyError(
+                f"Pack '{pack_name}' not found. Available packs: {available_packs}"
+            )
+
+        pack_funcs = registry.packs[pack_name]
+        if hasattr(pack_funcs, "__getattr__"):
+            # WorkerPackProxy - list functions differently
+            available_funcs = "use get_pack() to discover functions"
+        else:
+            available_funcs = ", ".join(sorted(pack_funcs.keys()))
+        raise KeyError(
+            f"Function '{func_name}' not found in pack '{pack_name}'. "
+            f"Available: {available_funcs}"
+        )
+
+    return registry.functions[name](**kwargs)
+
+
+def get_pack(name: str) -> Any:
+    """Get a pack proxy for calling multiple functions.
+
+    Returns a proxy object that allows calling pack functions using dot notation.
+
+    Args:
+        name: Pack name (e.g., "brave", "llm", "file").
+
+    Returns:
+        Pack proxy object with tool functions as attributes.
+
+    Raises:
+        KeyError: If the pack is not found.
+
+    Example:
+        brave = get_pack("brave")
+        results = brave.search(query="python")
+
+        llm = get_pack("llm")
+        summary = llm.transform(input=text, prompt="Summarize")
+    """
+    from ot.executor.pack_proxy import build_execution_namespace
+    from ot.executor.tool_loader import load_tool_registry
+
+    registry = load_tool_registry()
+
+    if name not in registry.packs:
+        available = ", ".join(sorted(registry.packs.keys()))
+        raise KeyError(f"Pack '{name}' not found. Available packs: {available}")
+
+    # Build namespace to get the wrapped proxy with stats tracking
+    namespace = build_execution_namespace(registry)
+
+    if name in namespace:
+        return namespace[name]
+
+    # Fallback to raw pack (shouldn't happen normally)
+    return registry.packs[name]

ot/utils/__init__.py

@@ -0,0 +1,81 @@
+"""OneTool utilities.
+
+Provides shared utilities for internal tools:
+- Text processing: truncate, format_error, run_command
+- Batch processing: batch_execute, normalize_items, format_batch_results
+- Caching: cache (TTL-based memoization)
+- HTTP utilities: safe_request, api_headers, check_api_key
+- Dependencies: check_cli, check_lib, ensure_cli, ensure_lib
+- Factory: lazy_client, LazyClient
+
+Extension tools (user-created in .onetool/tools/) can import directly from
+ot.* modules for logging, config, and inter-tool calling.
+"""
+
+from ot.utils.batch import batch_execute, format_batch_results, normalize_items
+from ot.utils.cache import CacheNamespace, cache
+from ot.utils.deps import (
+    Dependency,
+    DepsCheckResult,
+    check_cli,
+    check_deps,
+    check_lib,
+    check_secret,
+    ensure_cli,
+    ensure_lib,
+    requires_cli,
+    requires_lib,
+)
+from ot.utils.exceptions import flatten_exception_group
+from ot.utils.factory import LazyClient, lazy_client
+from ot.utils.format import serialize_result
+from ot.utils.http import api_headers, check_api_key, safe_request
+from ot.utils.platform import get_install_hint
+from ot.utils.sanitize import (
+    sanitize_output,
+    sanitize_tag_closes,
+    sanitize_triggers,
+    wrap_external_content,
+)
+from ot.utils.truncate import format_error, run_command, truncate
+
+__all__ = [
+    # Cache
+    "CacheNamespace",
+    "Dependency",
+    # Dependencies
+    "DepsCheckResult",
+    # Factory
+    "LazyClient",
+    # HTTP
+    "api_headers",
+    # Batch processing
+    "batch_execute",
+    "cache",
+    "check_api_key",
+    "check_cli",
+    "check_deps",
+    "check_lib",
+    "check_secret",
+    "ensure_cli",
+    "ensure_lib",
+    # Existing utilities
+    "flatten_exception_group",
+    "format_batch_results",
+    # Truncate
+    "format_error",
+    "get_install_hint",
+    "lazy_client",
+    "normalize_items",
+    "requires_cli",
+    "requires_lib",
+    "run_command",
+    "safe_request",
+    # Sanitization
+    "sanitize_output",
+    "sanitize_tag_closes",
+    "sanitize_triggers",
+    "serialize_result",
+    "truncate",
+    "wrap_external_content",
+]