pybinaryguard 1.0.0__py3-none-any.whl

pybinaryguard/__init__.py

@@ -0,0 +1,78 @@
+"""PyBinaryGuard -- Binary Compatibility Intelligence for Python.
+
+Detect binary incompatibilities *before* they crash your program.
+
+Quick start::
+
+    import pybinaryguard
+
+    report = pybinaryguard.scan()
+    print(report.health_score)
+
+    findings = pybinaryguard.check("torch")
+    profile = pybinaryguard.profile()
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from pybinaryguard.models.enums import ScanMode, Severity
+from pybinaryguard.models.finding import Finding, ScanReport
+from pybinaryguard.models.system import SystemProfile
+
+__all__ = [
+    "Finding",
+    "ScanMode",
+    "ScanReport",
+    "Severity",
+    "SystemProfile",
+    "check",
+    "inspect",
+    "profile",
+    "scan",
+]
+
+
+def scan(**kwargs: object) -> ScanReport:
+    """Full environment scan.
+
+    Returns a :class:`ScanReport` with all findings, health score, and
+    package counts.  Accepts the same keyword arguments as
+    :class:`~pybinaryguard.scanner.Scanner`.
+    """
+    from pybinaryguard.scanner import Scanner
+
+    scanner = Scanner(**kwargs)  # type: ignore[arg-type]
+    return scanner.run()
+
+
+def check(package: str, **kwargs: object) -> list:
+    """Check a specific installed package.
+
+    Returns a list of :class:`Finding` objects for the given package.
+    """
+    from pybinaryguard.scanner import Scanner
+
+    scanner = Scanner(packages=[package], **kwargs)  # type: ignore[arg-type]
+    report = scanner.run()
+    return report.findings
+
+
+def profile() -> SystemProfile:
+    """Collect the system profile without running compatibility checks."""
+    from pybinaryguard.scanner import Scanner
+
+    scanner = Scanner()
+    return scanner.get_profile()
+
+
+def inspect(file_path: str) -> list:
+    """Inspect a ``.whl`` or ``.so`` file against the current system.
+
+    Returns a list of :class:`Finding` objects.
+    """
+    from pybinaryguard.scanner import Scanner
+
+    scanner = Scanner()
+    return scanner.inspect_file(file_path)

pybinaryguard/__main__.py

@@ -0,0 +1,7 @@
+"""Support for ``python -m pybinaryguard``."""
+
+import sys
+
+from pybinaryguard.cli.main import main
+
+sys.exit(main())

pybinaryguard/agent/__init__.py

@@ -0,0 +1,63 @@
+"""PyBinaryGuard Agent SDK — agent-native binary compatibility intelligence.
+
+Provides structured, machine-readable diagnostics that AI agents can call,
+interpret, and act on without parsing human-formatted output.
+
+Quick start for agents::
+
+    from pybinaryguard.agent import scan, check, simulate_install, doctor
+
+    # Full environment scan — returns structured ActionableReport
+    report = scan()
+    print(report.to_dict())     # JSON-serializable
+    print(report.safe_actions)  # Auto-executable pip commands
+
+    # Check one package
+    result = check("torch")
+
+    # Predict compatibility BEFORE installing
+    sim = simulate_install("torch==2.4.0+cu124")
+
+    # Diagnose an error
+    dx = doctor("GLIBC_2.34 not found")
+
+    # Export tool schema for agent framework registration
+    from pybinaryguard.agent import export_tool_schema
+    schema = export_tool_schema(format="openai")
+
+    # Register as agent tool (one-liner)
+    tool = as_agent_tool()
+"""
+
+from __future__ import annotations
+
+from pybinaryguard.agent.tool_interface import (
+    ActionableReport,
+    AgentCheckResult,
+    AgentDoctorResult,
+    AgentSimulateResult,
+    RecommendedAction,
+    as_agent_tool,
+    check,
+    doctor,
+    scan,
+    simulate_install,
+)
+from pybinaryguard.agent.schema import export_tool_schema, get_tool_descriptors
+from pybinaryguard.agent.recommender import ActionRecommender
+
+__all__ = [
+    "ActionRecommender",
+    "ActionableReport",
+    "AgentCheckResult",
+    "AgentDoctorResult",
+    "AgentSimulateResult",
+    "RecommendedAction",
+    "as_agent_tool",
+    "check",
+    "doctor",
+    "export_tool_schema",
+    "get_tool_descriptors",
+    "scan",
+    "simulate_install",
+]

pybinaryguard/agent/guard.py

@@ -0,0 +1,232 @@
+"""Runtime import guard — intercept import failures with structured diagnostics.
+
+Activation::
+
+    # Method 1: Side-effect import (activates immediately)
+    import pybinaryguard.agent.guard
+
+    # Method 2: Explicit control
+    from pybinaryguard.agent.guard import enable_guard, disable_guard
+    enable_guard()
+    # ... do imports ...
+    disable_guard()
+
+    # Method 3: Context manager
+    from pybinaryguard.agent.guard import guarded_imports
+    with guarded_imports() as issues:
+        import torch
+    if issues:
+        print(issues)  # List of structured diagnostics
+
+When active, the guard installs a custom ``sys.excepthook`` that intercepts
+``ImportError`` and ``OSError`` (missing .so) during imports, runs a fast
+diagnostic, and stores structured results in ``guard.captured_issues``.
+
+The guard does NOT suppress exceptions — it captures diagnostics alongside
+the normal traceback.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, List, Optional, Type
+
+
+# Thread-local storage for guard state
+_local = threading.local()
+
+# Module-level state
+_original_excepthook: Optional[Callable[..., Any]] = None
+_guard_active: bool = False
+captured_issues: List[Dict[str, object]] = []
+
+
+def _diagnose_import_error(exc: ImportError) -> Dict[str, object]:
+    """Produce a structured diagnostic from an ImportError."""
+    issue: Dict[str, object] = {
+        "type": "import_error",
+        "module": exc.name or str(exc),
+        "message": str(exc),
+    }
+
+    msg = str(exc).lower()
+
+    # Detect GLIBC issues
+    if "glibc" in msg or "version" in msg and ".so" in msg:
+        issue["category"] = "glibc_mismatch"
+        issue["fix_hint"] = (
+            "The imported library requires a newer GLIBC than your system. "
+            "Try: pip install --force-reinstall <package>"
+        )
+    # Detect missing .so
+    elif "cannot open shared object" in msg or ".so" in msg:
+        issue["category"] = "missing_shared_library"
+        # Extract the library name
+        import re
+        lib_match = re.search(r"lib\w+\.so[\.\d]*", msg)
+        if lib_match:
+            issue["missing_library"] = lib_match.group()
+        issue["fix_hint"] = (
+            "A required shared library is missing. Install the system "
+            "dependency or reinstall the package."
+        )
+    # Detect CUDA errors
+    elif "cuda" in msg or "cudart" in msg or "nvrtc" in msg:
+        issue["category"] = "cuda_missing"
+        issue["fix_hint"] = (
+            "CUDA runtime not found. Install a CPU-only version or "
+            "set up the CUDA toolkit."
+        )
+    # Detect architecture issues
+    elif "wrong elf class" in msg or "exec format error" in msg:
+        issue["category"] = "architecture_mismatch"
+        issue["fix_hint"] = (
+            "Binary compiled for a different CPU architecture. "
+            "Reinstall with: pip install --no-binary :all: <package>"
+        )
+    else:
+        issue["category"] = "unknown"
+        issue["fix_hint"] = (
+            "Run: pybinaryguard check <package> for detailed diagnostics."
+        )
+
+    return issue
+
+
+def _diagnose_os_error(exc: OSError) -> Optional[Dict[str, object]]:
+    """Produce a structured diagnostic from an OSError if it's import-related."""
+    msg = str(exc).lower()
+
+    # Only handle .so loading failures
+    if ".so" not in msg and "shared object" not in msg:
+        return None
+
+    issue: Dict[str, object] = {
+        "type": "os_error",
+        "message": str(exc),
+        "category": "shared_object_load_failure",
+    }
+
+    import re
+    lib_match = re.search(r"(lib\w+\.so[\.\d]*)", msg)
+    if lib_match:
+        issue["missing_library"] = lib_match.group(1)
+
+    issue["fix_hint"] = (
+        "A shared library failed to load. Check that all system "
+        "dependencies are installed."
+    )
+    return issue
+
+
+def _guard_excepthook(
+    exc_type: Type[BaseException],
+    exc_value: BaseException,
+    exc_tb: Any,
+) -> None:
+    """Custom excepthook that captures structured diagnostics."""
+    global captured_issues
+
+    issue = None
+
+    if isinstance(exc_value, ImportError):
+        issue = _diagnose_import_error(exc_value)
+    elif isinstance(exc_value, OSError):
+        issue = _diagnose_os_error(exc_value)
+
+    if issue is not None:
+        captured_issues.append(issue)
+
+    # Always call the original excepthook — we don't suppress errors
+    if _original_excepthook is not None:
+        _original_excepthook(exc_type, exc_value, exc_tb)
+    else:
+        sys.__excepthook__(exc_type, exc_value, exc_tb)
+
+
+def enable_guard() -> None:
+    """Activate the import guard.
+
+    Installs a custom ``sys.excepthook`` that captures structured
+    diagnostics for import-related failures.
+    """
+    global _original_excepthook, _guard_active
+
+    if _guard_active:
+        return
+
+    _original_excepthook = sys.excepthook
+    sys.excepthook = _guard_excepthook
+    _guard_active = True
+
+
+def disable_guard() -> None:
+    """Deactivate the import guard, restoring the original excepthook."""
+    global _original_excepthook, _guard_active
+
+    if not _guard_active:
+        return
+
+    if _original_excepthook is not None:
+        sys.excepthook = _original_excepthook
+        _original_excepthook = None
+
+    _guard_active = False
+
+
+def is_active() -> bool:
+    """Return whether the import guard is currently active."""
+    return _guard_active
+
+
+def get_captured_issues() -> List[Dict[str, object]]:
+    """Return all captured issues since the guard was enabled."""
+    return list(captured_issues)
+
+
+def clear_captured_issues() -> None:
+    """Clear all captured issues."""
+    captured_issues.clear()
+
+
+@contextmanager
+def guarded_imports():
+    """Context manager that captures import diagnostics.
+
+    Usage::
+
+        with guarded_imports() as issues:
+            import some_problematic_module
+
+        if issues:
+            for issue in issues:
+                print(issue)
+
+    Yields a list that will be populated with any import-related
+    diagnostics captured during the block.
+    """
+    issues: List[Dict[str, object]] = []
+    was_active = _guard_active
+    prev_issues = list(captured_issues)
+
+    enable_guard()
+    clear_captured_issues()
+
+    try:
+        yield issues
+    finally:
+        # Capture any issues that occurred
+        issues.extend(captured_issues)
+
+        # Restore previous state
+        clear_captured_issues()
+        captured_issues.extend(prev_issues)
+
+        if not was_active:
+            disable_guard()
+
+
+# Auto-activate on import
+enable_guard()

pybinaryguard/agent/recommender.py

@@ -0,0 +1,283 @@
+"""Action recommendation engine for agent workflows.
+
+Transforms raw diagnostic findings into structured, executable actions
+classified by safety level so agents know what they can auto-execute
+versus what requires human approval.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from pybinaryguard.models.enums import Severity
+from pybinaryguard.models.finding import Finding
+
+
+@dataclass
+class RecommendedAction:
+    """A single recommended action an agent can take.
+
+    Attributes:
+        action_type: Category — "reinstall", "install", "uninstall",
+            "downgrade", "upgrade", "configure", "ignore".
+        target: The package or system component to act on.
+        command: Ready-to-execute shell command (usually pip).
+        reason: One-sentence explanation of why this action is needed.
+        safety: "safe" (agent can auto-execute), "review" (agent should
+            confirm with user), or "dangerous" (requires human approval).
+        confidence: 0.0-1.0 confidence that this action will fix the issue.
+        finding_id: The rule_id of the finding that triggered this action.
+        priority: Lower number = higher priority. 1 = fix first.
+    """
+
+    action_type: str
+    target: str
+    command: str
+    reason: str
+    safety: str  # "safe", "review", "dangerous"
+    confidence: float = 0.8
+    finding_id: str = ""
+    priority: int = 1
+
+    def to_dict(self) -> Dict[str, object]:
+        return {
+            "action_type": self.action_type,
+            "target": self.target,
+            "command": self.command,
+            "reason": self.reason,
+            "safety": self.safety,
+            "confidence": round(self.confidence, 2),
+            "priority": self.priority,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Action templates keyed by rule_id patterns
+# ---------------------------------------------------------------------------
+
+_ACTION_TEMPLATES: List[Dict[str, object]] = [
+    # CUDA mismatches
+    {
+        "pattern": r"CUDA_RUNTIME_MISMATCH|PYTORCH_CUDA_ABI_MISMATCH",
+        "action_type": "reinstall",
+        "command_template": "pip install {package} --index-url https://download.pytorch.org/whl/cu{cuda_short}",
+        "reason": "Package built for wrong CUDA version",
+        "safety": "safe",
+        "confidence": 0.9,
+    },
+    {
+        "pattern": r"CUDA_DRIVER_TOO_OLD",
+        "action_type": "configure",
+        "command_template": "# Upgrade GPU driver or install package for older CUDA: pip install {package}+cu{driver_cuda}",
+        "reason": "GPU driver too old for installed CUDA runtime",
+        "safety": "dangerous",
+        "confidence": 0.7,
+    },
+    # GLIBC
+    {
+        "pattern": r"GLIBC_VERSION_MISMATCH",
+        "action_type": "downgrade",
+        "command_template": "pip install {package}<={safe_version}",
+        "reason": "Package requires newer GLIBC than system provides",
+        "safety": "safe",
+        "confidence": 0.8,
+    },
+    {
+        "pattern": r"MUSL_GLIBC_CONFLICT",
+        "action_type": "reinstall",
+        "command_template": "pip install --no-binary :all: {package}",
+        "reason": "Binary wheel is glibc-linked but system uses musl (Alpine)",
+        "safety": "review",
+        "confidence": 0.7,
+    },
+    # Architecture
+    {
+        "pattern": r"ARCH_MISMATCH|JETSON_X86_WHEEL",
+        "action_type": "reinstall",
+        "command_template": "pip install --no-binary :all: {package}",
+        "reason": "Binary compiled for wrong CPU architecture",
+        "safety": "review",
+        "confidence": 0.6,
+    },
+    # Python ABI
+    {
+        "pattern": r"PYTHON_ABI_MISMATCH|PYTHON_VERSION_MISMATCH",
+        "action_type": "reinstall",
+        "command_template": "pip install --force-reinstall {package}",
+        "reason": "Package built for different Python version/ABI",
+        "safety": "safe",
+        "confidence": 0.9,
+    },
+    # Missing libraries
+    {
+        "pattern": r"MISSING_SHARED_LIB|CUDA_LIB_MISSING",
+        "action_type": "install",
+        "command_template": "# Install missing system library or: pip install {package}",
+        "reason": "Required shared library not found on system",
+        "safety": "review",
+        "confidence": 0.6,
+    },
+    # NumPy ABI
+    {
+        "pattern": r"NUMPY_ABI_MISMATCH",
+        "action_type": "reinstall",
+        "command_template": "pip install --force-reinstall {package}",
+        "reason": "NumPy C API version mismatch",
+        "safety": "safe",
+        "confidence": 0.9,
+    },
+    # CPU instruction set
+    {
+        "pattern": r"AVX2_REQUIRED|ILLEGAL_INSTRUCTION_RISK",
+        "action_type": "downgrade",
+        "command_template": "pip install {package} --prefer-binary",
+        "reason": "Binary requires CPU instructions not available on this system",
+        "safety": "review",
+        "confidence": 0.5,
+    },
+    # Board/embedded
+    {
+        "pattern": r"KNOWN_BROKEN_WHEEL|BOARD_INCOMPATIBLE_PACKAGE",
+        "action_type": "uninstall",
+        "command_template": "pip uninstall -y {package}",
+        "reason": "Package known incompatible with detected board",
+        "safety": "review",
+        "confidence": 0.8,
+    },
+    # Predictive failures
+    {
+        "pattern": r"PREDICTED_IMPORT_ERROR",
+        "action_type": "reinstall",
+        "command_template": "pip install --force-reinstall {package}",
+        "reason": "Predicted import failure based on dependency analysis",
+        "safety": "safe",
+        "confidence": 0.7,
+    },
+    # Container
+    {
+        "pattern": r"CONTAINER_NO_GPU_MOUNT",
+        "action_type": "configure",
+        "command_template": "# Re-run container with: --gpus all",
+        "reason": "GPU devices not mounted in container",
+        "safety": "dangerous",
+        "confidence": 0.9,
+    },
+    # TensorRT
+    {
+        "pattern": r"TENSORRT_INCOMPATIBLE",
+        "action_type": "reinstall",
+        "command_template": "pip install tensorrt=={compatible_version}",
+        "reason": "TensorRT version incompatible with current GPU/CUDA",
+        "safety": "review",
+        "confidence": 0.7,
+    },
+]
+
+
+class ActionRecommender:
+    """Transforms findings into executable recommended actions.
+
+    The recommender matches findings against known action templates and
+    produces structured actions that agents can auto-execute (safe),
+    present for review, or flag as dangerous.
+    """
+
+    def recommend(self, findings: List[Finding]) -> List[RecommendedAction]:
+        """Generate recommended actions from findings.
+
+        Parameters
+        ----------
+        findings:
+            Diagnostic findings from a scan or check.
+
+        Returns
+        -------
+        List[RecommendedAction]
+            Actions sorted by priority (highest priority first).
+        """
+        actions: List[RecommendedAction] = []
+        seen_targets: set = set()
+
+        for finding in findings:
+            if finding.severity == Severity.PASSED:
+                continue
+
+            action = self._match_action(finding)
+            if action is None:
+                continue
+
+            # Deduplicate: one action per target package
+            target_key = (action.action_type, action.target)
+            if target_key in seen_targets:
+                continue
+            seen_targets.add(target_key)
+
+            actions.append(action)
+
+        # Sort by priority: critical first, then by confidence descending
+        actions.sort(key=lambda a: (a.priority, -a.confidence))
+        return actions
+
+    def _match_action(self, finding: Finding) -> Optional[RecommendedAction]:
+        """Match a finding to an action template."""
+        for template in _ACTION_TEMPLATES:
+            pattern = template["pattern"]
+            if re.match(pattern, finding.rule_id):
+                return self._instantiate_action(template, finding)
+
+        # Fallback: use the finding's own suggestion if available
+        if finding.suggestion and finding.package:
+            return RecommendedAction(
+                action_type="fix",
+                target=finding.package,
+                command=finding.suggestion,
+                reason=finding.title,
+                safety="review",
+                confidence=finding.confidence * 0.6,
+                finding_id=finding.rule_id,
+                priority=self._severity_to_priority(finding.severity),
+            )
+
+        return None
+
+    def _instantiate_action(
+        self, template: Dict[str, object], finding: Finding
+    ) -> RecommendedAction:
+        """Create a concrete action from a template and finding."""
+        package = finding.package or "unknown"
+        command_template = str(template["command_template"])
+
+        # Fill template variables
+        command = command_template.format(
+            package=package,
+            cuda_short="121",  # sensible default
+            safe_version="",
+            driver_cuda="118",
+            compatible_version="",
+        )
+
+        # If the finding has a specific suggestion, prefer it
+        if finding.suggestion:
+            command = finding.suggestion
+
+        return RecommendedAction(
+            action_type=str(template["action_type"]),
+            target=package,
+            command=command,
+            reason=str(template["reason"]),
+            safety=str(template["safety"]),
+            confidence=float(template.get("confidence", 0.7)),
+            finding_id=finding.rule_id,
+            priority=self._severity_to_priority(finding.severity),
+        )
+
+    @staticmethod
+    def _severity_to_priority(severity: Severity) -> int:
+        return {
+            Severity.CRITICAL: 1,
+            Severity.WARNING: 2,
+            Severity.INFO: 3,
+            Severity.PASSED: 4,
+        }.get(severity, 3)