bioguider 0.2.19__py3-none-any.whl → 0.2.20__py3-none-any.whl

bioguider/generation/report_loader.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from typing import Tuple, Dict, Any
+
+from .models import EvaluationReport
+
+
+class EvaluationReportLoader:
+    def _parse_bool(self, token: str) -> Any:
+        if token == "True":
+            return True
+        if token == "False":
+            return False
+        return token
+
+    def _split_args(self, s: str) -> Dict[str, Any]:
+        # Split a function-like argument list into a dict, respecting quotes
+        args: Dict[str, Any] = {}
+        current = ""
+        parts = []
+        in_single = False
+        in_double = False
+        for ch in s:
+            if ch == "'" and not in_double:
+                in_single = not in_single
+                current += ch
+                continue
+            if ch == '"' and not in_single:
+                in_double = not in_double
+                current += ch
+                continue
+            if ch == "," and not in_single and not in_double:
+                parts.append(current.strip())
+                current = ""
+            else:
+                current += ch
+        if current.strip():
+            parts.append(current.strip())
+        for p in parts:
+            if not p:
+                continue
+            if "=" not in p:
+                continue
+            k, v = p.split("=", 1)
+            k = k.strip()
+            v = v.strip()
+            if (v.startswith("'") and v.endswith("'")) or (v.startswith('"') and v.endswith('"')):
+                v = v[1:-1]
+            else:
+                # try bool/int
+                if v in ("True", "False"):
+                    v = self._parse_bool(v)
+                else:
+                    try:
+                        v = int(v)
+                    except Exception:
+                        pass
+            args[k] = v
+        return args
+
+    def _parse_structured_block(self, text: str, key: str) -> Dict[str, Any] | None:
+        # Extract key=ClassName(arg1=val1, ...) and parse args
+        marker = f"{key}="
+        idx = text.find(marker)
+        if idx == -1:
+            return None
+        rest = text[idx + len(marker) :]
+        # find first '('
+        pidx = rest.find("(")
+        if pidx == -1:
+            return None
+        rest = rest[pidx + 1 :]
+        # find matching ')'
+        depth = 1
+        collected = ""
+        for ch in rest:
+            if ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth -= 1
+                if depth == 0:
+                    break
+            collected += ch
+        if not collected:
+            return None
+        return self._split_args(collected)
+
+    def _parse_submission_eval_str(self, text: str) -> Dict[str, Any]:
+        # Parse space-separated key=value pairs
+        out: Dict[str, Any] = {}
+        for token in text.strip().split():
+            if "=" not in token:
+                continue
+            k, v = token.split("=", 1)
+            v = v.strip()
+            if v in ("True", "False"):
+                out[k] = True if v == "True" else False
+            else:
+                out[k] = v
+        return out
+
+    def load(self, report_path: str) -> Tuple[EvaluationReport, str]:
+        with open(report_path, "r", encoding="utf-8") as fobj:
+            raw = json.load(fobj)
+
+        # Normalize nested stringified fields if any
+        def normalize(obj):
+            if isinstance(obj, str):
+                s = obj.strip()
+                if (s.startswith("{") and s.endswith("}")) or (s.startswith("[") and s.endswith("]")):
+                    try:
+                        return json.loads(s)
+                    except Exception:
+                        return obj
+                return obj
+            if isinstance(obj, dict):
+                return {k: normalize(v) for k, v in obj.items()}
+            if isinstance(obj, list):
+                return [normalize(v) for v in obj]
+            return obj
+
+        normalized = normalize(raw)
+
+        # Special handling for stringified evaluation fields
+        inst_eval = normalized.get("installation_evaluation")
+        if isinstance(inst_eval, str):
+            normalized["installation_evaluation"] = {
+                "structured_evaluation": self._parse_structured_block(inst_eval, "structured_evaluation"),
+            }
+
+        readme_eval = normalized.get("readme_evaluation")
+        if isinstance(readme_eval, dict):
+            fixed: Dict[str, Any] = {}
+            for fname, val in readme_eval.items():
+                if isinstance(val, str):
+                    fixed[fname] = {
+                        "structured_evaluation": self._parse_structured_block(val, "structured_evaluation"),
+                    }
+                else:
+                    fixed[fname] = val
+            normalized["readme_evaluation"] = fixed
+
+        submit_eval = normalized.get("submission_requirements_evaluation")
+        if isinstance(submit_eval, str):
+            normalized["submission_requirements_evaluation"] = self._parse_submission_eval_str(submit_eval)
+
+        report = EvaluationReport(**normalized)
+        return report, report_path
+
+

bioguider/generation/style_analyzer.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Dict
+
+from .models import StyleProfile
+
+
+class StyleAnalyzer:
+    def analyze(self, files: Dict[str, str]) -> StyleProfile:
+        profile = StyleProfile()
+
+        # Infer heading style: prefer README
+        readme = None
+        for name in ("README.md", "README.rst"):
+            if name in files:
+                readme = files[name]
+                break
+        sample = readme or next(iter(files.values()), "")
+        if "\n# " in sample or sample.startswith("# "):
+            profile.heading_style = "#"
+        elif "\n## " in sample:
+            profile.heading_style = "#"
+        else:
+            profile.heading_style = "#"
+
+        # List style
+        if "\n- " in sample:
+            profile.list_style = "-"
+        elif "\n* " in sample:
+            profile.list_style = "*"
+
+        # Tone markers (heuristic): keep minimal
+        profile.tone_markers = ["concise", "neutral"]
+        return profile
+
+

bioguider/generation/suggestion_extractor.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import List
+from .models import EvaluationReport, SuggestionItem
+
+
+class SuggestionExtractor:
+    def extract(self, report: EvaluationReport) -> List[SuggestionItem]:
+        suggestions: List[SuggestionItem] = []
+
+        # README-related suggestions
+        if report.readme_evaluation:
+            for file_name, evaluation in report.readme_evaluation.items():
+                structured = evaluation.get("structured_evaluation") if isinstance(evaluation, dict) else None
+                if structured:
+                    # Intro cleanup / overview enhancement beyond explicit suggestions
+                    suggestions.append(SuggestionItem(
+                        id=f"readme-intro-cleanup-{file_name}",
+                        category="readme.intro_cleanup",
+                        severity="should_fix",
+                        source={"section": "readme", "field": "overview", "evidence": "Improve top-level overview for clarity and tone."},
+                        target_files=[file_name],
+                        action="replace_intro",
+                        anchor_hint="Overview",
+                        content_guidance="Rewrite the opening summary to be clear, neutral, and typo-free.",
+                    ))
+                    # Dependency clarity
+                    dep_score = structured.get("dependency_score")
+                    dep_sugg = structured.get("dependency_suggestions")
+                    if dep_score in ("Poor", "Fair") or dep_sugg:
+                        suggestions.append(SuggestionItem(
+                            id=f"readme-dependencies-{file_name}",
+                            category="readme.dependencies",
+                            severity="should_fix",
+                            source={"section": "readme", "field": "dependencies", "evidence": str(dep_sugg or dep_score)},
+                            target_files=[file_name],
+                            action="add_dependencies_section",
+                            anchor_hint="Dependencies",
+                            content_guidance=str(dep_sugg or ""),
+                        ))
+
+                    # Hardware/Software specs
+                    hw_score = structured.get("hardware_and_software_spec_score")
+                    hw_sugg = structured.get("hardware_and_software_spec_suggestions")
+                    if hw_score in ("Poor", "Fair") or hw_sugg:
+                        suggestions.append(SuggestionItem(
+                            id=f"readme-sysreq-{file_name}",
+                            category="readme.system_requirements",
+                            severity="should_fix",
+                            source={"section": "readme", "field": "hardware_and_software", "evidence": str(hw_sugg or hw_score)},
+                            target_files=[file_name],
+                            action="add_system_requirements_section",
+                            anchor_hint="System Requirements",
+                            content_guidance=str(hw_sugg or ""),
+                        ))
+
+                    # License mention
+                    lic_sugg = structured.get("license_suggestions")
+                    lic_score = structured.get("license_score")
+                    if lic_sugg and lic_score:
+                        suggestions.append(SuggestionItem(
+                            id=f"readme-license-{file_name}",
+                            category="readme.license",
+                            severity="nice_to_have",
+                            source={"section": "readme", "field": "license", "evidence": str(lic_sugg)},
+                            target_files=[file_name],
+                            action="mention_license_section",
+                            anchor_hint="License",
+                            content_guidance=str(lic_sugg),
+                        ))
+
+                    # Readability structuring
+                    read_sugg = structured.get("readability_suggestions")
+                    if read_sugg:
+                        suggestions.append(SuggestionItem(
+                            id=f"readme-structure-{file_name}",
+                            category="readme.readability",
+                            severity="nice_to_have",
+                            source={"section": "readability", "field": "readability_suggestions", "evidence": str(read_sugg)},
+                            target_files=[file_name],
+                            action="normalize_headings_structure",
+                            anchor_hint="Installation",
+                            content_guidance=str(read_sugg),
+                        ))
+                        # If suggestions mention Usage, add a usage section
+                        if isinstance(read_sugg, str) and "Usage" in read_sugg:
+                            suggestions.append(SuggestionItem(
+                                id=f"readme-usage-{file_name}",
+                                category="readme.usage",
+                                severity="nice_to_have",
+                                source={"section": "readability", "field": "usage", "evidence": "Add Usage section as suggested."},
+                                target_files=[file_name],
+                                action="add_usage_section",
+                                anchor_hint="Usage",
+                                content_guidance="Provide a brief usage example and key commands.",
+                            ))
+
+        # Installation-related suggestions
+        if report.installation_evaluation:
+            structured = None
+            if isinstance(report.installation_evaluation, dict):
+                structured = report.installation_evaluation.get("structured_evaluation")
+            if structured:
+                dep_sugg = structured.get("dependency_suggestions")
+                if dep_sugg:
+                    for target in report.installation_files or []:
+                        suggestions.append(SuggestionItem(
+                            id=f"install-dep-clarify-{target}",
+                            category="installation.dependencies",
+                            severity="should_fix",
+                            source={"section": "installation", "field": "dependency_suggestions", "evidence": str(dep_sugg)},
+                            target_files=[target],
+                            action="clarify_mandatory_vs_optional",
+                            anchor_hint="Dependencies",
+                            content_guidance=str(dep_sugg),
+                        ))
+                hw = structured.get("hardware_requirements")
+                if hw is False:
+                    for target in report.installation_files or []:
+                        suggestions.append(SuggestionItem(
+                            id=f"install-hw-req-{target}",
+                            category="installation.hardware",
+                            severity="should_fix",
+                            source={"section": "installation", "field": "hardware_requirements", "evidence": "not specified"},
+                            target_files=[target],
+                            action="add_hardware_requirements",
+                            anchor_hint="Hardware Requirements",
+                            content_guidance="Add concise RAM/CPU recommendation as per report guidance.",
+                        ))
+
+        # Submission requirements could drive expected output/dataset sections; use only if in files list
+        # Keep minimal to avoid speculative content
+
+        return suggestions
+
+

bioguider/generation/test_metrics.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import json
+import re
+from difflib import SequenceMatcher
+from typing import Dict, Any, List, Tuple
+
+
+def _lev(a: str, b: str) -> float:
+    return 1.0 - SequenceMatcher(None, a, b).ratio()
+
+
+def _count_markdown_issues(text: str) -> int:
+    issues = 0
+    # naive checks
+    issues += text.count("[![") - text.count("](")  # unbalanced badge syntax
+    issues += text.count("[ ")  # bad link spacing
+    issues += len(re.findall(r"^#[^#\s]", text, flags=re.M))  # malformed header
+    return max(0, issues)
+
+
+def evaluate_fixes(baseline: str, corrupted: str, revised: str, injection_manifest: Dict[str, Any]) -> Dict[str, Any]:
+    per_error: List[Dict[str, Any]] = []
+    per_cat: Dict[str, Dict[str, int]] = {}
+
+    def mark(cat: str, key: str):
+        per_cat.setdefault(cat, {"total": 0, "fixed_to_baseline": 0, "fixed_to_valid": 0, "unchanged": 0, "worsened": 0})
+        per_cat[cat][key] += 1
+
+    for e in injection_manifest.get("errors", []):
+        cat = e.get("category", "unknown")
+        per_cat.setdefault(cat, {"total": 0, "fixed_to_baseline": 0, "fixed_to_valid": 0, "unchanged": 0, "worsened": 0})
+        per_cat[cat]["total"] += 1
+        orig = e.get("original_snippet", "")
+        mut = e.get("mutated_snippet", "")
+
+        # Determine the neighborhood and after-fix snippet
+        after = None
+        if mut and mut in corrupted:
+            # try to find replacement around mutated snippet in revised
+            idx = corrupted.find(mut)
+            window = corrupted[max(0, idx-200): idx+200]
+            # pick a few words from orig as hint
+            hint = orig[:50]
+            if hint and hint in revised:
+                after = hint
+        if after is None:
+            # fallback: search original snippet directly
+            after = orig if orig in revised else None
+
+        status = "unchanged"
+        notes = ""
+        if cat == "typo":
+            if orig and orig in revised:
+                status = "fixed_to_baseline"
+            elif mut and mut in revised:
+                status = "unchanged"
+            else:
+                status = "fixed_to_valid"
+        elif cat == "link":
+            # simple: link markdown well-formed
+            wellformed = re.search(r"\[[^\]]+\]\([^\s)]+\)", revised) is not None
+            status = "fixed_to_valid" if wellformed else "unchanged"
+        elif cat == "duplicate":
+            dup_before = corrupted.count(mut)
+            dup_after = revised.count(mut)
+            status = "fixed_to_valid" if dup_after < dup_before else "unchanged"
+        elif cat == "markdown_structure":
+            issues_before = _count_markdown_issues(corrupted)
+            issues_after = _count_markdown_issues(revised)
+            status = "fixed_to_valid" if issues_after < issues_before else "unchanged"
+        elif cat in ("bio_term", "function"):
+            if orig and orig in revised:
+                status = "fixed_to_baseline"
+            elif mut and mut in revised:
+                status = "unchanged"
+            else:
+                status = "fixed_to_valid"
+        else:
+            status = "unchanged"
+
+        mark(cat, status)
+        per_error.append({
+            "id": e.get("id"),
+            "category": cat,
+            "status": status,
+            "before": mut,
+            "after_contains_original": bool(orig and orig in revised),
+            "notes": notes,
+        })
+
+    # global metrics
+    issues_before = _count_markdown_issues(corrupted)
+    issues_after = _count_markdown_issues(revised)
+    global_metrics = {
+        "markdown_validity_delta": issues_before - issues_after,
+    }
+    return {
+        "per_error": per_error,
+        "per_category": per_cat,
+        "global": global_metrics,
+    }
+
+

bioguider/managers/evaluation_manager.py

@@ -1,13 +1,16 @@
 import os
 from pathlib import Path
 
+from bioguider.agents.evaluation_userguide_task import EvaluationUserGuideTask
 from bioguider.agents.prompt_utils import CollectionGoalItemEnum
+from bioguider.database.code_structure_db import CodeStructureDb
 from bioguider.utils.constants import ProjectMetadata
 from bioguider.utils.gitignore_checker import GitignoreChecker
 
 from ..agents.identification_task import IdentificationTask
 from ..rag.rag import RAG
 from ..utils.file_utils import parse_repo_url
+from ..utils.code_structure_builder import CodeStructureBuilder
 from ..database.summarized_file_db import SummarizedFilesDb
 from ..agents.evaluation_readme_task import EvaluationREADMETask
 from ..agents.evaluation_installation_task import EvaluationInstallationTask
@@ -30,6 +33,13 @@ class EvaluationManager:
         
         author, repo_name = parse_repo_url(repo_url)
         self.summary_file_db = SummarizedFilesDb(author, repo_name)
+        self.code_structure_db = CodeStructureDb(author, repo_name)
+        code_structure_builder = CodeStructureBuilder(
+            repo_path=repo_url, 
+            gitignore_path=Path(repo_url, ".gitignore"), 
+            code_structure_db=self.code_structure_db
+        )
+        code_structure_builder.build_code_structure()
 
     def identify_project(self) -> ProjectMetadata:
         repo_path = self.rag.repo_dir
@@ -119,6 +129,20 @@ class EvaluationManager:
         evaluation, files = evaluation_task.evaluate()
 
         return evaluation, files
+
+    def evaluate_userguide(self):
+        evaluation_task = EvaluationUserGuideTask(
+            llm=self.llm,
+            repo_path=self.rag.repo_dir,
+            gitignore_path=Path(self.rag.repo_dir, ".gitignore"),
+            meta_data=self.project_metadata,
+            step_callback=self.step_callback,
+            summarized_files_db=self.summary_file_db,
+            code_structure_db=self.code_structure_db,
+        )
+        evaluation, files = evaluation_task.evaluate()
+        return evaluation, files
+
         
         
     

bioguider/managers/generation_manager.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Tuple, Dict
+
+from bioguider.generation import (
+    EvaluationReportLoader,
+    SuggestionExtractor,
+    RepoReader,
+    StyleAnalyzer,
+    ChangePlanner,
+    DocumentRenderer,
+    OutputManager,
+    LLMContentGenerator,
+    LLMCleaner,
+)
+from bioguider.generation.models import GenerationManifest, GenerationReport
+from bioguider.utils.file_utils import parse_repo_url
+
+
+class DocumentationGenerationManager:
+    def __init__(self, llm, step_callback):
+        self.llm = llm
+        self.step_callback = step_callback
+        self.repo_url_or_path: str | None = None
+
+        self.loader = EvaluationReportLoader()
+        self.extractor = SuggestionExtractor()
+        self.style_analyzer = StyleAnalyzer()
+        self.planner = ChangePlanner()
+        self.renderer = DocumentRenderer()
+        self.output = OutputManager()
+        self.llm_gen = LLMContentGenerator(llm)
+        self.llm_cleaner = LLMCleaner(llm)
+
+    def print_step(self, step_name: str | None = None, step_output: str | None = None):
+        if self.step_callback is None:
+            return
+        self.step_callback(step_name=step_name, step_output=step_output)
+
+    def prepare_repo(self, repo_url_or_path: str):
+        self.repo_url_or_path = repo_url_or_path
+
+    def run(self, report_path: str, repo_path: str | None = None) -> str:
+        repo_path = repo_path or self.repo_url_or_path or ""
+        self.print_step(step_name="LoadReport", step_output=f"report_path={report_path}")
+        report, report_abs = self.loader.load(report_path)
+
+        self.print_step(step_name="ReadRepoFiles", step_output=f"repo_path={repo_path}")
+        reader = RepoReader(repo_path)
+        # Prefer report-listed files if available
+        target_files = []
+        if report.readme_files:
+            target_files.extend(report.readme_files)
+        if report.installation_files:
+            target_files.extend(report.installation_files)
+        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="AnalyzeStyle", step_output=f"files={[p for p in files.keys()]}")
+        style = self.style_analyzer.analyze(files)
+
+        self.print_step(step_name="ExtractSuggestions")
+        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="PlanChanges")
+        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="RenderDocuments")
+        # Apply edits cumulatively per file to ensure multiple suggestions are realized
+        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)
+        for fpath, edits in edits_by_file.items():
+            content = files.get(fpath, "")
+            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
+                content, stats = self.renderer.apply_edit(content, e)
+                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']}")
+
+        # Removed cleaner: duplication and fixes handled in prompts and renderer
+
+        # Prefer local repo folder name for outputs; fallback to author_repo from URL
+        out_repo_key = None
+        if repo_path and os.path.isdir(repo_path):
+            out_repo_key = os.path.basename(os.path.normpath(repo_path))
+        elif report.repo_url:
+            try:
+                author, name = parse_repo_url(report.repo_url)
+                out_repo_key = f"{author}_{name}"
+            except Exception:
+                out_repo_key = report.repo_url
+        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}")
+        out_dir = self.output.prepare_output_dir(out_repo_key)
+        artifacts = self.output.write_files(out_dir, revised, diff_stats_by_file=diff_stats)
+
+        manifest = GenerationManifest(
+            repo_url=report.repo_url,
+            report_path=report_abs,
+            output_dir=out_dir,
+            suggestions=suggestions,
+            planned_edits=plan.planned_edits,
+            artifacts=artifacts,
+            skipped=missing,
+        )
+        self.output.write_manifest(out_dir, manifest)
+        # Write human-readable generation report
+        gen_report_path = self._write_generation_report(out_dir, report.repo_url or str(self.repo_url_or_path or ""), plan, diff_stats, suggestions)
+        self.print_step(step_name="Done", step_output=f"output_dir={out_dir}")
+        return out_dir
+
+    def _write_generation_report(self, out_dir: str, repo_url: str, plan, diff_stats: Dict[str, dict], suggestions):
+        # Build a simple markdown report
+        lines: list[str] = []
+        lines.append(f"# Documentation Generation Report\n")
+        lines.append(f"Repo: {repo_url}\n")
+        lines.append(f"Output: {out_dir}\n")
+        lines.append("\n## Summary of Changes\n")
+        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")
+        for e in plan.planned_edits:
+            lines.append(f"- `{e.file_path}` -> {e.edit_type} -> {e.anchor.get('value','')}")
+        report_md = "\n".join(lines)
+        dest = os.path.join(out_dir, "GENERATION_REPORT.md")
+        with open(dest, "w", encoding="utf-8") as fobj:
+            fobj.write(report_md)
+        return dest
+
+