weaverx 0.1.1__py3-none-any.whl

weaverx/__init__.py

@@ -0,0 +1,3 @@
+"""WeaveRx — supportive GitHub triage for the medical AI community."""
+
+__version__ = "0.1.1"

weaverx/categories.py

@@ -0,0 +1,198 @@
+"""Medical AI issue categories with restorative, community-oriented framing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Priority(StrEnum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass(frozen=True, slots=True)
+class MedAICategory:
+    slug: str
+    display_name: str
+    description: str
+    suggested_labels: tuple[str, ...]
+    healer_framing: str
+
+
+MED_AI_CATEGORIES: tuple[MedAICategory, ...] = (
+    MedAICategory(
+        slug="dataset-access-licensing",
+        display_name="Dataset Access & Licensing",
+        description=(
+            "Questions about obtaining datasets, usage terms, attribution, "
+            "or redistribution constraints for medical imaging or clinical data."
+        ),
+        suggested_labels=("dataset", "data-access", "licensing"),
+        healer_framing=(
+            "Acknowledge how dataset friction slows research; offer clear paths "
+            "to documentation, access forms, or community-maintained mirrors."
+        ),
+    ),
+    MedAICategory(
+        slug="model-performance-pathology",
+        display_name="Model Performance (Pathology/Subgroup)",
+        description=(
+            "Reports or questions about model accuracy on specific pathologies, "
+            "anatomical sites, patient subgroups, or edge cases."
+        ),
+        suggested_labels=("performance", "pathology", "subgroup"),
+        healer_framing=(
+            "Validate the concern—subgroup performance matters clinically. "
+            "Invite reproducible eval details and point to benchmark scripts."
+        ),
+    ),
+    MedAICategory(
+        slug="reproducibility-environment",
+        display_name="Reproducibility & Environment",
+        description=(
+            "Setup issues, dependency conflicts, MONAI/nnU-Net version mismatches, "
+            "CUDA/PyTorch environments, or inability to reproduce published results."
+        ),
+        suggested_labels=("reproducibility", "environment", "monai", "nnunet"),
+        healer_framing=(
+            "Reproducibility is the bedrock of medical AI trust. Offer a gentle "
+            "checklist: versions, seeds, config files, and minimal repro steps."
+        ),
+    ),
+    MedAICategory(
+        slug="clinical-validation",
+        display_name="Clinical Validation Request",
+        description=(
+            "Requests for external validation, reader studies, prospective evaluation, "
+            "or guidance on moving from research code to clinical assessment."
+        ),
+        suggested_labels=("clinical-validation", "evaluation"),
+        healer_framing=(
+            "Honor the clinical lens. Clarify scope (research vs. regulated use) "
+            "and suggest validation frameworks without overpromising."
+        ),
+    ),
+    MedAICategory(
+        slug="privacy-compliance-dicom",
+        display_name="Privacy/Compliance/DICOM Considerations",
+        description=(
+            "PHI handling, de-identification, HIPAA/GDPR questions, DICOM metadata, "
+            "or concerns about sensitive data in issues or workflows."
+        ),
+        suggested_labels=("privacy", "compliance", "dicom", "phi"),
+        healer_framing=(
+            "Respond with care and containment. Never ask for patient identifiers; "
+            "redirect to safe, de-identified sharing practices."
+        ),
+    ),
+    MedAICategory(
+        slug="bug",
+        display_name="Bug",
+        description="Unexpected crashes, incorrect outputs, or broken functionality.",
+        suggested_labels=("bug",),
+        healer_framing=(
+            "Thank them for the report. Ask for minimal repro steps and environment "
+            "details in a supportive, non-blaming tone."
+        ),
+    ),
+    MedAICategory(
+        slug="feature-integration",
+        display_name="Feature/Integration Request",
+        description=(
+            "New capabilities, framework integrations (MONAI, nnU-Net, ITK), "
+            "or workflow improvements."
+        ),
+        suggested_labels=("enhancement", "integration"),
+        healer_framing=(
+            "Welcome the idea; explain fit with project scope and invite a design "
+            "sketch or use case from their clinical/research context."
+        ),
+    ),
+    MedAICategory(
+        slug="documentation",
+        display_name="Documentation",
+        description="Missing, unclear, or outdated docs, tutorials, or API references.",
+        suggested_labels=("documentation",),
+        healer_framing=(
+            "Documentation gaps are community gifts—each question helps the next "
+            "researcher. Point to existing docs and offer to clarify."
+        ),
+    ),
+)
+
+CATEGORY_BY_SLUG: dict[str, MedAICategory] = {c.slug: c for c in MED_AI_CATEGORIES}
+
+# Keywords used to boost duplicate detection and privacy scanning.
+MED_AI_KEYWORDS: frozenset[str] = frozenset(
+    {
+        "monai",
+        "nnunet",
+        "nn-u-net",
+        "dicom",
+        "nifti",
+        "chestxray",
+        "chexpert",
+        "mimic",
+        "brats",
+        "isic",
+        "pathology",
+        "segmentation",
+        "radiology",
+        "hipaa",
+        "gdpr",
+        "phi",
+        "de-identification",
+        "deidentification",
+        "clinical",
+        "validation",
+        "reproducibility",
+        "cuda",
+        "pytorch",
+    }
+)
+
+PRIVACY_KEYWORDS: frozenset[str] = frozenset(
+    {
+        "phi",
+        "hipaa",
+        "gdpr",
+        "patient id",
+        "patient name",
+        "mrn",
+        "medical record",
+        "dicom",
+        "identifiable",
+        "de-ident",
+        "deident",
+        "ssn",
+        "date of birth",
+        "dob",
+    }
+)
+
+
+def category_prompt_block() -> str:
+    """Format categories for LLM system prompts."""
+    lines: list[str] = []
+    for cat in MED_AI_CATEGORIES:
+        labels = ", ".join(cat.suggested_labels)
+        lines.append(
+            f"- **{cat.display_name}** (`{cat.slug}`): {cat.description} [labels: {labels}]"
+        )
+    return "\n".join(lines)
+
+
+def validate_category_slug(slug: str) -> str:
+    """Return slug if valid, otherwise the closest match or 'bug'."""
+    if slug in CATEGORY_BY_SLUG:
+        return slug
+    normalized = slug.lower().replace("_", "-").replace(" ", "-")
+    if normalized in CATEGORY_BY_SLUG:
+        return normalized
+    for cat in MED_AI_CATEGORIES:
+        if cat.slug in normalized or normalized in cat.slug:
+            return cat.slug
+    return "bug"

weaverx/cli.py

@@ -0,0 +1,322 @@
+"""WeaveRx CLI — medical AI GitHub triage from the terminal."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from weaverx import __version__
+from weaverx.categories import CATEGORY_BY_SLUG, Priority
+from weaverx.triage import TriageOptions, TriageResult, build_orchestrator
+from weaverx.utils import setup_logging
+
+app = typer.Typer(
+    name="weaverx",
+    help="WeaveRx — supportive AI triage for medical AI GitHub issues.",
+    no_args_is_help=True,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+PRIORITY_STYLE = {
+    Priority.LOW.value: "dim",
+    Priority.MEDIUM.value: "cyan",
+    Priority.HIGH.value: "yellow",
+    Priority.CRITICAL.value: "bold red",
+}
+
+SAFEGUARD_STATUS_STYLE = {
+    "clean": "green",
+    "review_recommended": "yellow",
+    "high_risk": "bold red",
+}
+
+SAFEGUARD_STATUS_ABBR = {
+    "clean": "OK",
+    "review_recommended": "REV",
+    "high_risk": "RISK",
+}
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"weaverx {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = None,
+) -> None:
+    """WeaveRx entrypoint."""
+
+
+def _render_duplicate_bar(score: float) -> Text:
+    filled = int(score * 10)
+    bar = "#" * filled + "-" * (10 - filled)
+    style = "green" if score < 0.4 else "yellow" if score < 0.7 else "red"
+    return Text(f"[{bar}] {score:.0%}", style=style)
+
+
+def render_triage_result(
+    result: TriageResult,
+    *,
+    verbose: bool = False,
+    output_console: Console | None = None,
+) -> None:
+    out = output_console or console
+    analysis = result.analysis
+    cat = CATEGORY_BY_SLUG.get(analysis.category)
+    category_name = cat.display_name if cat else analysis.category
+
+    title = f"Issue #{result.issue.number} - {result.issue.title[:60]}"
+    table = Table(title=title, box=box.ROUNDED)
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+
+    table.add_row("Category", category_name)
+    table.add_row(
+        "Priority",
+        Text(analysis.priority.upper(), style=PRIORITY_STYLE.get(analysis.priority, "white")),
+    )
+    table.add_row("Impact", analysis.impact_summary)
+    table.add_row("Duplicate likelihood", _render_duplicate_bar(analysis.duplicate_likelihood))
+    table.add_row("Suggested labels", ", ".join(analysis.suggested_labels) or "-")
+    table.add_row("Status", result.result_status().replace("_", " "))
+
+    if analysis.sources:
+        if verbose:
+            source_lines = [
+                f"[{s.type}] {_truncate(s.snippet, 80)} — {s.reason}" for s in analysis.sources
+            ]
+            table.add_row("Sources", "\n".join(source_lines))
+        else:
+            table.add_row("Sources", f"{len(analysis.sources)} excerpt(s) (use --verbose)")
+
+    if result.llm is not None:
+        table.add_row("LLM", f"{result.llm.provider} / {result.llm.model}")
+
+    if analysis.privacy_flags:
+        table.add_row("Privacy flags", ", ".join(analysis.privacy_flags))
+
+    if result.duplicate_matches:
+        dupes = "; ".join(
+            f"#{m.issue_number} ({m.score:.0%})" for m in result.duplicate_matches[:3]
+        )
+        table.add_row("Similar issues", dupes)
+
+    if result.safeguard is not None:
+        sg = result.safeguard
+        table.add_row("Safeguard score", f"{sg.score:.1f} / 10")
+        table.add_row(
+            "Safeguard status",
+            Text(
+                sg.status.replace("_", " ").upper(),
+                style=SAFEGUARD_STATUS_STYLE.get(sg.status, "white"),
+            ),
+        )
+        if sg.triggered:
+            flags = ", ".join(finding.id for finding in sg.triggered)
+            table.add_row("Safeguard flags", flags)
+
+    out.print(table)
+
+    draft_border = "green"
+    if result.safeguard is not None:
+        draft_border = SAFEGUARD_STATUS_STYLE.get(result.safeguard.status, "green")
+
+    draft_preview = result.draft_response if verbose else _truncate(result.draft_response, 400)
+    out.print(
+        Panel(
+            draft_preview,
+            title="Draft response",
+            subtitle="(use --verbose for full text)",
+            border_style=draft_border,
+        )
+    )
+
+    if result.safeguard is not None and result.safeguard.status == "high_risk":
+        out.print("[yellow]Safeguard: high risk — review draft carefully before posting.[/yellow]")
+
+    if result.dry_run:
+        out.print("[dim]Dry-run mode - no changes were made to GitHub.[/dim]")
+    if result.posted_comment:
+        out.print("[green]Posted triage comment to GitHub.[/green]")
+    if result.applied_labels:
+        out.print(f"[green]Applied labels:[/green] {', '.join(result.applied_labels)}")
+
+    out.print("[dim]WeaveRx drafts require human review - not for clinical use.[/dim]")
+
+
+def _truncate(text: str, max_len: int) -> str:
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3].rstrip() + "..."
+
+
+def _render_batch_summary(results: list[TriageResult]) -> None:
+    table = Table(title=f"Batch triage - {len(results)} issues", box=box.SIMPLE_HEAVY)
+    table.add_column("#", justify="right")
+    table.add_column("Title")
+    table.add_column("Category")
+    table.add_column("Priority")
+    table.add_column("Dup")
+    table.add_column("Safeguard")
+
+    for r in results:
+        cat = CATEGORY_BY_SLUG.get(r.analysis.category)
+        sg_abbr = "-"
+        if r.safeguard is not None:
+            sg_abbr = SAFEGUARD_STATUS_ABBR.get(r.safeguard.status, "?")
+        table.add_row(
+            str(r.issue.number),
+            _truncate(r.issue.title, 40),
+            cat.display_name if cat else r.analysis.category,
+            r.analysis.priority,
+            f"{r.analysis.duplicate_likelihood:.0%}",
+            sg_abbr,
+        )
+    console.print(table)
+
+
+def _output_json(payload: Any) -> None:
+    console.print_json(json.dumps(payload, indent=2))
+
+
+@app.command("triage")
+def triage_command(
+    repo: Annotated[str, typer.Option("--repo", help="GitHub repository (owner/name).")],
+    issue: Annotated[int | None, typer.Option("--issue", help="Issue number to triage.")] = None,
+    recent: Annotated[
+        int | None,
+        typer.Option("--recent", help="Triage N most recent open issues."),
+    ] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON only.")] = False,
+    mock: Annotated[bool, typer.Option("--mock", help="Offline mock mode (no API calls).")] = False,
+    mock_llm: Annotated[
+        bool,
+        typer.Option(
+            "--mock-llm",
+            help="Fetch real GitHub issues but use offline mock LLM (no XAI_API_KEY needed).",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Analyze only; never write to GitHub."),
+    ] = False,
+    confirm: Annotated[
+        bool,
+        typer.Option("--confirm", help="Confirm GitHub write actions."),
+    ] = False,
+    privacy_insight: Annotated[
+        bool,
+        typer.Option(
+            "--privacy-insight/--no-privacy-insight",
+            help="Flag possible PHI/DICOM concerns.",
+        ),
+    ] = True,
+    safeguards: Annotated[
+        bool,
+        typer.Option(
+            "--safeguards/--no-safeguards",
+            help="Run local draft safeguard heuristics (default: on).",
+        ),
+    ] = True,
+    llm_provider: Annotated[
+        str | None,
+        typer.Option(
+            "--llm-provider",
+            help=(
+                "LLM provider: grok, anthropic, or openai (default: grok or WEAVERX_LLM_PROVIDER)."
+            ),
+        ),
+    ] = None,
+    post_comment: Annotated[
+        bool,
+        typer.Option("--post-comment", help="Post draft response (requires --confirm)."),
+    ] = False,
+    apply_labels: Annotated[
+        bool,
+        typer.Option("--apply-labels", help="Apply suggested labels (requires --confirm)."),
+    ] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Verbose output.")] = False,
+) -> None:
+    """Triage one issue or a batch of recent issues."""
+    setup_logging(verbose)
+
+    if issue is None and recent is None:
+        err_console.print("[red]Provide --issue N or --recent N.[/red]")
+        raise typer.Exit(code=1)
+
+    if issue is not None and recent is not None:
+        err_console.print("[red]Use either --issue or --recent, not both.[/red]")
+        raise typer.Exit(code=1)
+
+    if mock and mock_llm:
+        err_console.print("[red]Use either --mock or --mock-llm, not both.[/red]")
+        raise typer.Exit(code=1)
+
+    options = TriageOptions(
+        repo=repo,
+        issue_number=issue,
+        recent=recent,
+        mock=mock,
+        mock_llm=mock_llm,
+        dry_run=dry_run or not (post_comment or apply_labels),
+        confirm=confirm,
+        privacy_insight=privacy_insight,
+        safeguards=safeguards,
+        llm_provider=llm_provider,
+        post_comment=post_comment,
+        apply_labels=apply_labels,
+    )
+
+    try:
+        orchestrator = build_orchestrator(
+            mock=mock,
+            mock_llm=mock_llm,
+            llm_provider=llm_provider,
+        )
+
+        if recent is not None:
+            results = orchestrator.triage_recent(options)
+            if json_output:
+                _output_json([r.to_dict() for r in results])
+            else:
+                _render_batch_summary(results)
+                if verbose:
+                    for r in results:
+                        render_triage_result(r, verbose=True)
+        else:
+            result = orchestrator.triage_one(options)
+            if json_output:
+                _output_json(result.to_dict())
+            else:
+                render_triage_result(result, verbose=verbose)
+
+    except ValueError as exc:
+        err_console.print(f"[red]Configuration error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    except Exception as exc:
+        err_console.print(f"[red]Triage failed:[/red] {exc}")
+        if verbose:
+            err_console.print_exception()
+        raise typer.Exit(code=2) from exc
+
+
+def run() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    run()

weaverx/draft_generator.py

@@ -0,0 +1,66 @@
+"""Supportive draft response refinement for medical AI issues."""
+
+from __future__ import annotations
+
+from weaverx.categories import CATEGORY_BY_SLUG
+from weaverx.github import GitHubIssue
+from weaverx.llm import TriageAnalysis
+
+
+def _opening_line(issue: GitHubIssue) -> str:
+    author = issue.user or "there"
+    return f"Hi @{author} - thank you for sharing this with the community."
+
+
+def _category_guidance(slug: str) -> str:
+    cat = CATEGORY_BY_SLUG.get(slug)
+    if not cat:
+        return ""
+    return cat.healer_framing
+
+
+def _privacy_addendum(flags: list[str]) -> str:
+    if not flags:
+        return ""
+    return (
+        "\n\n---\n"
+        "**Privacy note:** Please avoid sharing patient identifiers, DICOM UIDs tied to "
+        "individuals, or other PHI in public issues. De-identified logs, synthetic data, "
+        "or private maintainer channels are safer ways to share sensitive details."
+    )
+
+
+def _repro_checklist() -> str:
+    return (
+        "\n\n**Repro checklist (helps us help you faster):**\n"
+        "- Package versions (PyTorch, MONAI, nnU-Net, CUDA)\n"
+        "- Config files or trainer/plan identifiers\n"
+        "- Random seed and data split/fold\n"
+        "- Minimal command or notebook snippet"
+    )
+
+
+def refine_draft(issue: GitHubIssue, analysis: TriageAnalysis) -> str:
+    """
+    Ensure the draft feels supportive and includes practical next steps.
+    If the LLM draft is already strong, lightly augment rather than replace.
+    """
+    draft = analysis.draft_response.strip()
+    if len(draft) < 80:
+        draft = (
+            f"{_opening_line(issue)}\n\n"
+            f"{analysis.impact_summary}\n\n"
+            f"{_category_guidance(analysis.category)}"
+        )
+
+    if analysis.category == "reproducibility-environment" and "version" not in draft.lower():
+        draft += _repro_checklist()
+
+    needs_privacy = analysis.category == "privacy-compliance-dicom" or analysis.privacy_flags
+    if needs_privacy and "phi" not in draft.lower() and "patient" not in draft.lower():
+        draft += _privacy_addendum(analysis.privacy_flags)
+
+    if not draft.startswith("Hi"):
+        draft = f"{_opening_line(issue)}\n\n{draft}"
+
+    return draft.strip()

weaverx/duplicate_detector.py

@@ -0,0 +1,78 @@
+"""Lightweight duplicate issue detection without heavy ML dependencies."""
+
+from __future__ import annotations
+
+import re
+from difflib import SequenceMatcher
+
+from weaverx.categories import MED_AI_KEYWORDS
+from weaverx.github import GitHubIssue
+from weaverx.llm import DuplicateMatch
+
+
+def normalize_text(text: str) -> str:
+    text = text.lower()
+    text = re.sub(r"```.*?```", " ", text, flags=re.DOTALL)
+    text = re.sub(r"`[^`]+`", " ", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    text = re.sub(r"[^a-z0-9\s\-_/]", " ", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def _keyword_overlap(a: str, b: str) -> float:
+    words_a = {w for w in normalize_text(a).split() if w in MED_AI_KEYWORDS}
+    words_b = {w for w in normalize_text(b).split() if w in MED_AI_KEYWORDS}
+    if not words_a or not words_b:
+        return 0.0
+    overlap = len(words_a & words_b)
+    return overlap / max(len(words_a | words_b), 1)
+
+
+def similarity_score(source: GitHubIssue, candidate: GitHubIssue) -> float:
+    if source.number == candidate.number:
+        return 0.0
+
+    title_a = normalize_text(source.title)
+    title_b = normalize_text(candidate.title)
+    body_a = normalize_text(source.body)[:500]
+    body_b = normalize_text(candidate.body)[:500]
+
+    title_ratio = SequenceMatcher(None, title_a, title_b).ratio()
+    body_ratio = SequenceMatcher(None, body_a, body_b).ratio() if body_a and body_b else 0.0
+    keyword_boost = _keyword_overlap(
+        f"{source.title} {source.body}",
+        f"{candidate.title} {candidate.body}",
+    )
+
+    combined = (0.55 * title_ratio) + (0.30 * body_ratio) + (0.15 * keyword_boost)
+    return min(1.0, combined)
+
+
+def find_duplicates(
+    issue: GitHubIssue,
+    candidates: list[GitHubIssue],
+    *,
+    top_k: int = 3,
+    min_score: float = 0.25,
+) -> list[DuplicateMatch]:
+    scored: list[DuplicateMatch] = []
+    for candidate in candidates:
+        score = similarity_score(issue, candidate)
+        if score >= min_score:
+            scored.append(
+                DuplicateMatch(
+                    issue_number=candidate.number,
+                    title=candidate.title,
+                    score=score,
+                    url=candidate.html_url,
+                )
+            )
+    scored.sort(key=lambda m: m.score, reverse=True)
+    return scored[:top_k]
+
+
+def best_duplicate_score(matches: list[DuplicateMatch]) -> float:
+    if not matches:
+        return 0.0
+    return matches[0].score