@opendash-ai/cli 0.1.0-beta.1 → 0.1.0-beta.2

package/src/intelligence/analytics/reasoning/visible-reasoning.ts

@@ -1,609 +0,0 @@
-/**
- * Visible Reasoning Engine - Enterprise Quality
- * 
- * Makes the reasoning engine the VISIBLE NARRATOR.
- * 
- * 9 Requirements:
- * 1. Force reasoning before tool execution
- * 2. Surface reasoning to the user
- * 3. Remove fabricated business values
- * 4. Confidence must be evidence-based
- * 5. Recommendations must include decision scoring
- * 6. Use KPI equations
- * 7. Use counterfactual reasoning
- * 8. Explain every major conclusion
- * 9. Make reasoning engine the visible narrator
- */
-
-import { Effect, Context, Layer } from "effect"
-import { Log } from "../../../util"
-
-const log = Log.create({ service: "analytics.visible-reasoning" }
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-export interface VisibleReasoning {
-  // Step 1: Business Objective
-  businessObjective: string
-  
-  // Step 2: Problem Decomposition
-  problemDecomposition: string
-  
-  // Step 3: Workflow Selection
-  workflowSelection: string
-  
-  // Step 4: KPI Identification
-  kpiIdentification: string
-  
-  // Step 5: Hypotheses with Evidence
-  hypotheses: HypothesisWithEvidence[]
-  
-  // Step 6: Required Data
-  requiredData: string
-  
-  // Step 7: Analysis Plan
-  analysisPlan: string
-  
-  // Step 8: Confidence (Evidence-Based)
-  confidence: EvidenceBasedConfidence
-  
-  // Step 9: Recommendations with Decision Scoring
-  recommendations: RecommendationWithScoring[]
-  
-  // Step 10: Counterfactual Analysis
-  counterfactuals: CounterfactualAnalysis[]
-  
-  // Step 11: Conclusions with Evidence Chain
-  conclusions: ConclusionWithEvidence[]
-  
-  // Full narrative for user
-  narrative: string
-}
-
-export interface HypothesisWithEvidence {
-  id: string
-  statement: string
-  supporting: string[]
-  against: string[]
-  unknowns: string[]
-  testMethod: string
-  confidence: string
-}
-
-export interface EvidenceBasedConfidence {
-  overall: string
-  factors: ConfidenceFactor[]
-  formula: string
-}
-
-export interface ConfidenceFactor {
-  name: string
-  value: string
-  weight: number
-  contribution: string
-}
-
-export interface RecommendationWithScoring {
-  id: string
-  recommendation: string
-  impact: string
-  effort: string
-  risk: string
-  confidence: string
-  priorityScore: number
-  supportingEvidence: string
-}
-
-export interface CounterfactualAnalysis {
-  scenario: string
- 假设: string
-  expectedOutcome: string
-  calculation: string
-  supportedByData: boolean
-}
-
-export interface ConclusionWithEvidence {
-  conclusion: string
-  evidence: string
-  analysis: string
-  businessAction: string
-}
-
-// ─── Visible Reasoning Interface ─────────────────────────────────────────────
-
-export interface VisibleReasoningInterface {
-  readonly generateNarrative: (request: string) => Effect.Effect<VisibleReasoning>
-  readonly formatForUser: (reasoning: VisibleReasoning) => string
-  readonly formatBusinessObjective: (objective: string) => string
-  readonly formatProblemDecomposition: (decomposition: string) => string
-  readonly formatWorkflowSelection: (selection: string) => string
-  readonly formatKPIIdentification: (kpis: string) => string
-  readonly formatHypotheses: (hypotheses: HypothesisWithEvidence[]) => string
-  readonly formatRequiredData: (data: string) => string
-  readonly formatAnalysisPlan: (plan: string) => string
-  readonly formatConfidence: (confidence: EvidenceBasedConfidence) => string
-  readonly formatRecommendations: (recommendations: RecommendationWithScoring[]) => string
-  readonly formatCounterfactuals: (counterfactuals: CounterfactualAnalysis[]) => string
-  readonly formatConclusions: (conclusions: ConclusionWithEvidence[]) => string
-}
-
-export class VisibleReasoningEngine extends Context.Service<VisibleReasoningEngine, VisibleReasoningInterface>()("@opendash/VisibleReasoningEngine") {}
-
-// ─── Implementation ──────────────────────────────────────────────────────────
-
-const layer: Layer.Layer<VisibleReasoningEngine, never, never> = Layer.effect(
-  VisibleReasoningEngine,
-  Effect.gen(function* () {
-
-    // Generate complete visible reasoning
-    const generateNarrative = Effect.fn("generateNarrative")(function* (request: string) {
-      const lower = request.toLowerCase()
-      
-      // Step 1: Business Objective
-      let businessObjective = "Understand the situation and provide actionable recommendations"
-      if (/sales|revenue/i.test(lower)) {
-        businessObjective = "Identify why sales/revenue changed and recommend actions to address it"
-      } else if (/churn|retain/i.test(lower)) {
-        businessObjective = "Understand why customers are leaving and recommend retention strategies"
-      } else if (/forecast|predict/i.test(lower)) {
-        businessObjective = "Generate accurate forecasts to support business planning"
-      } else if (/optimize|improve/i.test(lower)) {
-        businessObjective = "Identify optimization opportunities and recommend improvements"
-      }
-      
-      // Step 2: Problem Decomposition
-      let problemDecomposition = `The request "${request}" needs to be decomposed into analyzable components.`
-      if (/dropped|declined|decreased|down/i.test(lower)) {
-        problemDecomposition = `This is a diagnostic problem: something declined and we need to understand why. We will investigate potential causes systematically.`
-      } else if (/forecast|predict|future/i.test(lower)) {
-        problemDecomposition = `This is a predictive problem: we need to estimate future values based on historical patterns.`
-      } else if (/optimize|improve|increase/i.test(lower)) {
-        problemDecomposition = `This is a prescriptive problem: we need to identify opportunities for improvement.`
-      }
-      
-      // Step 3: Workflow Selection
-      let workflowSelection = "Exploratory Data Analysis"
-      let workflowReasoning = "Default to exploration when problem type is unclear"
-      if (/dropped|declined|why/i.test(lower)) {
-        workflowSelection = "Root Cause Analysis"
-        workflowReasoning = "Problem is diagnostic - investigating why something happened"
-      } else if (/forecast|predict/i.test(lower)) {
-        workflowSelection = "Forecasting"
-        workflowReasoning = "Problem involves temporal prediction"
-      } else if (/optimize|improve/i.test(lower)) {
-        workflowSelection = "Optimization Analysis"
-        workflowReasoning = "Problem requires identifying improvement opportunities"
-      }
-      
-      // Step 4: KPI Identification
-      let kpiIdentification = "Primary metric needs to be identified from the data"
-      if (/sales|revenue/i.test(lower)) {
-        kpiIdentification = `Revenue = Price × Quantity\n\nDecompose into: Price, Quantity, and their drivers`
-      } else if (/churn/i.test(lower)) {
-        kpiIdentification = `Churn Rate = Customers Lost / Customers at Start\n\nCLV = ARPU / Churn Rate\n\nImpact: Churn increase directly reduces customer lifetime value`
-      } else if (/conversion/i.test(lower)) {
-        kpiIdentification = `Conversion Rate = Orders / Sessions\n\nDecompose into: Traffic quality, UX effectiveness, pricing`
-      }
-      
-      // Step 5: Hypotheses with Evidence
-      const hypotheses: HypothesisWithEvidence[] = []
-      
-      if (/sales|revenue|dropped|declined/i.test(lower)) {
-        hypotheses.push({
-          id: "H1",
-          statement: "Marketing spend reduction caused the decline",
-          supporting: [
-            "Historical data shows marketing-revenue correlation",
-            "Marketing budget was reduced in the period",
-          ],
-          against: [
-            "Organic traffic remained stable",
-            "Brand search volume unchanged",
-          ],
-          unknowns: [
-            "Competitor marketing spend",
-            "Market-wide advertising trends",
-          ],
-          testMethod: "Regression analysis with marketing spend as predictor",
-          confidence: "Medium - requires marketing spend data to verify",
-        })
-        
-        hypotheses.push({
-          id: "H2",
-          statement: "Seasonal factors contributed to the decline",
-          supporting: [
-            "Same period last year showed similar pattern",
-            "Industry trends indicate seasonal variation",
-          ],
-          against: [
-            "Decline exceeds normal seasonal variation",
-          ],
-          unknowns: [
-            "Complete seasonal history",
-            "External economic factors",
-          ],
-          testMethod: "Time series decomposition + year-over-year comparison",
-          confidence: "Medium - requires 2+ years of historical data",
-        })
-        
-        hypotheses.push({
-          id: "H3",
-          statement: "Competitive pressure affected market share",
-          supporting: [
-            "New competitor entered market",
-            "Industry reports show price competition",
-          ],
-          against: [
-            "Our prices remained stable",
-            "Customer surveys don't cite price",
-          ],
-          unknowns: [
-            "Competitor market share data",
-            "Price elasticity of our products",
-          ],
-          testMethod: "Competitive analysis + price sensitivity testing",
-          confidence: "Low - limited competitive data available",
-        })
-      }
-      
-      // Step 6: Required Data
-      let requiredData = "Data requirements need to be determined based on the analysis plan"
-      if (/sales|revenue/i.test(lower)) {
-        requiredData = `Required Data:
-- Sales transactions (date, amount, product, region)
-- Marketing spend (date, channel, amount)
-- Customer data (segments, acquisition source)
-- Historical data (2+ years for seasonality)
-
-Data Quality Checks:
-- Completeness > 95%
-- No duplicate transactions
-- Consistent date formatting
-- Valid product categories`
-      }
-      
-      // Step 7: Analysis Plan
-      let analysisPlan = `Phase 1: Data Quality Assessment
-- Validate completeness and accuracy
-- Identify missing values and outliers
-- Document data limitations
-
-Phase 2: Exploratory Analysis
-- Descriptive statistics
-- Distribution analysis
-- Correlation analysis
-
-Phase 3: Hypothesis Testing
-- Test each hypothesis with appropriate method
-- Calculate statistical significance
-- Document findings
-
-Phase 4: Root Cause Analysis
-- Identify primary drivers
-- Quantify contribution of each factor
-- Validate with evidence
-
-Phase 5: Recommendations
-- Develop actionable recommendations
-- Assess impact, effort, and risk
-- Prioritize by business value`
-      
-      // Step 8: Confidence (Evidence-Based)
-      const confidence: EvidenceBasedConfidence = {
-        overall: "Cannot determine without data analysis",
-        factors: [
-          {
-            name: "Data Completeness",
-            value: "Unknown",
-            weight: 0.3,
-            contribution: "Requires data quality assessment",
-          },
-          {
-            name: "Sample Size",
-            value: "Unknown",
-            weight: 0.2,
-            contribution: "Requires count of observations",
-          },
-          {
-            name: "Statistical Significance",
-            value: "Unknown",
-            weight: 0.3,
-            contribution: "Requires hypothesis testing",
-          },
-          {
-            name: "Validation Checks",
-            value: "Unknown",
-            weight: 0.2,
-            contribution: "Requires model validation",
-          },
-        ],
-        formula: "Confidence = Σ(Factor_Value × Factor_Weight) / Σ(Weights)",
-      }
-      
-      // Step 9: Recommendations with Decision Scoring
-      const recommendations: RecommendationWithScoring[] = []
-      
-      if (/sales|revenue|dropped|declined/i.test(lower)) {
-        recommendations.push({
-          id: "R1",
-          recommendation: "Investigate marketing spend impact on revenue",
-          impact: "High - Marketing often drives 30-50% of revenue",
-          effort: "Medium - Requires marketing data analysis",
-          risk: "Low - Reversible decision",
-          confidence: "Medium - Depends on data availability",
-          priorityScore: 8.5,
-          supportingEvidence: "Historical correlation between marketing spend and revenue",
-        })
-        
-        recommendations.push({
-          id: "R2",
-          recommendation: "Analyze seasonal patterns",
-          impact: "Medium - Seasonality typically explains 10-20% variation",
-          effort: "Low - Requires historical data comparison",
-          risk: "Low - No business change required",
-          confidence: "High - Well-established statistical method",
-          priorityScore: 7.5,
-          supportingEvidence: "Industry-standard approach for revenue analysis",
-        })
-        
-        recommendations.push({
-          id: "R3",
-          recommendation: "Monitor competitive landscape",
-          impact: "Medium - Competitive factors can shift market share",
-          effort: "High - Requires ongoing market research",
-          risk: "Medium - May reveal uncomfortable truths",
-          confidence: "Low - Limited competitive data",
-          priorityScore: 5.0,
-          supportingEvidence: "General business principle - competitors affect performance",
-        })
-      }
-      
-      // Step 10: Counterfactual Analysis
-      const counterfactuals: CounterfactualAnalysis[] = []
-      
-      if (/sales|revenue|dropped|declined/i.test(lower)) {
-        counterfactuals.push({
-          scenario: "What if marketing spend had remained constant?",
-          假设: "Marketing has a causal effect on revenue",
-          expectedOutcome: "Revenue would have declined less (estimated 5-10% instead of 18%)",
-          calculation: "Based on historical marketing elasticity of 0.3-0.5",
-          supportedByData: false, // Cannot calculate without actual data
-        })
-        
-        counterfactuals.push({
-          scenario: "What if we restore marketing to previous levels?",
-          假设: "Marketing effectiveness remains stable",
-          expectedOutcome: "Revenue recovery of 8-12% within 2 quarters",
-          calculation: "Cannot estimate from available data - requires actual marketing ROI measurement",
-          supportedByData: false,
-        })
-      }
-      
-      // Step 11: Conclusions with Evidence Chain
-      const conclusions: ConclusionWithEvidence[] = []
-      
-      if (/sales|revenue|dropped|declined/i.test(lower)) {
-        conclusions.push({
-          conclusion: "Multiple factors likely contributed to the revenue decline",
-          evidence: "Historical patterns, marketing changes, competitive dynamics",
-          analysis: "Requires comprehensive data analysis to isolate primary drivers",
-          businessAction: "Conduct detailed analysis before making strategic changes",
-        })
-      }
-      
-      // Generate full narrative
-      const narrative = [
-        `## Business Objective`,
-        businessObjective,
-        ``,
-        `## Problem Decomposition`,
-        problemDecomposition,
-        ``,
-        `## Workflow Selection`,
-        `Selected: ${workflowSelection}`,
-        `Reasoning: ${workflowReasoning}`,
-        ``,
-        `## KPI Identification`,
-        kpiIdentification,
-        ``,
-        `## Hypotheses`,
-        ...hypotheses.map(h => [
-          `### ${h.id}: ${h.statement}`,
-          `**Supporting Evidence:**`,
-          ...h.supporting.map(s => `- ${s}`),
-          `**Against Evidence:**`,
-          ...h.against.map(a => `- ${a}`),
-          `**Unknown Information:**`,
-          ...h.unknowns.map(u => `- ${u}`),
-          `**Test Method:** ${h.testMethod}`,
-          `**Confidence:** ${h.confidence}`,
-        ].join("\n")),
-        ``,
-        `## Required Data`,
-        requiredData,
-        ``,
-        `## Analysis Plan`,
-        analysisPlan,
-        ``,
-        `## Confidence Assessment`,
-        `**Overall:** ${confidence.overall}`,
-        `**Formula:** ${confidence.formula}`,
-        `**Factors:**`,
-        ...confidence.factors.map(f => `- ${f.name}: ${f.value} (weight: ${f.weight}) - ${f.contribution}`),
-        ``,
-        `## Recommendations`,
-        ...recommendations.map(r => [
-          `### ${r.id}: ${r.recommendation}`,
-          `**Impact:** ${r.impact}`,
-          `**Effort:** ${r.effort}`,
-          `**Risk:** ${r.risk}`,
-          `**Confidence:** ${r.confidence}`,
-          `**Priority Score:** ${r.priorityScore}/10`,
-          `**Supporting Evidence:** ${r.supportingEvidence}`,
-        ].join("\n")),
-        ``,
-        `## Counterfactual Analysis`,
-        ...counterfactuals.map(c => [
-          `### ${c.scenario}`,
-          `**Assumption:** ${c.假设}`,
-          `**Expected Outcome:** ${c.expectedOutcome}`,
-          `**Calculation:** ${c.calculation}`,
-          `**Supported by Data:** ${c.supportedByData ? "Yes" : "No - Cannot estimate from available data"}`,
-        ].join("\n")),
-        ``,
-        `## Conclusions`,
-        ...conclusions.map(c => [
-          `**Conclusion:** ${c.conclusion}`,
-          `**Evidence:** ${c.evidence}`,
-          `**Analysis:** ${c.analysis}`,
-          `**Business Action:** ${c.businessAction}`,
-        ].join("\n")),
-      ].join("\n")
-      
-      return {
-        businessObjective,
-        problemDecomposition,
-        workflowSelection: `${workflowSelection} - ${workflowReasoning}`,
-        kpiIdentification,
-        hypotheses,
-        requiredData,
-        analysisPlan,
-        confidence,
-        recommendations,
-        counterfactuals,
-        conclusions,
-        narrative,
-      }
-    })
-
-    // Format for user display
-    const formatForUser = (reasoning: VisibleReasoning): string => {
-      return reasoning.narrative
-    }
-
-    const formatBusinessObjective = (objective: string): string => {
-      return `## Business Objective\n\n${objective}`
-    }
-
-    const formatProblemDecomposition = (decomposition: string): string => {
-      return `## Problem Decomposition\n\n${decomposition}`
-    }
-
-    const formatWorkflowSelection = (selection: string): string => {
-      return `## Workflow Selection\n\n${selection}`
-    }
-
-    const formatKPIIdentification = (kpis: string): string => {
-      return `## KPI Identification\n\n${kpis}`
-    }
-
-    const formatHypotheses = (hypotheses: HypothesisWithEvidence[]): string => {
-      return [
-        `## Hypotheses`,
-        ``,
-        ...hypotheses.map(h => [
-          `### ${h.id}: ${h.statement}`,
-          ``,
-          `**Supporting Evidence:**`,
-          ...h.supporting.map(s => `- ${s}`),
-          ``,
-          `**Against Evidence:**`,
-          ...h.against.map(a => `- ${a}`),
-          ``,
-          `**Unknown Information:**`,
-          ...h.unknowns.map(u => `- ${u}`),
-          ``,
-          `**Test Method:** ${h.testMethod}`,
-          `**Confidence:** ${h.confidence}`,
-        ].join("\n")),
-      ].join("\n")
-    }
-
-    const formatRequiredData = (data: string): string => {
-      return `## Required Data\n\n${data}`
-    }
-
-    const formatAnalysisPlan = (plan: string): string => {
-      return `## Analysis Plan\n\n${plan}`
-    }
-
-    const formatConfidence = (confidence: EvidenceBasedConfidence): string => {
-      return [
-        `## Confidence Assessment`,
-        ``,
-        `**Overall:** ${confidence.overall}`,
-        ``,
-        `**Formula:** ${confidence.formula}`,
-        ``,
-        `**Factors:**`,
-        ...confidence.factors.map(f => `- ${f.name}: ${f.value} (weight: ${f.weight}) - ${f.contribution}`),
-      ].join("\n")
-    }
-
-    const formatRecommendations = (recommendations: RecommendationWithScoring[]): string => {
-      return [
-        `## Recommendations`,
-        ``,
-        ...recommendations.map(r => [
-          `### ${r.id}: ${r.recommendation}`,
-          ``,
-          `| Factor | Assessment |`,
-          `|--------|------------|`,
-          `| Impact | ${r.impact} |`,
-          `| Effort | ${r.effort} |`,
-          `| Risk | ${r.risk} |`,
-          `| Confidence | ${r.confidence} |`,
-          `| Priority Score | ${r.priorityScore}/10 |`,
-          ``,
-          `**Supporting Evidence:** ${r.supportingEvidence}`,
-        ].join("\n")),
-      ].join("\n")
-    }
-
-    const formatCounterfactuals = (counterfactuals: CounterfactualAnalysis[]): string => {
-      return [
-        `## Counterfactual Analysis`,
-        ``,
-        ...counterfactuals.map(c => [
-          `### ${c.scenario}`,
-          ``,
-          `**Assumption:** ${c.假设}`,
-          `**Expected Outcome:** ${c.expectedOutcome}`,
-          `**Calculation:** ${c.calculation}`,
-          `**Supported by Data:** ${c.supportedByData ? "Yes" : "No - Cannot estimate from available data"}`,
-        ].join("\n")),
-      ].join("\n")
-    }
-
-    const formatConclusions = (conclusions: ConclusionWithEvidence[]): string => {
-      return [
-        `## Conclusions`,
-        ``,
-        ...conclusions.map(c => [
-          `**Conclusion:** ${c.conclusion}`,
-          `**Evidence:** ${c.evidence}`,
-          `**Analysis:** ${c.analysis}`,
-          `**Business Action:** ${c.businessAction}`,
-        ].join("\n")),
-      ].join("\n")
-    }
-
-    return VisibleReasoningEngine.of({
-      generateNarrative,
-      formatForUser,
-      formatBusinessObjective,
-      formatProblemDecomposition,
-      formatWorkflowSelection,
-      formatKPIIdentification,
-      formatHypotheses,
-      formatRequiredData,
-      formatAnalysisPlan,
-      formatConfidence,
-      formatRecommendations,
-      formatCounterfactuals,
-      formatConclusions,
-    })
-  })
-)
-
-export const defaultLayer = layer