mdcontext 0.1.0 → 0.2.0

package/src/summarization/pipeline.ts

@@ -0,0 +1,231 @@
+/**
+ * Summary Generation Pipeline
+ *
+ * Orchestrates the full summarization flow:
+ * 1. Format search results for LLM input
+ * 2. Estimate cost (for API providers)
+ * 3. Get user consent (for paid operations)
+ * 4. Generate summary via provider
+ * 5. Return formatted output
+ */
+
+import { Effect } from 'effect'
+import type { CostEstimate } from './cost.js'
+import { estimateSummaryCost } from './cost.js'
+import {
+  buildPrompt,
+  type PromptTemplate,
+  type SearchContext,
+} from './prompts.js'
+import {
+  createSummarizer,
+  getBestAvailableSummarizer,
+} from './provider-factory.js'
+import type { AISummarizationConfig, SummarizationMode } from './types.js'
+import { SummarizationError } from './types.js'
+
+/**
+ * Search result that can be summarized.
+ */
+export interface SummarizableResult {
+  readonly documentPath: string
+  readonly heading: string
+  readonly content?: string
+  readonly score?: number
+  readonly similarity?: number
+}
+
+/**
+ * Options for the summarization pipeline.
+ */
+export interface PipelineOptions {
+  /** AI summarization configuration */
+  readonly config?: Partial<AISummarizationConfig>
+  /** Prompt template to use */
+  readonly template?: PromptTemplate
+  /** Enable streaming output */
+  readonly stream?: boolean
+  /** Callback for streaming chunks */
+  readonly onChunk?: (chunk: string) => void
+  /** Skip user consent for paid operations */
+  readonly skipConsent?: boolean
+  /** Callback for consent prompt (returns true to proceed) */
+  readonly onConsentPrompt?: (estimate: CostEstimate) => Promise<boolean>
+}
+
+/**
+ * Result from the summarization pipeline.
+ */
+export interface PipelineResult {
+  /** Generated summary text */
+  readonly summary: string
+  /** Provider that generated the summary */
+  readonly provider: string
+  /** Mode used (cli or api) */
+  readonly mode: SummarizationMode
+  /** Cost estimate (before execution) */
+  readonly estimatedCost: CostEstimate
+  /** Actual cost (if available) */
+  readonly actualCost?: number
+  /** Time taken in milliseconds */
+  readonly durationMs: number
+  /** Was this a free operation? */
+  readonly isFree: boolean
+}
+
+/**
+ * Format search results as text for the LLM.
+ */
+export const formatResultsForSummary = (
+  results: readonly SummarizableResult[],
+): string => {
+  return results
+    .map((r, i) => {
+      const lines: string[] = []
+      lines.push(`[${i + 1}] ${r.documentPath}`)
+      lines.push(`    Heading: ${r.heading}`)
+      if (r.score !== undefined) {
+        lines.push(`    Score: ${(r.score * 100).toFixed(1)}%`)
+      }
+      if (r.similarity !== undefined) {
+        lines.push(`    Similarity: ${(r.similarity * 100).toFixed(1)}%`)
+      }
+      if (r.content) {
+        // Truncate content to avoid huge inputs
+        const truncated =
+          r.content.length > 500 ? `${r.content.slice(0, 500)}...` : r.content
+        lines.push(`    Content: ${truncated}`)
+      }
+      return lines.join('\n')
+    })
+    .join('\n\n')
+}
+
+/**
+ * Run the summarization pipeline.
+ *
+ * This is the main entry point for generating summaries from search results.
+ */
+export const runSummarizationPipeline = (
+  results: readonly SummarizableResult[],
+  searchContext: SearchContext,
+  options: PipelineOptions = {},
+): Effect.Effect<PipelineResult, SummarizationError> =>
+  Effect.gen(function* () {
+    // Get or create summarizer
+    const summarizerResult = options.config
+      ? yield* Effect.tryPromise({
+          try: () => {
+            // Build config object conditionally to avoid undefined values
+            const config: AISummarizationConfig = {
+              mode: options.config?.mode ?? 'cli',
+              provider: options.config?.provider ?? 'claude',
+              ...(options.config?.model && { model: options.config.model }),
+              ...((options.stream ?? options.config?.stream) && {
+                stream: true,
+              }),
+              ...(options.config?.baseURL && {
+                baseURL: options.config.baseURL,
+              }),
+              ...(options.config?.apiKey && { apiKey: options.config.apiKey }),
+            }
+            return createSummarizer(config)
+          },
+          catch: (e) =>
+            e instanceof SummarizationError
+              ? e
+              : new SummarizationError(
+                  `Failed to create summarizer: ${e}`,
+                  'PROVIDER_NOT_FOUND',
+                ),
+        })
+      : yield* Effect.tryPromise({
+          try: async () => {
+            const result = await getBestAvailableSummarizer()
+            if (!result) {
+              throw new SummarizationError(
+                'No summarization providers available',
+                'PROVIDER_NOT_AVAILABLE',
+              )
+            }
+            return result.summarizer
+          },
+          catch: (e) =>
+            e instanceof SummarizationError
+              ? e
+              : new SummarizationError(
+                  `Failed to find summarizer: ${e}`,
+                  'PROVIDER_NOT_FOUND',
+                ),
+        })
+
+    const mode = options.config?.mode ?? 'cli'
+    const provider = options.config?.provider ?? 'claude'
+
+    // Format results for input
+    const resultsText = formatResultsForSummary(results)
+
+    // Estimate cost
+    const costEstimate = estimateSummaryCost(resultsText, mode, provider)
+
+    // Handle consent for paid operations
+    if (costEstimate.isPaid && !options.skipConsent) {
+      if (options.onConsentPrompt) {
+        const consented = yield* Effect.tryPromise({
+          try: () => options.onConsentPrompt!(costEstimate),
+          catch: () =>
+            new SummarizationError(
+              'Consent prompt failed',
+              'CLI_EXECUTION_FAILED',
+            ),
+        })
+
+        if (!consented) {
+          return yield* Effect.fail(
+            new SummarizationError(
+              'User declined summarization',
+              'CLI_EXECUTION_FAILED',
+            ),
+          )
+        }
+      }
+    }
+
+    // Build prompt
+    const prompt = buildPrompt(searchContext, options.template)
+
+    // Generate summary
+    const summaryResult = yield* Effect.tryPromise({
+      try: () => summarizerResult.summarize(resultsText, prompt),
+      catch: (e) =>
+        e instanceof SummarizationError
+          ? e
+          : new SummarizationError(
+              `Summarization failed: ${e}`,
+              'CLI_EXECUTION_FAILED',
+            ),
+    })
+
+    return {
+      summary: summaryResult.summary,
+      provider: summaryResult.provider,
+      mode: summaryResult.mode,
+      estimatedCost: costEstimate,
+      actualCost: summaryResult.estimatedCost,
+      durationMs: summaryResult.durationMs,
+      isFree: !costEstimate.isPaid,
+    }
+  })
+
+/**
+ * Quick helper to run summarization with Effect.runPromise.
+ */
+export const summarizeResults = async (
+  results: readonly SummarizableResult[],
+  searchContext: SearchContext,
+  options: PipelineOptions = {},
+): Promise<PipelineResult> => {
+  return Effect.runPromise(
+    runSummarizationPipeline(results, searchContext, options),
+  )
+}

package/src/summarization/prompts.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ACTIONABLE_PROMPT,
+  buildPrompt,
+  CONCISE_PROMPT,
+  DEFAULT_PROMPT,
+  DETAILED_PROMPT,
+  getPromptTemplate,
+  type PromptTemplate,
+  type SearchContext,
+  TECHNICAL_PROMPT,
+} from './prompts.js'
+
+describe('prompts', () => {
+  describe('getPromptTemplate', () => {
+    it('returns DEFAULT_PROMPT for "default" template', () => {
+      expect(getPromptTemplate('default')).toBe(DEFAULT_PROMPT)
+    })
+
+    it('returns CONCISE_PROMPT for "concise" template', () => {
+      expect(getPromptTemplate('concise')).toBe(CONCISE_PROMPT)
+    })
+
+    it('returns DETAILED_PROMPT for "detailed" template', () => {
+      expect(getPromptTemplate('detailed')).toBe(DETAILED_PROMPT)
+    })
+
+    it('returns ACTIONABLE_PROMPT for "actionable" template', () => {
+      expect(getPromptTemplate('actionable')).toBe(ACTIONABLE_PROMPT)
+    })
+
+    it('returns TECHNICAL_PROMPT for "technical" template', () => {
+      expect(getPromptTemplate('technical')).toBe(TECHNICAL_PROMPT)
+    })
+
+    it('returns DEFAULT_PROMPT as fallback for unknown template', () => {
+      const unknownTemplate = 'unknown' as PromptTemplate
+      expect(getPromptTemplate(unknownTemplate)).toBe(DEFAULT_PROMPT)
+    })
+  })
+
+  describe('buildPrompt', () => {
+    const baseContext: SearchContext = {
+      query: 'test query',
+      resultCount: 5,
+      searchMode: 'hybrid',
+    }
+
+    it('includes the base prompt template in output', () => {
+      const result = buildPrompt(baseContext)
+      expect(result).toContain(DEFAULT_PROMPT)
+    })
+
+    it('includes the query in output', () => {
+      const result = buildPrompt(baseContext)
+      expect(result).toContain('Query: "test query"')
+    })
+
+    it('includes result count in output', () => {
+      const result = buildPrompt(baseContext)
+      expect(result).toContain('Results found: 5')
+    })
+
+    it('includes search mode in output', () => {
+      const result = buildPrompt(baseContext)
+      expect(result).toContain('Search mode: hybrid')
+    })
+
+    it('uses default template when not specified', () => {
+      const result = buildPrompt(baseContext)
+      expect(result).toContain(DEFAULT_PROMPT)
+    })
+
+    it('uses specified template when provided', () => {
+      const result = buildPrompt(baseContext, 'concise')
+      expect(result).toContain(CONCISE_PROMPT)
+      expect(result).not.toContain(DEFAULT_PROMPT)
+    })
+
+    it('has proper formatting with separators', () => {
+      const result = buildPrompt(baseContext)
+      expect(result).toContain('---')
+      expect(result).toContain('Search Results:')
+    })
+
+    it('handles semantic search mode', () => {
+      const context: SearchContext = {
+        ...baseContext,
+        searchMode: 'semantic',
+      }
+      const result = buildPrompt(context)
+      expect(result).toContain('Search mode: semantic')
+    })
+
+    it('handles keyword search mode', () => {
+      const context: SearchContext = {
+        ...baseContext,
+        searchMode: 'keyword',
+      }
+      const result = buildPrompt(context)
+      expect(result).toContain('Search mode: keyword')
+    })
+
+    it('handles zero result count', () => {
+      const context: SearchContext = {
+        ...baseContext,
+        resultCount: 0,
+      }
+      const result = buildPrompt(context)
+      expect(result).toContain('Results found: 0')
+    })
+
+    it('handles large result count', () => {
+      const context: SearchContext = {
+        ...baseContext,
+        resultCount: 1000,
+      }
+      const result = buildPrompt(context)
+      expect(result).toContain('Results found: 1000')
+    })
+
+    it('handles special characters in query', () => {
+      const context: SearchContext = {
+        ...baseContext,
+        query: 'how do I use "quotes" and <brackets>?',
+      }
+      const result = buildPrompt(context)
+      expect(result).toContain('Query: "how do I use "quotes" and <brackets>?"')
+    })
+
+    it('works with all template types', () => {
+      const templates: PromptTemplate[] = [
+        'default',
+        'concise',
+        'detailed',
+        'actionable',
+        'technical',
+      ]
+      for (const template of templates) {
+        const result = buildPrompt(baseContext, template)
+        expect(result).toContain('Query: "test query"')
+        expect(result).toContain('Results found: 5')
+        expect(result).toContain('Search mode: hybrid')
+      }
+    })
+  })
+
+  describe('prompt content verification', () => {
+    describe('DEFAULT_PROMPT', () => {
+      it('contains guidelines section', () => {
+        expect(DEFAULT_PROMPT).toContain('Guidelines:')
+      })
+
+      it('mentions synthesizing results', () => {
+        expect(DEFAULT_PROMPT).toContain('Synthesize')
+      })
+
+      it('includes formatting instructions', () => {
+        expect(DEFAULT_PROMPT).toContain('Format your response')
+      })
+
+      it('mentions actionable insights', () => {
+        expect(DEFAULT_PROMPT).toContain('actionable insights')
+      })
+    })
+
+    describe('CONCISE_PROMPT', () => {
+      it('is relatively short', () => {
+        expect(CONCISE_PROMPT.length).toBeLessThan(200)
+      })
+
+      it('mentions 2-3 sentences', () => {
+        expect(CONCISE_PROMPT).toContain('2-3 sentences')
+      })
+
+      it('focuses on most important findings', () => {
+        expect(CONCISE_PROMPT).toContain('most important')
+      })
+    })
+
+    describe('DETAILED_PROMPT', () => {
+      it('is comprehensive (longer than default)', () => {
+        expect(DETAILED_PROMPT.length).toBeGreaterThan(CONCISE_PROMPT.length)
+      })
+
+      it('mentions executive summary', () => {
+        expect(DETAILED_PROMPT).toContain('Executive summary')
+      })
+
+      it('mentions code patterns', () => {
+        expect(DETAILED_PROMPT).toContain('code patterns')
+      })
+
+      it('mentions file references', () => {
+        expect(DETAILED_PROMPT).toContain('file references')
+      })
+
+      it('includes multiple numbered sections', () => {
+        expect(DETAILED_PROMPT).toContain('1.')
+        expect(DETAILED_PROMPT).toContain('2.')
+        expect(DETAILED_PROMPT).toContain('3.')
+      })
+    })
+
+    describe('ACTIONABLE_PROMPT', () => {
+      it('focuses on developer goals', () => {
+        expect(ACTIONABLE_PROMPT).toContain(
+          'developer is likely trying to accomplish',
+        )
+      })
+
+      it('mentions specific steps', () => {
+        expect(ACTIONABLE_PROMPT).toContain('specific steps')
+      })
+
+      it('mentions code snippets', () => {
+        expect(ACTIONABLE_PROMPT).toContain('code snippets')
+      })
+
+      it('mentions pitfalls', () => {
+        expect(ACTIONABLE_PROMPT).toContain('pitfalls')
+      })
+
+      it('emphasizes being direct and practical', () => {
+        expect(ACTIONABLE_PROMPT).toContain('direct and practical')
+      })
+    })
+
+    describe('TECHNICAL_PROMPT', () => {
+      it('focuses on technical perspective', () => {
+        expect(TECHNICAL_PROMPT).toContain('technical perspective')
+      })
+
+      it('mentions code patterns', () => {
+        expect(TECHNICAL_PROMPT).toContain('Code patterns')
+      })
+
+      it('mentions API signatures', () => {
+        expect(TECHNICAL_PROMPT).toContain('API signatures')
+      })
+
+      it('mentions configuration options', () => {
+        expect(TECHNICAL_PROMPT).toContain('Configuration options')
+      })
+
+      it('mentions best practices', () => {
+        expect(TECHNICAL_PROMPT).toContain('Best practices')
+      })
+
+      it('emphasizes concrete technical guidance', () => {
+        expect(TECHNICAL_PROMPT).toContain('concrete technical guidance')
+      })
+    })
+  })
+
+  describe('prompt uniqueness', () => {
+    it('all prompts are distinct', () => {
+      const prompts = [
+        DEFAULT_PROMPT,
+        CONCISE_PROMPT,
+        DETAILED_PROMPT,
+        ACTIONABLE_PROMPT,
+        TECHNICAL_PROMPT,
+      ]
+      const uniquePrompts = new Set(prompts)
+      expect(uniquePrompts.size).toBe(prompts.length)
+    })
+  })
+})

package/src/summarization/prompts.ts

@@ -0,0 +1,133 @@
+/**
+ * Prompt Templates for Search Result Summarization
+ *
+ * These prompts are designed to transform raw search results
+ * into actionable insights for developers.
+ */
+
+/**
+ * Available prompt templates for different summarization styles.
+ */
+export type PromptTemplate =
+  | 'default'
+  | 'concise'
+  | 'detailed'
+  | 'actionable'
+  | 'technical'
+
+/**
+ * Context about the search that generated these results.
+ */
+export interface SearchContext {
+  /** The original search query */
+  readonly query: string
+  /** Number of results found */
+  readonly resultCount: number
+  /** Search mode used */
+  readonly searchMode: 'hybrid' | 'semantic' | 'keyword'
+}
+
+/**
+ * Default prompt for summarizing search results.
+ *
+ * Designed to produce actionable, developer-focused insights.
+ */
+export const DEFAULT_PROMPT = `You are summarizing search results from a markdown documentation search tool.
+
+Your task: Synthesize these results into actionable insights that help the developer understand the relevant content.
+
+Guidelines:
+- Focus on answering the user's implicit question
+- Highlight the most relevant sections and their key points
+- Note any patterns or connections between results
+- Be concise but comprehensive
+- Use bullet points for clarity
+- If results seem incomplete, suggest what else the user might search for
+
+Format your response as:
+1. A brief summary (2-3 sentences)
+2. Key findings (bullet points)
+3. Recommended next steps (if applicable)`
+
+/**
+ * Concise prompt for quick summaries.
+ */
+export const CONCISE_PROMPT = `Summarize these search results in 2-3 sentences. Focus only on the most important findings that directly answer the query.`
+
+/**
+ * Detailed prompt for comprehensive analysis.
+ */
+export const DETAILED_PROMPT = `Provide a comprehensive analysis of these search results.
+
+Include:
+1. Executive summary (3-4 sentences)
+2. Detailed findings organized by topic
+3. Key code patterns or examples mentioned
+4. Relationships between different sections
+5. Gaps or areas that need more exploration
+6. Specific file references for follow-up`
+
+/**
+ * Actionable prompt focused on next steps.
+ */
+export const ACTIONABLE_PROMPT = `Analyze these search results and provide:
+
+1. What the developer is likely trying to accomplish
+2. The specific steps they should take based on these results
+3. Any code snippets or patterns they should use
+4. Potential pitfalls to avoid
+5. Related areas they might want to explore
+
+Be direct and practical.`
+
+/**
+ * Technical prompt for code-focused analysis.
+ */
+export const TECHNICAL_PROMPT = `Analyze these search results from a technical perspective.
+
+Focus on:
+- Code patterns and implementations mentioned
+- API signatures and usage
+- Configuration options
+- Dependencies and requirements
+- Best practices and anti-patterns
+
+Provide concrete technical guidance.`
+
+/**
+ * Get a prompt template by name.
+ */
+export const getPromptTemplate = (template: PromptTemplate): string => {
+  switch (template) {
+    case 'concise':
+      return CONCISE_PROMPT
+    case 'detailed':
+      return DETAILED_PROMPT
+    case 'actionable':
+      return ACTIONABLE_PROMPT
+    case 'technical':
+      return TECHNICAL_PROMPT
+    default:
+      return DEFAULT_PROMPT
+  }
+}
+
+/**
+ * Build a complete prompt with search context.
+ */
+export const buildPrompt = (
+  context: SearchContext,
+  template: PromptTemplate = 'default',
+): string => {
+  const basePrompt = getPromptTemplate(template)
+
+  return `${basePrompt}
+
+---
+Query: "${context.query}"
+Results found: ${context.resultCount}
+Search mode: ${context.searchMode}
+---
+
+Search Results:`
+}