mdcontext 0.0.1 → 0.2.0

package/src/summarization/cost.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for Cost Estimation Module
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  API_PRICING,
+  estimateSummaryCost,
+  estimateTokens,
+  formatCostDisplay,
+} from './cost.js'
+
+describe('estimateTokens', () => {
+  it('should estimate ~4 chars per token', () => {
+    expect(estimateTokens('test')).toBe(1)
+    expect(estimateTokens('testtest')).toBe(2)
+    expect(estimateTokens('x'.repeat(100))).toBe(25)
+  })
+
+  it('should round up partial tokens', () => {
+    expect(estimateTokens('abc')).toBe(1) // 0.75 -> 1
+    expect(estimateTokens('abcde')).toBe(2) // 1.25 -> 2
+  })
+
+  it('should handle empty string', () => {
+    expect(estimateTokens('')).toBe(0)
+  })
+})
+
+describe('estimateSummaryCost', () => {
+  describe('CLI providers (free)', () => {
+    it('should return isPaid=false for CLI mode', () => {
+      const result = estimateSummaryCost('test input', 'cli', 'claude')
+      expect(result.isPaid).toBe(false)
+      expect(result.estimatedCost).toBe(0)
+      expect(result.formattedCost).toBe('FREE (subscription)')
+    })
+
+    it('should still estimate tokens for CLI mode', () => {
+      const input = 'x'.repeat(400) // ~100 tokens
+      const result = estimateSummaryCost(input, 'cli', 'claude')
+      expect(result.inputTokens).toBe(100)
+      expect(result.outputTokens).toBe(500) // default
+    })
+  })
+
+  describe('API providers (paid)', () => {
+    it('should calculate cost for DeepSeek', () => {
+      const input = 'x'.repeat(4000) // ~1000 tokens
+      const result = estimateSummaryCost(input, 'api', 'deepseek', 500)
+
+      expect(result.inputTokens).toBe(1000)
+      expect(result.outputTokens).toBe(500)
+      expect(result.isPaid).toBe(true)
+      // Input: 1000 * 0.14 / 1M = 0.00014
+      // Output: 500 * 0.56 / 1M = 0.00028
+      // Total: 0.00042
+      expect(result.estimatedCost).toBeCloseTo(0.00042, 5)
+    })
+
+    it('should calculate cost for Anthropic (more expensive)', () => {
+      const input = 'x'.repeat(4000) // ~1000 tokens
+      const result = estimateSummaryCost(input, 'api', 'anthropic', 500)
+
+      expect(result.isPaid).toBe(true)
+      // Input: 1000 * 3.0 / 1M = 0.003
+      // Output: 500 * 15.0 / 1M = 0.0075
+      // Total: 0.0105
+      expect(result.estimatedCost).toBeCloseTo(0.0105, 4)
+    })
+
+    it('should calculate cost for OpenAI', () => {
+      const input = 'x'.repeat(4000)
+      const result = estimateSummaryCost(input, 'api', 'openai', 500)
+
+      expect(result.isPaid).toBe(true)
+      // Input: 1000 * 1.75 / 1M = 0.00175
+      // Output: 500 * 14.0 / 1M = 0.007
+      // Total: 0.00875
+      expect(result.estimatedCost).toBeCloseTo(0.00875, 5)
+    })
+
+    it('should handle CLI provider used with API mode (falls back to deepseek pricing)', () => {
+      const input = 'x'.repeat(4000)
+      // When a CLI provider is used with API mode, it falls back to deepseek pricing
+      const result = estimateSummaryCost(input, 'api', 'claude', 500)
+
+      expect(result.isPaid).toBe(true)
+      expect(result.estimatedCost).toBeCloseTo(0.00042, 5)
+    })
+  })
+
+  describe('provider comparison', () => {
+    it('should show Qwen as cheapest API provider', () => {
+      const input = 'x'.repeat(4000)
+      const qwen = estimateSummaryCost(input, 'api', 'qwen', 500)
+      const deepseek = estimateSummaryCost(input, 'api', 'deepseek', 500)
+      const anthropic = estimateSummaryCost(input, 'api', 'anthropic', 500)
+
+      expect(qwen.estimatedCost).toBeLessThan(deepseek.estimatedCost)
+      expect(deepseek.estimatedCost).toBeLessThan(anthropic.estimatedCost)
+    })
+  })
+})
+
+describe('formatCostDisplay', () => {
+  it('should format free CLI cost', () => {
+    const estimate = estimateSummaryCost('test', 'cli', 'claude')
+    const display = formatCostDisplay(estimate)
+    expect(display).toContain('FREE')
+    expect(display).toContain('claude')
+  })
+
+  it('should format paid API cost', () => {
+    const estimate = estimateSummaryCost('test', 'api', 'deepseek')
+    const display = formatCostDisplay(estimate)
+    expect(display).toContain('Estimated cost')
+    expect(display).toContain('$')
+  })
+})
+
+describe('API_PRICING', () => {
+  it('should have all expected providers', () => {
+    expect(API_PRICING.deepseek).toBeDefined()
+    expect(API_PRICING.qwen).toBeDefined()
+    expect(API_PRICING.anthropic).toBeDefined()
+    expect(API_PRICING.openai).toBeDefined()
+    expect(API_PRICING.gemini).toBeDefined()
+  })
+
+  it('should have valid pricing (input < output)', () => {
+    for (const pricing of Object.values(API_PRICING)) {
+      expect(pricing.input).toBeGreaterThan(0)
+      expect(pricing.output).toBeGreaterThan(0)
+      // Output tokens typically cost more
+      expect(pricing.output).toBeGreaterThanOrEqual(pricing.input)
+    }
+  })
+})

package/src/summarization/cost.ts

@@ -0,0 +1,102 @@
+/**
+ * Cost Estimation for AI Summarization
+ *
+ * Provides cost estimates for API providers before running queries.
+ * CLI providers are free (subscription-based), so cost is always 0.
+ */
+
+import type {
+  APIProviderName,
+  CLIProviderName,
+  SummarizationMode,
+} from './types.js'
+
+/**
+ * Type guard to check if a provider is an API provider
+ */
+const isAPIProvider = (provider: string): provider is APIProviderName => {
+  return ['deepseek', 'anthropic', 'openai', 'gemini', 'qwen'].includes(
+    provider,
+  )
+}
+
+/**
+ * Pricing per 1 million tokens for each provider.
+ * Values as of January 2026.
+ */
+export const API_PRICING: Record<
+  APIProviderName,
+  { input: number; output: number; displayName: string }
+> = {
+  deepseek: { input: 0.14, output: 0.56, displayName: 'DeepSeek' },
+  qwen: { input: 0.03, output: 0.12, displayName: 'Qwen' },
+  anthropic: { input: 3.0, output: 15.0, displayName: 'Anthropic Claude' },
+  openai: { input: 1.75, output: 14.0, displayName: 'OpenAI GPT' },
+  gemini: { input: 0.3, output: 2.5, displayName: 'Google Gemini' },
+}
+
+/**
+ * Cost estimate result
+ */
+export interface CostEstimate {
+  readonly inputTokens: number
+  readonly outputTokens: number
+  readonly estimatedCost: number
+  readonly provider: string
+  readonly isPaid: boolean
+  readonly formattedCost: string
+}
+
+/**
+ * Simple token estimation (4 chars ≈ 1 token).
+ */
+export const estimateTokens = (text: string): number => {
+  return Math.ceil(text.length / 4)
+}
+
+/**
+ * Estimate the cost of summarizing text.
+ */
+export const estimateSummaryCost = (
+  input: string,
+  mode: SummarizationMode,
+  provider: CLIProviderName | APIProviderName,
+  maxOutputTokens: number = 500,
+): CostEstimate => {
+  const inputTokens = estimateTokens(input)
+
+  if (mode === 'cli') {
+    return {
+      inputTokens,
+      outputTokens: maxOutputTokens,
+      estimatedCost: 0,
+      provider,
+      isPaid: false,
+      formattedCost: 'FREE (subscription)',
+    }
+  }
+
+  // For API mode, use API pricing (default to deepseek if provider not found)
+  const pricing = isAPIProvider(provider)
+    ? API_PRICING[provider]
+    : API_PRICING.deepseek
+  const inputCost = (inputTokens * pricing.input) / 1_000_000
+  const outputCost = (maxOutputTokens * pricing.output) / 1_000_000
+  const totalCost = inputCost + outputCost
+
+  return {
+    inputTokens,
+    outputTokens: maxOutputTokens,
+    estimatedCost: totalCost,
+    provider,
+    isPaid: true,
+    formattedCost: `$${totalCost.toFixed(4)}`,
+  }
+}
+
+export const formatCostDisplay = (estimate: CostEstimate): string => {
+  if (!estimate.isPaid) {
+    return `Using ${estimate.provider} (subscription - FREE)`
+  }
+  return `Estimated cost: ${estimate.formattedCost}`
+}

package/src/summarization/error-handler.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Tests for Error Handler Module
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  formatSummarizationError,
+  isRecoverableError,
+} from './error-handler.js'
+import { SummarizationError } from './types.js'
+
+describe('formatSummarizationError', () => {
+  describe('SummarizationError handling', () => {
+    it('should format PROVIDER_NOT_AVAILABLE with install URL', () => {
+      const error = new SummarizationError(
+        'Claude not installed',
+        'PROVIDER_NOT_AVAILABLE',
+        'claude',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('not available')
+      expect(message).toContain('https://claude.ai/download')
+    })
+
+    it('should format NO_API_KEY with env var hint', () => {
+      const error = new SummarizationError(
+        'API key missing',
+        'NO_API_KEY',
+        'deepseek',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('API key')
+      expect(message).toContain('DEEPSEEK_API_KEY')
+    })
+
+    it('should format RATE_LIMITED with CLI suggestion', () => {
+      const error = new SummarizationError(
+        'Rate limit hit',
+        'RATE_LIMITED',
+        'openai',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('Rate limit')
+      expect(message).toContain('CLI provider')
+    })
+
+    it('should format CLI_EXECUTION_FAILED with details', () => {
+      const error = new SummarizationError(
+        'Process exited with code 1',
+        'CLI_EXECUTION_FAILED',
+        'claude',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('CLI error')
+      expect(message).toContain('Process exited with code 1')
+    })
+
+    it('should handle TIMEOUT errors', () => {
+      const error = new SummarizationError(
+        'Something went wrong',
+        'TIMEOUT',
+        'claude',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('timed out')
+    })
+  })
+
+  describe('generic Error handling', () => {
+    it('should extract message from regular Error', () => {
+      const error = new Error('Network failed')
+      const message = formatSummarizationError(error)
+
+      expect(message).toBe('Network failed')
+    })
+  })
+
+  describe('unknown error handling', () => {
+    it('should handle null/undefined', () => {
+      expect(formatSummarizationError(null)).toBe(
+        'An unknown error occurred during summarization.',
+      )
+      expect(formatSummarizationError(undefined)).toBe(
+        'An unknown error occurred during summarization.',
+      )
+    })
+  })
+})
+
+describe('isRecoverableError', () => {
+  it('should return true for API_REQUEST_FAILED', () => {
+    const error = new SummarizationError(
+      'Request failed',
+      'API_REQUEST_FAILED',
+      'deepseek',
+    )
+    expect(isRecoverableError(error)).toBe(true)
+  })
+
+  it('should return true for TIMEOUT', () => {
+    const error = new SummarizationError('Timed out', 'TIMEOUT', 'claude')
+    expect(isRecoverableError(error)).toBe(true)
+  })
+
+  it('should return false for RATE_LIMITED', () => {
+    const error = new SummarizationError(
+      'Rate limited',
+      'RATE_LIMITED',
+      'openai',
+    )
+    expect(isRecoverableError(error)).toBe(false)
+  })
+
+  it('should return false for NO_API_KEY', () => {
+    const error = new SummarizationError('No key', 'NO_API_KEY', 'anthropic')
+    expect(isRecoverableError(error)).toBe(false)
+  })
+
+  it('should return false for non-SummarizationError', () => {
+    expect(isRecoverableError(new Error('Generic'))).toBe(false)
+  })
+})

package/src/summarization/error-handler.ts

@@ -0,0 +1,111 @@
+/**
+ * Error Handler for Summarization
+ *
+ * Provides user-friendly error messages and graceful degradation.
+ * Ensures summarization failures don't crash the CLI.
+ */
+
+import { SummarizationError, type SummarizationErrorCode } from './types.js'
+
+/**
+ * Error message templates for different error codes.
+ */
+const ERROR_MESSAGES: Record<SummarizationErrorCode, string> = {
+  PROVIDER_NOT_FOUND: 'Summarization provider not found.',
+  PROVIDER_NOT_AVAILABLE:
+    'Summarization provider is not available. Check installation.',
+  CLI_EXECUTION_FAILED: 'CLI execution failed.',
+  API_REQUEST_FAILED: 'API request failed.',
+  RATE_LIMITED: 'Rate limit exceeded. Please try again later.',
+  INVALID_RESPONSE: 'Received invalid response from provider.',
+  TIMEOUT: 'Request timed out. Try again or reduce result count.',
+  NO_API_KEY: 'API key not configured.',
+}
+
+/**
+ * Installation URLs for CLI providers.
+ */
+const CLI_INSTALL_URLS: Record<string, string> = {
+  claude: 'https://claude.ai/download',
+  copilot: 'https://github.com/features/copilot',
+  opencode: 'https://github.com/opencode-ai/opencode',
+  aider: 'https://aider.chat',
+  cline: 'https://github.com/cline/cline',
+}
+
+/**
+ * Environment variable names for API keys.
+ */
+const API_KEY_ENV_VARS: Record<string, string> = {
+  deepseek: 'DEEPSEEK_API_KEY',
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  gemini: 'GOOGLE_API_KEY',
+  qwen: 'QWEN_API_KEY',
+}
+
+/**
+ * Format a SummarizationError into a user-friendly message.
+ */
+export const formatSummarizationError = (error: unknown): string => {
+  if (error instanceof SummarizationError) {
+    const baseMessage = ERROR_MESSAGES[error.code] ?? error.message
+
+    // Add provider-specific hints
+    if (error.code === 'PROVIDER_NOT_AVAILABLE' && error.provider) {
+      const installUrl = CLI_INSTALL_URLS[error.provider]
+      if (installUrl) {
+        return `${baseMessage}\n   Install ${error.provider}: ${installUrl}`
+      }
+    }
+
+    if (error.code === 'NO_API_KEY' && error.provider) {
+      const envVar = API_KEY_ENV_VARS[error.provider]
+      if (envVar) {
+        return `${baseMessage}\n   Set environment variable: ${envVar}`
+      }
+    }
+
+    if (error.code === 'RATE_LIMITED') {
+      return `${baseMessage}\n   Try using a CLI provider (free with subscription) instead.`
+    }
+
+    if (error.code === 'CLI_EXECUTION_FAILED' && error.message) {
+      // Include the actual error message for CLI failures
+      return `CLI error: ${error.message}`
+    }
+
+    return baseMessage
+  }
+
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'An unknown error occurred during summarization.'
+}
+
+/**
+ * Check if an error is recoverable (can retry).
+ */
+export const isRecoverableError = (error: unknown): boolean => {
+  if (error instanceof SummarizationError) {
+    // These errors might succeed on retry
+    return ['API_REQUEST_FAILED', 'TIMEOUT'].includes(error.code)
+  }
+  return false
+}
+
+/**
+ * Create a console-friendly error display.
+ */
+export const displaySummarizationError = (error: unknown): void => {
+  const message = formatSummarizationError(error)
+
+  console.error('')
+  console.error('Summarization failed:')
+  console.error(`   ${message}`)
+  console.error('')
+  console.error('   Showing search results without summary.')
+  console.error('')
+}

package/src/summarization/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Summarization Module
+ *
+ * AI-powered summarization of search results using CLI tools (free)
+ * or API providers (pay-per-use via Vercel AI SDK).
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createSummarizer, buildPrompt } from './summarization/index.js'
+ *
+ * // Create a summarizer from config
+ * const summarizer = await createSummarizer({
+ *   mode: 'cli',
+ *   provider: 'claude',
+ * })
+ *
+ * // Build prompt with context
+ * const prompt = buildPrompt({
+ *   query: 'authentication',
+ *   resultCount: 10,
+ *   searchMode: 'hybrid',
+ * })
+ *
+ * // Generate summary
+ * const result = await summarizer.summarize(searchResultsText, prompt)
+ * console.log(result.summary)
+ * ```
+ *
+ * ## Architecture
+ *
+ * - **CLI Providers**: Free with subscription (Claude Code, Copilot, etc.)
+ * - **API Providers**: Pay-per-use via Vercel AI SDK (DeepSeek, OpenAI, etc.)
+ * - **Detection**: Auto-detect installed CLI tools
+ * - **Factory**: Create providers from config
+ */
+
+// CLI providers
+export {
+  ClaudeCLISummarizer,
+  detectInstalledCLIs,
+  getCLIInfo,
+  isCLIInstalled,
+  KNOWN_CLIS,
+} from './cli-providers/index.js'
+// Cost estimation
+export type { CostEstimate } from './cost.js'
+export {
+  API_PRICING,
+  estimateSummaryCost,
+  estimateTokens,
+  formatCostDisplay,
+} from './cost.js'
+// Error handling
+export {
+  displaySummarizationError,
+  formatSummarizationError,
+  isRecoverableError,
+} from './error-handler.js'
+// Pipeline
+export type {
+  PipelineOptions,
+  PipelineResult,
+  SummarizableResult,
+} from './pipeline.js'
+export {
+  formatResultsForSummary,
+  runSummarizationPipeline,
+  summarizeResults,
+} from './pipeline.js'
+// Prompts
+export type { PromptTemplate, SearchContext } from './prompts.js'
+export {
+  ACTIONABLE_PROMPT,
+  buildPrompt,
+  CONCISE_PROMPT,
+  DEFAULT_PROMPT,
+  DETAILED_PROMPT,
+  getPromptTemplate,
+  TECHNICAL_PROMPT,
+} from './prompts.js'
+// Provider factory
+export {
+  createSummarizer,
+  getBestAvailableSummarizer,
+} from './provider-factory.js'
+// Core types
+export type {
+  AISummarizationConfig,
+  APIProviderName,
+  APIProviderPricing,
+  CLIInfo,
+  CLIProviderName,
+  StreamingSummarizer,
+  StreamOptions,
+  SummarizationErrorCode,
+  SummarizationMode,
+  Summarizer,
+  SummarizerFactory,
+  SummaryResult,
+} from './types.js'
+export { SummarizationError } from './types.js'