Skip to content

discovery.md

Latest commit

 

History

History
899 lines (715 loc) · 23.6 KB

discovery.md

File metadata and controls

899 lines (715 loc) · 23.6 KB
Raw

Discovery API Reference

Complete API documentation for the cctypes transcript discovery system.

Table of Contents

DiscoveryEngine

The main orchestrator for the discovery process, coordinating analysis, generation, and validation.

Constructor

constructor(config: DiscoveryConfig)

Creates a new discovery engine with the specified configuration.

Parameters:

  • config: DiscoveryConfig - Discovery configuration options

Example:

const engine = new DiscoveryEngine({
  sources: {
    files: ['./transcripts/**/*.jsonl']
  },
  output: {
    outputDir: './generated',
    generateGuards: true
  },
  analysis: {
    minOccurrences: 3
  }
});

Methods

discover(): Promise<DiscoveryState>

Executes the complete discovery process: analysis, generation, and validation.

Returns: Promise<DiscoveryState> - Final state of the discovery process

Example:

const result = await engine.discover();

if (result.phase === 'complete') {
  console.log('Discovery completed successfully!');
  console.log(`Found ${Object.keys(result.results.analysis.toolPatterns).length} tools`);
} else {
  console.error('Discovery failed:', result.errors);
}

on(listener: (event: DiscoveryEvent) => void): void

Registers an event listener for discovery progress updates.

Parameters:

  • listener: (event: DiscoveryEvent) => void - Event handler function

Example:

engine.on((event) => {
  switch (event.type) {
    case 'progress':
      console.log(`${event.data.phase}: ${event.data.progress}%`);
      break;
    case 'phase-change':
      console.log(`Entering phase: ${event.data.phase}`);
      break;
    case 'error':
      console.error('Discovery error:', event.data.status);
      break;
    case 'complete':
      console.log('Discovery completed');
      break;
  }
});

abort(): void

Aborts the current discovery process.

Example:

// Start discovery
const discoveryPromise = engine.discover();

// Abort after 30 seconds
setTimeout(() => {
  engine.abort();
  console.log('Discovery aborted due to timeout');
}, 30000);

getState(): DiscoveryState

Returns the current state of the discovery process.

Returns: DiscoveryState - Current discovery state

Example:

const currentState = engine.getState();
console.log(`Current phase: ${currentState.phase}`);
console.log(`Progress: ${currentState.progress}%`);

Properties

config: Readonly<DiscoveryConfig>

The configuration used by this discovery engine (read-only).

isRunning: boolean

Indicates whether a discovery process is currently running.

TranscriptAnalyzer

Analyzes transcript entries to discover patterns and generate analysis results.

Constructor

constructor(config?: AnalysisConfig)

Parameters:

  • config?: AnalysisConfig - Optional analysis configuration

Methods

analyze(entries: TranscriptEntry[]): Promise<AnalysisResult>

Analyzes transcript entries to discover patterns.

Parameters:

  • entries: TranscriptEntry[] - Array of transcript entries to analyze

Returns: Promise<AnalysisResult> - Analysis results with discovered patterns

Example:

const analyzer = new TranscriptAnalyzer({
  minOccurrences: 3,
  maxDepth: 5
});

const entries = await loadTranscriptEntries('./transcripts/*.jsonl');
const analysis = await analyzer.analyze(entries);

console.log(`Found ${Object.keys(analysis.toolPatterns).length} tool patterns`);
console.log(`Processed ${analysis.statistics.totalEntries} entries`);

analyzeToolPatterns(entries: ToolInvocationEntry[]): Promise<Record<string, ToolPattern>>

Analyzes tool usage patterns from tool invocation entries.

Parameters:

  • entries: ToolInvocationEntry[] - Tool invocation entries

Returns: Promise<Record<string, ToolPattern>> - Tool patterns keyed by tool name

Example:

const toolEntries = entries.filter(e => e.type === 'tool_use') as ToolInvocationEntry[];
const toolPatterns = await analyzer.analyzeToolPatterns(toolEntries);

Object.entries(toolPatterns).forEach(([toolName, pattern]) => {
  console.log(`${toolName}: ${pattern.occurrences} uses, confidence: ${pattern.confidence}`);
});

analyzeMessagePatterns(entries: MessageEntry[]): Promise<MessagePattern[]>

Analyzes message patterns from message entries.

Parameters:

  • entries: MessageEntry[] - Message entries

Returns: Promise<MessagePattern[]> - Discovered message patterns

analyzeEntryPatterns(entries: TranscriptEntry[]): Promise<Record<string, EntryPattern>>

Analyzes general entry patterns from all transcript entries.

Parameters:

  • entries: TranscriptEntry[] - All transcript entries

Returns: Promise<Record<string, EntryPattern>> - Entry patterns keyed by entry type

Configuration

interface AnalysisConfig {
  /** Minimum occurrences required to generate a pattern */
  minOccurrences?: number; // default: 2
  /** Whether to include optional properties in analysis */
  includeOptionalProperties?: boolean; // default: true
  /** Maximum depth for nested object analysis */
  maxDepth?: number; // default: 5
  /** Whether to collect value examples */
  collectExamples?: boolean; // default: true
  /** Maximum number of examples per pattern */
  maxExamples?: number; // default: 10
}

TypeScriptGenerator

Generates TypeScript type definitions from analysis results.

Constructor

constructor(config?: GenerationConfig)

Methods

generate(analysis: AnalysisResult): Promise<GeneratedCode>

Generates TypeScript code from analysis results.

Parameters:

  • analysis: AnalysisResult - Results from transcript analysis

Returns: Promise<GeneratedCode> - Generated TypeScript code

Example:

const generator = new TypeScriptGenerator({
  generateGuards: true,
  generateExamples: true,
  interfacePrefix: 'Discovered',
  includeJSDoc: true
});

const generatedCode = await generator.generate(analysisResult);

console.log('Generated types:');
console.log(generatedCode.types);

if (generatedCode.guards) {
  console.log('Generated type guards:');
  console.log(generatedCode.guards);
}

generateToolTypes(toolPatterns: Record<string, ToolPattern>): Promise<string>

Generates TypeScript interfaces for tool input/output patterns.

Parameters:

  • toolPatterns: Record<string, ToolPattern> - Tool patterns from analysis

Returns: Promise<string> - Generated TypeScript interfaces

generateTypeGuards(analysis: AnalysisResult): Promise<string>

Generates type guard functions for runtime type checking.

Parameters:

  • analysis: AnalysisResult - Analysis results

Returns: Promise<string> - Generated type guard functions

Example:

const guards = await generator.generateTypeGuards(analysis);
console.log(guards);

// Output:
// export function isDiscoveredBashInput(value: unknown): value is DiscoveredBashInput {
//   return typeof value === 'object' && value !== null &&
//     'command' in value && typeof (value as any).command === 'string';
// }

generateExamples(analysis: AnalysisResult): Promise<string>

Generates usage examples from analysis results.

Parameters:

  • analysis: AnalysisResult - Analysis results

Returns: Promise<string> - Generated usage examples

Configuration

interface GenerationConfig {
  /** Whether to generate type guards */
  generateGuards?: boolean; // default: true
  /** Whether to generate usage examples */
  generateExamples?: boolean; // default: true
  /** Prefix for generated interface names */
  interfacePrefix?: string; // default: 'Discovered'
  /** Whether to include JSDoc comments */
  includeJSDoc?: boolean; // default: true
  /** Indentation style */
  indentation?: 'spaces' | 'tabs'; // default: 'spaces'
  /** Number of spaces for indentation */
  indentSize?: number; // default: 2
  /** Whether to use semicolons */
  useSemicolons?: boolean; // default: true
}

TypeScriptValidator

Validates generated TypeScript code and checks compatibility with existing types.

Constructor

constructor(config?: ValidationConfig)

Methods

validate(generatedCode: GeneratedCode, analysis: AnalysisResult): Promise<ValidationResult>

Validates generated TypeScript code.

Parameters:

  • generatedCode: GeneratedCode - Generated TypeScript code
  • analysis: AnalysisResult - Original analysis results

Returns: Promise<ValidationResult> - Validation results

Example:

const validator = new TypeScriptValidator({
  existingTypesDir: './src/types',
  strictValidation: true
});

const validationResult = await validator.validate(generatedCode, analysis);

if (validationResult.valid) {
  console.log('✅ Generated types are valid');
} else {
  console.log('❌ Validation failed:');
  validationResult.errors.forEach(error => {
    console.log(`  - [${error.type}] ${error.message}`);
    if (error.suggestion) {
      console.log(`    Suggestion: ${error.suggestion}`);
    }
  });
}

validateSyntax(code: string): Promise<ValidationError[]>

Validates TypeScript syntax of generated code.

Parameters:

  • code: string - TypeScript code to validate

Returns: Promise<ValidationError[]> - Syntax validation errors

validateCompatibility(generatedCode: GeneratedCode, existingTypesDir: string): Promise<CompatibilityReport>

Checks compatibility between generated types and existing type definitions.

Parameters:

  • generatedCode: GeneratedCode - Generated TypeScript code
  • existingTypesDir: string - Directory containing existing type files

Returns: Promise<CompatibilityReport> - Compatibility analysis

Example:

const compatibilityReport = await validator.validateCompatibility(
  generatedCode,
  './src/types'
);

console.log(`Compatible types: ${compatibilityReport.compatible.length}`);
console.log(`Conflicting types: ${compatibilityReport.conflicts.length}`);

compatibilityReport.conflicts.forEach(conflict => {
  console.log(`Conflict: ${conflict.name} (${conflict.severity})`);
  if (conflict.resolution) {
    console.log(`Resolution: ${conflict.resolution}`);
  }
});

Configuration

interface ValidationConfig {
  /** Directory containing existing type definitions */
  existingTypesDir?: string;
  /** Whether to perform strict validation */
  strictValidation?: boolean; // default: false
  /** TypeScript compiler options */
  compilerOptions?: ts.CompilerOptions;
  /** Whether to check for naming conflicts */
  checkNamingConflicts?: boolean; // default: true
}

Configuration Types

DiscoveryConfig

interface DiscoveryConfig {
  /** Input sources for discovery */
  sources: {
    /** Directory containing transcript files */
    transcriptDir?: string;
    /** Specific transcript files to analyze */
    files?: string[];
    /** Raw transcript entries (for programmatic use) */
    entries?: TranscriptEntry[];
  };

  /** Output configuration */
  output: {
    /** Output directory for generated types */
    outputDir: string;
    /** Generated TypeScript file name */
    filename?: string; // default: 'discovered-types.ts'
    /** Whether to generate type guards */
    generateGuards?: boolean; // default: true
    /** Whether to generate usage examples */
    generateExamples?: boolean; // default: true
  };

  /** Analysis configuration */
  analysis: {
    /** Minimum occurrences required to generate a type */
    minOccurrences?: number; // default: 2
    /** Whether to include optional properties */
    includeOptionalProperties?: boolean; // default: true
    /** Maximum depth for nested object analysis */
    maxDepth?: number; // default: 5
  };

  /** Validation configuration */
  validation: {
    /** Whether to validate against existing types */
    validateAgainstExisting?: boolean; // default: true
    /** Directory containing existing type definitions */
    existingTypesDir?: string; // default: './src'
  };
}

Result Types

AnalysisResult

interface AnalysisResult {
  /** Tool usage patterns discovered */
  toolPatterns: Record<string, ToolPattern>;
  /** Message patterns discovered */
  messagePatterns: MessagePattern[];
  /** Entry patterns discovered */
  entryPatterns: Record<string, EntryPattern>;
  /** Statistics about the analysis */
  statistics: AnalysisStatistics;
}

ToolPattern

interface ToolPattern {
  /** Tool name */
  name: string;
  /** Number of occurrences found */
  occurrences: number;
  /** Input parameter patterns */
  inputSchema: ParameterPattern;
  /** Response patterns */
  responseSchema: ParameterPattern;
  /** Examples of actual usage */
  examples: ToolUsageExample[];
  /** Confidence score (0-1) for the pattern */
  confidence: number;
}

ParameterPattern

interface ParameterPattern {
  /** TypeScript type string */
  type: string;
  /** Whether the parameter is required */
  required: boolean;
  /** Possible values (for enums/unions) */
  values?: unknown[];
  /** Nested properties (for objects) */
  properties?: Record<string, ParameterPattern>;
  /** Array item type (for arrays) */
  items?: ParameterPattern;
  /** Examples of actual values */
  examples: unknown[];
  /** Description inferred from usage */
  description?: string;
}

GeneratedCode

interface GeneratedCode {
  /** Main type definitions */
  types: string;
  /** Type guard functions */
  guards?: string;
  /** Usage examples */
  examples?: string;
  /** Export statements */
  exports: string;
}

ValidationResult

interface ValidationResult {
  /** Whether validation passed */
  valid: boolean;
  /** Validation errors found */
  errors: ValidationError[];
  /** Warnings about potential issues */
  warnings: ValidationWarning[];
  /** Compatibility report with existing types */
  compatibility: CompatibilityReport;
}

DiscoveryState

interface DiscoveryState {
  /** Current phase of discovery */
  phase: 'initializing' | 'analyzing' | 'generating' | 'validating' | 'complete' | 'error';
  /** Progress percentage (0-100) */
  progress: number;
  /** Current status message */
  status: string;
  /** Results from completed phases */
  results: {
    analysis?: AnalysisResult;
    generation?: GeneratedCode;
    validation?: ValidationResult;
  };
  /** Any errors that occurred */
  errors: Error[];
  /** Start time of discovery */
  startTime: Date;
  /** End time of discovery (if complete) */
  endTime?: Date;
}

Event System

DiscoveryEvent

interface DiscoveryEvent {
  /** Event type */
  type: 'progress' | 'phase-change' | 'error' | 'complete';
  /** Event data */
  data: DiscoveryState;
  /** Timestamp of event */
  timestamp: Date;
}

Event Types

Event Type Description When Fired
progress Progress update within current phase Periodically during analysis, generation, validation
phase-change Discovery entered a new phase At the start of each major phase
error An error occurred during discovery When any recoverable or unrecoverable error happens
complete Discovery process completed When all phases complete successfully

Event Handling Examples

// Basic progress tracking
engine.on((event) => {
  console.log(`[${event.type}] ${event.data.phase}: ${event.data.status}`);
});

// Progress bar implementation
engine.on((event) => {
  if (event.type === 'progress') {
    updateProgressBar(event.data.phase, event.data.progress);
  }
});

// Error handling
engine.on((event) => {
  if (event.type === 'error') {
    logError('Discovery error:', event.data.errors);
    // Optionally abort or retry
    engine.abort();
  }
});

// Phase-specific handling
engine.on((event) => {
  if (event.type === 'phase-change') {
    switch (event.data.phase) {
      case 'analyzing':
        console.log('Starting pattern analysis...');
        break;
      case 'generating':
        console.log('Generating TypeScript types...');
        break;
      case 'validating':
        console.log('Validating generated code...');
        break;
      case 'complete':
        console.log('Discovery completed successfully!');
        displayResults(event.data.results);
        break;
    }
  }
});

Examples

Basic Usage

import { DiscoveryEngine } from 'cctypes/transcript/discovery';

async function basicDiscovery() {
  const engine = new DiscoveryEngine({
    sources: {
      files: ['./transcripts/**/*.jsonl']
    },
    output: {
      outputDir: './generated-types',
      generateGuards: true,
      generateExamples: true
    },
    analysis: {
      minOccurrences: 2,
      maxDepth: 5
    }
  });

  const result = await engine.discover();
  
  if (result.phase === 'complete' && result.results.analysis) {
    console.log('Discovery completed!');
    console.log(`Tools found: ${Object.keys(result.results.analysis.toolPatterns).length}`);
    console.log(`Entries processed: ${result.results.analysis.statistics.totalEntries}`);
  }
}

Advanced Usage with Custom Analysis

import { 
  DiscoveryEngine, 
  TranscriptAnalyzer, 
  TypeScriptGenerator,
  TypeScriptValidator
} from 'cctypes/transcript/discovery';

class CustomAnalyzer extends TranscriptAnalyzer {
  protected override async analyzeToolPatterns(entries: ToolInvocationEntry[]) {
    const patterns = await super.analyzeToolPatterns(entries);
    
    // Custom analysis: boost confidence for frequently used tools
    Object.values(patterns).forEach(pattern => {
      if (pattern.occurrences > 100) {
        pattern.confidence = Math.min(1.0, pattern.confidence + 0.1);
      }
    });
    
    return patterns;
  }
}

class CustomGenerator extends TypeScriptGenerator {
  protected override generateInterface(name: string, pattern: ParameterPattern): string {
    // Add custom JSDoc with confidence and occurrence info
    const jsdoc = `/**\n * ${name} - Generated from transcript analysis\n * Occurrences: ${pattern.examples.length}\n */`;
    const interfaceCode = super.generateInterface(name, pattern);
    return `${jsdoc}\n${interfaceCode}`;
  }
}

async function advancedDiscovery() {
  const config = {
    sources: {
      transcriptDir: './transcripts'
    },
    output: {
      outputDir: './src/generated',
      filename: 'claude-types.ts'
    },
    analysis: {
      minOccurrences: 5,
      maxDepth: 6
    },
    validation: {
      validateAgainstExisting: true,
      existingTypesDir: './src/types'
    }
  };
  
  const engine = new DiscoveryEngine(config);
  
  // Use custom components
  engine.setAnalyzer(new CustomAnalyzer());
  engine.setGenerator(new CustomGenerator());
  engine.setValidator(new TypeScriptValidator({ strictValidation: true }));
  
  // Set up comprehensive event handling
  engine.on((event) => {
    switch (event.type) {
      case 'progress':
        console.log(`Progress: ${event.data.phase} ${event.data.progress}%`);
        break;
      case 'phase-change':
        console.log(`Phase: ${event.data.phase} - ${event.data.status}`);
        break;
      case 'error':
        console.error('Error:', event.data.errors);
        break;
      case 'complete':
        console.log('Discovery completed successfully!');
        displayDetailedResults(event.data);
        break;
    }
  });
  
  try {
    const result = await engine.discover();
    return result;
  } catch (error) {
    console.error('Discovery failed:', error);
    throw error;
  }
}

function displayDetailedResults(state: DiscoveryState) {
  const { analysis, generation, validation } = state.results;
  
  if (analysis) {
    console.log('\n=== Analysis Results ===');
    console.log(`Tools discovered: ${Object.keys(analysis.toolPatterns).length}`);
    console.log(`Message patterns: ${analysis.messagePatterns.length}`);
    console.log(`Processing time: ${analysis.statistics.processingTime}ms`);
    
    // Show top tools by usage
    const topTools = Object.entries(analysis.toolPatterns)
      .sort(([,a], [,b]) => b.occurrences - a.occurrences)
      .slice(0, 5);
      
    console.log('\nTop 5 tools by usage:');
    topTools.forEach(([name, pattern], i) => {
      console.log(`  ${i + 1}. ${name}: ${pattern.occurrences} uses (${Math.round(pattern.confidence * 100)}% confidence)`);
    });
  }
  
  if (generation) {
    console.log('\n=== Generation Results ===');
    console.log(`Generated ${generation.types.length} characters of TypeScript code`);
    if (generation.guards) {
      console.log(`Generated type guards: ${generation.guards.split('function').length - 1}`);
    }
  }
  
  if (validation) {
    console.log('\n=== Validation Results ===');
    console.log(`Valid: ${validation.valid ? '✅' : '❌'}`);
    console.log(`Errors: ${validation.errors.length}`);
    console.log(`Warnings: ${validation.warnings.length}`);
    
    if (validation.errors.length > 0) {
      console.log('\nValidation errors:');
      validation.errors.forEach((error, i) => {
        console.log(`  ${i + 1}. [${error.type}] ${error.message}`);
      });
    }
  }
}

Streaming Analysis for Large Files

import { TranscriptAnalyzer } from 'cctypes/transcript/discovery';
import { createReadStream } from 'fs';
import { createInterface } from 'readline';

class StreamingAnalyzer extends TranscriptAnalyzer {
  async analyzeFromStream(filePath: string): Promise<AnalysisResult> {
    const entries: TranscriptEntry[] = [];
    const fileStream = createReadStream(filePath);
    const rl = createInterface({
      input: fileStream,
      crlfDelay: Infinity
    });

    for await (const line of rl) {
      try {
        const entry = JSON.parse(line) as TranscriptEntry;
        entries.push(entry);
        
        // Process in batches to manage memory
        if (entries.length >= 1000) {
          await this.processBatch(entries.splice(0, 1000));
        }
      } catch (error) {
        console.warn(`Skipping invalid JSON line: ${line}`);
      }
    }
    
    // Process remaining entries
    if (entries.length > 0) {
      await this.processBatch(entries);
    }
    
    return this.getAccumulatedResults();
  }
  
  private async processBatch(entries: TranscriptEntry[]): Promise<void> {
    // Process batch and accumulate results
    const batchAnalysis = await this.analyze(entries);
    this.accumulateResults(batchAnalysis);
  }
}

async function analyzeStreamingData() {
  const analyzer = new StreamingAnalyzer();
  const result = await analyzer.analyzeFromStream('./large-transcript.jsonl');
  console.log('Streaming analysis completed:', result.statistics);
}

Integration with Build Systems

// webpack-plugin.js
class TranscriptDiscoveryPlugin {
  constructor(options = {}) {
    this.options = {
      transcriptPattern: './transcripts/**/*.jsonl',
      outputDir: './src/generated',
      ...options
    };
  }
  
  apply(compiler) {
    compiler.hooks.beforeCompile.tapPromise('TranscriptDiscovery', async () => {
      const { DiscoveryEngine } = await import('cctypes/transcript/discovery');
      
      const engine = new DiscoveryEngine({
        sources: { files: [this.options.transcriptPattern] },
        output: { outputDir: this.options.outputDir },
        analysis: { minOccurrences: 2 }
      });
      
      await engine.discover();
      console.log('Transcript discovery completed before build');
    });
  }
}

module.exports = TranscriptDiscoveryPlugin;