lean_ctx/core/gain/

mod.rs

pub mod bridge_status;
pub mod evidence;
#[allow(dead_code)]
pub mod gain_score;
#[allow(dead_code)]
pub mod live_pricing;
pub mod model_pricing;
pub mod reach;
pub mod stream_savings;
pub mod task_classifier;

use serde::{Deserialize, Serialize};

use crate::core::a2a::cost_attribution::CostStore;
use crate::core::gain::gain_score::GainScore;
use crate::core::gain::model_pricing::{ModelPricing, ModelQuote};
use crate::core::gain::stream_savings::StreamSavings;
use crate::core::gain::task_classifier::{TaskCategory, TaskClassifier};
use crate::core::heatmap::HeatMap;
use crate::core::stats::StatsStore;

#[derive(Clone)]
pub struct GainEngine {
    pub stats: StatsStore,
    pub costs: CostStore,
    pub heatmap: HeatMap,
    pub pricing: ModelPricing,
    pub events: Vec<crate::core::events::LeanCtxEvent>,
    pub session: Option<crate::core::session::SessionState>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GainSummary {
    pub model: ModelQuote,
    pub total_commands: u64,
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub tokens_saved: u64,
    /// Tokens removed from traffic whose output lean-ctx controls.
    #[serde(default)]
    pub effective_input_tokens: u64,
    #[serde(default)]
    pub effective_output_tokens: u64,
    #[serde(default)]
    pub effective_tokens_saved: u64,
    /// Compression percentage over compressible traffic only.
    #[serde(default)]
    pub effective_compression_pct: f64,
    /// Reduction percentage over all recorded traffic, including passthrough.
    #[serde(default)]
    pub total_reduction_pct: f64,
    pub gain_rate_pct: f64,
    /// Fixed per-turn context lean-ctx injects (tool schemas + server
    /// instructions + rules block). On a provider WITHOUT prompt caching this
    /// rides — and is re-billed on — every turn, so the net bill impact is
    /// `tokens_saved − injected_overhead_tokens_per_turn × turns`. Note that
    /// `tokens_saved` / `gain_rate_pct` are measured against lean-ctx-touched
    /// traffic (their denominator), not the full provider bill (GitHub #361).
    #[serde(default)]
    pub injected_overhead_tokens_per_turn: u64,
    /// Provider turns (requests) the proxy actually saw carry the injected
    /// prefix. `0` when the proxy is not in the request path; the provider bill
    /// impact is then unknown (`net_bill_impact_*` = `None`).
    #[serde(default)]
    pub turns: u64,
    /// `injected_overhead_tokens_per_turn × turns` — the total fixed context tax
    /// re-billed across the run on a provider without prompt caching.
    #[serde(default)]
    pub injected_overhead_total_tokens: u64,
    /// `tokens_saved − injected_overhead_total_tokens`. Legacy DTO field: with no
    /// observed provider turn it equals the gross savings and says nothing about
    /// the bill — read `net_bill_impact_tokens` and `economic_evidence` instead.
    #[serde(default)]
    pub net_tokens_saved: i64,
    /// What the economic figures rest on (local estimate … paired control).
    #[serde(default)]
    pub economic_evidence: evidence::EconomicEvidence,
    /// Whether the proxy carried provider requests, i.e. the bill side is visible.
    #[serde(default)]
    pub provider_path_observed: bool,
    /// Net provider-bill impact in tokens — `None` when the provider path was not
    /// observed. Never the gross number in disguise.
    #[serde(default)]
    pub net_bill_impact_tokens: Option<i64>,
    /// Net provider-bill impact in USD — `None` when not observable.
    #[serde(default)]
    pub net_bill_impact_usd: Option<f64>,
    /// Configured fixed-context budget (`[context] budget_tokens`); 0 disables
    /// the check (#964). Surfaced so `gain` can flag a bloated injected prefix.
    #[serde(default)]
    pub injected_overhead_budget_tokens: u64,
    /// Whether `injected_overhead_tokens_per_turn` exceeds a non-zero budget (#964).
    #[serde(default)]
    pub over_budget: bool,
    pub avoided_usd: f64,
    /// Bill-weighted savings split by provider token stream (#1191).
    #[serde(default)]
    pub stream_savings: StreamSavings,
    /// Estimated grid energy avoided (Wh) by keeping `tokens_saved` out of context.
    pub energy_wh: f64,
    /// Estimated CO₂-equivalent avoided (grams), derived from `energy_wh`.
    pub co2_grams: f64,
    pub tool_spend_usd: f64,
    pub roi: Option<f64>,
    pub score: GainScore,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub daemon_hint: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TaskGainRow {
    pub category: TaskCategory,
    pub commands: u64,
    pub tokens_saved: u64,
    pub tool_calls: u64,
    pub tool_spend_usd: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FileGainRow {
    pub path: String,
    pub access_count: u32,
    pub tokens_saved: u64,
    pub compression_pct: f32,
}

/// Navigability (0–100) of the project containing the current working dir, from
/// the persisted Code Health report. `None` when not in a project or the engine
/// has not computed health yet — the gain score then falls back to its legacy
/// four-component weighting so users are never penalised (#1086).
fn current_project_navigability() -> Option<u32> {
    let root = crate::core::config::Config::find_project_root()?;
    crate::core::code_health::persist::load(&root).map(|h| h.score.score)
}

impl GainEngine {
    pub fn load() -> Self {
        Self {
            // Aggregate across split data dirs so the gain score, cost view and
            // net-of-injection line agree with the hero headline (#500).
            stats: crate::core::stats::load_for_display(),
            costs: crate::core::a2a::cost_attribution::CostStore::load(),
            heatmap: crate::core::heatmap::HeatMap::load(),
            pricing: ModelPricing::load(),
            events: crate::core::events::load_events_from_file(500),
            session: crate::core::session::SessionState::load_latest(),
        }
    }

    pub fn summary(&self, model: Option<&str>) -> GainSummary {
        let quote = self.pricing.quote(model);
        let total_tokens_saved = self
            .stats
            .total_input_tokens
            .saturating_sub(self.stats.total_output_tokens);
        let effective = self.stats.compression_totals();
        let effective_tokens_saved = effective.saved_tokens();
        let effective_compression_pct = effective.compression_pct();
        let total_reduction_pct = self.stats.total_reduction_pct();
        let turns = crate::core::context_overhead::observed_turns();
        let (first_inject, reread) = self.stats.stream_savings(turns);
        let injected_overhead_tokens_per_turn =
            crate::core::context_overhead::ContextOverhead::cached().total_tokens() as u64;
        let bounce_tokens = crate::core::bounce_tracker::global()
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .total_wasted_tokens() as u64;
        let stream_savings = StreamSavings::calculate(
            first_inject,
            reread,
            injected_overhead_tokens_per_turn,
            crate::core::context_overhead::native_baseline_tokens_per_turn(),
            turns,
            bounce_tokens,
            quote.cost,
        );
        let avoided_usd = stream_savings.net_usd_saved;
        let tool_spend_usd = self.costs.total_cost().max(0.0);
        let score = GainScore::compute(
            &self.stats,
            &self.costs,
            &self.pricing,
            model,
            current_project_navigability(),
        );
        // is_daemon_running() is cross-platform; the old #[cfg(not(unix))] = None
        // branch suppressed daemon state on Windows. See #576.
        let daemon_hint = if crate::daemon::is_daemon_running() {
            None
        } else {
            Some(
                "daemon not running — stats tracked locally (lean-ctx serve -d for full tracking)"
                    .to_string(),
            )
        };
        // Reconcile to the real bill: the proxy is the only component that sees
        // every provider turn, so its persisted request count is the honest
        // multiplier for the per-turn injection tax (GitHub #361). The math is
        // shared with the verified savings ledger/ROI (#685).
        let (injected_overhead_total_tokens, net_tokens_saved) =
            crate::core::context_overhead::net_of_injection(
                effective_tokens_saved,
                injected_overhead_tokens_per_turn,
                turns,
            );
        // Without an observed provider turn the bill side is invisible: net and ROI
        // stay unknown instead of collapsing to the gross savings.
        let economics = evidence::economic_view(
            self.stats.total_commands,
            turns,
            net_tokens_saved,
            avoided_usd,
            tool_spend_usd,
        );
        let roi = economics.roi;
        // Budget awareness (#964): flag when the fixed per-turn prefix outgrows
        // the configured `[context] budget_tokens` (shared knob with `doctor
        // overhead`). 0 disables the check.
        let injected_overhead_budget_tokens =
            crate::core::config::Config::load().context_budget_tokens_effective() as u64;
        let over_budget = injected_overhead_budget_tokens > 0
            && injected_overhead_tokens_per_turn > injected_overhead_budget_tokens;
        GainSummary {
            model: quote,
            total_commands: self.stats.total_commands,
            input_tokens: self.stats.total_input_tokens,
            output_tokens: self.stats.total_output_tokens,
            tokens_saved: total_tokens_saved,
            effective_input_tokens: effective.input_tokens,
            effective_output_tokens: effective.output_tokens,
            effective_tokens_saved,
            effective_compression_pct,
            total_reduction_pct,
            gain_rate_pct: effective_compression_pct,
            injected_overhead_tokens_per_turn,
            turns,
            injected_overhead_total_tokens,
            net_tokens_saved,
            economic_evidence: economics.evidence,
            provider_path_observed: economics.evidence.bill_impact_observable(),
            net_bill_impact_tokens: economics.net_bill_impact_tokens,
            net_bill_impact_usd: economics.net_bill_impact_usd,
            injected_overhead_budget_tokens,
            over_budget,
            avoided_usd,
            stream_savings,
            energy_wh: crate::core::energy::wh_for_tokens(effective_tokens_saved),
            co2_grams: crate::core::energy::co2_grams_for_tokens(effective_tokens_saved),
            tool_spend_usd,
            roi,
            score,
            daemon_hint,
        }
    }

    pub fn gain_score(&self, model: Option<&str>) -> GainScore {
        GainScore::compute(
            &self.stats,
            &self.costs,
            &self.pricing,
            model,
            current_project_navigability(),
        )
    }

    pub fn task_breakdown(&self) -> Vec<TaskGainRow> {
        use std::collections::HashMap;

        let mut by_cat: HashMap<TaskCategory, TaskGainRow> = HashMap::new();

        for (cmd_key, st) in &self.stats.commands {
            let cat = TaskClassifier::classify_command_key(cmd_key);
            let row = by_cat.entry(cat).or_insert(TaskGainRow {
                category: cat,
                commands: 0,
                tokens_saved: 0,
                tool_calls: 0,
                tool_spend_usd: 0.0,
            });
            row.commands += st.count;
            row.tokens_saved += st.input_tokens.saturating_sub(st.output_tokens);
        }

        for (tool, tc) in &self.costs.tools {
            let cat = TaskClassifier::classify_tool(tool);
            let row = by_cat.entry(cat).or_insert(TaskGainRow {
                category: cat,
                commands: 0,
                tokens_saved: 0,
                tool_calls: 0,
                tool_spend_usd: 0.0,
            });
            row.tool_calls += tc.total_calls;
            row.tool_spend_usd += tc.cost_usd;
        }

        let mut out: Vec<TaskGainRow> = by_cat.into_values().collect();
        out.sort_by_key(|x| std::cmp::Reverse(x.tokens_saved));
        out
    }

    pub fn heatmap_gains(&self, limit: usize) -> Vec<FileGainRow> {
        let mut items: Vec<_> = self.heatmap.entries.values().collect();
        items.sort_by_key(|x| std::cmp::Reverse(x.total_tokens_saved));
        items.truncate(limit);
        items
            .into_iter()
            .map(|e| FileGainRow {
                path: e.path.clone(),
                access_count: e.access_count,
                tokens_saved: e.total_tokens_saved,
                compression_pct: e.avg_compression_ratio * 100.0,
            })
            .collect()
    }
}