Shared Types Implementation in llm-mcp

Overview

This document describes the implementation of shared types from the shared-utils directory in the llm-mcp project. The implementation follows a backward-compatible approach that allows existing code to continue working while providing a path to migrate to the shared types.

Implementation Strategy

The implementation strategy for llm-mcp follows these principles:

1. Extend Shared Types: Legacy types extend shared types where applicable
2. Adapter Classes: Adapter classes are provided to convert between project-specific and shared interfaces
3. Deprecation Notices: Legacy types are marked as deprecated to encourage migration to shared types
4. Enhanced Interfaces: New interfaces are created that extend shared interfaces with llm-mcp-specific functionality

Implemented Changes

1. Model Types (types/models.ts)

• Kept the original ModelConfig for backward compatibility but marked it as deprecated
• Created a new ExtendedModelConfig interface that extends shared ModelConfig with llm-mcp-specific fields
• Added conversion functions between legacy and shared types
• Updated ModelVersion and ModelRegistry to use the new ExtendedModelConfig

// New extended type that incorporates shared type
export interface ExtendedModelConfig extends SharedModelConfig {
  type: 'llm' | 'embedding' | 'classifier' | 'generator';
  // ...additional llm-mcp-specific fields
}

// Conversion function
export function toSharedModelConfig(config: ModelConfig): SharedModelConfig {
  return {
    id: config.id,
    name: config.name,
    // ...mapping fields
  };
}

2. AI Provider Interface (interfaces/ai-provider.ts)

• Kept the original AiProvider interface for backward compatibility but marked it as deprecated
• Imported the shared AiProvider interface as SharedAiProvider
• Created a new EnhancedAiProvider interface that extends SharedAiProvider with llm-mcp-specific methods
• Added adapter functions to convert between legacy and shared provider interfaces

// Enhanced AI provider that extends the shared interface
export interface EnhancedAiProvider extends SharedAiProvider {
  // MCP-specific methods
  processGenerationRequest(request: GenerationRequest): Promise<GenerationResponse>;
  processChatRequest(request: ChatRequest): Promise<ChatResponse>;
  getProviderMetrics(): Record<string, any>;
  getStatus(): 'online' | 'offline' | 'degraded';
  getUsageStats(): {
    // Usage statistics
  };
}

// Adapter functions
export function adaptToSharedProvider(provider: AiProvider): SharedAiProvider {
  return provider as SharedAiProvider;
}

export function adaptToLegacyProvider(provider: SharedAiProvider): AiProvider {
  return provider as AiProvider;
}

3. AI Streaming Types (interfaces/ai-streaming.ts)

• Kept the original AiOperationState and StreamingMetrics interfaces for backward compatibility
• Imported the shared interfaces from shared-utils
• Created adapter classes that implement the shared interfaces using the legacy implementations
• Added comprehensive mapping between legacy and shared interface properties

// Adapter class for operation state
export class AiOperationStateAdapter implements SharedAiOperationState {
  private legacyState: AiOperationState;

  constructor(legacyState: AiOperationState) {
    this.legacyState = legacyState;
  }

  // Implement shared interface using legacy state
  get status(): 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' {
    const status = this.legacyState.getStatus();
    // Map legacy status to shared status
    // ...
  }
  // ...other properties
}

Migration Path

The implementation provides a clear path for migrating to shared types:

1. Immediate Changes:

   • New code should use ExtendedModelConfig instead of ModelConfig
   • New AI providers should implement EnhancedAiProvider
   • Use adapter classes to integrate with existing code

2. Near-term Changes (1-3 months):

   • Update service interfaces to use shared types
   • Implement conversion functions where needed for compatibility
   • Gradually convert legacy implementations to use the shared types directly

3. Long-term Changes (3-6 months):

   • Remove deprecated types and adapter classes
   • Use shared types throughout the codebase
   • Maintain only llm-mcp-specific extensions of shared types

Key Benefits

This implementation of shared types in llm-mcp provides several benefits:

1. Improved Interoperability: Standardized types across services
2. Reduced Duplication: Eliminates duplicate type definitions
3. Type Safety: Strong typing for cross-service communication
4. Extensibility: Domain-specific types can extend shared types
5. Backward Compatibility: Existing code continues to work

Next Steps

1. Update Core Services: Update service implementations to use shared types
2. Update Models Registry: Update the model registry to use ExtendedModelConfig
3. Update AI Providers: Implement EnhancedAiProvider in all AI providers
4. Update Vector Bridge: Update vector-bridge components to use shared vector types
5. Documentation: Update project documentation to reference shared types