Nav Stats

#!/usr/bin/env python3
"""
Calculate Navigator efficiency score (0-100).

Weights:
- Token savings: 40 points (85%+ = max)
- Cache efficiency: 30 points (100% = max)
- Context usage: 30 points (<40% = max, >80% = 0)
"""

import sys
import argparse

def calculate_efficiency_score(
    tokens_saved_percent: float,
    cache_efficiency: float,
    context_usage_percent: float
) -> int:
    """
    Calculate Navigator efficiency score (0-100).

    Args:
        tokens_saved_percent: Percentage of tokens saved vs baseline (0-100)
        cache_efficiency: Cache hit rate (0-100)
        context_usage_percent: Percentage of context window used (0-100)

    Returns:
        int: Efficiency score (0-100)
    """
    # Token savings (40 points max)
    # 85%+ savings = 40 points, linear scale below
    token_score = min(40, (tokens_saved_percent / 85) * 40)

    # Cache efficiency (30 points max)
    # 100% = 30 points, linear scale
    cache_score = (cache_efficiency / 100) * 30

    # Context usage (30 points max)
    # <40% = 30 points (excellent)
    # 40-80% = linear from 30 to 0 (good → fair)
    # >80% = 0 points (poor - context overloaded)
    if context_usage_percent < 40:
        context_score = 30
    elif context_usage_percent <= 80:
        # Linear decay from 30 (at 40%) to 0 (at 80%)
        context_score = 30 - ((context_usage_percent - 40) / 40) * 30
    else:
        context_score = 0

    total_score = int(token_score + cache_score + context_score)

    # Ensure score is in valid range
    return max(0, min(100, total_score))

def interpret_score(score: int) -> str:
    """
    Interpret efficiency score into human-readable rating.

    Args:
        score: Efficiency score (0-100)

    Returns:
        str: Rating (excellent, good, fair, poor)
    """
    if score >= 90:
        return "excellent"
    elif score >= 80:
        return "good"
    elif score >= 70:
        return "fair"
    else:
        return "poor"

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Calculate Navigator efficiency score"
    )
    parser.add_argument(
        "--tokens-saved-percent",
        type=float,
        required=True,
        help="Percentage of tokens saved vs baseline (0-100)"
    )
    parser.add_argument(
        "--cache-efficiency",
        type=float,
        required=True,
        help="Cache hit rate percentage (0-100)"
    )
    parser.add_argument(
        "--context-usage",
        type=float,
        required=True,
        help="Context window usage percentage (0-100)"
    )
    parser.add_argument(
        "--verbose",
        action="store_true",
        help="Show detailed breakdown"
    )

    args = parser.parse_args()

    score = calculate_efficiency_score(
        args.tokens_saved_percent,
        args.cache_efficiency,
        args.context_usage
    )

    if args.verbose:
        rating = interpret_score(score)
        print(f"Efficiency Score: {score}/100 ({rating})")
        print(f"  Token savings: {args.tokens_saved_percent}%")
        print(f"  Cache efficiency: {args.cache_efficiency}%")
        print(f"  Context usage: {args.context_usage}%")
    else:
        # Output just the score (parseable)
        print(score)

    sys.exit(0)

#!/usr/bin/env python3
"""
Format Navigator efficiency metrics into visual, shareable report.
"""

import sys
import argparse

def format_number(num: int) -> str:
    """Format number with commas for readability."""
    return f"{num:,}"

def interpret_score(score: int) -> str:
    """Get rating label for score."""
    if score >= 90:
        return "excellent"
    elif score >= 80:
        return "good"
    elif score >= 70:
        return "fair"
    else:
        return "poor"

def get_recommendations(
    savings_percent: int,
    cache_efficiency: float,
    context_usage: int,
    efficiency_score: int
) -> list:
    """
    Generate actionable recommendations based on metrics.

    Returns:
        list: List of recommendation strings
    """
    recs = []

    # Check token savings
    if savings_percent < 70:
        recs.append(("⚠️", "Token savings below target (70%+)"))
        recs.append(("→", "Check: Are you loading more docs than needed?"))
        recs.append(("→", "Tip: Use navigator to find docs, don't load all upfront"))
        recs.append(("", "Read more: .agent/philosophy/CONTEXT-EFFICIENCY.md"))
    elif savings_percent >= 85:
        recs.append(("✅", "Excellent token savings - keep using lazy-loading strategy"))

    # Check cache efficiency
    if cache_efficiency < 80:
        recs.append(("⚠️", "Cache efficiency low (<80%)"))
        recs.append(("→", "Check: CLAUDE.md properly configured?"))
        recs.append(("→", "Tip: Ensure prompt caching enabled"))
        recs.append(("", "Read more: .agent/philosophy/PATTERNS.md (Caching pattern)"))
    elif cache_efficiency >= 95:
        recs.append(("✅", "Cache working perfectly - no optimization needed"))

    # Check context usage
    if context_usage > 80:
        recs.append(("⚠️", "Context usage high (80%+)"))
        recs.append(("→", "Consider: Create context marker and compact"))
        recs.append(("→", "Tip: Compact after completing sub-tasks"))
        recs.append(("", "Read more: .agent/philosophy/ANTI-PATTERNS.md"))
    elif context_usage < 40:
        recs.append(("✅", "Context usage healthy - plenty of room for work"))

    # Default excellent message
    if not recs and efficiency_score >= 90:
        recs.append(("✅", "Excellent efficiency - keep it up!"))
        recs.append(("", ""))
        recs.append(("", "Share your efficiency: Take a screenshot! #ContextEfficiency"))

    return recs

def format_report(
    baseline: int,
    loaded: int,
    saved: int,
    savings_percent: int,
    cache_efficiency: float,
    context_usage: int,
    efficiency_score: int,
    time_saved: int
) -> str:
    """
    Format efficiency report.

    Returns:
        str: Formatted report
    """
    rating = interpret_score(efficiency_score)
    recs = get_recommendations(savings_percent, cache_efficiency, context_usage, efficiency_score)

    report = f"""╔══════════════════════════════════════════════════════╗
║          NAVIGATOR EFFICIENCY REPORT                 ║
╚══════════════════════════════════════════════════════╝

📊 TOKEN USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Documentation loaded:    {format_number(loaded):>12} tokens
Baseline (all docs):     {format_number(baseline):>12} tokens
Tokens saved:            {format_number(saved):>12} tokens ({savings_percent}% ↓)

💾 CACHE PERFORMANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cache efficiency:        {cache_efficiency:>16.1f}% ({"perfect" if cache_efficiency >= 99 else "good" if cache_efficiency >= 90 else "fair"})

📈 SESSION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context usage:           {context_usage:>16}% ({rating})
Efficiency score:        {efficiency_score:>12}/100 ({rating})

⏱️  TIME SAVED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Estimated time saved:    {time_saved:>13} minutes

💡 WHAT THIS MEANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Navigator loaded {savings_percent}% fewer tokens than loading all docs.
Your context window is {100 - context_usage}% available for actual work.
"""

    # Add recommendations section
    if recs:
        report += "\n🎯 RECOMMENDATIONS\n"
        report += "━" * 54 + "\n"
        for icon, text in recs:
            if icon:
                report += f"{icon}  {text}\n"
            else:
                report += f"{text}\n"

    return report

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Format Navigator efficiency report"
    )
    parser.add_argument("--baseline", type=int, required=True, help="Baseline tokens (all docs)")
    parser.add_argument("--loaded", type=int, required=True, help="Actually loaded tokens")
    parser.add_argument("--saved", type=int, required=True, help="Tokens saved")
    parser.add_argument("--savings-percent", type=int, required=True, help="Savings percentage")
    parser.add_argument("--cache-efficiency", type=float, required=True, help="Cache efficiency %")
    parser.add_argument("--context-usage", type=int, required=True, help="Context usage %")
    parser.add_argument("--efficiency-score", type=int, required=True, help="Efficiency score (0-100)")
    parser.add_argument("--time-saved", type=int, required=True, help="Time saved (minutes)")

    args = parser.parse_args()

    report = format_report(
        args.baseline,
        args.loaded,
        args.saved,
        args.savings_percent,
        args.cache_efficiency,
        args.context_usage,
        args.efficiency_score,
        args.time_saved
    )

    print(report)
    sys.exit(0)