""" API matching system using fuzzy string matching and semantic similarity. """ from typing import Dict, List, Any, Optional, Tuple, NamedTuple from dataclasses import dataclass from enum import Enum import json import re import concurrent.futures try: from rapidfuzz import fuzz, process RAPIDFUZZ_AVAILABLE = True except ImportError: RAPIDFUZZ_AVAILABLE = False from config.settings import settings from src.utils.logging_config import logger class MatchType(Enum): """Types of API matches.""" EXACT = "exact" FUZZY = "fuzzy" SEMANTIC = "semantic" PATTERN = "pattern" @dataclass class APIOperation: """Represents an API operation.""" name: str method: str endpoint: str description: str parameters: List[Dict[str, Any]] tags: List[str] summary: Optional[str] = None operation_id: Optional[str] = None @dataclass class APIMatch: """Represents a match between keywords and API operations.""" keyword: str operation: APIOperation match_type: MatchType similarity_score: float confidence: float reasoning: str class APIMatcher: """Matches extracted keywords to available API operations.""" def __init__(self, config: Optional[Dict[str, Any]] = None): """Initialize the API matcher.""" self.config = config or {} self.operations: List[APIOperation] = [] self.operation_index: Dict[str, APIOperation] = {} # Configuration self.fuzzy_threshold = self.config.get('fuzzy_threshold', settings.fuzzy_match_threshold) self.similarity_threshold = self.config.get('similarity_threshold', settings.similarity_threshold) self.max_matches = self.config.get('max_matches', 10) if not RAPIDFUZZ_AVAILABLE: logger.warning("RapidFuzz not available. Fuzzy matching will be limited.") logger.info("Initialized APIMatcher") def load_openapi_spec(self, spec: Dict[str, Any]) -> None: """ Load API operations from OpenAPI specification. Args: spec: OpenAPI specification dictionary """ operations = [] try: paths = spec.get('paths', {}) for path, path_item in paths.items(): for method, operation in path_item.items(): if method.upper() in ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']: # Extract operation details op = APIOperation( name=operation.get('operationId', f"{method}_{path.replace('/', '_')}"), method=method.upper(), endpoint=path, description=operation.get('description', ''), summary=operation.get('summary', ''), parameters=operation.get('parameters', []), tags=operation.get('tags', []), operation_id=operation.get('operationId') ) operations.append(op) self.operations = operations self._build_operation_index() logger.info(f"Loaded {len(operations)} API operations from OpenAPI spec") except Exception as e: logger.error(f"Error loading OpenAPI spec: {e}") raise def add_operation(self, operation: APIOperation) -> None: """Add a single API operation.""" self.operations.append(operation) self.operation_index[operation.name] = operation logger.debug(f"Added operation: {operation.name}") def add_operations(self, operations: List[APIOperation]) -> None: """Add multiple API operations.""" self.operations.extend(operations) self._build_operation_index() logger.info(f"Added {len(operations)} operations") def _build_operation_index(self) -> None: """Build index for fast operation lookup.""" self.operation_index = {op.name: op for op in self.operations} def match_keywords(self, keywords: List[str]) -> List[APIMatch]: """ Match keywords to API operations. Args: keywords: List of extracted keywords Returns: List of API matches sorted by confidence """ if not self.operations: logger.warning("No API operations loaded") return [] all_matches = [] # Match each keyword against all operations in parallel with concurrent.futures.ThreadPoolExecutor() as executor: for matches in executor.map(self._match_single_keyword, keywords): all_matches.extend(matches) # Remove duplicates and sort by confidence unique_matches = self._deduplicate_matches(all_matches) sorted_matches = sorted(unique_matches, key=lambda x: x.confidence, reverse=True) return sorted_matches[:self.max_matches] def _match_single_keyword(self, keyword: str) -> List[APIMatch]: """Match a single keyword against all operations.""" matches = [] for operation in self.operations: # Try different matching strategies match_results = [ self._exact_match(keyword, operation), self._fuzzy_match(keyword, operation), self._pattern_match(keyword, operation), self._semantic_match(keyword, operation) ] # Keep the best match for this operation best_match = max(match_results, key=lambda x: x.confidence if x else 0) if best_match and best_match.confidence > 0.3: # Minimum confidence threshold matches.append(best_match) return matches def _exact_match(self, keyword: str, operation: APIOperation) -> Optional[APIMatch]: """Check for exact matches.""" keyword_lower = keyword.lower() # Check operation name if keyword_lower == operation.name.lower(): return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.EXACT, similarity_score=1.0, confidence=1.0, reasoning="Exact match with operation name" ) # Check tags for tag in operation.tags: if keyword_lower == tag.lower(): return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.EXACT, similarity_score=1.0, confidence=0.9, reasoning=f"Exact match with tag: {tag}" ) # Check if keyword appears in description if keyword_lower in operation.description.lower(): return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.EXACT, similarity_score=1.0, confidence=0.8, reasoning="Exact match in description" ) return None def _fuzzy_match(self, keyword: str, operation: APIOperation) -> Optional[APIMatch]: """Perform fuzzy string matching.""" if not RAPIDFUZZ_AVAILABLE: return None # Prepare search targets targets = [ operation.name, operation.summary or "", operation.description, " ".join(operation.tags), operation.endpoint ] best_score = 0 best_target = "" for target in targets: if target: score = fuzz.WRatio(keyword.lower(), target.lower()) if score > best_score: best_score = score best_target = target if best_score >= self.fuzzy_threshold: confidence = min(0.9, best_score / 100.0) return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.FUZZY, similarity_score=best_score / 100.0, confidence=confidence, reasoning=f"Fuzzy match with '{best_target}' (score: {best_score})" ) return None def _pattern_match(self, keyword: str, operation: APIOperation) -> Optional[APIMatch]: """Match using patterns and heuristics.""" keyword_lower = keyword.lower() # HTTP method patterns method_patterns = { 'get': ['get', 'fetch', 'retrieve', 'find', 'search', 'list'], 'post': ['create', 'add', 'new', 'insert', 'submit'], 'put': ['update', 'modify', 'change', 'edit', 'replace'], 'delete': ['delete', 'remove', 'destroy', 'drop'], 'patch': ['patch', 'partial', 'modify'] } # Check if keyword matches operation method pattern for method, patterns in method_patterns.items(): if operation.method.lower() == method and keyword_lower in patterns: return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.PATTERN, similarity_score=0.8, confidence=0.7, reasoning=f"Pattern match: '{keyword}' suggests {method.upper()} operation" ) # Resource name patterns endpoint_parts = [part for part in operation.endpoint.split('/') if part and not part.startswith('{')] for part in endpoint_parts: if keyword_lower in part.lower() or part.lower() in keyword_lower: return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.PATTERN, similarity_score=0.7, confidence=0.6, reasoning=f"Pattern match with endpoint resource: {part}" ) return None def _semantic_match(self, keyword: str, operation: APIOperation) -> Optional[APIMatch]: """Perform semantic matching (placeholder for now).""" # This would use embeddings/transformers for semantic similarity # For now, implement basic word overlap keyword_words = set(keyword.lower().split()) # Combine operation text operation_text = " ".join([ operation.name, operation.summary or "", operation.description, " ".join(operation.tags) ]).lower() operation_words = set(operation_text.split()) # Calculate Jaccard similarity intersection = keyword_words.intersection(operation_words) union = keyword_words.union(operation_words) if union: similarity = len(intersection) / len(union) if similarity > 0.2: # Minimum semantic similarity return APIMatch( keyword=keyword, operation=operation, match_type=MatchType.SEMANTIC, similarity_score=similarity, confidence=similarity * 0.6, # Lower confidence for basic semantic matching reasoning=f"Semantic similarity based on word overlap: {intersection}" ) return None def _deduplicate_matches(self, matches: List[APIMatch]) -> List[APIMatch]: """Remove duplicate matches, keeping the best one for each operation.""" operation_matches = {} for match in matches: op_key = f"{match.operation.method}_{match.operation.endpoint}" if op_key not in operation_matches or match.confidence > operation_matches[op_key].confidence: operation_matches[op_key] = match return list(operation_matches.values()) def get_operation_by_name(self, name: str) -> Optional[APIOperation]: """Get operation by name.""" return self.operation_index.get(name) def get_operations_by_tag(self, tag: str) -> List[APIOperation]: """Get operations by tag.""" return [op for op in self.operations if tag.lower() in [t.lower() for t in op.tags]] def get_operations_by_method(self, method: str) -> List[APIOperation]: """Get operations by HTTP method.""" return [op for op in self.operations if op.method.upper() == method.upper()] def search_operations(self, query: str) -> List[APIOperation]: """Search operations by query string.""" if not RAPIDFUZZ_AVAILABLE: # Fallback to simple text search query_lower = query.lower() results = [] for op in self.operations: search_text = f"{op.name} {op.description} {' '.join(op.tags)}".lower() if query_lower in search_text: results.append(op) return results # Use fuzzy search search_targets = [] for op in self.operations: search_text = f"{op.name} {op.description} {' '.join(op.tags)}" search_targets.append((search_text, op)) matches = process.extract( query, [target[0] for target in search_targets], scorer=fuzz.WRatio, limit=10 ) results = [] for match, score, _ in matches: if score >= 60: # Minimum score for search results # Find corresponding operation for text, op in search_targets: if text == match: results.append(op) break return results def get_stats(self) -> Dict[str, Any]: """Get matcher statistics.""" method_counts = {} tag_counts = {} for op in self.operations: method_counts[op.method] = method_counts.get(op.method, 0) + 1 for tag in op.tags: tag_counts[tag] = tag_counts.get(tag, 0) + 1 return { 'total_operations': len(self.operations), 'methods': method_counts, 'tags': tag_counts, 'fuzzy_matching_available': RAPIDFUZZ_AVAILABLE, 'configuration': { 'fuzzy_threshold': self.fuzzy_threshold, 'similarity_threshold': self.similarity_threshold, 'max_matches': self.max_matches } }