bioguider 0.2.29__py3-none-any.whl → 0.2.31__py3-none-any.whl

bioguider/managers/generation_manager.py

@@ -24,6 +24,7 @@ class DocumentationGenerationManager:
         self.llm = llm
         self.step_callback = step_callback
         self.repo_url_or_path: str | None = None
+        self.start_time = None
 
         self.loader = EvaluationReportLoader()
         self.extractor = SuggestionExtractor()
@@ -42,12 +43,36 @@ class DocumentationGenerationManager:
     def prepare_repo(self, repo_url_or_path: str):
         self.repo_url_or_path = repo_url_or_path
 
+    def _get_generation_time(self) -> str:
+        """Get formatted generation time with start, end, and duration"""
+        if self.start_time is None:
+            return "Not tracked"
+        import time
+        import datetime
+        end_time = time.time()
+        duration = end_time - self.start_time
+        
+        start_str = datetime.datetime.fromtimestamp(self.start_time).strftime("%H:%M:%S")
+        end_str = datetime.datetime.fromtimestamp(end_time).strftime("%H:%M:%S")
+        
+        if duration < 60:
+            duration_str = f"{duration:.1f}s"
+        elif duration < 3600:
+            duration_str = f"{duration/60:.1f}m"
+        else:
+            duration_str = f"{duration/3600:.1f}h"
+            
+        return f"{start_str} → {end_str} ({duration_str})"
+
     def run(self, report_path: str, repo_path: str | None = None) -> str:
+        import time
+        self.start_time = time.time()
         repo_path = repo_path or self.repo_url_or_path or ""
-        self.print_step(step_name="LoadReport", step_output=f"report_path={report_path}")
+        self.print_step(step_name="LoadReport", step_output=f"Loading evaluation report from {report_path}...")
         report, report_abs = self.loader.load(report_path)
+        self.print_step(step_name="LoadReport", step_output="✓ Evaluation report loaded successfully")
 
-        self.print_step(step_name="ReadRepoFiles", step_output=f"repo_path={repo_path}")
+        self.print_step(step_name="ReadRepoFiles", step_output=f"Reading repository files from {repo_path}...")
         reader = RepoReader(repo_path)
         # Prefer report-listed files if available; include all report-declared file lists
         target_files = []
@@ -64,54 +89,111 @@ class DocumentationGenerationManager:
                 if isinstance(key, str) and key.strip():
                     userguide_files.append(key)
         target_files.extend(userguide_files)
+        
+        # Add tutorial files from tutorial_evaluation keys
+        tutorial_files: list[str] = []
+        if getattr(report, "tutorial_files", None):
+            tutorial_files.extend([p for p in report.tutorial_files if isinstance(p, str)])
+        elif getattr(report, "tutorial_evaluation", None) and isinstance(report.tutorial_evaluation, dict):
+            for key in report.tutorial_evaluation.keys():
+                if isinstance(key, str) and key.strip():
+                    tutorial_files.append(key)
+        target_files.extend(tutorial_files)
+        
         if getattr(report, "submission_requirements_files", None):
             target_files.extend(report.submission_requirements_files)
         target_files = [p for p in target_files if isinstance(p, str) and p.strip()]
         target_files = list(dict.fromkeys(target_files))  # de-dup
         files, missing = reader.read_files(target_files) if target_files else reader.read_default_targets()
+        self.print_step(step_name="ReadRepoFiles", step_output=f"✓ Read {len(files)} files from repository")
 
-        self.print_step(step_name="AnalyzeStyle", step_output=f"files={[p for p in files.keys()]}")
+        self.print_step(step_name="AnalyzeStyle", step_output="Analyzing document style and formatting...")
         style = self.style_analyzer.analyze(files)
+        self.print_step(step_name="AnalyzeStyle", step_output="✓ Document style analysis completed")
 
-        self.print_step(step_name="ExtractSuggestions")
+        self.print_step(step_name="ExtractSuggestions", step_output="Extracting suggestions from evaluation report...")
         suggestions = self.extractor.extract(report)
-        self.print_step(step_name="Suggestions", step_output=f"count={len(suggestions)} ids={[s.id for s in suggestions]}")
+        self.print_step(step_name="Suggestions", step_output=f"✓ Extracted {len(suggestions)} suggestions from evaluation report")
 
-        self.print_step(step_name="PlanChanges")
+        self.print_step(step_name="PlanChanges", step_output="Planning changes based on suggestions...")
         plan = self.planner.build_plan(repo_path=repo_path, style=style, suggestions=suggestions, available_files=files)
-        self.print_step(step_name="PlannedEdits", step_output=f"count={len(plan.planned_edits)} files={list(set(e.file_path for e in plan.planned_edits))}")
+        self.print_step(step_name="PlannedEdits", step_output=f"✓ Planned {len(plan.planned_edits)} edits across {len(set(e.file_path for e in plan.planned_edits))} files")
 
-        self.print_step(step_name="RenderDocuments")
-        # Apply edits cumulatively per file to ensure multiple suggestions are realized
+        self.print_step(step_name="RenderDocuments", step_output=f"Rendering documents with LLM (processing {len(plan.planned_edits)} edits)...")
+        # Apply edits; support full-file regeneration using the evaluation report as the sole authority
         revised: Dict[str, str] = {}
         diff_stats: Dict[str, dict] = {}
         edits_by_file: Dict[str, list] = {}
         for e in plan.planned_edits:
             edits_by_file.setdefault(e.file_path, []).append(e)
+        
+        total_files = len(edits_by_file)
+        processed_files = 0
+
+        # Prepare evaluation data subset to drive LLM full document generation
+        evaluation_data = {
+            "readme_evaluation": getattr(report, "readme_evaluation", None),
+            "installation_evaluation": getattr(report, "installation_evaluation", None),
+            "userguide_evaluation": getattr(report, "userguide_evaluation", None),
+            "tutorial_evaluation": getattr(report, "tutorial_evaluation", None),
+        }
+
         for fpath, edits in edits_by_file.items():
-            content = files.get(fpath, "")
+            processed_files += 1
+            self.print_step(step_name="ProcessingFile", step_output=f"Processing {fpath} ({processed_files}/{total_files}) - {len(edits)} edits")
+            
+            original_content = files.get(fpath, "")
+            content = original_content
             total_stats = {"added_lines": 0}
             for e in edits:
-                # Generate LLM content for section if template is generic
-                context = files.get(fpath, "")
-                gen_section, gen_usage = self.llm_gen.generate_section(
-                    suggestion=next((s for s in suggestions if s.id == e.suggestion_id), None) if e.suggestion_id else None,
-                    style=plan.style_profile,
-                    context=context,
-                ) if e.suggestion_id else ""
-                if isinstance(gen_section, str) and gen_section:
-                    self.print_step(step_name="LLMSection", step_output=f"file={fpath} suggestion={e.suggestion_id} tokens={gen_usage.get('total_tokens', 0)}\n{gen_section}")
-                    # Ensure header present
-                    if gen_section.lstrip().startswith("#"):
-                        e.content_template = gen_section
-                    else:
-                        title = e.anchor.get('value', '').strip() or ''
-                        e.content_template = f"## {title}\n\n{gen_section}" if title else gen_section
+                context = original_content
+                if not e.content_template or e.content_template.strip() == "":
+                    # Generate LLM content - use full document generation for full_replace, section generation for others
+                    suggestion = next((s for s in suggestions if s.id == e.suggestion_id), None) if e.suggestion_id else None
+                    if suggestion:
+                        if e.edit_type == "full_replace":
+                            self.print_step(step_name="GeneratingContent", step_output=f"Generating full document for {e.suggestion_id} using LLM...")
+                            gen_content, gen_usage = self.llm_gen.generate_full_document(
+                                target_file=e.file_path,
+                                evaluation_report={"suggestion": suggestion.content_guidance, "evidence": suggestion.source.get("evidence", "") if suggestion.source else ""},
+                                context=context,
+                            )
+                            if isinstance(gen_content, str) and gen_content:
+                                self.print_step(step_name="LLMFullDoc", step_output=f"✓ Generated full document for {e.suggestion_id} ({gen_usage.get('total_tokens', 0)} tokens)")
+                                e.content_template = gen_content
+                        else:
+                            self.print_step(step_name="GeneratingContent", step_output=f"Generating section for {e.suggestion_id} using LLM...")
+                            gen_section, gen_usage = self.llm_gen.generate_section(
+                                suggestion=suggestion,
+                                style=plan.style_profile,
+                                context=context,
+                            )
+                            if isinstance(gen_section, str) and gen_section:
+                                self.print_step(step_name="LLMSection", step_output=f"✓ Generated section for {e.suggestion_id} ({gen_usage.get('total_tokens', 0)} tokens)")
+                                # Ensure header present
+                                if gen_section.lstrip().startswith("#"):
+                                    e.content_template = gen_section
+                                else:
+                                    title = e.anchor.get('value', '').strip() or ''
+                                    e.content_template = f"## {title}\n\n{gen_section}" if title else gen_section
                 content, stats = self.renderer.apply_edit(content, e)
+                # After applying full document or section changes, run a general cleaner pass for all text files
+                # to fix markdown/formatting issues without changing meaning.
+                try:
+                    if fpath.endswith((".md", ".rst", ".Rmd", ".Rd")) and content:
+                        self.print_step(step_name="CleaningContent", step_output=f"Cleaning formatting for {fpath}...")
+                        cleaned, _usage = self.llm_cleaner.clean_readme(content)
+                        if isinstance(cleaned, str) and cleaned.strip():
+                            content = cleaned
+                        
+                        # LLM cleaner now handles markdown fences and unwanted summaries
+                            
+                except Exception:
+                    pass
                 total_stats["added_lines"] = total_stats.get("added_lines", 0) + stats.get("added_lines", 0)
             revised[fpath] = content
             diff_stats[fpath] = total_stats
-            self.print_step(step_name="RenderedFile", step_output=f"file={fpath} added_lines={total_stats['added_lines']}")
+            self.print_step(step_name="RenderedFile", step_output=f"✓ Completed {fpath} - added {total_stats['added_lines']} lines")
 
         # Removed cleaner: duplication and fixes handled in prompts and renderer
 
@@ -128,11 +210,23 @@ class DocumentationGenerationManager:
         else:
             out_repo_key = self.repo_url_or_path or "repo"
 
-        self.print_step(step_name="WriteOutputs", step_output=f"repo_key={out_repo_key}")
+        self.print_step(step_name="WriteOutputs", step_output=f"Writing outputs to {out_repo_key}...")
         out_dir = self.output.prepare_output_dir(out_repo_key)
         # Ensure all files we read (even without edits) are written to outputs alongside revisions
         all_files_to_write: Dict[str, str] = dict(files)
         all_files_to_write.update(revised)
+        # Also copy originals next to the new files for side-by-side comparison
+        def original_copy_name(path: str) -> str:
+            # Handle all file extensions properly
+            if "." in path:
+                base, ext = path.rsplit(".", 1)
+                return f"{base}.original.{ext}"
+            return f"{path}.original"
+
+        for orig_path, orig_content in files.items():
+            all_files_to_write[original_copy_name(orig_path)] = orig_content
+        
+        self.print_step(step_name="WritingFiles", step_output=f"Writing {len(all_files_to_write)} files to output directory...")
         artifacts = self.output.write_files(out_dir, all_files_to_write, diff_stats_by_file=diff_stats)
 
         manifest = GenerationManifest(
@@ -144,8 +238,11 @@ class DocumentationGenerationManager:
             artifacts=artifacts,
             skipped=missing,
         )
+        self.print_step(step_name="WritingManifest", step_output="Writing generation manifest...")
         self.output.write_manifest(out_dir, manifest)
+        
         # Write human-readable generation report
+        self.print_step(step_name="WritingReport", step_output="Writing generation report...")
         gen_report_path = self._write_generation_report(
             out_dir,
             report.repo_url or str(self.repo_url_or_path or ""),
@@ -155,7 +252,7 @@ class DocumentationGenerationManager:
             artifacts,
             missing,
         )
-        self.print_step(step_name="Done", step_output=f"output_dir={out_dir}")
+        self.print_step(step_name="Done", step_output=f"✓ Generation completed! Output directory: {out_dir}")
         return out_dir
 
     def _write_generation_report(
@@ -168,35 +265,279 @@ class DocumentationGenerationManager:
         artifacts,
         skipped: List[str],
     ):
-        # Build a simple markdown report
+        # Build a user-friendly markdown report
         lines: list[str] = []
-        lines.append(f"# Documentation Changelog\n")
-        lines.append(f"Repo: {repo_url}\n")
-        lines.append(f"Output: {out_dir}\n")
-        lines.append("\n## Summary of Changes\n")
+        lines.append(f"# Documentation Generation Report\n")
+        lines.append(f"**Repository:** {repo_url}\n")
+        lines.append(f"**Generated:** {out_dir}\n")
+        
+        # Processing timeline
+        total_improvements = len(plan.planned_edits)
+        start_time_str = self._get_generation_time().split(" → ")[0] if self.start_time else "Not tracked"
+        end_time_str = self._get_generation_time().split(" → ")[1].split(" (")[0] if self.start_time else "Not tracked"
+        duration_str = self._get_generation_time().split("(")[1].replace(")", "") if self.start_time else "Not tracked"
+        
+        lines.append(f"**Processing Timeline:**\n")
+        lines.append(f"- **Start Time:** {start_time_str}\n")
+        lines.append(f"- **End Time:** {end_time_str}\n")
+        lines.append(f"- **Duration:** {duration_str}\n")
+        
+        # Calculate statistics by category
+        category_stats = {}
+        file_stats = {}
         for e in plan.planned_edits:
             sug = next((s for s in suggestions if s.id == e.suggestion_id), None)
-            why = sug.source.get("evidence", "") if sug and sug.source else ""
-            lines.append(f"- File: `{e.file_path}` | Action: {e.edit_type} | Section: {e.anchor.get('value','')} | Added lines: {diff_stats.get(e.file_path,{}).get('added_lines',0)}")
-            if why:
-                lines.append(f"  - Why: {why}")
-        lines.append("\n## Planned Edits\n")
+            if sug and sug.category:
+                category = sug.category.split('.')[0]  # e.g., "readme.dependencies" -> "readme"
+                category_stats[category] = category_stats.get(category, 0) + 1
+            
+            file_stats[e.file_path] = file_stats.get(e.file_path, 0) + 1
+        
+        # Calculate evaluation report statistics
+        score_stats = {"Excellent": 0, "Good": 0, "Fair": 0, "Poor": 0}
+        processed_suggestions = set()
         for e in plan.planned_edits:
-            lines.append(f"- `{e.file_path}` -> {e.edit_type} -> {e.anchor.get('value','')}")
+            sug = next((s for s in suggestions if s.id == e.suggestion_id), None)
+            if sug and sug.source and sug.id not in processed_suggestions:
+                score = sug.source.get("score", "")
+                if score in score_stats:
+                    score_stats[score] += 1
+                processed_suggestions.add(sug.id)
+        
+        # Calculate success rate based on processed suggestions only
+        processed_suggestions_count = len([s for s in suggestions if s.source and s.source.get("score", "") in ("Fair", "Poor")])
+        fixed_suggestions = len([s for s in processed_suggestions if s in [sug.id for sug in suggestions if sug.source and sug.source.get("score", "") in ("Fair", "Poor")]])
+        
+        # Add professional summary and key metrics
+        lines.append(f"\n## Summary\n")
+        
+        # Concise summary for busy developers
+        lines.append(f"This is a report of automated documentation enhancements generated by BioGuider.\n")
+        lines.append(f"\nOur AI analyzed your existing documentation to identify areas for improvement based on standards for high-quality scientific software. It then automatically rewrote the files to be more accessible and useful for biomedical researchers.\n")
+        lines.append(f"\nThis changelog provides a transparent record of what was modified and why. We encourage you to review the changes before committing. Original file versions are backed up with a `.original` extension.\n")
+        
+        # Core metrics
+        total_lines_added = sum(stats.get('added_lines', 0) for stats in diff_stats.values())
+        success_rate = (fixed_suggestions/processed_suggestions_count*100) if processed_suggestions_count > 0 else 0
+        
+        # Lead with success rate - the most important outcome
+        lines.append(f"\n### Key Metrics\n")
+        lines.append(f"- **Success Rate:** {success_rate:.1f}% ({fixed_suggestions} of {processed_suggestions_count} processed suggestions addressed)\n")
+        lines.append(f"- **Total Impact:** {total_improvements} improvements across {len(file_stats)} files\n")
+        lines.append(f"- **Content Added:** {total_lines_added} lines of enhanced documentation\n")
+        
+        # Explain why some suggestions were filtered out
+        total_suggestions = len(suggestions)
+        filtered_count = total_suggestions - processed_suggestions_count
+        if filtered_count > 0:
+            lines.append(f"\n### Processing Strategy\n")
+            lines.append(f"- **Suggestions filtered out:** {filtered_count} items\n")
+            lines.append(f"- **Reason:** Only 'Fair' and 'Poor' priority suggestions were processed\n")
+            lines.append(f"- **Rationale:** Focus on critical issues that need immediate attention\n")
+            lines.append(f"- **Quality threshold:** 'Excellent' and 'Good' suggestions already meet standards\n")
+        
+        # Priority breakdown - answer "Was it important work?"
+        lines.append(f"\n### Priority Breakdown\n")
+        priority_fixed = 0
+        priority_total = 0
+        
+        for score in ["Poor", "Fair"]:
+            count = score_stats[score]
+            if count > 0:
+                priority_total += count
+                priority_fixed += count
+                lines.append(f"- **{score} Priority:** {count} items → 100% addressed\n")
         
-        # Summarize all files written with basic status
-        lines.append("\n## Files Written\n")
-        for art in artifacts:
-            stats = art.diff_stats or {}
-            added = stats.get("added_lines", 0)
-            status = "Revised" if added and added > 0 else "Copied"
-            lines.append(f"- {art.dest_rel_path} | status: {status} | added_lines: {added}")
+        # Remove confusing "Critical Issues" bullet - success rate already shown above
         
-        # Skipped or missing files
+        # Quality assurance note
+        excellent_count = score_stats.get("Excellent", 0)
+        good_count = score_stats.get("Good", 0)
+        if excellent_count > 0 or good_count > 0:
+            lines.append(f"\n### Quality Assurance\n")
+            lines.append(f"- **High-Quality Items:** {excellent_count + good_count} suggestions already meeting standards (no changes needed)\n")
+        
+        # Group improvements by file type for better readability
+        by_file = {}
+        for e in plan.planned_edits:
+            if e.file_path not in by_file:
+                by_file[e.file_path] = []
+            by_file[e.file_path].append(e)
+        
+        lines.append(f"\n## Files Improved\n")
+        for file_path, edits in by_file.items():
+            added_lines = diff_stats.get(file_path, {}).get('added_lines', 0)
+            lines.append(f"\n### {file_path}\n")
+            lines.append(f"**Changes made:** {len(edits)} improvement(s), {added_lines} lines added\n")
+            
+            for e in edits:
+                sug = next((s for s in suggestions if s.id == e.suggestion_id), None)
+                guidance = sug.content_guidance if sug else ""
+                evidence = sug.source.get("evidence", "") if sug and sug.source else ""
+                section = e.anchor.get('value', 'General improvements')
+                
+                # Convert technical action names to user-friendly descriptions
+                # Use the suggestion action if available, otherwise fall back to edit type
+                action_key = sug.action if sug else e.edit_type
+                
+                # Generate category-based description for full_replace actions
+                if action_key == 'full_replace' and sug:
+                    category = sug.category or ""
+                    category_display = category.split('.')[-1].replace('_', ' ').title() if category else ""
+                    
+                    # Create specific descriptions based on category
+                    if 'readme' in category.lower():
+                        action_desc = 'Enhanced README documentation'
+                    elif 'tutorial' in category.lower():
+                        action_desc = 'Improved tutorial content'
+                    elif 'userguide' in category.lower():
+                        action_desc = 'Enhanced user guide documentation'
+                    elif 'installation' in category.lower():
+                        action_desc = 'Improved installation instructions'
+                    elif 'dependencies' in category.lower():
+                        action_desc = 'Enhanced dependency information'
+                    elif 'readability' in category.lower():
+                        action_desc = 'Improved readability and clarity'
+                    elif 'setup' in category.lower():
+                        action_desc = 'Enhanced setup and configuration'
+                    elif 'reproducibility' in category.lower():
+                        action_desc = 'Improved reproducibility'
+                    elif 'structure' in category.lower():
+                        action_desc = 'Enhanced document structure'
+                    elif 'code_quality' in category.lower():
+                        action_desc = 'Improved code quality'
+                    elif 'verification' in category.lower():
+                        action_desc = 'Enhanced result verification'
+                    elif 'performance' in category.lower():
+                        action_desc = 'Added performance considerations'
+                    elif 'context' in category.lower():
+                        action_desc = 'Enhanced context and purpose'
+                    elif 'error_handling' in category.lower():
+                        action_desc = 'Improved error handling'
+                    else:
+                        action_desc = f'Enhanced {category_display}' if category_display else 'Comprehensive rewrite'
+                else:
+                    # Use existing action descriptions for non-full_replace actions
+                    action_desc = {
+                        'append_section': f'Added "{section}" section',
+                        'insert_after_header': f'Enhanced content in "{section}"',
+                        'rmarkdown_integration': f'Integrated improvements in "{section}"',
+                        'replace_intro_block': f'Improved "{section}" section',
+                        'add_dependencies_section': 'Added dependencies information',
+                        'add_system_requirements_section': 'Added system requirements',
+                        'add_hardware_requirements': 'Added hardware requirements',
+                        'clarify_mandatory_vs_optional': 'Clarified dependencies',
+                        'improve_readability': f'Improved readability in "{section}"',
+                        'improve_setup': f'Enhanced setup instructions in "{section}"',
+                        'improve_reproducibility': f'Improved reproducibility in "{section}"',
+                        'improve_structure': f'Enhanced structure in "{section}"',
+                        'improve_code_quality': f'Improved code quality in "{section}"',
+                        'improve_verification': f'Enhanced result verification in "{section}"',
+                        'improve_performance': f'Added performance notes in "{section}"',
+                        'improve_clarity_and_error_handling': f'Improved clarity and error handling in "{section}"',
+                        'improve_consistency': f'Improved consistency in "{section}"',
+                        'improve_context': f'Enhanced context in "{section}"',
+                        'improve_error_handling': f'Improved error handling in "{section}"',
+                        'add_overview_section': f'Added "{section}" section'
+                    }.get(action_key, f'Improved {action_key}')
+                
+                lines.append(f"- **{action_desc}**")
+                
+                # Show evaluation reasoning that triggered this improvement
+                if sug and sug.source:
+                    evidence = sug.source.get("evidence", "")
+                    score = sug.source.get("score", "")
+                    category = sug.category or ""
+                    
+                    # Format category for display (e.g., "readme.dependencies" -> "Dependencies")
+                    category_display = category.split('.')[-1].replace('_', ' ').title() if category else ""
+                    
+                    if evidence:
+                        # Handle different evidence types
+                        if isinstance(evidence, dict):
+                            # Extract key information from dict evidence
+                            evidence_text = evidence.get("dependency_suggestions", "") or evidence.get("evidence", "")
+                            if not evidence_text:
+                                evidence_text = f"Installation evaluation: {evidence.get('overall_score', 'Unknown')} score"
+                        else:
+                            evidence_text = str(evidence)
+                            # Handle Python dict string evidence (from full_replace actions)
+                            if evidence_text.startswith("{") and evidence_text.endswith("}"):
+                                try:
+                                    import ast
+                                    evidence_dict = ast.literal_eval(evidence_text)
+                                    # Extract specific suggestions from the evaluation report
+                                    dep_sugg = evidence_dict.get("dependency_suggestions", "")
+                                    hw_req = evidence_dict.get("hardware_requirements", False)
+                                    compat_os = evidence_dict.get("compatible_os", True)
+                                    overall_score = evidence_dict.get("overall_score", "")
+                                    
+                                    # Build specific reason based on evaluation findings
+                                    reasons = []
+                                    if dep_sugg:
+                                        reasons.append(f"Dependencies: {dep_sugg}")
+                                    if hw_req is False:
+                                        reasons.append("Hardware requirements not specified")
+                                    if compat_os is False:
+                                        reasons.append("Operating system compatibility unclear")
+                                    if overall_score and overall_score not in ("Excellent", "Good"):
+                                        reasons.append(f"Overall score: {overall_score}")
+                                    
+                                    if reasons:
+                                        evidence_text = "; ".join(reasons)
+                                    else:
+                                        evidence_text = f"Installation evaluation score: {overall_score}"
+                                except:
+                                    evidence_text = "Installation documentation needs improvement"
+                        
+                        if score and category_display:
+                            lines.append(f"  - *Reason:* [{category_display} - {score}] {evidence_text}")
+                        elif score:
+                            lines.append(f"  - *Reason:* [{score}] {evidence_text}")
+                        elif category_display:
+                            lines.append(f"  - *Reason:* [{category_display}] {evidence_text}")
+                        else:
+                            lines.append(f"  - *Reason:* {evidence_text}")
+                    elif score:
+                        lines.append(f"  - *Reason:* Evaluation score was '{score}' - needs improvement")
+                
+                # Show what was actually implemented (different from reason)
+                if guidance:
+                    # Extract key action from guidance to show what was implemented
+                    if "dependencies" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Added comprehensive dependency list with installation instructions")
+                    elif "system requirements" in guidance.lower() or "hardware" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Added system requirements and platform-specific installation details")
+                    elif "comparative statement" in guidance.lower() or "beneficial" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Added comparative analysis highlighting Seurat's advantages")
+                    elif "readability" in guidance.lower() or "bullet" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Enhanced readability with structured lists and examples")
+                    elif "overview" in guidance.lower() or "summary" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Improved overview section with clear, professional tone")
+                    elif "accessible" in guidance.lower() or "non-experts" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Simplified language for broader accessibility")
+                    elif "examples" in guidance.lower() or "usage" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Added practical examples and usage scenarios")
+                    elif "error" in guidance.lower() or "debug" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Added error handling guidance and troubleshooting tips")
+                    elif "context" in guidance.lower() or "scenarios" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Expanded context and real-world application examples")
+                    elif "structure" in guidance.lower() or "organization" in guidance.lower():
+                        lines.append(f"  - *Implemented:* Improved document structure and organization")
+                    else:
+                        # Truncate long guidance to avoid repetition
+                        short_guidance = guidance[:100] + "..." if len(guidance) > 100 else guidance
+                        lines.append(f"  - *Implemented:* {short_guidance}")
+                
+                lines.append("")
+        
+        # Note about skipped files
         if skipped:
-            lines.append("\n## Skipped or Missing Files\n")
+            lines.append(f"\n## Note\n")
+            lines.append(f"The following files were not modified as they were not found in the repository:")
             for rel in skipped:
                 lines.append(f"- {rel}")
+        
         report_md = "\n".join(lines)
         dest = os.path.join(out_dir, "GENERATION_REPORT.md")
         with open(dest, "w", encoding="utf-8") as fobj:

{bioguider-0.2.29.dist-info → bioguider-0.2.31.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bioguider
-Version: 0.2.29
+Version: 0.2.31
 Summary: An AI-Powered package to help biomedical developers to generate clear documentation
 License: MIT
 Author: Cankun Wang

{bioguider-0.2.29.dist-info → bioguider-0.2.31.dist-info}/RECORD

@@ -43,20 +43,20 @@ bioguider/conversation.py,sha256=DIvk_d7pz_guuORByK1eaaF09FAK-8shcNTrbSUHz9Y,177
 bioguider/database/code_structure_db.py,sha256=q9tGZLWrjPi7a3u1b2iUnMO30lNWKbeMOkpDRffev2M,16973
 bioguider/database/summarized_file_db.py,sha256=U60c62e2Bx7PwsTAcCQgljNxD5u5awjpj5qpHEgJbac,4801
 bioguider/generation/__init__.py,sha256=esV02QgCsY67-HBwSHDbA5AcbKzNRIT3wDwwh6N4OFM,945
-bioguider/generation/change_planner.py,sha256=1u_1tcVwggVw6QebXvPJVULYnRAIkKMteFxbnf42aAw,6964
-bioguider/generation/document_renderer.py,sha256=67-XGFGNe8WgHJpqkHLMecgk2OeV8a5cJRAeDTLsXG4,1806
-bioguider/generation/llm_cleaner.py,sha256=aMxc3j6IH_9mCfBjxY1bn0bAUtUkUoHjumobzGkN0h8,1422
-bioguider/generation/llm_content_generator.py,sha256=1pfXYRykvGgLGu9YJH-DhvaMzb7hy_EyvHQ8XojUBQ8,3684
+bioguider/generation/change_planner.py,sha256=0N10jvkfn2J9b598FKOKPQecwmQv68yeuUvMZn81nOI,9715
+bioguider/generation/document_renderer.py,sha256=Md8NMo0CXNIqatWOdKE-_4k02Y3T_BCLmEPLTEiYUCA,7984
+bioguider/generation/llm_cleaner.py,sha256=qFgS5xi7bBO8HAJ9WFNzH3p9AhOsAkYjchKQHuAUWWM,2917
+bioguider/generation/llm_content_generator.py,sha256=UbRURH6RdEWBVVqQi96SlTkNEOt01yyuxr76jR8__GA,10983
 bioguider/generation/llm_injector.py,sha256=bVxP6Asv2em4MBOB5yFsS14AuaeT7NLKQQMcsEqXjPY,17352
-bioguider/generation/models.py,sha256=q9sF32Iu5VAa59UbheqPWEZn4bYeGGUVzpW24NJR_SM,2518
+bioguider/generation/models.py,sha256=MlJOLjPHk8xs-UGW-TGN_M9cevTuxTG4tjm1d1L15go,2699
 bioguider/generation/output_manager.py,sha256=uwLyavND4kXOHlsXB0Berab3y8u6bhaEmQOQLl7wDAM,1963
 bioguider/generation/repo_reader.py,sha256=ivTURU61fR8er4ev7gSpOxER3FJv2d9GAx_X5JoVTvQ,1177
-bioguider/generation/report_loader.py,sha256=m6_zcXsm5X6cFUB0ypVo1rjwjQzPAwwg83tc4H0X_eA,5598
+bioguider/generation/report_loader.py,sha256=bxajeTDxod36iFsbSZhXSQjotxqP7LuAg5MC9OqX_p0,5911
 bioguider/generation/style_analyzer.py,sha256=Vn9FAK1qJBNLolLC1tz362k4UBaPl107BlvkQc8pV2I,983
-bioguider/generation/suggestion_extractor.py,sha256=tfkyWtdbAo-maLCF_wqwBXyh93yjulvDY17FuvTnTjk,7611
+bioguider/generation/suggestion_extractor.py,sha256=kkPOYE6FXRtYlogV0GQdBraZZJm08I6Oux5YKGUF1UU,29442
 bioguider/generation/test_metrics.py,sha256=ACXmSZc2L_UkkmC5h2s4tG44MXW1d-hClFwPCD5_BFI,7505
 bioguider/managers/evaluation_manager.py,sha256=EoZ8V4rmx16zk1J3N9cNjeo0aCa7i32fLEQ3b2UolEQ,5917
-bioguider/managers/generation_manager.py,sha256=94Fe-0q37t7QIP2lkdmEiTjb8-hbiz9XX9h8Gi6BkSU,9594
+bioguider/managers/generation_manager.py,sha256=GqjCci2eWHnIcJ-SOn5-hEMi8p3Jk4Q5E4KSObKELPs,31945
 bioguider/managers/generation_test_manager.py,sha256=3mOBzQVpsLo_LpSspJcofn3CNtvgagS1DMr9Zuwkzq4,5307
 bioguider/rag/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bioguider/rag/config.py,sha256=5g4IqTzgyfZfax9Af9CTkXShgItPOt4_9TEMSekCPik,4602
@@ -74,7 +74,7 @@ bioguider/utils/pyphen_utils.py,sha256=cdZc3qphkvMDeL5NiZ8Xou13M_uVNP7ifJ-FwxO-0
 bioguider/utils/python_file_handler.py,sha256=BERiE2RHxpu3gAzv26jr8ZQetkrtnMZOv9SjpQ7WIdg,2650
 bioguider/utils/r_file_handler.py,sha256=8HpFaYKP8N1nItwr9tOx49m99pcLSt8EUtTNTJ7xNoE,19564
 bioguider/utils/utils.py,sha256=h8OhCjzLpHkb3ndnjRBUOBHD7csbHdEVNXf75SRN8Zc,4413
-bioguider-0.2.29.dist-info/LICENSE,sha256=qzkvZcKwwA5DuSuhXMOm2LcO6BdEr4V7jwFZVL2-jL4,1065
-bioguider-0.2.29.dist-info/METADATA,sha256=O4IRhR2hhEuFMeWOYCSeQvyKHZUdWdGosGssGN0gohs,1962
-bioguider-0.2.29.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-bioguider-0.2.29.dist-info/RECORD,,
+bioguider-0.2.31.dist-info/LICENSE,sha256=qzkvZcKwwA5DuSuhXMOm2LcO6BdEr4V7jwFZVL2-jL4,1065
+bioguider-0.2.31.dist-info/METADATA,sha256=k5RSl8D1JHB5mFSCWqcJjTLF1WDDhtBw2BbFfmg-Trw,1962
+bioguider-0.2.31.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+bioguider-0.2.31.dist-info/RECORD,,