auto-coder 0.1.288__py3-none-any.whl → 0.1.290__py3-none-any.whl

autocoder/rag/cache/cache_result_merge.py

@@ -0,0 +1,265 @@
+from typing import List, Dict, Any, Optional, Set, Tuple
+import logging
+from enum import Enum
+from collections import defaultdict, Counter
+from loguru import logger
+class MergeStrategy(str, Enum):
+    """合并策略枚举类"""
+    SIMPLE_EXTEND = "simple_extend"  # 简单扩展（当前实现）
+    FREQUENCY_RANK = "frequency_rank"  # 按频率排序
+    WEIGHTED_RANK = "weighted_rank"  # 加权排序
+    INTERLEAVE = "interleave"  # 交错合并
+    DEDUPLICATE = "deduplicate"  # 去重合并
+    QUERY_WEIGHTED = "query_weighted"  # 按查询加权
+
+
+class CacheResultMerger:
+    """
+    缓存结果合并策略模块
+
+    本模块提供了多种合并搜索结果的策略，用于处理多查询场景下的结果整合。
+
+    主要包括：
+    1. 简单扩展 (SIMPLE_EXTEND): 直接合并所有结果列表
+    2. 频率排序 (FREQUENCY_RANK): 根据文件路径出现频率排序
+    3. 加权排序 (WEIGHTED_RANK): 考虑结果排名位置的加权排序
+    4. 交错合并 (INTERLEAVE): 交错合并多个查询结果
+    5. 去重合并 (DEDUPLICATE): 合并结果并去除重复文件
+    6. 查询加权 (QUERY_WEIGHTED): 考虑查询重要性的加权排序
+
+    使用示例:
+    ```python
+    from cache_result_merge import CacheResultMerger, MergeStrategy
+
+    # 创建合并器
+    merger = CacheResultMerger(max_results=100)
+
+    # 假设有多个查询结果
+    query_results = [
+        ("query1", [result1, result2, ...]),
+        ("query2", [result3, result4, ...])
+    ]
+
+    # 使用特定策略合并
+    merged_results = merger.merge(
+        query_results, 
+        strategy=MergeStrategy.WEIGHTED_RANK
+    )
+    ```
+    """
+    
+    def __init__(self, max_results: int = None):
+        """
+        初始化结果合并器
+        
+        Args:
+            max_results: 最大结果数，如果为None则不限制
+        """
+        self.max_results = max_results
+    
+    def merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]], 
+              strategy: MergeStrategy = MergeStrategy.WEIGHTED_RANK) -> List[Dict[str, Any]]:
+        """
+        根据指定策略合并查询结果
+        
+        Args:
+            query_results: 查询结果列表，每项为(查询, 结果列表)的元组
+            strategy: 合并策略
+            
+        Returns:
+            合并后的结果列表
+        """
+        if strategy == MergeStrategy.SIMPLE_EXTEND:
+            return self._simple_extend_merge(query_results)
+        elif strategy == MergeStrategy.FREQUENCY_RANK:
+            return self._frequency_rank_merge(query_results)
+        elif strategy == MergeStrategy.WEIGHTED_RANK:
+            return self._weighted_rank_merge(query_results)
+        elif strategy == MergeStrategy.INTERLEAVE:
+            return self._interleave_merge(query_results)
+        elif strategy == MergeStrategy.DEDUPLICATE:
+            return self._deduplicate_merge(query_results)
+        elif strategy == MergeStrategy.QUERY_WEIGHTED:
+            return self._query_weighted_merge(query_results)
+        else:
+            logger.warning(f"未知的合并策略: {strategy}，使用简单扩展策略")
+            return self._simple_extend_merge(query_results)
+    
+    def _simple_extend_merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]]) -> List[Dict[str, Any]]:
+        """
+        简单扩展策略：将所有结果简单合并
+        
+        Args:
+            query_results: 查询结果列表
+            
+        Returns:
+            合并后的结果列表
+        """
+        all_results = []
+        for query, results in query_results:
+            all_results.extend(results)
+        
+        logger.info(f"简单扩展策略合并结果: 从 {sum(len(r) for _, r in query_results)} 条到 {len(all_results)} 条")
+        return all_results[:self.max_results] if self.max_results else all_results
+    
+    def _frequency_rank_merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]]) -> List[Dict[str, Any]]:
+        """
+        频率排序策略：按文件路径出现频率排序
+        
+        Args:
+            query_results: 查询结果列表
+            
+        Returns:
+            合并后的结果列表
+        """
+        # 合并所有结果
+        all_results = []
+        for _, results in query_results:
+            all_results.extend(results)
+        
+        # 按文件路径计数
+        file_path_counts = Counter(result["file_path"] for result in all_results)
+        
+        # 建立文件路径到结果的映射，保留每个文件路径的第一个结果
+        file_to_result = {}
+        for result in all_results:
+            file_path = result["file_path"]
+            if file_path not in file_to_result:
+                file_to_result[file_path] = result
+        
+        # 按频率排序
+        sorted_results = [file_to_result[file_path] for file_path, _ in file_path_counts.most_common()]
+        
+        logger.info(f"频率排序策略合并结果: 从 {len(all_results)} 条到 {len(sorted_results)} 条，按文件出现频率排序")
+        return sorted_results[:self.max_results] if self.max_results else sorted_results
+    
+    def _weighted_rank_merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]]) -> List[Dict[str, Any]]:
+        """
+        加权排序策略：考虑结果位置和频率的加权排序
+        
+        Args:
+            query_results: 查询结果列表
+            
+        Returns:
+            合并后的结果列表
+        """
+        # 按文件路径评分
+        file_path_scores = defaultdict(float)
+        file_to_result = {}
+        
+        for _, results in query_results:
+            for rank, result in enumerate(results):
+                file_path = result["file_path"]
+                # 排名越高，得分越高（排名从0开始，所以用1/(rank+1)）
+                rank_score = 1.0 / (rank + 1)
+                file_path_scores[file_path] += rank_score
+                
+                # 保存每个文件路径的第一个结果
+                if file_path not in file_to_result:
+                    file_to_result[file_path] = result
+        
+        # 按分数排序
+        sorted_results = [file_to_result[file_path] 
+                        for file_path, _ in sorted(file_path_scores.items(), key=lambda x: x[1], reverse=True)]
+        
+        logger.info(f"加权排序策略合并结果: 得到 {len(sorted_results)} 条结果，按位置加权排序")
+        return sorted_results[:self.max_results] if self.max_results else sorted_results
+    
+    def _interleave_merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]]) -> List[Dict[str, Any]]:
+        """
+        交错合并策略：交错合并各查询的结果
+        
+        Args:
+            query_results: 查询结果列表
+            
+        Returns:
+            合并后的结果列表
+        """
+        # 获取每个查询的结果列表
+        result_lists = [results for _, results in query_results]
+        if not result_lists:
+            return []
+        
+        # 交错合并结果
+        interleaved = []
+        seen_files = set()
+        
+        # 找出最长列表长度
+        max_len = max(len(results) for results in result_lists)
+        
+        # 交错合并
+        for i in range(max_len):
+            for results in result_lists:
+                if i < len(results):
+                    result = results[i]
+                    file_path = result["file_path"]
+                    if file_path not in seen_files:
+                        seen_files.add(file_path)
+                        interleaved.append(result)
+        
+        logger.info(f"交错合并策略合并结果: 得到 {len(interleaved)} 条唯一结果")
+        return interleaved[:self.max_results] if self.max_results else interleaved
+    
+    def _deduplicate_merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]]) -> List[Dict[str, Any]]:
+        """
+        去重合并策略：合并并去除重复的文件路径
+        
+        Args:
+            query_results: 查询结果列表
+            
+        Returns:
+            合并后的结果列表
+        """
+        all_results = []
+        seen_files = set()
+        
+        for _, results in query_results:
+            for result in results:
+                file_path = result["file_path"]
+                if file_path not in seen_files:
+                    seen_files.add(file_path)
+                    all_results.append(result)
+        
+        logger.info(f"去重合并策略合并结果: 从 {sum(len(r) for _, r in query_results)} 条到 {len(all_results)} 条唯一结果")
+        return all_results[:self.max_results] if self.max_results else all_results
+    
+    def _query_weighted_merge(self, query_results: List[Tuple[str, List[Dict[str, Any]]]]) -> List[Dict[str, Any]]:
+        """
+        查询加权策略：根据查询的重要性加权排序结果
+        
+        Args:
+            query_results: 查询结果列表，包含(查询, 结果)对
+            
+        Returns:
+            合并后的结果列表
+        """
+        # 按照查询词加权
+        file_path_scores = defaultdict(float)
+        file_to_result = {}
+        query_weights = {}
+        
+        # 计算每个查询的权重 (可以根据查询的长度、特殊性等调整)
+        total_queries = len(query_results)
+        for i, (query, _) in enumerate(query_results):
+            # 默认权重，可以根据查询特性调整
+            query_weights[query] = 1.0
+        
+        # 计算文件得分
+        for query, results in query_results:
+            query_weight = query_weights[query]
+            for rank, result in enumerate(results):
+                file_path = result["file_path"]
+                # 排名越高，得分越高
+                rank_score = 1.0 / (rank + 1)
+                file_path_scores[file_path] += rank_score * query_weight
+                
+                # 保存每个文件路径的第一个结果
+                if file_path not in file_to_result:
+                    file_to_result[file_path] = result
+        
+        # 按分数排序
+        sorted_results = [file_to_result[file_path] 
+                        for file_path, _ in sorted(file_path_scores.items(), key=lambda x: x[1], reverse=True)]
+        
+        logger.info(f"查询加权策略合并结果: 得到 {len(sorted_results)} 条结果，按查询加权排序")
+        return sorted_results[:self.max_results] if self.max_results else sorted_results 

autocoder/rag/cache/file_monitor_cache.py

@@ -11,6 +11,17 @@ from watchfiles import Change, DefaultFilter, awatch, watch
 
 
 class AutoCoderRAGDocListener(BaseCacheManager):
+    """
+    基于文件系统实时监控的代码缓存管理器。
+    
+    此类实现了对代码库的实时监控，当文件发生变化时（新增、修改、删除）自动更新缓存。
+    与其他缓存管理器不同，它使用 watchfiles 库进行文件变更监控，无需定期扫描文件系统。
+    
+    类属性:
+        cache: 缓存字典，存储处理后的文件内容
+        ignore_dirs: 需要忽略的目录列表
+        ignore_entity_patterns: 需要忽略的文件模式列表
+    """
     cache: Dict[str, Dict] = {}
     ignore_dirs = [
         "__pycache__",
@@ -38,6 +49,43 @@ class AutoCoderRAGDocListener(BaseCacheManager):
     ]
 
     def __init__(self, path: str, ignore_spec, required_exts: List) -> None:
+        """
+        初始化文件监控缓存管理器。
+        
+        参数:
+            path: 需要监控的代码库根目录
+            ignore_spec: 指定哪些文件/目录应被忽略的规则
+            required_exts: 需要处理的文件扩展名列表
+            
+        缓存结构 (self.cache):
+            self.cache 是一个字典，其结构比其他缓存管理器更简单:
+            {
+                "file_path1": {                  # 键为文件的绝对路径
+                    "file_path": str,            # 文件的绝对路径
+                    "content": List[Dict],       # 文件内容的结构化表示，每个元素是 SourceCode 对象的序列化
+                },
+                "file_path2": { ... },
+                ...
+            }
+            
+            与其他缓存管理器的主要区别:
+            1. 不需要存储 MD5 哈希或修改时间，因为文件变更通过监控系统直接获取
+            2. 没有本地持久化机制，所有缓存在内存中维护
+            3. 缓存更新基于事件驱动，而非定期扫描
+            
+        文件监控机制:
+            - 使用 watchfiles 库监控文件系统变更
+            - 支持三种事件类型: 添加(added)、修改(modified)、删除(deleted)
+            - 使用单独线程进行监控，不阻塞主线程
+            - 监控遵循配置的忽略规则和所需扩展名过滤
+            - 初始化时会先加载所有符合条件的文件
+            
+        源代码处理:
+            使用 process_file_local 函数处理单个文件:
+            - 参数: file_path (文件路径)
+            - 返回值: List[SourceCode]
+            - 文件处理后，直接更新内存中的缓存
+        """
         self.path = path
         self.ignore_spec = ignore_spec
         self.required_exts = required_exts
@@ -59,13 +107,27 @@ class AutoCoderRAGDocListener(BaseCacheManager):
         self.watch_thread.start()
 
     def stop(self):
+        """
+        停止文件监控线程。
+        
+        设置停止事件并等待监控线程结束，用于在对象销毁前优雅地关闭监控。
+        """
         self.stop_event.set()
         self.watch_thread.join()
 
     def __del__(self):
+        """
+        析构函数，确保在对象被销毁时停止监控线程。
+        """
         self.stop()
 
     def load_first(self):
+        """
+        初始化时加载所有符合条件的文件。
+        
+        获取所有符合过滤条件的文件，并将它们添加到缓存中。
+        这确保了缓存在开始监控前已经包含所有现有文件。
+        """
         files_to_process = self.get_all_files()
         if not files_to_process:
             return
@@ -73,6 +135,17 @@ class AutoCoderRAGDocListener(BaseCacheManager):
             self.update_cache(item)
 
     def update_cache(self, file_path):
+        """
+        处理单个文件并更新缓存。
+        
+        参数:
+            file_path: 文件的绝对路径
+            
+        处理流程:
+            1. 使用 process_file_local 函数解析文件内容
+            2. 将解析结果序列化并存储在缓存中
+            3. 日志记录更新的文件及当前缓存状态
+        """
         source_code = process_file_local(file_path)
         self.cache[file_path] = {
             "file_path": file_path,
@@ -82,11 +155,25 @@ class AutoCoderRAGDocListener(BaseCacheManager):
         logger.info(f"current cache: {self.cache.keys()}")
 
     def remove_cache(self, file_path):
+        """
+        从缓存中移除指定文件。
+        
+        参数:
+            file_path: 要移除的文件的绝对路径
+        """
         del self.cache[file_path]
         logger.info(f"remove cache: {file_path}")
         logger.info(f"current cache: {self.cache.keys()}")
 
     def open_watch(self):
+        """
+        启动文件系统监控线程。
+        
+        此方法会持续监控文件系统变更，直到 stop_event 被设置。
+        当检测到文件变更时，会根据变更类型执行相应的操作:
+        - 添加/修改文件: 调用 update_cache 更新缓存
+        - 删除文件: 调用 remove_cache 从缓存中移除
+        """
         logger.info(f"start monitor: {self.path}...")
         for changes in watch(
             self.path, watch_filter=self.file_filter, stop_event=self.stop_event
@@ -98,26 +185,52 @@ class AutoCoderRAGDocListener(BaseCacheManager):
                 elif action == Change.deleted:
                     self.remove_cache(path)
 
-    def get_cache(self,options:Optional[Dict[str,Any]]=None):
+    def get_cache(self, options: Optional[Dict[str, Any]] = None):
+        """
+        获取当前缓存。
+        
+        参数:
+            options: 可选的参数，指定获取缓存时的选项
+            
+        返回:
+            当前内存中的缓存字典
+        """
         return self.cache
 
     def _load_ignore_file(self):
+        """
+        加载忽略文件规则。
+        
+        首先尝试加载 .serveignore 文件，如果不存在，则尝试加载 .gitignore 文件。
+        
+        返回:
+            包含忽略规则的字符串列表
+        """
         serveignore_path = os.path.join(self.path, ".serveignore")
         gitignore_path = os.path.join(self.path, ".gitignore")
 
         if os.path.exists(serveignore_path):
-            with open(serveignore_path, "r",encoding="utf-8") as ignore_file:
+            with open(serveignore_path, "r", encoding="utf-8") as ignore_file:
                 patterns = ignore_file.readlines()
                 return [pattern.strip() for pattern in patterns]
         elif os.path.exists(gitignore_path):
-            with open(gitignore_path, "r",encoding="utf-8") as ignore_file:
+            with open(gitignore_path, "r", encoding="utf-8") as ignore_file:
                 patterns = ignore_file.readlines()
                 return [pattern.strip() for pattern in patterns]
         return []
 
     def get_all_files(self) -> List[str]:
+        """
+        获取所有符合条件的文件路径。
+        
+        遍历指定目录，应用忽略规则和扩展名过滤，
+        返回所有符合条件的文件的绝对路径。
+        
+        返回:
+            符合条件的文件路径列表
+        """
         all_files = []
-        for root, dirs, files in os.walk(self.path,followlinks=True):
+        for root, dirs, files in os.walk(self.path, followlinks=True):
             dirs[:] = [d for d in dirs if not d.startswith(".")]
 
             if self.ignore_spec: