code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/token_tracking/register_callbacks.py

@@ -0,0 +1,277 @@
+"""Register slash commands and startup hook for the token-tracking plugin.
+
+Commands:
+    /tracking gain [today|week|month|all]
+    /tracking cc-economics [today|week|month|all]
+    /tracking session [N]
+    /tracking edit-efficiency [today|week|month|all]
+    /tracking help
+"""
+
+import logging
+from typing import Any
+
+from code_muse.callbacks import register_callback
+from code_muse.config import get_current_autosave_id
+from code_muse.messaging import emit_info
+from code_muse.plugins.token_tracking.database import TrackingDatabase, get_tracking_db
+from code_muse.plugins.token_tracking.edit_analyzer import analyze_replacement
+from code_muse.plugins.token_tracking.reports import (
+    cc_economics_report,
+    edit_efficiency_report,
+    gain_report,
+    session_report,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _get_db() -> TrackingDatabase:
+    """Return the shared ``TrackingDatabase`` instance."""
+    return get_tracking_db()
+
+
+# ------------------------------------------------------------------
+# Startup hook
+# ------------------------------------------------------------------
+
+
+def _on_startup() -> None:
+    """Run database cleanup on application startup."""
+    try:
+        db = _get_db()
+        removed = db.cleanup()
+        logger.debug("Token tracking startup cleanup removed %s rows", removed)
+    except Exception:
+        pass
+
+
+# ------------------------------------------------------------------
+# Post-tool-call hook (edit efficiency tracking)
+# ------------------------------------------------------------------
+
+
+def _on_post_tool_call(
+    tool_name: str,
+    tool_args: dict[str, Any],
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> Any:
+    """Intercept file-edit tools to measure context inflation.
+
+    Analyses ``create_file``, ``replace_in_file``, and ``delete_snippet``
+    calls, stores byte-level metrics, and returns *None* so the tool
+    result is left untouched.
+    """
+    if tool_name not in ("create_file", "replace_in_file", "delete_snippet"):
+        return None
+
+    try:
+        file_path = tool_args.get("file_path", "")
+        success = True
+        if isinstance(result, dict) and result.get("error"):
+            success = False
+
+        if tool_name == "create_file":
+            old_text = ""
+            new_text = tool_args.get("content", "")
+            _store_edit_analysis(tool_name, file_path, old_text, new_text, success)
+
+        elif tool_name == "delete_snippet":
+            old_text = tool_args.get("snippet", "")
+            new_text = ""
+            _store_edit_analysis(tool_name, file_path, old_text, new_text, success)
+
+        elif tool_name == "replace_in_file":
+            replacements = tool_args.get("replacements", [])
+            if not replacements:
+                return None
+
+            # Aggregate across all replacements in this call (Pi style)
+            totals: dict[str, int] = {
+                "old_bytes": 0,
+                "new_bytes": 0,
+                "total_edit_bytes": 0,
+                "shared_prefix_bytes": 0,
+                "shared_suffix_bytes": 0,
+                "shared_context_bytes": 0,
+                "core_old_bytes": 0,
+                "core_new_bytes": 0,
+                "core_bytes": 0,
+                "wrapper_payload_bytes": 0,
+            }
+            has_core_change = False
+            total_core = 0
+            total_edit = 0
+
+            for rep in replacements:
+                old_text = rep.get("old_text", "")
+                new_text = rep.get("new_text", "")
+                analysis = analyze_replacement(old_text, new_text)
+
+                for key in totals:
+                    totals[key] += analysis[key]
+
+                if not analysis["no_core_change"]:
+                    has_core_change = True
+                total_core += analysis["core_bytes"]
+                total_edit += analysis["total_edit_bytes"]
+
+            no_core_change = not has_core_change
+            inflation_ratio = (
+                None
+                if no_core_change
+                else (total_edit / total_core if total_core else None)
+            )
+
+            db = _get_db()
+            db.insert_edit_analysis(
+                tool_name=tool_name,
+                file_path=file_path,
+                old_bytes=totals["old_bytes"],
+                new_bytes=totals["new_bytes"],
+                total_edit_bytes=totals["total_edit_bytes"],
+                shared_prefix_bytes=totals["shared_prefix_bytes"],
+                shared_suffix_bytes=totals["shared_suffix_bytes"],
+                shared_context_bytes=totals["shared_context_bytes"],
+                core_old_bytes=totals["core_old_bytes"],
+                core_new_bytes=totals["core_new_bytes"],
+                core_bytes=totals["core_bytes"],
+                wrapper_payload_bytes=totals["wrapper_payload_bytes"],
+                inflation_ratio=inflation_ratio,
+                no_core_change=no_core_change,
+                success=success,
+                session_id=get_current_autosave_id(),
+            )
+
+    except Exception:
+        logger.debug("Edit efficiency tracking failed for %s", tool_name, exc_info=True)
+
+    return None
+
+
+def _store_edit_analysis(
+    tool_name: str,
+    file_path: str,
+    old_text: str,
+    new_text: str,
+    success: bool,
+) -> None:
+    """Analyze a single replacement and store it in the database."""
+    analysis = analyze_replacement(old_text, new_text)
+    db = _get_db()
+    db.insert_edit_analysis(
+        tool_name=tool_name,
+        file_path=file_path,
+        old_bytes=analysis["old_bytes"],
+        new_bytes=analysis["new_bytes"],
+        total_edit_bytes=analysis["total_edit_bytes"],
+        shared_prefix_bytes=analysis["shared_prefix_bytes"],
+        shared_suffix_bytes=analysis["shared_suffix_bytes"],
+        shared_context_bytes=analysis["shared_context_bytes"],
+        core_old_bytes=analysis["core_old_bytes"],
+        core_new_bytes=analysis["core_new_bytes"],
+        core_bytes=analysis["core_bytes"],
+        wrapper_payload_bytes=analysis["wrapper_payload_bytes"],
+        inflation_ratio=analysis["inflation_ratio"],
+        no_core_change=analysis["no_core_change"],
+        success=success,
+        session_id=get_current_autosave_id(),
+    )
+
+
+# ------------------------------------------------------------------
+# Help
+# ------------------------------------------------------------------
+
+
+def _on_custom_command_help() -> list[tuple[str, str]]:
+    """Provide help entries for /help display."""
+    return [
+        ("tracking gain [time]", "Token savings report (today/week/month/all)"),
+        ("tracking cc-economics [time]", "Estimated Claude Code dollar savings"),
+        ("tracking session [N]", "Per-session adoption stats (default 10)"),
+        (
+            "tracking edit-efficiency [time]",
+            "Edit context-inflation / efficiency report",
+        ),
+    ]
+
+
+# ------------------------------------------------------------------
+# Slash-command handler
+# ------------------------------------------------------------------
+
+
+async def _on_custom_command(command: str, name: str) -> bool | None:
+    """Handle ``/tracking …`` slash commands.
+
+    Args:
+        command: Full command string (e.g. ``/tracking gain week``).
+        name: First token after the slash (always ``tracking`` here).
+
+    Returns:
+        ``True`` if handled, ``None`` if not a tracking command.
+    """
+    if name != "tracking":
+        return None
+
+    tokens = command.strip().split()
+    subcommand = tokens[1] if len(tokens) > 1 else "help"
+    arg = tokens[2] if len(tokens) > 2 else None
+
+    db = _get_db()
+
+    if subcommand in ("help",):
+        emit_info(
+            "Available /tracking commands:\n"
+            "  /tracking gain [today|week|month|all]\n"
+            "  /tracking cc-economics [today|week|month|all]\n"
+            "  /tracking session [N]\n"
+            "  /tracking help"
+        )
+        return True
+
+    if subcommand == "gain":
+        time_range = arg or "all"
+        report = gain_report(db, time_range)
+        emit_info(report)
+        return True
+
+    if subcommand == "cc-economics":
+        time_range = arg or "all"
+        report = cc_economics_report(db, time_range)
+        emit_info(report)
+        return True
+
+    if subcommand == "session":
+        limit = int(arg) if arg is not None and arg.isdigit() else 10
+        report = session_report(db, limit)
+        emit_info(report)
+        return True
+
+    if subcommand == "edit-efficiency":
+        time_range = arg or "all"
+        report = edit_efficiency_report(db, time_range)
+        emit_info(report)
+        return True
+
+    # Unknown subcommand — still consumed by this plugin
+    emit_info(
+        f"Unknown /tracking subcommand: {subcommand}\n"
+        "Try /tracking help for available commands."
+    )
+    return True
+
+
+# ------------------------------------------------------------------
+# Register
+# ------------------------------------------------------------------
+
+register_callback("startup", _on_startup)
+register_callback("custom_command_help", _on_custom_command_help)
+register_callback("custom_command", _on_custom_command)
+register_callback("post_tool_call", _on_post_tool_call)
+
+logger.debug("Token Tracking plugin callbacks registered")

code_muse/plugins/token_tracking/reports.py

@@ -0,0 +1,329 @@
+"""Query and formatting functions for token tracking reports.
+
+Provides ``gain_report``, ``cc_economics_report``, and ``session_report``.
+"""
+
+from code_muse.plugins.token_tracking.database import TrackingDatabase
+
+# ------------------------------------------------------------------
+# Time-range helpers
+# ------------------------------------------------------------------
+
+_TIME_RANGE_SQL = {
+    "today": "date(timestamp) = date('now')",
+    "week": "timestamp >= datetime('now', '-7 days')",
+    "month": "timestamp >= datetime('now', '-30 days')",
+    "all": "1=1",
+}
+
+
+def _time_filter(time_range: str) -> str:
+    """Return a SQLite WHERE clause fragment for the given range."""
+    return _TIME_RANGE_SQL.get(time_range, "1=1")
+
+
+# ------------------------------------------------------------------
+# Cost estimation
+# ------------------------------------------------------------------
+
+
+def _estimate_tokens_to_cost(input_tokens: int, output_tokens: int = 0) -> float:
+    """Estimate Claude 3.5 Sonnet cost in USD.
+
+    Pricing:
+        * $3 / 1M input tokens
+        * $15 / 1M output tokens
+    """
+    input_cost = input_tokens * 3.0 / 1_000_000
+    output_cost = output_tokens * 15.0 / 1_000_000
+    return input_cost + output_cost
+
+
+# ------------------------------------------------------------------
+# Reports
+# ------------------------------------------------------------------
+
+
+def gain_report(db: TrackingDatabase, time_range: str = "all") -> str:
+    """Format a token-savings report.
+
+    Args:
+        db: A ``TrackingDatabase`` instance.
+        time_range: One of ``today``, ``week``, ``month``, ``all``.
+
+    Returns:
+        Multi-line string suitable for display in the UI.
+    """
+    where = _time_filter(time_range)
+
+    row = db.query_one(
+        f"""
+        SELECT
+            COALESCE(SUM(raw_tokens), 0),
+            COALESCE(SUM(compressed_tokens), 0),
+            COUNT(*)
+        FROM executions
+        WHERE {where}
+        """
+    )
+    total_raw, total_compressed, total_commands = row or (0, 0, 0)
+    total_raw = int(total_raw)
+    total_compressed = int(total_compressed)
+    total_commands = int(total_commands)
+
+    saved = total_raw - total_compressed
+    savings_pct = (saved / max(total_raw, 1) * 100.0) if total_raw else 0.0
+
+    top_strategies = db.query_all(
+        f"""
+        SELECT
+            strategy,
+            COUNT(*) AS cmd_count,
+            COALESCE(SUM(raw_tokens - compressed_tokens), 0) AS saved_tokens
+        FROM executions
+        WHERE {where}
+        GROUP BY strategy
+        ORDER BY saved_tokens DESC
+        LIMIT 5
+        """
+    )
+
+    lines = [
+        "Token Savings Report",
+        f"Time range: {time_range}",
+        f"Total commands: {total_commands}",
+        f"Raw tokens: {total_raw} → Compressed tokens: {total_compressed}",
+        f"Savings: {saved} tokens ({savings_pct:.1f}%)",
+        "Top 5 strategies:",
+    ]
+    if top_strategies:
+        for strategy, cmd_count, saved_tokens in top_strategies:
+            lines.append(
+                f"  {strategy}: {cmd_count} commands, {int(saved_tokens)} tokens saved"
+            )
+    else:
+        lines.append("  (no data)")
+
+    return "\n".join(lines)
+
+
+def cc_economics_report(db: TrackingDatabase, time_range: str = "all") -> str:
+    """Estimate dollar savings using Claude Code pricing.
+
+    Treats raw tokens as "uncompressed input" and compressed tokens as
+    "actual input after filtering".  Output tokens are not tracked
+    separately so we only show input-side economics.
+
+    Args:
+        db: A ``TrackingDatabase`` instance.
+        time_range: One of ``today``, ``week``, ``month``, ``all``.
+
+    Returns:
+        Compact, LLM-readable summary string.
+    """
+    where = _time_filter(time_range)
+
+    row = db.query_one(
+        f"""
+        SELECT COALESCE(SUM(raw_tokens), 0), COALESCE(SUM(compressed_tokens), 0)
+        FROM executions
+        WHERE {where}
+        """
+    )
+    total_raw, total_compressed = row or (0, 0)
+    total_raw = int(total_raw)
+    total_compressed = int(total_compressed)
+
+    cost_uncompressed = _estimate_tokens_to_cost(total_raw, 0)
+    cost_compressed = _estimate_tokens_to_cost(total_compressed, 0)
+    savings = cost_uncompressed - cost_compressed
+
+    lines = [
+        "Claude Code Economics Report",
+        f"Time range: {time_range}",
+        f"Uncompressed input cost: ${cost_uncompressed:.4f}",
+        f"Compressed input cost:   ${cost_compressed:.4f}",
+        f"Estimated savings:       ${savings:.4f}",
+    ]
+    return "\n".join(lines)
+
+
+def session_report(db: TrackingDatabase, limit: int = 10) -> str:
+    """Report per-session adoption statistics.
+
+    Args:
+        db: A ``TrackingDatabase`` instance.
+        limit: Maximum number of recent sessions to show.
+
+    Returns:
+        Multi-line string with adoption metrics per session.
+    """
+    sessions = db.query_all(
+        """
+        SELECT
+            session_id,
+            COUNT(*) AS total_commands,
+            SUM(CASE WHEN strategy != 'unknown' THEN 1 ELSE 0 END) AS filtered_commands,
+            MIN(timestamp) AS first_ts,
+            MAX(timestamp) AS last_ts
+        FROM executions
+        GROUP BY session_id
+        ORDER BY first_ts DESC
+        LIMIT ?
+        """,
+        (limit,),
+    )
+
+    if not sessions:
+        return "Session Report\n(no tracking data)"
+
+    lines = ["Session Report"]
+    total_adoption_sum = 0.0
+    total_sessions = len(sessions)
+
+    for session_id, total_cmds, filtered_cmds, first_ts, last_ts in sessions:
+        total_cmds = int(total_cmds)
+        filtered_cmds = int(filtered_cmds)
+        adoption = (filtered_cmds / max(total_cmds, 1)) * 100.0
+        total_adoption_sum += adoption
+
+        flag = " ⚠️ low adoption" if adoption < 50 else ""
+        lines.append(
+            f"\nSession {session_id[:8]}…"
+            f"\n  Commands: {total_cmds} total, {filtered_cmds} filtered"
+            f"\n  Adoption: {adoption:.1f}%{flag}"
+            f"\n  First: {first_ts}"
+            f"\n  Last:  {last_ts}"
+        )
+
+    overall_avg = total_adoption_sum / max(total_sessions, 1)
+    lines.append(f"\nOverall average adoption: {overall_avg:.1f}%")
+
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------
+# Edit efficiency report
+# ------------------------------------------------------------------
+
+
+def edit_efficiency_report(db: TrackingDatabase, time_range: str = "all") -> str:
+    """Format an edit-efficiency / context-inflation report.
+
+    Args:
+        db: A ``TrackingDatabase`` instance.
+        time_range: One of ``today``, ``week``, ``month``, ``all``.
+
+    Returns:
+        Multi-line string suitable for display in the UI.
+    """
+    edits = db.query_edit_summary(time_range)
+
+    if not edits:
+        range_label = {
+            "today": "today",
+            "week": "last 7 days",
+            "month": "last 30 days",
+            "all": "all time",
+        }.get(time_range, time_range)
+        return f"Edit Efficiency Report ({range_label})\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n(no edit tracking data)"
+
+    total = len(edits)
+    tool_counts: dict[str, int] = {}
+    inflation_values: list[float] = []
+    no_core_count = 0
+    edits_with_inflation: list[tuple[float, str, int, int]] = []
+    bucket_success: dict[str, list[tuple[int, int]]] = {
+        "<4x": [],
+        "4-10x": [],
+        "10-25x": [],
+        "25x+": [],
+    }
+
+    for edit in edits:
+        tool = edit["tool_name"]
+        tool_counts[tool] = tool_counts.get(tool, 0) + 1
+
+        if edit["no_core_change"]:
+            no_core_count += 1
+
+        ratio = edit["inflation_ratio"]
+        if ratio is not None:
+            inflation_values.append(ratio)
+            edits_with_inflation.append(
+                (ratio, edit["file_path"], edit["total_edit_bytes"], edit["core_bytes"])
+            )
+
+            success = 1 if edit["success"] else 0
+            if ratio < 4:
+                bucket_success["<4x"].append((success, 1))
+            elif ratio < 10:
+                bucket_success["4-10x"].append((success, 1))
+            elif ratio < 25:
+                bucket_success["10-25x"].append((success, 1))
+            else:
+                bucket_success["25x+"].append((success, 1))
+        else:
+            # No core change — count in no_core bucket but don't show inflation
+            pass
+
+    range_label = {
+        "today": "today",
+        "week": "last 7 days",
+        "month": "last 30 days",
+        "all": "all time",
+    }.get(time_range, time_range)
+
+    lines = [
+        f"Edit Efficiency Report ({range_label})",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        f"Total edit calls: {total}",
+    ]
+    for tool, count in sorted(tool_counts.items(), key=lambda x: -x[1]):
+        lines.append(f"  • {tool}: {count}")
+
+    lines.append("")
+    lines.append("Context inflation:")
+
+    if inflation_values:
+        inflation_values.sort()
+        median = inflation_values[len(inflation_values) // 2]
+        p95_idx = int(len(inflation_values) * 0.95)
+        p95 = inflation_values[min(p95_idx, len(inflation_values) - 1)]
+        lines.append(f"  median inflation: {median:.2f}x")
+        lines.append(f"  p95 inflation: {p95:.2f}x")
+    else:
+        lines.append("  median inflation: N/A")
+        lines.append("  p95 inflation: N/A")
+
+    lines.append(
+        f"  no-core-change: {no_core_count} edits ({no_core_count / max(total, 1) * 100:.1f}%)"
+    )
+
+    # Worst offenders
+    worst = sorted(edits_with_inflation, key=lambda x: -x[0])[:10]
+    worst = [w for w in worst if w[0] > 20]
+    if worst:
+        lines.append("")
+        lines.append("Worst offenders (>20x inflation):")
+        for i, (ratio, path, total_bytes, core_bytes) in enumerate(worst, 1):
+            lines.append(
+                f"  {i}. {path} — {ratio:.1f}x ({total_bytes:,} bytes → {core_bytes:,} bytes core)"
+            )
+
+    # Failure rate by bucket
+    lines.append("")
+    lines.append("Failure rate by inflation bucket:")
+    for bucket in ("<4x", "4-10x", "10-25x", "25x+"):
+        entries = bucket_success[bucket]
+        if entries:
+            successes = sum(s for s, _ in entries)
+            total_bucket = len(entries)
+            rate = successes / total_bucket * 100
+            lines.append(
+                f"  {bucket}: {rate:.1f}% success ({successes}/{total_bucket})"
+            )
+        else:
+            lines.append(f"  {bucket}: N/A")
+
+    return "\n".join(lines)

code_muse/plugins/universal_constructor/__init__.py

@@ -0,0 +1,13 @@
+"""Universal Constructor - Dynamic tool creation and management plugin.
+
+This plugin enables users to create, manage, and deploy custom tools
+that extend Muse's capabilities. Tools are stored in the user's
+config directory and can be organized into namespaces via subdirectories.
+"""
+
+from pathlib import Path
+
+# User tools directory - where user-created UC tools live
+USER_UC_DIR = Path.home() / ".muse" / "plugins" / "universal_constructor"
+
+__all__ = ["USER_UC_DIR"]