bioguider 0.2.28__tar.gz → 0.2.30__tar.gz

{bioguider-0.2.28 → bioguider-0.2.30}/PKG-INFO

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

bioguider-0.2.30/bioguider/generation/change_planner.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from typing import List, Dict
+
+from .models import SuggestionItem, StyleProfile, DocumentPlan, PlannedEdit
+
+
+class ChangePlanner:
+    def build_plan(
+        self,
+        repo_path: str,
+        style: StyleProfile,
+        suggestions: List[SuggestionItem],
+        available_files: Dict[str, str],
+    ) -> DocumentPlan:
+        planned: List[PlannedEdit] = []
+        seen_headers: set[tuple[str, str]] = set()
+
+        def section_header(title: str) -> str:
+            # use heading level 2 for inserts to be safe
+            h = style.heading_style or "#"
+            return f"{h*2} {title}\n\n"
+
+        for s in suggestions:
+            for target in s.target_files:
+                if target not in available_files:
+                    # allow planning; renderer will skip if missing
+                    pass
+
+                if s.action == "add_dependencies_section":
+                    # Use LLM generation instead of template
+                    header_key = (target, (s.anchor_hint or "Dependencies").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Dependencies"},
+                        content_template="",  # Will be generated by LLM
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "add_system_requirements_section":
+                    # Use LLM generation instead of template
+                    header_key = (target, (s.anchor_hint or "System Requirements").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "System Requirements"},
+                        content_template="",  # Will be generated by LLM
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "mention_license_section":
+                    content = section_header("License") + "This project is released under the MIT License. See LICENSE for details.\n"
+                    header_key = (target, (s.anchor_hint or "License").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "License"},
+                        content_template=content,
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "normalize_headings_structure":
+                    # Minimal placeholder: avoid heavy rewrites
+                    # Plan a no-op or a small note; actual normalization could be added later
+                    continue
+                elif s.action == "add_usage_section":
+                    content = section_header("Usage") + "- Brief example of typical workflow.\n"
+                    header_key = (target, "usage")
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": "Usage"},
+                        content_template=content,
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "replace_intro":
+                    # Replace intro block (between H1 and first H2) with a clean Overview section
+                    # Use empty content_template so LLM can generate content based on guidance
+                    header_key = (target, "overview")
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="replace_intro_block",
+                        anchor={"type": "header", "value": "Overview"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "clarify_mandatory_vs_optional":
+                    # Use specific guidance from evaluation report instead of generic template
+                    guidance = s.content_guidance or "Specify compatibility details for dependencies across operating systems and architectures."
+                    content = section_header("Dependencies") + f"- {guidance}\n"
+                    header_key = (target, "dependencies")
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": "Dependencies"},
+                        content_template=content,
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "add_hardware_requirements":
+                    # Use LLM generation instead of template
+                    header_key = (target, (s.anchor_hint or "Hardware Requirements").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Hardware Requirements"},
+                        content_template="",  # Will be generated by LLM
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "improve_clarity_and_error_handling":
+                    # Handle targeted improvements to user guides
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Introduction"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_consistency":
+                    # Handle consistency improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Examples"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_tutorial_quality":
+                    # Handle tutorial quality improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Setup"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_readability":
+                    # Handle readability improvements
+                    header_key = (target, (s.anchor_hint or "Introduction").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Introduction"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "improve_setup":
+                    # Handle setup improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Setup"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_reproducibility":
+                    # Handle reproducibility improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Setup"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_structure":
+                    # Handle structure improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Introduction"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_code_quality":
+                    # Handle code quality improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Code Examples"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_verification":
+                    # Handle verification improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Results"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_performance":
+                    # Handle performance improvements
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Performance"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "improve_context":
+                    # Handle context improvements for userguides
+                    header_key = (target, (s.anchor_hint or "Introduction").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Introduction"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "improve_error_handling":
+                    # Handle error handling improvements for userguides
+                    header_key = (target, (s.anchor_hint or "Examples").strip().lower())
+                    if header_key in seen_headers:
+                        continue
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Examples"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                    seen_headers.add(header_key)
+                elif s.action == "add_overview_section":
+                    # Handle overview section for README
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="append_section",
+                        anchor={"type": "header", "value": s.anchor_hint or "Overview"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+                elif s.action == "full_replace":
+                    # Handle full document replacement
+                    planned.append(PlannedEdit(
+                        file_path=target,
+                        edit_type="full_replace",
+                        anchor={"type": "document", "value": "full_document"},
+                        content_template="",  # Will be filled by LLM generation
+                        rationale=s.source.get("evidence", ""),
+                        suggestion_id=s.id,
+                    ))
+
+        # If a file is planned for full_replace, suppress other edits for that file to avoid redundancy
+        by_file: Dict[str, List[PlannedEdit]] = {}
+        for e in planned:
+            by_file.setdefault(e.file_path, []).append(e)
+        filtered: List[PlannedEdit] = []
+        for fpath, edits in by_file.items():
+            has_full = any(e.edit_type == "full_replace" for e in edits)
+            if has_full:
+                filtered.extend([e for e in edits if e.edit_type == "full_replace"])
+            else:
+                filtered.extend(edits)
+
+        return DocumentPlan(repo_path=repo_path, style_profile=style, planned_edits=filtered)
+
+

{bioguider-0.2.28 → bioguider-0.2.30}/bioguider/generation/document_renderer.py

@@ -40,6 +40,11 @@ class DocumentRenderer:
             added = len(edit.content_template.splitlines())
             content = new_content
 
+        elif edit.edit_type == "full_replace":
+            # Replace entire document content
+            content = edit.content_template
+            added = len(edit.content_template.splitlines())
+
         # Other edit types (insert_after_header, replace_block) can be added as needed
 
         return content, {"added_lines": added}

{bioguider-0.2.28 → bioguider-0.2.30}/bioguider/generation/llm_cleaner.py

@@ -6,10 +6,10 @@ from bioguider.agents.common_conversation import CommonConversation
 
 
 CLEANUP_PROMPT = """
-You are “BioGuider,” a precise editor for biomedical/bioinformatics documentation.
+You are "BioGuider," a precise editor for biomedical/bioinformatics documentation.
 
 TASK
-Given a full README markdown, produce a corrected version that:
+Given a documentation file (README, RMarkdown, or other), produce a corrected version that:
 - Fixes typos, grammar, capitalization, and spacing
 - Corrects malformed markdown (headers, lists, links, code fences)
 - Repairs or normalizes link formatting; keep URLs absolute if present
@@ -17,14 +17,22 @@ Given a full README markdown, produce a corrected version that:
 - Preserves technical accuracy and biomedical domain terminology (do not invent features)
 - Keeps tone neutral and professional; avoid marketing language
 - Preserves all valid information; do not delete content unless it is a duplicate or malformed
+- For RMarkdown files (.Rmd): Preserve YAML frontmatter, R code chunks, and existing structure exactly
+
+CRITICAL REQUIREMENTS:
+- Do NOT wrap the entire document in markdown code fences (```markdown). Return pure content only.
+- If the document starts with ```markdown and ends with ```, remove these fences completely.
+- Do NOT modify YAML frontmatter in RMarkdown files
+- Do NOT modify R code chunks (```{r} blocks) in RMarkdown files
+- Do NOT change the overall structure or organization of the document
 
 INPUT
-<<README>>
-{readme}
-<</README>>
+<<DOCUMENT>>
+{doc}
+<</DOCUMENT>>
 
 OUTPUT
-Return ONLY the revised markdown (no commentary, no explanations).
+Return ONLY the revised content (no commentary, no explanations, no code fences).
 """
 
 
@@ -35,8 +43,8 @@ class LLMCleaner:
     def clean_readme(self, content: str) -> tuple[str, dict]:
         conv = CommonConversation(self.llm)
         output, token_usage = conv.generate(
-            system_prompt=CLEANUP_PROMPT.format(readme=content[:30000]),
-            instruction_prompt="Provide the corrected README markdown only.",
+            system_prompt=CLEANUP_PROMPT.format(doc=content[:30000]),
+            instruction_prompt="Provide the corrected documentation content only.",
         )
         return output.strip(), token_usage
 

bioguider-0.2.30/bioguider/generation/llm_content_generator.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from typing import Dict
+import json
+from langchain_openai.chat_models.base import BaseChatOpenAI
+
+from bioguider.agents.common_conversation import CommonConversation
+from .models import StyleProfile, SuggestionItem
+
+
+LLM_SECTION_PROMPT = """
+You are "BioGuider," a precise documentation generator for biomedical/bioinformatics software.
+
+GOAL
+Write or refine a single documentation section named "{section}". Follow the specific guidance from the evaluation report exactly.
+
+INPUTS (use only what is provided; never invent)
+- suggestion_category: {suggestion_category}
+- anchor_title: {anchor_title}
+- guidance: {guidance}
+- evidence_from_evaluation: {evidence}
+- repo_context_excerpt (analyze tone/formatting; do not paraphrase it blindly): <<{context}>>
+
+CRITICAL REQUIREMENTS
+- Follow the guidance EXACTLY as provided: {guidance}
+- Address the specific suggestions from the evaluation report precisely
+- Do not deviate from the guidance or add unrelated content
+- If guidance mentions specific packages, requirements, or details, include them exactly
+- For RMarkdown files (.Rmd), preserve the original structure including YAML frontmatter, code chunks, and existing headers
+- NEVER generate generic placeholder content like "Clear 2–3 sentence summary" or "brief description"
+- ALWAYS use the specific guidance provided above to create concrete, actionable content
+
+STYLE & CONSTRAINTS
+- Fix obvious errors in the content.
+- Preserve the existing tone and style markers: {tone_markers}
+- Use heading style "{heading_style}" and list style "{list_style}"; link style "{link_style}".
+- Neutral, professional tone; avoid marketing claims.
+- Omit details you cannot substantiate from inputs/context; do not invent.
+- Prefer bullets; keep it short and skimmable.
+- Biomedical examples must avoid PHI; assume de-identified data.
+- Output must be plain markdown for this section only, with no commentary and no backticks.
+- Avoid duplication: if similar content exists in the repo context, rewrite succinctly instead of repeating.
+- Never remove, alter, or recreate top-of-file badges/shields/logos (e.g., CI, PyPI, Conda, Docs shields). Assume they remain unchanged; do not output replacements for them.
+- When targeting README content, do not rewrite the document title or header area; generate only the requested section body to be inserted below existing headers/badges.
+
+SECTION GUIDELINES (follow guidance exactly)
+- Dependencies: Include specific packages mentioned in guidance (e.g., "ggplot2", "dplyr", etc.)
+- System Requirements: Include R version requirements and platform-specific instructions as mentioned in guidance
+- Hardware Requirements: Include RAM/CPU recommendations as specified in guidance
+- License: one sentence referencing the license and pointing to the LICENSE file.
+- Install (clarify dependencies): Include compatibility details across operating systems and architectures as mentioned in guidance
+- Tutorial improvements: Add specific examples, error handling, and reproducibility notes as mentioned in guidance
+- User guide improvements: Enhance clarity, add missing information, and improve error handling as mentioned in guidance
+- If the section does not fit the above, produce content that directly addresses the guidance provided.
+
+OUTPUT FORMAT
+- Return only the section markdown (no code fences).
+- Start with a level-2 header: "## {anchor_title}" unless the content already starts with a header.
+- Ensure the content directly addresses: {guidance}
+- DO NOT include generic instructions or placeholder text
+- ONLY generate content that fulfills the specific guidance provided
+"""
+
+LLM_FULLDOC_PROMPT = """
+You are “BioGuider,” a documentation rewriter.
+
+GOAL
+Rewrite a complete target document using only the provided evaluation report signals and the repository context excerpts. Output a full, ready-to-publish markdown file that is more complete and directly usable.
+
+INPUTS (authoritative)
+- evaluation_report (structured JSON excerpts): <<{evaluation_report}>>
+- target_file: {target_file}
+- repo_context_excerpt (do not copy blindly; use only to keep style/tone): <<{context}>>
+
+STRICT CONSTRAINTS
+- Base the content solely on the evaluation report. Do not invent features, data, or claims not supported by it.
+- Prefer completeness and usability: produce the full file content, not just minimal "added" snippets.
+- Preserve top-of-file badges/logos if they exist in the original; keep title and header area intact unless the report requires changes.
+- Fix obvious errors; improve structure and readability per report suggestions.
+- Include ONLY sections specifically requested by the evaluation report - do not add unnecessary sections.
+- Avoid redundancy: do not duplicate information across multiple sections.
+- Keep links well-formed; keep neutral, professional tone; concise, skimmable formatting.
+- CRITICAL: Do NOT wrap the entire document inside markdown code fences (```markdown). Do NOT start with ```markdown or end with ```. Return pure markdown content suitable for copy/paste.
+- For RMarkdown files (.Rmd), preserve YAML frontmatter exactly and do not wrap content in code fences.
+
+OUTPUT
+- Return only the full markdown content for {target_file}. No commentary, no fences.
+"""
+
+
+class LLMContentGenerator:
+    def __init__(self, llm: BaseChatOpenAI):
+        self.llm = llm
+
+    def generate_section(self, suggestion: SuggestionItem, style: StyleProfile, context: str = "") -> tuple[str, dict]:
+        conv = CommonConversation(self.llm)
+        section_name = suggestion.anchor_hint or suggestion.category.split(".")[-1].replace("_", " ").title()
+        system_prompt = LLM_SECTION_PROMPT.format(
+            tone_markers=", ".join(style.tone_markers or []),
+            heading_style=style.heading_style,
+            list_style=style.list_style,
+            link_style=style.link_style,
+            section=section_name,
+            anchor_title=section_name,
+            suggestion_category=suggestion.category,
+            evidence=(suggestion.source.get("evidence", "") if suggestion.source else ""),
+            context=context[:2500],
+            guidance=(suggestion.content_guidance or "").strip(),
+        )
+        content, token_usage = conv.generate(system_prompt=system_prompt, instruction_prompt="Write the section content now.")
+        return content.strip(), token_usage
+
+    def generate_full_document(self, target_file: str, evaluation_report: dict, context: str = "") -> tuple[str, dict]:
+        conv = CommonConversation(self.llm)
+        system_prompt = LLM_FULLDOC_PROMPT.format(
+            target_file=target_file,
+            evaluation_report=json.dumps(evaluation_report)[:6000],
+            context=context[:4000],
+        )
+        content, token_usage = conv.generate(system_prompt=system_prompt, instruction_prompt="Write the full document now.")
+        return content.strip(), token_usage
+
+

{bioguider-0.2.28 → bioguider-0.2.30}/bioguider/generation/models.py

@@ -18,6 +18,10 @@ class EvaluationReport(BaseModel):
     userguide_evaluation: Optional[Dict[str, Any]] = None
     userguide_files: Optional[List[str]] = None
 
+    # Optional: tutorial evaluation content and any explicitly listed files
+    tutorial_evaluation: Optional[Dict[str, Any]] = None
+    tutorial_files: Optional[List[str]] = None
+
     submission_requirements_evaluation: Optional[Dict[str, Any]] = None
     submission_requirements_files: Optional[List[str]] = None
 

{bioguider-0.2.28 → bioguider-0.2.30}/bioguider/generation/output_manager.py

@@ -3,14 +3,14 @@ from __future__ import annotations
 import os
 import json
 from datetime import datetime
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 
 from .models import OutputArtifact, GenerationManifest, PlannedEdit
 
 
 class OutputManager:
-    def __init__(self, base_outputs_dir: str = "outputs"):
-        self.base_outputs_dir = base_outputs_dir
+    def __init__(self, base_outputs_dir: Optional[str] = None):
+        self.base_outputs_dir = base_outputs_dir or "outputs"
 
     def prepare_output_dir(self, repo_url_or_name: str) -> str:
         repo_name = self._extract_repo_name(repo_url_or_name)

{bioguider-0.2.28 → bioguider-0.2.30}/bioguider/generation/report_loader.py

@@ -150,6 +150,12 @@ class EvaluationReportLoader:
             normalized["userguide_evaluation"] = userguide_eval["evaluation"]
             normalized["userguide_files"] = userguide_eval["files"]
 
+        # Tutorial evaluation handling
+        tutorial_eval = normalized.get("tutorial")
+        if tutorial_eval and isinstance(tutorial_eval.get("evaluation"), dict):
+            normalized["tutorial_evaluation"] = tutorial_eval["evaluation"]
+            normalized["tutorial_files"] = tutorial_eval["files"]
+
         # userguide_eval = normalized.get("userguide")
         # if isinstance(userguide_eval, str):
         #     normalized["userguide_evaluation"] = self._parse_structured_block(userguide_eval["evaluation"], "structured_evaluation")